Review: the fork against Evolution API 2.3.7

.github/workflows/fork-tests.yml

@@ -0,0 +1,81 @@
+# The fork's tests. Every commit on a fork/ branch runs them, so a test:
+# commit shows its red run and the fix: commit after it shows green (FORK.md).
+name: fork tests
+
+on:
+  push:
+    branches: ['fork/**']
+  pull_request:
+  schedule:
+    # Weekly, against the newest Baileys release, so a new version is a
+    # diff to read before anyone bumps the pin.
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: typecheck and tests (pinned Baileys)
+    runs-on: ubuntu-latest
+    # A few tests need what only a real database does (foreign keys, cascades):
+    # they create and drop their own database on this server (test/helpers/real-postgres.ts).
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports: ['5432:5432']
+        options: >-
+          --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 10
+    env:
+      FORK_TEST_PG_URL: postgresql://postgres:postgres@127.0.0.1:5432/postgres
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run db:generate
+        env:
+          DATABASE_PROVIDER: postgresql
+      - run: npx tsc --noEmit
+      - name: tests
+        run: |
+          expected=$(node -p "require('./package.json').dependencies.baileys")
+          BAILEYS_EXPECT="$expected" npx vitest run
+
+  baileys-latest:
+    name: tests against the newest Baileys
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    # A few tests need what only a real database does (foreign keys, cascades):
+    # they create and drop their own database on this server (test/helpers/real-postgres.ts).
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports: ['5432:5432']
+        options: >-
+          --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 10
+    env:
+      FORK_TEST_PG_URL: postgresql://postgres:postgres@127.0.0.1:5432/postgres
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm install --no-save baileys@latest
+      - run: npm run db:generate
+        env:
+          DATABASE_PROVIDER: postgresql
+      - name: tests
+        run: |
+          installed=$(node -p "require('baileys/package.json').version")
+          echo "Testing baileys $installed"
+          BAILEYS_EXPECT="$installed" npx vitest run

.gitignore

