tamper-signal 1.4.0 → 1.5.0

package/AGENTS.md

@@ -73,6 +73,11 @@ same package: `tamper-signal/light`, `tamper-signal/badge`,
 `tamper-signal/element`, `tamper-signal/react`. JS reads .csv/.tsv/.json/
 .ndjson; only the Python side reads .xlsx.
 
+CI signing works here too: `TAMPER_SIGNAL_KEY` (PEM contents of the private
+key) wins over any key path, same semantics as the Python side (step 5).
+`tamper-signal verify --json` emits the same structured verdict as the
+Python CLI.
+
 ## 2. Scaffold the project (once)
 
 ```bash
@@ -129,8 +134,20 @@ optional and checks the file the dashboard actually reads against the final
 receipt. `--warn-drift` additionally flags any control-totals movement across
 links (only for pipelines expected to preserve totals).
 
-Add `--json` to get a structured verdict instead of the text report. Parse
-this rather than scraping text:
+Key rotation: `--pub` repeats. Old chains stay green while new receipts sign
+under a new key: `receipts verify chain.json --pub new.pub --pub old.pub`. A
+signature valid under any trusted key is trusted; the browser surfaces accept
+a list the same way (the `<tamper-signal>` element takes a space-separated
+`pub-key` list).
+
+CI signing: set `TAMPER_SIGNAL_KEY` to the PEM contents of the private key
+(a repo secret) and the wrapper, ingest, and export sign without a key file
+on disk. The env var wins over any `--key` path while set. The Node CLI
+(`tamper-signal ingest`) honors the same env var with the same precedence.
+
+Add `--json` to get a structured verdict instead of the text report (both
+CLIs: `receipts verify --json` and `tamper-signal verify --json` emit the
+same payload). Parse this rather than scraping text:
 
 ```json
 {
@@ -150,11 +167,21 @@ this rather than scraping text:
     "totals_delta": ["row_count 4987 -> 304 (-4683)"]
   },
   "data_mismatch": null,
-  "report": ["human-legible lines"]
+  "receipt_mismatch": null,
+  "report": ["human-legible lines"],
+  "anchor": ["anchor report lines; present only when --anchor is passed"]
 }
 ```
 
-`broken_link` and `data_mismatch` are null unless the verdict is red.
+`broken_link`, `data_mismatch`, and `receipt_mismatch` are null unless the
+verdict is red, and all three stay null when red comes from an anchor
+mismatch (the chain itself is intact; the reason is in `anchor` and
+`report`). `receipt_mismatch` lists receipt files that no longer match the
+sha256 chain.json records for them: a receipt was rewritten after the chain
+was. With `--anchor`, the `anchor` array is added and the anchor outcome is
+folded into `verdict`, `exit_code`, `caveats`, and `report` (a missing
+anchor turns a green run yellow; a mismatch turns it red), so the payload
+never contradicts itself.
 
 ### CI: verify the chain on every push
 
@@ -185,6 +212,52 @@ jobs:
 Exit 1 (red) fails the build; exit 2 (yellow) surfaces a warning annotation
 without failing.
 
+## 5b. Anchoring (optional, for disputes and audits)
+
+The local keypair is the day-to-day root of trust; its known gap is that
+whoever holds the key can re-sign a fresh chain. When existence-at-a-time
+matters (client disputes, audits), anchor the chain in the public Sigstore
+transparency log:
+
+```bash
+pip install "tamper-signal[anchor]"
+receipts anchor                       # browser login locally; automatic in GitHub Actions
+receipts verify receipts/chain.json --anchor
+```
+
+Agent note: run `receipts anchor` in CI (GitHub Actions and similar), where
+an ambient OIDC credential makes it non-interactive. Outside CI it opens a
+browser login and blocks until a human completes it; do not invoke it from
+an unattended session.
+
+The anchor covers receipt contents, not just names: chain.json records the
+sha256 of every receipt file, and `verify` enforces those hashes, so a
+receipt re-signed after anchoring is red even though chain.json itself did
+not change. Chains written before 1.5.0 carry no receipt hashes; anchoring
+them yields a yellow "anchor covers chain.json only" caveat until the
+pipeline re-runs.
+
+`anchor.json` (next to chain.json) records the Sigstore bundle plus the
+identity and issuer used; `verify --anchor` enforces that identity, reports
+the logged time on success, exits 2 when no anchor exists, and exits 1 when
+the chain changed after anchoring. `receipts anchor --json` emits the anchor
+record (identity, issuer, integrated time) as JSON for CI logs. An anchor
+made with `--staging` is rejected at verify time unless you pass
+`--anchor-staging`, so the anchor file cannot pick a weaker trust root. To
+pin whose anchor is acceptable instead of trusting the recorded one, pass
+`--anchor-identity` (and optionally `--anchor-issuer`); in CI that looks
+like:
+
+```bash
+receipts verify receipts/chain.json --anchor \
+  --anchor-identity "https://github.com/OWNER/REPO/.github/workflows/anchor.yml@refs/heads/main" \
+  --anchor-issuer "https://token.actions.githubusercontent.com"
+```
+
+Re-anchor after every pipeline run that changes the chain. Honest scope: an
+anchor proves this exact chain existed at the logged time under the recorded
+identity, nothing more.
+
 ## 6. Add the signal to the host UI
 
 With a bundler, import straight from the npm package

package/README.md

@@ -2,7 +2,7 @@
 
 # The light is green, the data is clean.
 
-[![PyPI](https://img.shields.io/pypi/v/tamper-signal)](https://pypi.org/project/tamper-signal/) [![npm](https://img.shields.io/npm/v/tamper-signal)](https://www.npmjs.com/package/tamper-signal) [![Socket Badge (npm)](https://badge.socket.dev/npm/package/tamper-signal/1.2.0)](https://socket.dev/npm/package/tamper-signal/overview/1.2.0) [![Socket Badge (PyPI)](https://badge.socket.dev/pypi/package/tamper-signal/1.2.0)](https://socket.dev/pypi/package/tamper-signal/overview/1.2.0) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/tamper-signal)](https://pypi.org/project/tamper-signal/) [![npm](https://img.shields.io/npm/v/tamper-signal)](https://www.npmjs.com/package/tamper-signal) [![Socket Badge (npm)](https://badge.socket.dev/npm/package/tamper-signal/1.5.0)](https://socket.dev/npm/package/tamper-signal/overview/1.4.0) [![Socket Badge (PyPI)](https://badge.socket.dev/pypi/package/tamper-signal/1.5.0)](https://socket.dev/pypi/package/tamper-signal/overview/1.4.0) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 Your social team exports a month of TikTok performance data. Someone vibe-codes a dashboard on top of it with an AI assistant in an afternoon. It looks great. Then a transform silently drops 22 rows, or the model hallucinates an aggregation, and the numbers in front of your boss are wrong. Nothing in that workflow catches it. This is the missing verification layer: every stage of the pipeline signs a receipt for what went in and what came out, and one command (or a badge on the dashboard itself) tells you whether the chain is intact, or exactly where it broke and by how much.
 
@@ -52,7 +52,7 @@ receipts doctor               # integration self-check with actionable fixes
 receipts serve                # serve receipts/ on localhost with CORS (dev only)
 ```
 
