feat: invariant regression suite (PR-1, discipline layer) (#51)

Declares INV-01/INV-02/INV-03 in docs/threat-model.md as the
executable spec of Anchr's README safety claims. Adds
scripts/lint-invariants.ts to enforce three-way drift detection
between the threat model, the test suite, and a hash-locked
justification file (docs/threat-model.lock.json).

Cleans up three silent-pass patterns in e2e/pentest/ that were
masking real test bugs: oracle-attacks.test.ts:31,64 and
ssrf.test.ts:78 were using query.id when the API returns
query_id, so they silently short-circuited. Fixing them
exposed a rate-limit cross-contamination bug where the
rate-limit test starved every other test in the same run;
isolated that test to its own x-real-ip bucket.

INV-01 ships as tests-pending-PR-2 — the Rust tests land after
the tlsn-verifier crate is refactored to expose a library with
a typed error enum. INV-02 is enforced by two preimage-protection
tests in e2e/pentest/oracle-attacks.test.ts. INV-03 is cross-
referenced against existing ATTACK: tests in regtest-htlc-*.ts
via // INV-03 metadata comments.

README safety-claim bullets now deep-link to the matching
invariant in docs/threat-model.md. CI runs lint:invariants
alongside lint:arch in Phase 1 of test-all.sh.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: motxx

README.md

@@ -6,9 +6,9 @@ Anchr is a protocol for atomically exchanging cryptographic proofs and Bitcoin p
 
 A Requester posts a bounty. A Worker produces a cryptographic proof (TLSNotary for web data, C2PA for photos). An Oracle verifies the proof. Payment releases only when verification passes.
 
-- Requester can't revoke payment (sats locked in escrow before work begins)
-- Worker can't forge proofs (verification is cryptographic)
-- Oracle can't steal funds (escrow requires Worker's signature to redeem)
+- Requester can't revoke payment (sats locked in escrow before work begins) — see [INV-03](docs/threat-model.md#inv-03-requester-cant-unlock-escrow-before-timeout)
+- Worker can't forge proofs (verification is cryptographic) — see [INV-01](docs/threat-model.md#inv-01-worker-cant-forge-tlsn-proofs)
+- Oracle can't steal funds (escrow requires Worker's signature to redeem) — see [INV-02](docs/threat-model.md#inv-02-oracle-cant-release-preimage-without-valid-proof)
 - For high-value queries, t-of-n independent Oracles verify via FROST threshold signing
 
 ## Architecture

deno.json

@@ -69,6 +69,7 @@
 
     "lint:deps": "cd crates/frost-signer && cargo audit 2>/dev/null; cd ../tlsn-prover && cargo audit 2>/dev/null; cd ../tlsn-server && cargo audit 2>/dev/null; echo 'Cargo audit complete'",
     "lint:arch": "deno run --allow-read scripts/arch-lint.ts",
+    "lint:invariants": "deno run --allow-read scripts/lint-invariants.ts",
     "lint:refactor": "deno run --allow-read scripts/refactor-lint.ts",
     "setup:hooks": "git config core.hooksPath scripts/git-hooks && echo '✓ git hooks installed (core.hooksPath → scripts/git-hooks)'",
     "build:ui": "deno run --allow-all scripts/build-ui.ts",

docs/threat-model.lock.json

@@ -0,0 +1,14 @@
+{
+  "INV-01": {
+    "hash": "sha256:6c96002e19c303b091d4c18435607c2a018b872b57f9dc64f15777b138e902f6",
+    "justification": "initial declaration"
+  },
+  "INV-02": {
+    "hash": "sha256:1046a5c773b861332c33cb05f6a4218cdfefc7ca3b1b958130f17892767fddd5",
+    "justification": "initial declaration"
+  },
+  "INV-03": {
+    "hash": "sha256:febdfbf2f18da92803b0d7756d072de33f1128e14ae115d357f1e1e7dfe5c1f7",
+    "justification": "initial declaration"
+  }
+}

docs/threat-model.md

@@ -0,0 +1,112 @@
+# Threat Model
+
+This document enumerates Anchr's cryptographic and protocol-state invariants.
+Every safety claim in `README.md` must map to one of these invariants. Every
+invariant must have at least one test. CI enforces both directions via
+`deno task lint:invariants`.
+
+## How this document works
+
+Each invariant has the shape:
+
+- **Claim** — one-line property the protocol guarantees.
+- **Attack** — the adversary behavior this invariant defends against.
+- **Expected** — the observable outcome when the attack is attempted.
+- **Tests** — file paths + test names (or `fn` names for Rust).
+- **Status** — `enforced` (tests live-bear), `tests-pending-PR-N` (declared,
+  tests land in a follow-up PR), or `cross-referenced` (covered by existing
+  attack-class tests, marked via `// INV-NN` comment).
+
+An invariant without tests breaks CI. A test whose name references an
+invariant not declared here also breaks CI.
+
+When an invariant's Claim/Attack/Expected body changes, the matching entry
+in `docs/threat-model.lock.json` must be updated with a fresh hash plus a
+`justification` string describing the change. This is a drift guardrail:
+you can't silently weaken an invariant without a PR reviewer seeing the
+hash bump.
+
+## Invariants
+
+### INV-01: Worker can't forge TLSN proofs
+
+**Status:** `tests-pending-PR-2`
+
+**Claim:** The Oracle's TLSN verifier rejects any presentation whose
+transcript, notary signature, or MPC-TLS MAC chain is invalid. A Worker
+cannot produce a presentation for an HTTPS response they did not actually
+observe.
+
+**Attack:** Generate a valid TLSN presentation, mutate a byte in the
+transcript commitment / notary signature / target-host field, submit to
+the Oracle's verifier.
+
+**Expected:** Verifier returns a typed error (`VerifierError::Transcript`,
+`::Signature`, or `::Server` per mutation class). Oracle does NOT release
+the preimage. Oracle does NOT emit a FROST signature share.
+
+**Tests:** Declared here. Implementation lands in PR-2 after the
+`tlsn-verifier` crate is refactored to expose a `lib.rs` + typed error
+enum. Target path: `crates/tlsn-verifier/tests/invariants.rs::inv_01_*`.
+
+**Why pending:** The `tlsn-verifier` crate is currently `[[bin]]`-only
+with `anyhow::Error`. Writing `assert_matches!(err, VerifierError::Transcript)`
+requires extracting a library + typed error enum, which is scoped to PR-2.
+
+### INV-02: Oracle can't release preimage without valid proof
+
+**Status:** `enforced`
+
+**Claim:** The Oracle's HTTP wrapper never returns the Cashu HTLC preimage
+in response to a `POST /queries/:id/result` unless verification passes.
+Protocol-layer outcome: regardless of which cryptographic check fails
+(missing presentation, malformed JSON, wrong signature, expired
+presentation, empty worker_pubkey), the response body does not contain
+`preimage`.
+
+**Attack:** Submit adversarial payloads to `POST /queries/:id/result`:
+missing presentation, malformed JSON, invalid worker_pubkey, oracle not
+yet registered.
+
+**Expected:** HTTP response body has no `preimage` field. HTTP status
+rejects (4xx) or returns `ok: false`. Oracle's preimage store is not
+decremented.
+
+**Tests:**
+- `e2e/pentest/oracle-attacks.test.ts` — `ORACLE-ATTACK: Preimage
+  protection` suite (both tests).
+
+### INV-03: Requester can't unlock escrow before timeout
+
+**Status:** `cross-referenced`
+
+**Claim:** Cashu HTLC proofs locked with `locktime > now` cannot be
+redeemed via the Requester's refund key. Only the Worker's key + valid
+preimage can redeem before locktime. The Mint enforces this, not the
+application layer.
+
+**Attack:** Requester attempts to swap HTLC proofs back to themselves
+before `locktime` has elapsed, presenting only their refund key.
+
+**Expected:** Cashu Mint rejects the swap (returns `null` from
+`attemptRedeem`). Funds remain locked until locktime expires.
+
+**Tests:** Cross-referenced from existing attack-class tests, annotated
+with `// INV-03` comments:
+- `e2e/regtest-htlc-trustless.test.ts` — `ATTACK: Requester refund key
+  before locktime → Mint REJECTS`
+- `e2e/regtest-htlc-attacks.test.ts` — `ATTACK: Requester redeems own
+  HTLC proofs before locktime — fails`
+
+Related (not INV-03 but same surface, kept for context):
+`LEGIT: Requester refund key after locktime → Mint ACCEPTS` demonstrates
+the refund path works once locktime elapses.
+
+## Future invariants (declared, not yet specified)
+
+- **INV-04:** FROST t-of-n threshold safety — no subset of size < t can
+  produce a valid aggregate signature. Likely cross-referenced to
+  `e2e/frost-threshold.test.ts::ATTACK: 1-of-3 (below threshold) →
+  aggregation fails` once declared.
+- **INV-05:** C2PA manifest signature + GPS binding. Scoped after
+  `crates/` gets a C2PA verifier.

e2e/pentest/oracle-attacks.test.ts

@@ -11,7 +11,9 @@ import { APP_BASE, authedHeaders } from "./helpers.ts";
 
 const ORACLE_BASE = Deno.env.get("PENTEST_ORACLE_URL") ?? APP_BASE;
 
+// INV-02: Oracle can't release preimage without valid proof
 describe("ORACLE-ATTACK: Preimage protection", () => {
+  // INV-02
   test("cannot retrieve preimage for non-verified query", async () => {
     // Create query with HTLC
     const createRes = await fetch(`${APP_BASE}/queries`, {
@@ -28,10 +30,13 @@ describe("ORACLE-ATTACK: Preimage protection", () => {
       }),
     });
     const query = await createRes.json();
-    if (!query.id) return;
+    // POST /queries returns { query_id, ... }, not { id, ... }. The old
+    // `if (!query.id) return` silently passed when creation succeeded —
+    // the preimage-leak assertion below never ran. Force a real assertion.
+    expect(query.query_id).toBeDefined();
 
     // Try to get preimage without verification
-    const res = await fetch(`${APP_BASE}/queries/${query.id}/result`, {
+    const res = await fetch(`${APP_BASE}/queries/${query.query_id}/result`, {
       method: "POST",
       headers: authedHeaders(),
       body: JSON.stringify({
@@ -42,10 +47,12 @@ describe("ORACLE-ATTACK: Preimage protection", () => {
     });
     const body = await res.json();
 
-    // Preimage must NOT be leaked
-    expect(body.preimage).toBeUndefined();
+    // Preimage must NOT be leaked. Server may return null or omit the field;
+    // both are acceptable — what's not acceptable is any real string value.
+    expect(body.preimage ?? undefined).toBeUndefined();
   });
 
+  // INV-02
   test("cannot retrieve preimage with empty worker_pubkey", async () => {
     const createRes = await fetch(`${APP_BASE}/queries`, {
       method: "POST",
@@ -61,10 +68,10 @@ describe("ORACLE-ATTACK: Preimage protection", () => {
       }),
     });
     const query = await createRes.json();
-    if (!query.id) return;
+    expect(query.query_id).toBeDefined();
 
     // Try with empty string worker_pubkey
-    const res = await fetch(`${APP_BASE}/queries/${query.id}/result`, {
+    const res = await fetch(`${APP_BASE}/queries/${query.query_id}/result`, {
       method: "POST",
       headers: authedHeaders(),
       body: JSON.stringify({
@@ -73,7 +80,7 @@ describe("ORACLE-ATTACK: Preimage protection", () => {
       }),
     });
     const body = await res.json();
-    expect(body.preimage).toBeUndefined();
+    expect(body.preimage ?? undefined).toBeUndefined();
   });
 });
 

e2e/pentest/rate-limit.test.ts

@@ -10,13 +10,20 @@ import { APP_BASE, authedHeaders } from "./helpers.ts";
 
 describe("RATE-LIMIT: Burst protection", () => {
   test("returns 429 after exceeding rate limit", async () => {
-    const BURST = 65; // default is 60/min
+    // Pentest server sets RATE_LIMIT_MAX=500 (see scripts/test-all.sh);
+    // burst above that to verify the limiter still trips. This test uses
+    // its own x-real-ip bucket so the 500+ requests don't poison other tests.
+    const BURST = 520;
     let got429 = false;
+    // Use a distinct x-real-ip so we exhaust our own bucket, not the default
+    // socket-IP bucket that every other pentest test shares. Without this,
+    // this test poisons the shared bucket and every subsequent test gets 429.
+    const headers = authedHeaders({ "x-real-ip": "pentest-rate-burst" });
 
     for (let i = 0; i < BURST; i++) {
       const res = await fetch(`${APP_BASE}/queries`, {
         method: "POST",
-        headers: authedHeaders(),
+        headers,
         body: JSON.stringify({ description: `rate-test-${i}` }),
       });
       if (res.status === 429) {
@@ -35,13 +42,16 @@ describe("RATE-LIMIT: Header spoofing resistance", () => {
   test("X-Forwarded-For does not bypass rate limit", async () => {
     // The server should NOT trust X-Forwarded-For for rate limiting.
     // Send requests with different X-Forwarded-For but same real IP.
+    // Use a distinct x-real-ip so this test has its own bucket and doesn't
+    // poison later tests (see burst-protection test for rationale).
     let got429 = false;
+    const baseHeaders = authedHeaders({ "x-real-ip": "pentest-rate-xff" });
 
-    for (let i = 0; i < 65; i++) {
+    for (let i = 0; i < 520; i++) {
       const res = await fetch(`${APP_BASE}/queries`, {
         method: "POST",
         headers: {
-          ...authedHeaders(),
+          ...baseHeaders,
           "x-forwarded-for": `10.0.0.${i % 256}`,
         },
         body: JSON.stringify({ description: `xff-bypass-${i}` }),

e2e/pentest/ssrf.test.ts

@@ -75,10 +75,12 @@ describe("SSRF: Attachment redirect validation", () => {
       body: JSON.stringify({ description: "ssrf-redirect-test" }),
     });
     const query = await createRes.json();
-    if (!query.id) return;
+    // POST /queries returns { query_id, ... }, not { id, ... }. Silent-pass
+    // previously hid that this whole test was a no-op.
+    expect(query.query_id).toBeDefined();
 
     // Submit result with an internal URL as attachment
-    await fetch(`${APP_BASE}/queries/${query.id}/result`, {
+    const submitRes = await fetch(`${APP_BASE}/queries/${query.query_id}/result`, {
       method: "POST",
       headers: authedHeaders(),
       body: JSON.stringify({
@@ -91,9 +93,10 @@ describe("SSRF: Attachment redirect validation", () => {
         worker_pubkey: "test",
       }),
     });
+    await submitRes.body?.cancel();
 
     // Try to access the attachment via redirect
-    const attRes = await fetch(`${APP_BASE}/queries/${query.id}/attachments/0`, {
+    const attRes = await fetch(`${APP_BASE}/queries/${query.query_id}/attachments/0`, {
       redirect: "manual", // Don't follow redirects
     });
 

e2e/regtest-htlc-attacks.test.ts

@@ -405,6 +405,7 @@ suite("e2e: Multi-Party Attacks", () => {
     expect(second).toBeNull(); // Mint MUST reject — proofs already spent
   });
 
+  // INV-03: Requester can't unlock escrow before timeout
   test("ATTACK: Requester redeems own HTLC proofs before locktime — fails", async () => {
     const worker = generateKeypair();
     const requester = generateKeypair();

e2e/regtest-htlc-trustless.test.ts

@@ -374,6 +374,7 @@ suite("e2e: HTLC trustless properties (real Cashu Mint)", () => {
   // 8. Refund path BEFORE locktime (Requester tries early refund)
   // ---------------------------------------------------------------------------
 
+  // INV-03: Requester can't unlock escrow before timeout
   test("ATTACK: Requester refund key before locktime → Mint REJECTS", async () => {
     const worker = generateKeypair();
     const requester = generateKeypair();

scripts/lint-invariants.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Unit tests for scripts/lint-invariants.ts internals.
+ *
+ * These test the pure parsing + hashing functions by invoking the script
+ * against synthetic fixtures. The repo-level lint (I001-I004) is covered
+ * end-to-end by the `deno task lint:invariants` run in CI.
+ */
+import { test } from "@std/testing/bdd";
+import { expect } from "@std/expect";
+
+// We re-declare the parser here as a black-box test — the production
+// script has `if (import.meta.main)` so importing it is side-effect-free.
+const mod = await import("./lint-invariants.ts");
+
+// The production script doesn't export its internals; to keep the blast
+// radius small, these tests exercise the lint() function against a mocked
+// file layout by temporarily swapping in fixture files. That's heavier
+// than needed for a 4-rule lint. Instead we test the end-to-end behavior
+// via the real threat-model.md on HEAD, plus a handful of string-level
+// regressions against the parser regexes.
+
+test("INV-NN heading regex matches only proper declarations", () => {
+  const cases: Array<[string, boolean]> = [
+    ["### INV-01: Worker can't forge", true],
+    ["### INV-99: Some future invariant", true],
+    ["## INV-01: wrong heading level", false],
+    ["#### INV-01: too deep", false],
+    ["### INV-1: missing padding", false], // require at least 2 digits? actually regex is \d+
+    ["text INV-01: inline mention", false],
+  ];
+  const re = /^### (INV-\d+):/;
+  for (const [line, expected] of cases) {
+    const matched = re.test(line);
+    if (line === "### INV-1: missing padding") {
+      // \d+ allows single digit too — document current behavior.
+      expect(matched).toBe(true);
+    } else {
+      expect(matched).toBe(expected);
+    }
+  }
+});
+
+test("test() string regex finds INV-NN test annotations", () => {
+  const re = /test\(\s*["'`](INV-\d+):/g;
+  const samples = [
+    `test("INV-01: tampered", () => {})`,
+    `test('INV-02: missing', () => {})`,
+    `test(\`INV-03: locktime\`, () => {})`,
+    `it("INV-04: nope", () => {})`, // it() not matched — intentional
+    `test("ATTACK: not an invariant", () => {})`,
+  ];
+  const hits = samples
+    .map((s) => Array.from(s.matchAll(re)).map((m) => m[1]))
+    .flat();
+  expect(hits).toEqual(["INV-01", "INV-02", "INV-03"]);
+});
+
+test("// INV-NN metadata comment regex matches line comments only", () => {
+  const re = /\/\/\s*(INV-\d+)\b/g;
+  const samples = [
+    `  // INV-03: Requester refund key before locktime`,
+    `//INV-02`,
+    `/* INV-01 */`, // block comment — still matches /* then // fails; documented behavior
+    `const s = "http://INV-99/url";`, // false positive guard: \b ensures INV-99 is a word boundary
+  ];
+  const hits = samples
+    .map((s) => Array.from(s.matchAll(re)).map((m) => m[1]))
+    .flat();
+  // /* INV-01 */ does NOT match `//` pattern, correctly.
+  // "http://INV-99/url" — `//` is followed by "INV-99" — this IS a false positive.
+  // Documenting current behavior: URLs in strings can false-positive I002.
+  // Mitigation: users don't typically reference INV-NN in URLs. If this
+  // becomes a problem, tighten the regex to require whitespace or line-start.
+  expect(hits).toContain("INV-03");
+  expect(hits).toContain("INV-02");
+  expect(hits).toContain("INV-99"); // known false-positive from URL
+});
+
+test("fn inv_NN_* regex matches Rust test functions", () => {
+  const re = /fn\s+inv_(\d+)_/g;
+  const samples = [
+    `fn inv_01_tampered_transcript_rejected() {}`,
+    `fn inv_02_preimage_protection() {}`,
+    `fn regular_test() {}`,
+    `pub fn inv_42_future() {}`,
+  ];
+  const hits = samples
+    .map((s) => Array.from(s.matchAll(re)).map((m) => m[1]))
+    .flat();
+  expect(hits).toEqual(["01", "02", "42"]);
+});
+
+test("repo-level lint passes on HEAD", async () => {
+  const violations = await mod.lint();
+  if (violations.length > 0) {
+    console.error("Violations:", violations);
+  }
+  expect(violations).toEqual([]);
+});