@@ -34,13 +34,16 @@ lerna-debug.log*
 # Project related
 /instances/*
 !/instances/.gitkeep
-/test/
+
 /src/env.yml
 /store
 *.env
 
 /temp/*
 
+# Raw live-check recordings (docs/LIVE-CHECKS.md): never committed
+/live-records/
+
 .DS_Store
 *.DS_Store
 .tool-versions

AGENTS.md

@@ -1,3 +1,67 @@
+# Working in this fork (read first)
+
+This is an unofficial fork of Evolution API 2.3.7 (`FORK.md`).
+These rules are this fork's own standard. They are not Evolution's, and they
+do not go into pull requests offered to evolution-foundation/evolution-api.
+
+## Test first, always: red, then green
+
+1. Write the test that reproduces the bug or specifies the behaviour, and run
+   it against the code as it is. It must FAIL, for the reason the bug gives.
+   A test that passes before the fix proves nothing: rewrite it.
+2. Commit the test alone: `test: <what it proves>`. CI runs on that commit,
+   and its red run is the evidence.
+3. Make the smallest change that turns it green, with the rest of the suite
+   still green, and commit it: `fix: ...` or `feat: ...`. Push the two commits
+   one at a time, so CI records each.
+
+Never change a test to make it pass, and never skip or delete a failing test
+without saying why in the commit.
+
+## How the tests run
+
+- `npm test` runs vitest over `test/**/*.test.ts`. The tests run Evolution's
+  TypeScript source, not the bundle, against the Baileys that `package.json`
+  pins (`BAILEYS_DIR` points them at another build).
+- A fixture is a WhatsApp-side input (a `HistorySync` proto, an app-state
+  action, an encrypted patch), turned into events by the Baileys version under
+  test. Hand-written events are allowed only where Baileys has no builder.
+- `test/helpers/baileys-service.ts` builds the real `BaileysStartupService`
+  with an in-memory Prisma and the real Baileys event buffer; `deliver()`
+  sends a batch the way the socket does (buffered).
+- Every test runs under a configuration profile (`test/helpers/profiles.ts`).
+  The default is `minimal`, a production configuration that stores only the instance; a test
+  of storage uses `stored`. A behaviour that depends on a flag is tested
+  under both.
+- Assert what a consumer observes: the webhook payload, the stored row, the
+  socket call, the HTTP answer. Assert exact fields, not substrings.
+- No test touches WhatsApp, a real account or the network beyond localhost.
+
+## Recordings and fixtures (live checks)
+
+A live check records a real session (`LIVE_RECORD_DIR`, `docs/LIVE-CHECKS.md`).
+Raw recordings hold real people's numbers, names and messages. Any agent or
+person working here follows these rules, with no exception:
+
+- Never commit, stage or copy anything from `LIVE_RECORD_DIR` (or
+  `live-records/`). Only the scrubber's output (`scripts/live-scrub.ts`) goes
+  into `test/fixtures/live/`.
+- Before committing a fixture, run `npx tsx scripts/live-guard.ts` and read
+  `scrub-report.json` (`"leakGate": "pass"`, counts that fit the check).
+- Open and skim every new fixture file yourself. The guard cannot recognise a
+  name or a message text; you can.
+- If anything looks like a phone number, a user part of an `@lid` or
+  `@s.whatsapp.net` address that is not a scrubber fake, a name, a message
+  text, a signed media URL (`mmg.whatsapp.net`, `oh=` / `oe=` parameters), an
+  email, a token or a key: stop. Fix the scrubber and scrub again. Never edit
+  a fixture by hand.
+- Never paste a raw recording, or any part of one, into a commit, an issue, a
+  pull request or a chat.
+- A fixture's replay test must fail when the behaviour it covers is broken:
+  run it once against the code before the fix and say so in the commit.
+
+---
+
 # Evolution API - AI Agent Guidelines
 
 This document provides comprehensive guidelines for AI agents (Claude, GPT, Cursor, etc.) working with the Evolution API codebase.

CLAUDE.md

@@ -1,3 +1,5 @@
+**This is a fork: read the first section of `AGENTS.md` (test first, red then green) before changing anything.**
+
 # CLAUDE.md
 
 This file provides comprehensive guidance to Claude AI when working with the Evolution API codebase.

FORK.md

@@ -0,0 +1,84 @@
+# This fork
+
+An unofficial fork of [Evolution API](https://github.com/evolution-foundation/evolution-api)
+2.3.7. It is not endorsed by Evolution Foundation, and
+the image it builds is not an official Evolution API build: it carries its own
+name of its own, not Evolution's.
+
+## Why it exists
+
+Evolution API has no test suite. Every bug below shipped because nothing could
+catch it, and a consumer that needed a fix could only patch the minified bundle
+with string replacements. This fork shows the other way: the same code, a test
+harness that runs Evolution's own TypeScript source against the real Baileys,
+and every change made test first.
+
+## The rule: red, then green
+
+Every change in this fork is two commits, in this order:
+
+1. `test: ...`, a test that reproduces the bug and **fails** on the code as it
+   is. CI runs on that commit, so its red run is the proof that the test sees
+   the bug.
+2. `fix: ...` (or `feat:`), the smallest change that makes that test pass,
+   with the rest of the suite still green.
+
+A fix without a failing test first is not merged here. See `AGENTS.md`.
+
+## Base
+
+- Source: the `2.3.7` tag (`cd800f29`). Upstream `main` has the same code.
+  Upstream `develop` (2.4.0) is not used: it requires licence activation
+  against Evolution Foundation's server and breaks `POST /instance/create`.
+- Baileys pinned to `7.0.0-rc14` (2.3.7 ships rc.9, which is inside the range
+  of CVE-2026-48063).
+
+## Changes from 2.3.7
+
+Each line is a pair of commits: the test that failed on the code before the
+fix, then the fix. For most, that code is 2.3.7 itself; several need what the
+fork added first (the test harness, the Baileys 7.0.0-rc14 pin), and a red commit
+that only fails to import what its fix adds proves nothing about behaviour.
+`git log 2.3.7..` is the source of truth, and `git diff 2.3.7 --stat` lists
+every file modified from the original. Upstream issues and pull requests are
+named where one exists.
+
+**Contacts, names and groups**
+- App-state sync keys are reloaded with `fromObject` in all three auth stores, so saved names, labels, mutes and archives keep syncing after a restart (#2576, #2384; fixes also offered in #2685 and #2610).
+- Every @lid to phone mapping Baileys learns is forwarded on `contacts.upsert`, captured before Baileys' event buffer drops it.
+- Every `contacts.upsert` item for a contact says whether its name is the one the owner saved (`saved`), and only when that is certain. The @lid mapping items above carry `pushName: null` and no `saved`: a consumer that replaces a whole contact with an item, rather than merging its fields, loses the name.
+- Group updates reach subscriptions stored as `GROUP_UPDATE`, in all seven transports and in the global configurations (#2652).
+- Group metadata is filled from `groups.update` instead of queried again for every group on every listing.
+- `chats.update`, `chats.set` and `chats.upsert` items carry the chat's archive, pin and mute state (`archived`, `pinned`, `muteEndTime`) when Baileys has it, and omit a field it does not have rather than guess.
+
+**Messages and privacy**
+- A `getMessage` miss or failed lookup answers nothing, so Baileys no longer relays an empty message on a retry and uses it up (#2705, and #2706 for groups; fixes also offered in #2728 and #2623).
+- The fork's own log lines at `LOG_LEVEL=ERROR,WARN`, and Baileys' error logs, carry bounded fields, not message text, phone numbers, JIDs or push names; an exception's message is kept only scrubbed of URLs, JIDs, quoted parts and phone numbers (also as a person writes them). This is not a guarantee for every line: inherited code still logs some raw errors (integrations such as S3, Chatwoot and the chatbots are not covered by the tests), and a name inside an exception's unquoted words is not recognisable.
+- The `messages.upsert` webhook key of a DM WhatsApp addresses by @lid shows the phone JID as `remoteJid`, as 2.3.7 does, but keeps the original @lid in `remoteJidAlt` (2.3.7 copied the phone there too and lost it), with `addressingMode: 'pn'`: upstream develop's swap.
+- A media re-upload request names the message by the address the phone stores it under: the @lid from `remoteJidAlt` or `participantAlt` when the key shows the phone, or, for a key stored from 2.3.7 (the phone twice, `addressingMode: 'lid'`), the @lid Baileys' LID mapping has for the phone. The phone refuses a request that names an @lid chat by its phone JID. A key with the phone and its @lid beside it cannot say which of the two the phone keeps (a DM WhatsApp addresses by phone looks the same), so a refusal under the @lid is asked again once under the key as given. A request the phone does not answer in time ends Baileys' own wait for it, so no listener is left and a late answer changes nothing.
+- A media download records whether it asked the phone to re-upload an expired file and how that ended (a bounded log line, and `reupload` on the download's error), and when the phone refused, why (`reason=` on the log line, `reuploadReason` on the error and the HTTP answer: the phone's result such as `NOT_FOUND`, `error_<code>`, `missing_ciphertext`, or `no_answer`). Baileys 7.0.0-rc14 never asks on a CDN 404 or 410 (its check misses the status), so Evolution asks the phone itself, once per download, for at most 60s. A CDN 403 counts as expired only when the link that actually failed (the one on Baileys' error, which is the directPath when the message has one, else the url) carries exactly one `oe` query parameter, in hex unix seconds, that has passed by the local clock. This is a conservative heuristic: on 84 history-sync attachments, 403 answered 34 of 34 expired links and 0 of 50 valid ones, where a valid link to a dropped file answered 404 or 410.
+- A media download turns the media key back into bytes (from a base64 string, or the object JSON makes of a Uint8Array or a Buffer) before it asks the phone to re-upload, since Baileys 7.0.0-rc14 derives the re-upload's key from the value as given and then cannot decrypt the phone's answer (Baileys #2729 proposed the same fix there).
+- `POST /chat/getBase64FromMediaMessage` takes an optional `reupload` (boolean, default true). With `false` the phone is never asked to re-upload, and a file gone from the CDN (404, 410, or 403 on an expired link) fails at once with a 400 that says so; the HTTP error carries `reupload` for any failed download.
+- A failed media download never answers with the media link. The error's own text (Baileys' "Failed to fetch stream from" and the signed CDN link, whose `oh`, `oe` and `_nc_*` parameters let anyone holding it fetch the file, and whose directPath alone names it) used to be the message of the HTTP answer, of what the error handler posts to the errors webhook, and of the S3 upload's error log. The answer now says what failed, never where: `The media could not be downloaded (HTTP <status>)`, or the kind of error and its network code when there is no status, with `reupload` and `reuploadReason` as before; a text Evolution threw itself (it names no link) stands.
+
+**Proxy**
+- Media downloads, media uploads and the WhatsApp Web version fetch leave through the instance's proxy (uploads failed outright on a proxied instance).
+- A connect waits for the instance's proxy and stored settings, so it never starts from the server's own address or with default settings. Reloading the proxy keeps the one in force until the new one is read; a proxyscrape list that cannot be fetched fails the connect (and it is retried), and a proxyscrape download with no socket exit to share fails, rather than either going out directly. Tested with a local HTTP and SOCKS5 proxy; other transports a deployment adds are not covered.
+
+**Sessions and connections**
+- A database error never replaces a linked session's credentials with fresh ones, and a failed settings read no longer drops an event batch.
+- A logout or delete while the socket is down keeps the session until WhatsApp is told, so the device leaves the phone's Linked devices; it answers `202 PENDING` meanwhile and forwards nothing (#2520, #2508 in part). The pending logout is recorded on the instance's row (`disconnectionObject.logoutPending`) as well as in a file next to the session keys, so a restart that lost the instances volume still finishes it; when it cannot be recorded, the logout or delete answers 500 instead of 202. A logout is finished only on WhatsApp's word: its answer to remove-companion-device, or its refusal of the device on the next connection; the socket's own close after sending the request (all Baileys' `logout()` waits for) is not one. Concurrent logouts and deletes share one run and answer with its outcome. A deleted instance keeps its database row until then (Session and Proxy cascade from it), out of the API, its name taken and its token cleared.
+- Reconnects back off from 1s to 60s instead of spinning, the version fetch times out after 10s, and an instance never runs two sockets: a reload after a profile or privacy change joins a connect under way, and once an instance is removed nothing builds a socket for it, runs a batch it had queued, or forwards anything (#2134, #2184, #2430; ideas from #2732). A connect that fails at boot keeps the instance in the API and is retried on the same backoff.
+- A creds write that fails is logged and tried again until it lands, and stored creds that cannot be parsed fail the connect instead of being replaced by fresh ones.
+- Session files on disk are replaced whole, never written in place: each signal key file of the Prisma auth store (keys live under INSTANCE_DIR next to creds in the database) and the pending-logout marker go to a temp file in the same directory, are flushed, renamed over the target and the directory flushed. A process killed mid-write, a full disk or two writes of one key at once used to leave a torn or empty file, and a key file that does not parse reads as no key; tested by SIGKILLing a writer at random moments (half the files torn or empty before, none after). A failed write keeps the previous file and rejects; writes of one file run in call order; a temp file a killed writer left is removed when the store next opens. The provider-files store writes on its own server and Redis holds no files, so neither is covered.
+- Profile pictures are looked up once per contact per hour, at most four at a time, and history never waits on them (#1883). The picture update a history batch sends carries each contact's newest name, and a lookup that finishes after WhatsApp said the picture changed or was removed is dropped.
+- One pairing code per connect attempt, and a fresh QR budget per attempt (#2100, #2696).
+
+**Live checks**
+- A live check against a real phone can be recorded (`LIVE_RECORD_DIR`; the QR, its image and pairing codes are never written), scrubbed into a fixture, and replayed through the real event buffer and service in a test. The scrubber keeps a value as written only under a field it lists with a value that field is known to take, and stops on a field it does not know; its leak gate searches the output for every raw value that is not structure; a guard scans every committed fixture. None of them recognises a name the scrubber mistook for structure, so a person still reads every new fixture. A replay compares the webhooks' content, not their order or the pictures, and runs on events already decoded: it shows what Evolution does with what WhatsApp sent, not the encryption or the timing around it. The protocol, the check catalogue and the results log are in `docs/LIVE-CHECKS.md`.
+
+## Licence
+
+Evolution API is licensed under the Apache License 2.0 with additional
+conditions (`LICENSE`), which this fork keeps unchanged. `NOTICE` carries
+Evolution Foundation's attribution and states the modifications.

NOTICE

@@ -0,0 +1,27 @@
+Evolution API
+Copyright 2026 Evolution Foundation
+
+This product includes software developed by Evolution Foundation
+(https://evolutionfoundation.com.br).
+
+Trademark notice
+"Evolution Foundation", "Evolution" and "Evolution API" are trademarks of
+Evolution Foundation. The Evolution API logo, wordmark, and visual identity
+are governed by Evolution Foundation's Trademark and Brand Assets Policy
+(https://github.com/evolution-foundation/evolution-api/blob/main/TRADEMARKS.md).
+This fork does not change the Evolution API user interface or its brand assets.
+
+Third-party attributions
+
+This product includes software derived from CodeChat WhatsApp API
+(https://github.com/code-chat-br/whatsapp-api), originally licensed under MIT.
+The CodeChat project implemented the Baileys library
+(https://github.com/WhiskeySockets/Baileys), which Evolution API also uses for
+its WhatsApp Web integration.
+
+Modifications
+
+This is an unofficial fork of Evolution API 2.3.7, maintained by Almog Cohen
+(https://github.com/AlmogCohen/evolution-api). It is not endorsed
+by Evolution Foundation. The changes are described in FORK.md, and each one is
+a separate commit with the test that proves it.

README.md

@@ -1,3 +1,5 @@
+> **Unofficial fork** of Evolution API 2.3.7, made test first. Not endorsed by Evolution Foundation. See [FORK.md](FORK.md) for what changed and why.
+
 <h1 align="center">Evolution Api</h1>
 
 <div align="center">