-`ingest` and `verify --data` accept .xlsx, .csv, .tsv, .json (array of objects), and .ndjson; the semantic hash is identical across formats, so an xlsx ingest verifies against a CSV copy of the same data. `verify` exits with the traffic light: 0 green, 1 red, 2 yellow (verifies, with caveats). Add `--warn-drift` to also flag any control-totals movement across links as a caveat; it is off by default because filters and aggregations legitimately move totals. `--json` emits a structured verdict (schema in `AGENTS.md`) for CI and coding agents.
+`--pub` repeats for key rotation (any trusted key verifies), and `TAMPER_SIGNAL_KEY` can carry the PEM private key in CI so no key file touches disk. `ingest` and `verify --data` accept .xlsx, .csv, .tsv, .json (array of objects), and .ndjson; the semantic hash is identical across formats, so an xlsx ingest verifies against a CSV copy of the same data. `verify` exits with the traffic light: 0 green, 1 red, 2 yellow (verifies, with caveats). Add `--warn-drift` to also flag any control-totals movement across links as a caveat; it is off by default because filters and aggregations legitimately move totals. `--json` emits a structured verdict (schema in `AGENTS.md`) for CI and coding agents.
 
 Transforms record their own receipts by wrapping any list-of-dicts to list-of-dicts function:
 
@@ -160,16 +160,19 @@ The light answers "is it fine?"; the console answers "where, exactly, and by how
 
 *The verification console: calm when green, surgical when red.*
 
+## Anchoring (optional)
+
+`pip install "tamper-signal[anchor]"`, then `receipts anchor` signs the exact bytes of chain.json into the public Sigstore transparency log under your OIDC identity (browser login locally, automatic in GitHub Actions). Because chain.json records the sha256 of every receipt file, the anchor covers the receipts themselves, not just their names. `receipts verify --anchor` then proves this exact chain, receipts included, existed at the logged time, independent of the signing key, closing the "whoever holds the key can quietly re-sign everything" gap for the moments that matter. A missing anchor is a yellow caveat; a chain that changed after anchoring is red.
+
 ## What this proves, and what it doesn't
 
 This proves **continuity, not correctness**. It can't tell you the data is right, but it can prove nobody changed it. The chain shows the dashboard numbers descend from the ingested export through a known sequence of code, and it locates the exact stage where a number changed unexpectedly. If the source export is itself wrong, the chain faithfully verifies wrong numbers. It is not a data-quality tool.
 
-Also worth knowing: the signing key lives on your machine, and today that local Ed25519 keypair is the whole root of trust. Anyone holding the key can sign a fresh, internally consistent chain. External anchoring (below) is what closes that gap.
+Also worth knowing: the signing key lives on your machine, and day to day that local Ed25519 keypair is the root of trust. Anyone holding the key can sign a fresh, internally consistent chain; anchoring (above) is what closes that gap when it matters.
 
 ## Roadmap
 
 - **Richer yellow taxonomy.** Yellow currently detects coverage gaps, unrecognized signing keys, and opt-in totals drift. Distinct severities and smarter drift heuristics are open questions (see `designs/01-NOTES.md`).
