test(fuzz): differential fuzzing against upstream Baileys

.github/workflows/fuzz.yml

@@ -0,0 +1,165 @@
+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'
+        type: string
+
+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.
+      - name: Open an issue for the findings
+        if: always() && (steps.report.outputs.clean == 'false' || steps.fuzz.outcome != 'success')
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('node:fs')
+            const summary = fs.readFileSync('fuzz-summary.md', 'utf8')
+            const seed = process.env.FUZZ_SEED
+            const mode = process.env.FUZZ_MODE
+            const budget = process.env.FUZZ_TIME_BUDGET_MS
+            const title = `Nightly fuzz: findings on seed ${seed}`
+
+            // One open issue per topic, updated rather than duplicated: a fuzzer
+            // that opens a fresh issue every night trains people to close them
+            // unread.
+            const existing = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              labels: 'fuzz'
+            })
+
+            const body = [
+              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=${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')
+
+            if (existing.data.length > 0) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: existing.data[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"