test(fuzz): differential fuzzing against upstream Baileys

.github/workflows/fuzz.yml

@@ -0,0 +1,261 @@
+name: Nightly Fuzz
+
+# Two modes, on purpose.
+#
+# Every pull request already runs the fuzz suite through `npm test`, with a fixed
+# seed and small per-target budgets. That run is deterministic: it cannot fail
+# because of an unlucky draw, which is the only way a fuzz suite survives contact
+# with a CI system people have to trust.
+#
+# This job is where the searching happens. It varies the seed per run, raises the
+# budgets, and enforces the parts of the known-divergence registry that would be
+# hostile on a pull request — entries past their review date, and entries that no
+# longer excuse anything.
+
+on:
+  schedule:
+    # 03:17 UTC, off the hour so it does not queue behind everything else.
+    - cron: '17 3 * * *'
+  workflow_dispatch:
+    inputs:
+      seed:
+        description: 'Fuzz seed (defaults to the run id)'
+        required: false
+        type: string
+      mode:
+        description: 'smoke or deep'
+        required: false
+        default: 'deep'
+        # A choice, not free text: the runner rejects anything else outright, and
+        # a rejected dispatch is better than one that silently runs a smoke pass.
+        type: choice
+        options:
+          - deep
+          - smoke
+
+# One fuzz run at a time in the *repository*, not per ref. The tracking issue is
+# repository-wide, so two runs on different refs — a nightly and a manual
+# dispatch on a branch — would each look it up, each find nothing, and each
+# create one. Every later run then comments on and closes only the lowest
+# number, leaving the duplicate open forever holding a stale report. Queued
+# rather than cancelled: the in-flight run's result is the one worth keeping.
+concurrency:
+  group: fuzz
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  fuzz:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run the fuzz suite
+        id: fuzz
+        env:
+          # A fresh seed per run is the point: the fixed-seed smoke run on every
+          # PR has already searched its own corner exhaustively.
+          FUZZ_SEED: ${{ inputs.seed || github.run_id }}
+          FUZZ_MODE: ${{ inputs.mode || 'deep' }}
+          FUZZ_TIME_BUDGET_MS: '180000'
+          FUZZ_REPORT_DIR: fuzz-reports
+          FUZZ_STRICT_ALLOWLIST: '1'
+        # --expose-gc turns on the WASM handle-leak probe, which skips without it.
+        # --test-timeout bounds a decoder that stops returning: the runner's own
+        # slowMs is measured after the check completes, so it cannot see an input
+        # that never completes. The parent process owns this timer, so it fires
+        # even when the child's event loop is blocked by a synchronous WASM loop.
+        run: node --expose-gc --test --test-timeout=1800000 "./src/__fuzz__/**/*.test.ts"
+        continue-on-error: true
+
+      - name: Summarise
+        id: report
+        if: always()
+        run: |
+          {
+            node scripts/fuzz/report.ts fuzz-reports --markdown --fail-on-stale \
+              ${{ steps.fuzz.outcome == 'success' && ' ' || '--run-failed' }}
+          } > fuzz-summary.md 2>&1 && echo "clean=true" >> "$GITHUB_OUTPUT" || echo "clean=false" >> "$GITHUB_OUTPUT"
+          cat fuzz-summary.md >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: fuzz-reports-${{ github.run_id }}
+          path: |
+            fuzz-reports/
+            fuzz-summary.md
+          retention-days: 30
+
+      # The fuzz outcome is part of the condition, not just the report: a run can
+      # fail on something the report has no findings for — a harness crash, a
+      # suite-level assertion — and an issue is exactly what those need too.
+      #
+      # Runs on every outcome, not only failures. A clean run has something to
+      # say too: without it the tracking issue stayed open forever holding a
+      # report the nightly had since disproved, which is the fastest way to
+      # teach people to ignore it.
+      - name: Update the tracking issue
+        if: always()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('node:fs')
+            const summary = fs.readFileSync('fuzz-summary.md', 'utf8')
+            // The seed is a free-form workflow input, so the reproduction command
+            // has to quote it or it is not the command that ran: `nightly run`
+            // would make the shell treat `run` as the program, and a `;` would
+            // append a second command to whatever the reader pastes. Same rule as
+            // the runner's own replay hint.
+            const shellQuote = value =>
+              /^[\w.:@/+=-]+$/.test(value) ? value : `'${String(value).replaceAll("'", String.raw`'\''`)}'`
+            // The same condition the step used to be gated on, now a value: the
+            // report found nothing *and* the run itself did not fail.
+            const clean = ${{ steps.report.outputs.clean == 'true' && steps.fuzz.outcome == 'success' }}
+            const seed = process.env.FUZZ_SEED
+            const mode = process.env.FUZZ_MODE
+            const budget = process.env.FUZZ_TIME_BUDGET_MS
+            // Stable across runs, so the issue this job owns is identifiable by
+            // something other than a label anyone can apply. The seed moved into
+            // the body: it changes nightly, and a title that changes cannot be a key.
+            const title = 'Nightly fuzz: open findings'
+            const marker = '<!-- nightly-fuzz-tracking-issue -->'
+
+            // One open issue per topic, updated rather than duplicated: a fuzzer
+            // that opens a fresh issue every night trains people to close them
+            // unread.
+            //
+            // Matched on the marker alone. `listForRepo` returns pull requests as
+            // well as issues, and the generic `fuzz` label is one anybody can put on
+            // anything — so the label by itself would let the nightly report land in
+            // an unrelated thread, or on a PR, and the API's default ordering makes
+            // which one unstable as more labelled items are opened.
+            //
+            // And the label cannot be part of the *query* either, only of the
+            // answer. A label is editable by anyone with write access: strip `fuzz`
+            // from the open tracking issue and a label-scoped search stops returning
+            // it before the marker is ever consulted, so the next failing night files
+            // a duplicate and no clean night can ever find and close the original.
+            // The marker lives in the body, which is the one part of the issue this
+            // job writes and nothing routine edits. It still *applies* the label on
+            // creation, for people who browse that way — it just never trusts it.
+            //
+            // The cost is listing open issues rather than a label slice, which is
+            // why it paginates. The lowest number wins, so the choice does not depend
+            // on page order either.
+            const open = await github.paginate(github.rest.issues.listForRepo, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              per_page: 100
+            })
+            const owned = open
+              .filter(item => !item.pull_request && (item.body ?? '').includes(marker))
+              .sort((left, right) => left.number - right.number)
+
+            const body = [
+              marker,
+              `Seed: \`${seed}\` · mode \`${mode}\``,
+              '',
+              summary,
+              '',
+              `Run: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+              // The run's own flags, or the reproduction can pass where the run
+              // failed: without --expose-gc the leak probe skips, without
+              // FUZZ_STRICT_ALLOWLIST an expired entry is a warning rather than a
+              // failure, and the budget decides how many inputs each target gets
+              // through before it truncates. The mode is read back rather than
+              // hard-coded to `deep`, because a manual dispatch can run `smoke`
+              // and `npm run fuzz:deep` would then reproduce a different run.
+              `Reproduce locally: \`FUZZ_SEED=${shellQuote(seed)} FUZZ_MODE=${mode} FUZZ_TIME_BUDGET_MS=${budget} FUZZ_STRICT_ALLOWLIST=1 node --expose-gc --test --test-timeout=1800000 "./src/__fuzz__/**/*.test.ts"\``,
+              '',
+              '---',
+              '_Generated by [Claude Code](https://claude.ai/code)_'
+            ].join('\n')
+
+            // A clean run closes the issue rather than opening one. Commented
+            // first, so the thread records *why* it closed and against which
+            // seed — a bare close leaves whoever reopens it guessing.
+            // Every owned issue, not just the lowest. The concurrency group is
+            // repository-wide now so two runs cannot race into duplicates, but one
+            // may already exist from before that, or from a hand-filed issue
+            // carrying the marker — and closing only `owned[0]` would leave it open
+            // forever holding a report the nightly has disproved.
+            if (clean) {
+              for (const issue of owned) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issue.number,
+                body: [
+                  marker,
+                  `The nightly is clean on seed \`${seed}\` (mode \`${mode}\`), so this is closed.`,
+                  '',
+                  `Run: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
+                  '',
+                  'It reopens by itself: the next run with findings files against this same marker, or creates a fresh issue if this one is closed.',
+                  '',
+                  '---',
+                  '_Generated by [Claude Code](https://claude.ai/code)_'
+                ].join('\n')
+              })
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issue.number,
+                state: 'closed',
+                state_reason: 'completed'
+              })
+              }
+              return
+            }
+
+            if (owned.length > 0) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: owned[0].number,
+                body
+              })
+            } else {
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title,
+                body,
+                labels: ['fuzz']
+              })
+            }
+        env:
+          FUZZ_SEED: ${{ inputs.seed || github.run_id }}
+          # Mirrored from the run step, so the reproduction command names the mode
+          # and budget the findings were actually produced under.
+          FUZZ_MODE: ${{ inputs.mode || 'deep' }}
+          FUZZ_TIME_BUDGET_MS: '180000'
+
+      # The fuzz and summarise steps deliberately do not fail on the spot, so the
+      # artifacts get uploaded and the issue gets filed first. Without a final gate
+      # the job would then finish green holding findings, which is the one outcome
+      # that would make the whole nightly pointless.
+      - name: Fail the job when the run was not clean
+        if: always() && (steps.fuzz.outcome != 'success' || steps.report.outputs.clean != 'true')
+        run: |
+          echo "fuzz outcome: ${{ steps.fuzz.outcome }}"
+          echo "report clean: ${{ steps.report.outputs.clean }}"
+          exit 1

README.md

@@ -27,6 +27,14 @@ so existing integrations can migrate with minimal changes. See
 | Key management | JS auth state | Rust `PersistenceManager` |
 | Auto-reconnect | Manual `startSock()` loop | Transient drops retried in Rust (fibonacci backoff); terminal ones still yours |
 
+Compatibility is checked rather than assumed: a declaration audit against
+upstream's `.d.ts`, a wire-fidelity audit of the send path, ~50 behavioural
+compatibility suites, and a
+[differential fuzz suite](src/__fuzz__/README.md) that generates its own inputs
+from the proto schema and compares the two libraries directly. Differences the
+fuzzers find are recorded with a reason and a review date, and known open ones
+are listed in `src/__fuzz__/harness/divergence.ts`.
+
 ## Documentation
 
 The full API reference and guides live in the

package.json

@@ -47,6 +47,7 @@
     "lib/**/*",
     "!lib/**/*.map",
     "!lib/**/__tests__/**",
+    "!lib/__fuzz__/**",
     "!lib/**/*.test.*",
     "!lib/**/*.test-e2e.*"
   ],
@@ -70,6 +71,10 @@
     "prepack": "npm run build && node scripts/check-pack.ts",
     "prepare": "npm run build",
     "test": "node --test",
+    "fuzz": "node --test --test-timeout=600000 ./src/__fuzz__/**/*.test.ts",
+    "fuzz:deep": "FUZZ_MODE=deep node --expose-gc --test --test-timeout=1800000 ./src/__fuzz__/**/*.test.ts",
+    "fuzz:record": "FUZZ_RECORD=1 node --test --test-timeout=600000 ./src/__fuzz__/**/*.test.ts",
+    "fuzz:report": "node scripts/fuzz/report.ts",
     "test:compat-auditor": "node --test scripts/compatibility/__tests__/audit.test.ts",
     "typecheck:compat-auditor": "npm run build --silent && npm run compat:check-waproto --silent && npm run compat:layers --silent && tsc -p scripts/compatibility/tsconfig.json",
     "test:e2e": "NODE_TLS_REJECT_UNAUTHORIZED=0 ADV_SECRET_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= node --expose-gc --test --test-concurrency=1 ./src/__tests__/e2e/*.test-e2e.ts"