-- **External anchoring.** Sigstore transparency logs or RFC 3161 timestamps, so a chain can't be silently re-signed after the fact. The attachment points are already marked `FUTURE:` in `tamper_signal/keys.py` and `tamper_signal/receipts.py`.
 
 
 ## Relation to OpenLineage, dbt, and Great Expectations

package/badge/badge.js

@@ -134,18 +134,34 @@ export async function verifySignature(receipt, pubKeyHex) {
 // could make the viewer's browser fetch arbitrary / cross-origin resources.
 const SAFE_RECEIPT_NAME = /^[A-Za-z0-9._-]+$/;
 
+async function sha256Hex(buf) {
+  const digest = await crypto.subtle.digest("SHA-256", buf);
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
 export async function loadChain(chainUrl) {
   const base = new URL(chainUrl, window.location.href);
   const chain = await (await fetch(base)).json();
+  // Newer chains record each receipt file's sha256; enforcing it here mirrors
+  // the CLI verifiers, so an anchored chain.json transitively witnesses the
+  // receipt contents. Older chains (no receipt_hashes) skip the check.
+  const recorded =
+    chain.receipt_hashes && typeof chain.receipt_hashes === "object" ? chain.receipt_hashes : null;
+  const canHash = Boolean(recorded && globalThis.crypto && crypto.subtle);
   const receipts = [];
+  const receiptMismatches = [];
   for (const name of chain.receipts || []) {
     if (typeof name !== "string" || !SAFE_RECEIPT_NAME.test(name)) {
       throw new Error("unsafe receipt name in chain: " + name);
     }
     const url = new URL(name, base);
-    receipts.push(await (await fetch(url)).json());
+    // Fetch raw bytes so the receipt hashes exactly as it sits on disk, then
+    // parse the same bytes.
+    const buf = await (await fetch(url)).arrayBuffer();
+    if (canHash && (await sha256Hex(buf)) !== recorded[name]) receiptMismatches.push(name);
+    receipts.push(JSON.parse(new TextDecoder().decode(buf)));
   }
-  return { chain, receipts };
+  return { chain, receipts, receiptMismatches };
 }
 
 // Gaps in the generated NNN_ receipt numbering, mirroring tamper_signal/receipts.py's
@@ -176,15 +192,19 @@ export function coverageGaps(receiptNames) {
 // embedded in chain.json means the chain is internally consistent but vouched
 // for by a key the caller does not trust (yellow), not broken (red).
 export async function checkSignatures(receipts, trustedKeyHex, chainKeyHex) {
+  // trustedKeyHex may be a single key or a list (key rotation). This inlines
+  // _as_trusted_keys (tamper_signal/receipts.py) / asTrustedKeys
+  // (node/receipts.js); update all three in lockstep.
+  const trusted = (Array.isArray(trustedKeyHex) ? trustedKeyHex : [trustedKeyHex]).filter(Boolean);
   let valid = true;
   let unrecognized = false;
-  const useFallback = chainKeyHex && chainKeyHex !== trustedKeyHex;
+  const useFallback = chainKeyHex && !trusted.includes(chainKeyHex);
   for (const r of receipts) {
     let ok = false;
-    try {
-      ok = await verifySignature(r, trustedKeyHex);
-    } catch (_e) {
-      ok = false;
+    for (const key of trusted) {
+      try {
+        if (await verifySignature(r, key)) { ok = true; break; }
+      } catch (_e) { /* malformed key or signature: try the next */ }
     }
     if (ok) continue;
     if (useFallback) {
@@ -239,9 +259,9 @@ export function evaluate(receipts) {
 // legitimately move totals).
 export async function verifyReceipts(chainUrl, pubKeyHex, opts = {}) {
   const verifiedAt = new Date().toISOString();
-  let chain, receipts;
+  let chain, receipts, receiptMismatches;
   try {
-    ({ chain, receipts } = await loadChain(chainUrl));
+    ({ chain, receipts, receiptMismatches } = await loadChain(chainUrl));
   } catch (_e) {
     return { state: "unverifiable", reason: "could not load chain", caveats: [], verifiedAt };
   }
@@ -275,6 +295,14 @@ export async function verifyReceipts(chainUrl, pubKeyHex, opts = {}) {
   summary.finalRows = totalsOf(receipts[receipts.length - 1]).row_count;
   summary.transforms = receipts.filter((r) => r.kind === "transform_receipt").length;
 
+  if (receiptMismatches && receiptMismatches.length) {
+    return {
+      ...summary,
+      state: "red",
+      reason: `receipt file mismatch at ${receiptMismatches.join(", ")}`,
+    };
+  }
+
   const trustedKey = pubKeyHex || chain.public_key;
   const sigResult = await checkSignatures(receipts, trustedKey, chain.public_key);
   summary.signaturesValid = sigResult.valid;

package/badge/element.js

@@ -7,7 +7,8 @@
 //
 // Attributes (all but `chain` optional):
 //   chain          URL of chain.json (required; nothing mounts without it)
-//   pub-key        trusted public key hex; defaults to the chain's embedded key
+//   pub-key        trusted public key hex (space or comma separated list for
+//                  key rotation); defaults to the chain's embedded key
 //   watch          re-verify every N milliseconds
 //   warn-drift     present = flag any control-totals movement across links
 //   receipts-href  href for the popover's "view receipts" link
@@ -61,7 +62,9 @@ class TamperSignalElement extends HTMLElement {
     const chain = this.getAttribute("chain");
     if (!chain) return; // nothing to verify yet; attribute may arrive later
     const watch = Number(this.getAttribute("watch"));
-    this._handle = mountTamperSignal(this, chain, this.getAttribute("pub-key") || undefined, {
+    const pubAttr = (this.getAttribute("pub-key") || "").trim();
+    const pubKeys = pubAttr ? pubAttr.split(/[\s,]+/) : undefined;
+    this._handle = mountTamperSignal(this, chain, pubKeys, {
       watch: Number.isFinite(watch) && watch > 0 ? watch : undefined,
       warnDrift: this.hasAttribute("warn-drift"),
       receiptsHref: this.getAttribute("receipts-href") || undefined,

package/badge/light.js

@@ -5,6 +5,7 @@
 // rendering layer differs. No build step, no framework.
 //
 // mountTamperSignal(hostEl, chainUrl, pubKeyHex?, opts?)
+//   pubKeyHex: a trusted key hex, or an array of them (key rotation).
 //   Same argument contract as renderReceiptBadge, with the light appended to
 //   hostEl rather than replacing its contents. Returns a handle:
 //   { el, ready, refresh(), destroy(), getState(), setOpen(open) }.
@@ -103,6 +104,13 @@ function injectLightStyles() {
     color:var(--lr-text);font:12px/1.55 inherit;font-family:inherit;text-align:left;
     box-shadow:0 16px 48px rgba(4,8,14,0.45);z-index:2147483000;display:none}
   .lr-light .lr-pop.lr-open{display:block}
+  /* On narrow screens the pill can sit anywhere in a wrapped header, so an
+     anchored popover clips at the viewport edge; pin it as a bottom sheet. */
+  @media (max-width: 600px){
+    .lr-light .lr-pop{position:fixed;left:10px;right:10px;top:auto;bottom:14px;
+      width:auto;max-width:none}
+    .lr-light .lr-pop::before{display:none}
+  }
   .lr-light .lr-pop-head{display:flex;flex-wrap:wrap;align-items:baseline;gap:4px 8px;background:var(--lr-chrome);
     border-bottom:1px solid var(--lr-border);border-radius:10px 10px 0 0;padding:9px 14px;font-size:11px}
   .lr-light .lr-wordmark{color:var(--lr-dim);letter-spacing:1px}
@@ -190,7 +198,8 @@ function shortCaveatTag(caveats) {
 
 export function mountTamperSignal(hostEl, chainUrl, pubKeyHex, opts) {
   // Allow mountTamperSignal(el, url, {watch: ...}) without a key argument.
-  if (pubKeyHex && typeof pubKeyHex === "object") {
+  // Arrays are trusted keysets (rotation), not options.
+  if (pubKeyHex && typeof pubKeyHex === "object" && !Array.isArray(pubKeyHex)) {
     opts = pubKeyHex;
     pubKeyHex = undefined;
   }

package/node/cli.js

@@ -21,6 +21,9 @@ import {
   buildSourceManifest,
   readChain,
   readReceipt,
+  receiptFileHashes,
+  stageNameOf,
+  totalsOf,
   verifyChain,
   writeChain,
   writeReceipt,
@@ -34,7 +37,7 @@ commands:
   ingest <file> --origin "..." [--key keys/signing.key] [--out receipts/]
                                              create a signed source manifest
                                              (.csv, .tsv, .json, .ndjson)
-  verify <chain.json> [--pub key.pub] [--data <file>] [--warn-drift]
+  verify <chain.json> [--pub key.pub ...] [--data <file>] [--warn-drift] [--json]
                                              verify a chain (exit 0 green, 1 red, 2 yellow)
 `;
 
@@ -63,6 +66,10 @@ function cmdIngest(args) {
   }
   const raw = readFileSync(file);
   const records = loadRecords(file);
+  if (process.env.TAMPER_SIGNAL_KEY) {
+    // The env var silently outranks --key; say so where it matters.
+    console.error("Signing with TAMPER_SIGNAL_KEY from the environment (overrides --key)");
+  }
   const privateKey = loadPrivateKey(values.key);
   const manifest = buildSourceManifest({
     filename: basename(file),
@@ -89,9 +96,10 @@ function cmdVerify(args) {
     args,
     allowPositionals: true,
     options: {
-      pub: { type: "string" },
+      pub: { type: "string", multiple: true },
       data: { type: "string" },
       "warn-drift": { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
     },
   });
   const chainPath = positionals[0];
@@ -110,8 +118,17 @@ function cmdVerify(args) {
   }
 
   const chainKey = chain.public_key;
-  const publicHex = values.pub ? loadPublicKeyHex(values.pub) : chainKey;
-  if (!publicHex) {
+  const publicHex = values.pub?.length ? values.pub.map(loadPublicKeyHex) : chainKey;
+  if (Array.isArray(publicHex)) {
+    // An empty key file must not silently shrink the trusted set: the
+    // filtered-out key would fall back to the chain-embedded key instead.
+    const empty = values.pub.filter((path, i) => !publicHex[i]);
+    if (empty.length) {
+      console.error(`Empty public key file passed to --pub: ${empty.join(", ")}`);
+      return 1;
+    }
+  }
+  if (!publicHex || (Array.isArray(publicHex) && !publicHex.length)) {
     console.error("No public key: pass --pub or embed one in chain.json");
     return 1;
   }
@@ -124,13 +141,40 @@ function cmdVerify(args) {
     dataTotals = controlTotals(records);
   }
 
+  // Chains that record receipt hashes get them enforced; older chains skip.
+  const recordedHashes =
+    chain.receipt_hashes && typeof chain.receipt_hashes === "object" ? chain.receipt_hashes : null;
+  const actualHashes = recordedHashes ? receiptFileHashes(chainDir, chain.receipts ?? []) : null;
+
   const result = verifyChain(receipts, publicHex, dataHash, dataTotals, {
     chainPublicHex: chainKey,
     receiptNames: chain.receipts ?? [],
     warnDrift: values["warn-drift"],
+    recordedHashes,
+    actualHashes,
   });
-  for (const line of result.lines) console.log(line);
-  return { green: 0, red: 1, yellow: 2 }[result.verdict];
+  const code = { green: 0, red: 1, yellow: 2 }[result.verdict];
+  if (values.json) {
+    // Same payload shape as the Python CLI's verify --json (AGENTS.md step 5).
+    const payload = {
+      verdict: result.verdict,
+      exit_code: code,
+      spec_version: chain.spec_version ?? null,
+      receipts: receipts.length,
+      transforms: receipts.filter((r) => r.kind === "transform_receipt").length,
+      stages: receipts.map(stageNameOf),
+      final_row_count: receipts.length ? (totalsOf(receipts[receipts.length - 1]).row_count ?? null) : null,
+      caveats: result.caveats,
+      broken_link: result.brokenLinkDetail,
+      data_mismatch: result.dataMismatch,
+      receipt_mismatch: result.receiptMismatch,
+      report: result.lines,
+    };
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    for (const line of result.lines) console.log(line);
+  }
+  return code;
 }
 
 const [, , command, ...rest] = process.argv;

package/node/keys.js

@@ -46,8 +46,11 @@ export function generateKeys(outDir) {
   return { privatePath, publicPath };
 }
 
+// When TAMPER_SIGNAL_KEY is set, its contents (the PEM text) are used instead
+// of the file, so CI pipelines can sign without a key file on disk.
 export function loadPrivateKey(path) {
-  return createPrivateKey(readFileSync(path));
+  const env = process.env.TAMPER_SIGNAL_KEY;
+  return createPrivateKey(env || readFileSync(path));
 }
 
 export function loadPublicKeyHex(path) {

package/node/receipts.js

@@ -156,9 +156,27 @@ export function readChain(chainPath) {
   return JSON.parse(readFileSync(chainPath, "utf-8"));
 }
 
+export function receiptFileHashes(chainDir, receiptFiles) {
+  // sha256 of each receipt file's raw bytes, keyed by filename.
+  const out = {};
+  for (const name of receiptFiles) {
+    out[name] = createHash("sha256").update(readFileSync(join(chainDir, name))).digest("hex");
+  }
+  return out;
+}
+
 export function writeChain(chainDir, receiptFiles, publicHex) {
+  // chain.json records the sha256 of each receipt file so it commits to the
+  // receipt contents, not just their names: anchoring chain.json then
+  // transitively witnesses every receipt. The receipt files must already be
+  // on disk (every caller writes receipts before the chain).
   mkdirSync(chainDir, { recursive: true });
-  const chain = { spec_version: SPEC_VERSION, public_key: publicHex, receipts: receiptFiles };
+  const chain = {
+    spec_version: SPEC_VERSION,
+    public_key: publicHex,
+    receipts: receiptFiles,
+    receipt_hashes: receiptFileHashes(chainDir, receiptFiles),
+  };
   const path = join(chainDir, CHAIN_FILENAME);
   writeFileSync(path, JSON.stringify(chain, null, 2) + "\n");
   return path;
@@ -220,11 +238,37 @@ const short = (value) =>
       ? value
       : `${value.slice(0, 4)}...${value.slice(-2)}`;
 
+// Mirrors _as_trusted_keys in tamper_signal/receipts.py; badge/badge.js
+// checkSignatures inlines the same rule -- update all three in lockstep when
+// the normalization changes.
+function asTrustedKeys(publicHex) {
+  if (publicHex === null || publicHex === undefined) return [];
+  return (Array.isArray(publicHex) ? publicHex : [publicHex]).filter(Boolean);
+}
+
 // Mirrors tamper_signal/receipts.py verify_chain, including the yellow
-// verdict. Returns { ok, verdict, caveats, lines, brokenLink }.
+// verdict. Returns { ok, verdict, caveats, lines, brokenLink, brokenLinkDetail,
+// dataMismatch, receiptMismatch }.
 export function verifyChain(receipts, publicHex, dataSemanticHash = null, dataTotals = null, options = {}) {
-  const { chainPublicHex = null, receiptNames = null, warnDrift = false } = options;
-  const result = { ok: true, verdict: "green", caveats: [], lines: [], brokenLink: null };
+  const {
+    chainPublicHex = null,
+    receiptNames = null,
+    warnDrift = false,
+    recordedHashes = null,
+    actualHashes = null,
+  } = options;
+  // publicHex may be a single trusted key or a list (key rotation).
+  const trusted = asTrustedKeys(publicHex);
+  const result = {
+    ok: true,
+    verdict: "green",
+    caveats: [],
+    lines: [],
+    brokenLink: null,
+    brokenLinkDetail: null,
+    dataMismatch: null,
+    receiptMismatch: null,
+  };
   const fail = (...lines) => {
     result.ok = false;
     result.verdict = "red";
@@ -236,11 +280,29 @@ export function verifyChain(receipts, publicHex, dataSemanticHash = null, dataTo
     return result;
   }
 
-  // 1) Signatures, trusted key first, chain key as fallback.
+  // 0) Receipt files against the hashes chain.json records. This is what
+  // lets an anchored chain.json transitively witness receipt contents.
+  if (recordedHashes !== null && actualHashes !== null) {
+    const mismatched = (receiptNames ?? []).filter(
+      (name) => actualHashes[name] !== recordedHashes[name]
+    );
+    if (mismatched.length) {
+      result.receiptMismatch = mismatched;
+      for (const name of mismatched) {
+        fail(
+          `✗ RECEIPT FILE MISMATCH: ${name} does not match the hash ` +
+            "recorded in chain.json; the receipt was rewritten after the chain was"
+        );
+      }
+      return result;
+    }
+  }
+
+  // 1) Signatures, trusted keys first, chain key as fallback.
   const unrecognized = [];
-  const useFallback = Boolean(chainPublicHex) && chainPublicHex !== publicHex;
+  const useFallback = Boolean(chainPublicHex) && !trusted.includes(chainPublicHex);
   receipts.forEach((receipt, index) => {
-    if (verifySignature(receipt, publicHex)) return;
+    if (trusted.some((key) => verifySignature(receipt, key))) return;
     if (useFallback && verifySignature(receipt, chainPublicHex)) {
       unrecognized.push(index);
       return;
@@ -257,9 +319,10 @@ export function verifyChain(receipts, publicHex, dataSemanticHash = null, dataTo
         return "<malformed key>";
       }
     };
+    const fingerprints = trusted.map(fp).join(", ") || "(none)";
     result.caveats.push(
       `unrecognized signing key: ${unrecognized.length} receipt(s) (${stages}) verify under ` +
-        `the chain's embedded key ${fp(chainPublicHex)}, not the trusted key ${fp(publicHex)}`
+        `the chain's embedded key ${fp(chainPublicHex)}, not any of the ${trusted.length} trusted key(s) (${fingerprints})`
     );
   }
 
@@ -270,6 +333,13 @@ export function verifyChain(receipts, publicHex, dataSemanticHash = null, dataTo
     if (found !== expected) {
       result.brokenLink = index;
       const delta = totalsDelta(totalsOf(receipts[index - 1]), totalsOf(receipts[index]));
+      result.brokenLinkDetail = {
+        link: [index - 1, index],
+        stage: stageNameOf(receipts[index]),
+        expected_input_hash: expected,
+        found_input_hash: found,
+        totals_delta: delta,
+      };
       fail(
         `✗ CHAIN BROKEN at link ${index - 1} -> ${index} (${stageNameOf(receipts[index])})`,
         `  expected input hash ${short(expected)}  (output of ${stageNameOf(receipts[index - 1])})`,
@@ -286,6 +356,12 @@ export function verifyChain(receipts, publicHex, dataSemanticHash = null, dataTo
     const expected = outputHashOf(final);
     if (dataSemanticHash !== expected) {
       const delta = dataTotals !== null ? totalsDelta(totalsOf(final), dataTotals) : null;
+      result.dataMismatch = {
+        stage: stageNameOf(final),
+        expected_output_hash: expected,
+        found_data_hash: dataSemanticHash,
+        totals_delta: delta,
+      };
       fail(
         `✗ DATA MISMATCH against final receipt (${stageNameOf(final)})`,
         `  expected output hash ${short(expected)}`,

package/node/test/badge.test.js

@@ -0,0 +1,107 @@
+// Executes the browser verification core (badge/badge.js) under Node's
+// WebCrypto. The static drift test proves the shipped copies are byte-equal;
+// this one actually runs the logic: multi-key rotation, the yellow fallback,
+// and the receipt-hash enforcement that makes anchoring meaningful.
+
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import { evidenceHash, semanticHash } from "../canonical.js";
+import { generateKeys, loadPrivateKey, publicHexFromPrivate } from "../keys.js";
+import { loadCsv } from "../load.js";
+import {
+  SOURCE_RECEIPT_NAME,
+  buildSourceManifest,
+  readReceipt,
+  writeChain,
+  writeReceipt,
+} from "../receipts.js";
+
+// badge.js expects a browser; give it just enough of one before importing.
+globalThis.window = { location: { href: "http://localhost/" }, crypto: globalThis.crypto };
+
+const { verifyReceipts, ed25519Available } = await import("../../badge/badge.js");
+
+const CSV = "date,campaign_name,spend_usd\n2026-05-01,a,10.50\n2026-05-02,b,20.00\n";
+
+function buildChainDir() {
+  const dir = mkdtempSync(join(tmpdir(), "tamper-signal-badge-"));
+  const keys = join(dir, "keys");
+  const chainDir = join(dir, "receipts");
+  generateKeys(keys);
+  const privateKey = loadPrivateKey(join(keys, "signing.key"));
+  const publicHex = publicHexFromPrivate(privateKey);
+  const csvPath = join(dir, "export.csv");
+  writeFileSync(csvPath, CSV);
+  const records = loadCsv(csvPath);
+  const manifest = buildSourceManifest({
+    filename: "export.csv",
+    evidenceHash: evidenceHash(Buffer.from(CSV)),
+    byteSize: CSV.length,
+    declaredOrigin: "badge test",
+    semanticHash: semanticHash(records),
+    records,
+    privateKey,
+  });
+  writeReceipt(chainDir, SOURCE_RECEIPT_NAME, manifest);
+  writeChain(chainDir, [SOURCE_RECEIPT_NAME], publicHex);
+  return { chainDir, publicHex };
+}
+
+function serve(chainDir) {
+  // Route badge.js's fetch() calls to the files on disk, by basename.
+  globalThis.fetch = async (url) => {
+    const name = decodeURIComponent(String(url).split("/").pop());
+    const buf = readFileSync(join(chainDir, name));
+    return {
+      json: async () => JSON.parse(buf.toString("utf-8")),
+      arrayBuffer: async () => buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength),
+    };
+  };
+}
+
+// Node ships WebCrypto Ed25519 from 18 on, but gate anyway: where it is
+// missing these tests prove nothing and should skip loudly, not fail.
+const available = await ed25519Available();
+
+test("browser core: green under the chain key and a rotated keyset", { skip: !available }, async () => {
+  const { chainDir, publicHex } = buildChainDir();
+  serve(chainDir);
+  assert.equal((await verifyReceipts("chain.json")).state, "green");
+  assert.equal((await verifyReceipts("chain.json", publicHex)).state, "green");
+  assert.equal((await verifyReceipts("chain.json", [publicHex])).state, "green");
+
+  const otherDir = mkdtempSync(join(tmpdir(), "tamper-signal-badge-rot-"));
+  generateKeys(otherDir);
+  const otherHex = publicHexFromPrivate(loadPrivateKey(join(otherDir, "signing.key")));
+  assert.equal((await verifyReceipts("chain.json", [otherHex, publicHex])).state, "green");
+
+  const yellow = await verifyReceipts("chain.json", [otherHex]);
+  assert.equal(yellow.state, "yellow");
+  assert.match(yellow.caveats[0], /unrecognized signing key/);
+});
+
+test("browser core: receipt rewritten after the chain is red", { skip: !available }, async () => {
+  const { chainDir } = buildChainDir();
+  serve(chainDir);
+  const receipt = readReceipt(chainDir, SOURCE_RECEIPT_NAME);
+  receipt.semantic_hash = "0".repeat(64);
+  writeReceipt(chainDir, SOURCE_RECEIPT_NAME, receipt);
+
+  const result = await verifyReceipts("chain.json");
+  assert.equal(result.state, "red");
+  assert.match(result.reason, /receipt file mismatch/);
+});
+
+test("browser core: chains without receipt hashes still verify", { skip: !available }, async () => {
+  const { chainDir } = buildChainDir();
+  serve(chainDir);
+  const chainPath = join(chainDir, "chain.json");
+  const chain = JSON.parse(readFileSync(chainPath, "utf-8"));
+  delete chain.receipt_hashes; // chains written before 1.5.0
+  writeFileSync(chainPath, JSON.stringify(chain, null, 2) + "\n");
+  assert.equal((await verifyReceipts("chain.json")).state, "green");
+});

package/node/test/chain.test.js

@@ -2,7 +2,7 @@
 // verify green; tamper -> red; foreign input -> ChainTailMismatch.
 
 import assert from "node:assert/strict";
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { test } from "node:test";
@@ -15,6 +15,7 @@ import {
   buildSourceManifest,
   loadReceipts,
   readReceipt,
+  receiptFileHashes,
   verifyChain,
   writeChain,
   writeReceipt,
@@ -95,3 +96,85 @@ test("foreign input is refused before the transform runs", async () => {
   await assert.rejects(step([{ not: "the chain tail" }]), ChainTailMismatch);
   assert.equal(ran, false);
 });
+
+test("rotated trusted-key sets verify chains signed under the old key", async () => {
+  const { chainDir, publicHex } = setup();
+  const otherDir = mkdtempSync(join(tmpdir(), "tamper-signal-rot-"));
+  generateKeys(otherDir);
+  const newHex = publicHexFromPrivate(loadPrivateKey(join(otherDir, "signing.key")));
+
+  const receipts = loadReceipts(chainDir);
+  // New + old trusted: green. New only (no fallback): red.
+  assert.equal(verifyChain(receipts, [newHex, publicHex]).verdict, "green");
+  assert.equal(verifyChain(receipts, [newHex]).verdict, "red");
+});
+
+test("writeChain records a sha256 for every receipt file", () => {
+  const { chainDir } = setup();
+  const chain = JSON.parse(readFileSync(join(chainDir, "chain.json"), "utf-8"));
+  assert.deepEqual(Object.keys(chain.receipt_hashes), chain.receipts);
+  for (const hash of Object.values(chain.receipt_hashes)) assert.match(hash, /^[0-9a-f]{64}$/);
+});
+
+test("receipt rewritten after the chain is a red receipt-file mismatch", () => {
+  const { chainDir, publicHex } = setup();
+  const receipt = readReceipt(chainDir, SOURCE_RECEIPT_NAME);
+  receipt.semantic_hash = "0".repeat(64);
+  writeReceipt(chainDir, SOURCE_RECEIPT_NAME, receipt);
+
+  const chain = JSON.parse(readFileSync(join(chainDir, "chain.json"), "utf-8"));
+  const result = verifyChain(loadReceipts(chainDir), publicHex, null, null, {
+    chainPublicHex: chain.public_key,
+    receiptNames: chain.receipts,
+    recordedHashes: chain.receipt_hashes,
+    actualHashes: receiptFileHashes(chainDir, chain.receipts),
+  });
+  assert.equal(result.verdict, "red");
+  assert.deepEqual(result.receiptMismatch, [SOURCE_RECEIPT_NAME]);
+  assert.ok(result.lines[0].includes("RECEIPT FILE MISMATCH"));
+});
+
+test("unrecognized signing key with a trusted set is yellow and names the keyset", () => {
+  const { chainDir, publicHex } = setup();
+  const otherDir = mkdtempSync(join(tmpdir(), "tamper-signal-rot-"));
+  generateKeys(otherDir);
+  const newHex = publicHexFromPrivate(loadPrivateKey(join(otherDir, "signing.key")));
+
+  const receipts = loadReceipts(chainDir);
+  // Verifies under the chain-embedded key but not the trusted set: yellow.
+  const result = verifyChain(receipts, [newHex], null, null, { chainPublicHex: publicHex });
+  assert.equal(result.verdict, "yellow");
+  assert.match(result.caveats[0], /1 trusted key/);
+});
+
+test("CLI verify --json emits the machine-readable verdict", async () => {
+  const { execFileSync } = await import("node:child_process");
+  const { fileURLToPath } = await import("node:url");
+  const { chainDir } = setup();
+  const cli = fileURLToPath(new URL("../cli.js", import.meta.url));
+  const out = execFileSync(process.execPath, [cli, "verify", join(chainDir, "chain.json"), "--json"], {
+    encoding: "utf-8",
+  });
+  const payload = JSON.parse(out);
+  assert.equal(payload.verdict, "green");
+  assert.equal(payload.exit_code, 0);
+  assert.deepEqual(payload.stages, ["source"]);
+  assert.equal(payload.receipt_mismatch, null);
+  assert.ok(Array.isArray(payload.report));
+});
+
+test("TAMPER_SIGNAL_KEY env supplies the signing key", () => {
+  const dir = mkdtempSync(join(tmpdir(), "tamper-signal-env-"));
+  generateKeys(dir);
+  const pem = readFileSync(join(dir, "signing.key"), "utf-8");
+  // Expected value comes from the FILE before the env override exists, so the
+  // assertion really compares env-loading against file-loading.
+  const expected = publicHexFromPrivate(loadPrivateKey(join(dir, "signing.key")));
+  process.env.TAMPER_SIGNAL_KEY = pem;
+  try {
+    const key = loadPrivateKey(join(dir, "missing.key"));
+    assert.equal(publicHexFromPrivate(key), expected);
+  } finally {
+    delete process.env.TAMPER_SIGNAL_KEY;
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tamper-signal",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Signed receipts for vibe-coded data pipelines. Proves nobody changed your data, and shows the exact link if they did.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "AGENTS.md"
   ],
   "scripts": {
-    "test": "node --test \"node/test/*.test.js\""
+    "test": "node --test node/test/badge.test.js node/test/canonical.test.js node/test/chain.test.js node/test/interop.test.js node/test/express.test.js"
   },
   "engines": {
     "node": ">=18.17"