Add deterministic weekly Socket Firewall review

.github/workflows/ci.yml

@@ -20,6 +20,18 @@ jobs:
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 24
+          cache: npm
+      - name: Configure Socket Firewall for verifier dependencies
+        uses: workos/setup-socket-firewall@ca93dd8aa351f54f4729fe3377a9be23c631c25d # v1
+        with:
+          token: ${{ secrets.PUBLIC_SOCKET_FIREWALL_TOKEN }}
+          allow-external-fork-fallback: true
+      - name: Install verifier dependencies
+        run: npm ci --ignore-scripts --no-audit --no-fund
+      - name: Remove Socket Firewall credentials before executing verifier source
+        uses: workos/setup-socket-firewall/teardown@ca93dd8aa351f54f4729fe3377a9be23c631c25d # v1
+      - name: Run offline verifier tests
+        run: npm run check
       - name: Check shell style and test coverage policy
         run: |
           set -euo pipefail

.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+*.inventory.json
+reports/*
+!reports/.gitkeep

CONTRIBUTING.md

@@ -5,7 +5,7 @@ Thanks for helping improve the WorkOS Socket Firewall GitHub Action.
 ## Development requirements
 
 - Bash on Linux or macOS
-- Node.js 24 or later, matching the branch-repair JavaScript action runtime
+- Node.js 24 or later and npm, matching the branch-repair JavaScript action runtime and CI
 - Go, for the pinned `shfmt` check
 - ShellCheck
 - Passwordless `sudo` and a disposable Linux runner for integration testing that modifies `/etc/hosts`
@@ -26,11 +26,31 @@ bash scripts/scrub-lockfile.test.sh
 node --test scripts/scrub-npm-lockfile.test.mjs scripts/fix-lockfile.test.mjs
 bash scripts/build-release.test.sh
 bash scripts/publish-release.test.sh
+npm ci --ignore-scripts --no-audit --no-fund
+npm run check
 ```
 
+`npm run check` runs formatting and pure mocked Node tests offline after dependencies are installed. `npm test` and `npm run test:unit` both run all verifier suites. No credential or live discovery-ref lookup is needed for these tests. The install and pinned Go formatter command above may access the network; they are not offline tests.
+
 CI runs the same static and unit checks on every pull request. The npm scrub smoke matrix tests the internal normalizer and `npm ci --ignore-scripts` against both npm filenames and lockfile versions 1–3 without credentials. Branch-repair tests exercise the action controller against a simulated GitHub API, asserting the target branch, single-file commit, expected-head race protection, no-op, fork/default-branch guards, and denied writes. Release-tree tests run those same controller tests using the packaged runtime. Token-backed GitHub-hosted smoke jobs additionally exercise every supported package manager and a scrubbed npm lockfile with public registry DNS blocked.
 
-The minimum test-coverage policy is one shell test suite for every executable shell source file. Changes to supported package-manager behavior must also include a token-backed frozen-lockfile smoke test.
+Existing public/fork secret gates and token-backed smoke jobs are independent of the detector. Never add a live organization audit or release snapshot verification to normal source CI.
+
+The minimum test-coverage policy is one shell test suite for every executable shell source file. Verifier changes require synthetic Node fixtures for per-download setup/teardown boundaries, opaque execution, immutable-SHA reads, partial failures and private reporting. Preserve REST/GraphQL token-visible inventory reconciliation without claiming it proves organization-wide completeness. Changes to supported package-manager behavior must also include a token-backed frozen-lockfile smoke test.
+
+## Operator-only commands
+
+`npm run inventory` and `npm run audit:live` are read-only manual commands using an existing authorized `gh` session. Confirm organization-wide read access separately before making organization-wide claims. No scheduling or remediation is implicit. See README for the scan scope and limitations.
+
+For recurring agent use, `npm run review:weekly -- --state /durable/private/ledger.json` runs the audit and applies explicit fingerprint-bound decisions. `npm run review -- init|show|record|forget --state ...` manages that private ledger; see README for exact arguments. Never auto-initialize a missing weekly ledger, auto-acknowledge new cases, expire decisions by elapsed time, or publish the ledger/source report in this public repository. The weekly JSON intentionally contains private repository/job metadata; raw audit terminal output remains counts-only.
+
+Weekly-review changes require deterministic replay tests, unrelated-commit/order stability, new-repository/job and input-drift reopening, immutable repository IDs, durable decisions across visibility loss, and fail-closed missing/corrupt/partial state and concurrent writes. Test the next run after recording/fixing a finding, not only the first clean result. This adds report fingerprints/IDs to schema3 without changing primary or strict classification semantics.
+
+Audit schema3 separates primary observed configuration from strict `assuranceDispositions`. Acceptance tests must show that arbitrary execution before or after setup, pipelines, package scripts and script-only siblings do not invent missing installs or erase configuration. An actual uncovered install, explicit configuration conflict or unresolved relevant source must remain visible. Cover conditional Corepack state, scoped environment/registry changes, quoted data versus executable commands, executor payload boundaries, composite input binding and snapshot-bound reusable-workflow references. Preserve strict security/opacity diagnostics and source acquisition limits. `integrated` is configuration evidence, not runtime proof. `no-js-ci` is absence of an observed install path, not assurance about script bodies. Do not introduce a historical cohort, coverage percentage or blanket repository allowlist. Approved source exclusions must remain explicitly recorded, pin-checked and separate from protection claims.
+
+Full results are owner-only, ignored `reports/inventory.json` and `reports/live-audit.json`; terminal JSON contains sanitized counts. Audit `scanErrors`/`scanStatus` distinguish operational failures from discovered gaps. Exit 1 includes partial scans; exit 0 can still include `needs-sfw` or `needs-review`. Do not force-add reports, expose inventory/source in logs, or upload full reports as artifacts.
+
+`npm run verify-action` is a separate live, strict historical release snapshot check, not a normal CI check. Advancing `v1` or changing the current release manifest can intentionally invalidate it. Mocked release tests use `tools/rollout/fixtures/release-manifest.txt`, preserving integrity regression tests without binding source CI to future manifest changes. Keep the actual runtime manifest and action-only publication boundaries intact.
 
 ## Pull request guidelines