tamper-signal 1.2.0 → 1.5.0

package/AGENTS.md

@@ -35,9 +35,12 @@ These govern copy, code comments, commit messages, and UI text you produce:
 Requires Python 3.11+.
 
 ```bash
-pip install git+https://github.com/welovejeff/tamper-evident-verification.git
+pip install tamper-signal
 ```
 
+(Installing from source also works:
+`pip install git+https://github.com/welovejeff/tamper-evident-verification.git`)
+
 This provides the `receipts` CLI and the `tamper_signal` Python package.
 Verify: `receipts --help` exits 0. JavaScript-only project? Use step 1b and
 the JS equivalents; the two stacks produce interchangeable chains.
@@ -70,14 +73,21 @@ 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.
 
-## 2. Generate a signing keypair (once per project)
+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
-receipts keygen --out keys/
+receipts init
 ```
 
-Writes `keys/signing.key` (private, PEM; never commit) and `keys/signing.pub`
-(raw 32-byte hex; safe to commit). Add `keys/` and `*.key` to .gitignore now.
+Idempotent. Generates `keys/signing.key` (private, PEM; never commit) and
+`keys/signing.pub` (raw hex; safe to commit), adds `keys/` and `*.key` to
+.gitignore, creates `receipts/`, and prints exactly what it did. The pieces
+are also available separately (`receipts keygen --out keys/`).
 
 ## 3. Start the chain at the source export
 
@@ -121,9 +131,132 @@ receipts verify receipts/chain.json --pub keys/signing.pub --data path/to/dashbo
 
 Exit codes are the traffic light: **0 green, 1 red, 2 yellow**. `--data` is
 optional and checks the file the dashboard actually reads against the final
-receipt. In CI: fail the build on exit 1; surface exit 2 to a human rather
-than failing silently. `--warn-drift` additionally flags any control-totals
-movement across links (only for pipelines expected to preserve totals).
+receipt. `--warn-drift` additionally flags any control-totals movement across
+links (only for pipelines expected to preserve totals).
+
+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
+{
+  "verdict": "green | yellow | red",
+  "exit_code": 0,
+  "spec_version": "1.1",
+  "receipts": 3,
+  "transforms": 2,
+  "stages": ["source", "clean", "aggregate"],
+  "final_row_count": 304,
+  "caveats": ["..."],
+  "broken_link": {
+    "link": [1, 2],
+    "stage": "aggregate",
+    "expected_input_hash": "...",
+    "found_input_hash": "...",
+    "totals_delta": ["row_count 4987 -> 304 (-4683)"]
+  },
+  "data_mismatch": null,
+  "receipt_mismatch": null,
+  "report": ["human-legible lines"],
+  "anchor": ["anchor report lines; present only when --anchor is passed"]
+}
+```
+
+`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
+
+```yaml
+# .github/workflows/tamper-signal.yml
+name: tamper-signal
+on: [push]
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install tamper-signal
+      - name: Verify the receipt chain
+        run: |
+          set +e
+          receipts verify receipts/chain.json --json | tee verdict.json
+          code=$?
+          if [ "$code" = "2" ]; then
+            echo "::warning::The light is yellow, a human should look: $(python -c 'import json;print("; ".join(json.load(open("verdict.json"))["caveats"]))')"
+            exit 0
+          fi
+          exit $code
+```
+
+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
 
@@ -159,11 +292,48 @@ and badge.js beside it) and write one tag:
 Attributes mirror the options: `pub-key`, `watch`, `warn-drift`,
 `receipts-href`, `theme`.
 
-Static serving examples: Flask
-`app = Flask(__name__, static_folder="receipts", static_url_path="/receipts")`;
-FastAPI `app.mount("/receipts", StaticFiles(directory="receipts"))`; Express
-`app.use("/receipts", express.static("receipts"))`. A purely static site can
-copy `receipts/` into its public directory at build time.
+Prefer the one-call attach helpers; each serves the receipts directory AND
+the bundled browser assets, and returns a `snippet` to render once in the
+layout (it mounts the signal into `header`, falling back to `body`):
+
+```python
+# Flask
+from tamper_signal.flask_ext import attach
+signal = attach(app, receipts_dir="receipts/")   # then: {{ signal.snippet | safe }}
+
+# FastAPI
+from tamper_signal.fastapi_ext import attach
+signal = attach(app, receipts_dir="receipts/")
+```
+
+```js
+// Express (or any Connect-style router)
+import { tamperSignal } from "tamper-signal/express";
+const signal = tamperSignal(app, { receiptsDir: "receipts/" });
+// serve signal.snippet once in your layout
+```
+
+Next.js: copy `receipts/` into `public/receipts/` as part of the pipeline
+run (the simplest correct path; receipts are plain files), then mount with
+`<TamperSignal chain="/receipts/chain.json" />` from `tamper-signal/react`
+in a client component, or the `<tamper-signal>` element in any layout.
+
+Streamlit: `from tamper_signal.streamlit_ext import signal, verified_dataframe`.
+These verify SERVER-SIDE with the Python verifier and the pill says so;
+Streamlit cannot serve the receipts directory for the in-browser walk, and
+faking the stronger claim would violate rule 1.
+
+Every attach helper also serves the verification console at
+`<assets_prefix>/console` (e.g. `/tamper-signal/console`): the chain as an
+inspectable pipeline with the break pinned at the severed link, for the
+dashboard's builder and for auditors. Mention it to the user when handing
+over; it is the page to open when the light is anything but green.
+
+Manual fallback when no helper fits: serve the directory statically (Flask
+`static_folder="receipts"`, FastAPI `StaticFiles`, Express
+`express.static("receipts")`), or copy `receipts/` into the public dir of a
+static site at build time. For local development, `receipts serve` serves
+the directory on localhost with CORS open and caching off.
 
 Placement: the right end of the host header, after the host's own controls.
 The pill is intentionally dark and mono; do not restyle it to match the host
@@ -189,15 +359,44 @@ under `control_totals.numeric_sums` / `null_counts`.
 ## 8. The Data tab (when asked for table UI or views)
 
 The project's stance: a dashboard built on verified data should show the
-verified table, not just charts. If the user asks for the table UI, add a
-"Data" tab next to the charts that renders the final stage's output (the same
-file `--data` verifies), labeled with the current verdict. The design
-reference is `designs/03-data-tab.html` with notes in `designs/03-NOTES.md`;
-there is no packaged component yet, so build it in the host's own stack and
-say so honestly.
+verified table, not just charts. Two steps:
+
+1. After the pipeline runs, export the canonical table document:
+
+   ```bash
+   receipts export --chain receipts/chain.json --data path/to/dashboard_data.xlsx
+   ```
+
+   This writes `receipts/table.json` and refuses if the data does not match
+   the final receipt (the Data tab only ever shows attested data). Re-run it
+   whenever the pipeline runs, or the tab will honestly report a stale table.
+
+2. Mount the table (vendor `badge/table.js` beside badge.js, or import
+   `tamper-signal/table`):
+
+   ```html
+   <script type="module">
+     import { mountReceiptTable } from "/static/table.js";
+     mountReceiptTable(document.querySelector("#data-tab"), "/receipts/chain.json");
+   </script>
+   ```
+
+The component re-hashes the served document in the viewer's browser and
+compares it against the final receipt, so VERIFIED means the rows on screen
+are byte-for-byte the attested data. It renders its own states: green, yellow
+with caveats, chain broken (with the moved columns flagged), and "not the
+attested data" when table.json is stale or edited. Design reference:
+`designs/03-data-tab.html`.
 
 ## 9. Verify your work before reporting done
 
+Run `receipts doctor` first: it checks the Python version, that the private
+key exists and is not tracked by git, that .gitignore covers it, and that the
+chain verifies; pass `--url http://localhost:PORT/chain.json` to also confirm
+the receipts directory is reachable over HTTP. Every failure prints its fix.
+Exit 0 means the integration is healthy. Then confirm the user-visible
+surfaces:
+
 1. `receipts verify receipts/chain.json --pub keys/signing.pub` exits 0.
 2. Load the host page: the pill reads `VERIFIED · chain intact` (click it for
    the per-stage popover).
@@ -233,3 +432,5 @@ say so honestly.
 | `examples/chains/` | Committed known-good and known-broken demo chains |
 | `designs/` | Working HTML mockups for the signal, console, and Data tab |
 | `docs/MESSAGING.md` | Copy rules; the source of truth for any words you write |
+| `docs/solutions/` | Documented solutions to past problems (bugs, patterns, conventions), organized by category with YAML frontmatter (`module`, `tags`, `problem_type`); relevant when working in documented areas |
+| `CONCEPTS.md` | Shared domain vocabulary (entities, named processes, status concepts); relevant when orienting to the codebase |

package/README.md

@@ -2,9 +2,11 @@
 
 # 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.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.
 
-**Live demo:** [welovejeff.github.io/tamper-evident-verification](https://welovejeff.github.io/tamper-evident-verification/) re-verifies a real committed receipt chain in your browser: swap in a tampered chain or an untrusted key and watch the light catch it.
+**Live demo:** [tampersignal.com](https://tampersignal.com/) re-verifies a real committed receipt chain in your browser: swap in a tampered chain or an untrusted key and watch the light catch it.
 
 **Pointing a coding agent at this repo?** `AGENTS.md` is the full integration runbook: install, keygen, ingest, wrap transforms, mount the signal, verify. Tell your agent "add tamper signal" and it will find it.
 
@@ -26,15 +28,15 @@ The badge and the verifier reduce the whole chain to one state:
 
 *The inline status light: a small dark instrument in your dashboard's header. When the chain breaks, it reaches into the page and flags the exact metric that no longer descends from the source.*
 
-Honest status: all three verdicts are implemented in `receipts verify` and the browser badge. Yellow today covers two detectable caveats (a coverage gap in the receipt numbering, and signatures that only verify under the chain's embedded key rather than the key you trust) plus opt-in control-total drift via `--warn-drift`. The Data tab and console animations in this README are design previews of later interface tiers, built from the working mockups in `designs/`. The badge also renders a separate amber state ("could not load" or "verification unsupported in this browser"); that is a capability fallback that says nothing about the chain, not the yellow verdict.
+Honest status: all three verdicts are implemented in `receipts verify` and the browser badge. Yellow today covers two detectable caveats (a coverage gap in the receipt numbering, and signatures that only verify under the chain's embedded key rather than the key you trust) plus opt-in control-total drift via `--warn-drift`. The animations in this README are renders of the design mockups in `designs/`; the interfaces they depict have since shipped (`badge/light.js`, `badge/table.js`, `badge/console.js`). The badge also renders a separate amber state ("could not load" or "verification unsupported in this browser"); that is a capability fallback that says nothing about the chain, not the yellow verdict.
 
 ## 60-second quickstart
 
-Python 3.11+. Open source (MIT), `pip`-installable.
+Python 3.11+. Open source (MIT).
 
 ```bash
-git clone <this repo> && cd tamper-evident-verification
-pip install -e .
+pip install tamper-signal
+git clone https://github.com/welovejeff/tamper-evident-verification && cd tamper-evident-verification
 receipts demo
 ```
 
@@ -43,12 +45,14 @@ receipts demo
 ## CLI
 
 ```bash
-receipts keygen --out keys/
+receipts init                 # scaffold: keys, .gitignore safety, receipts dir (idempotent)
 receipts ingest sample_export.xlsx --origin "TikTok export, May 2026" --key keys/signing.key --out receipts/
 receipts verify receipts/chain.json --pub keys/signing.pub --data dashboard.xlsx
+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.
+`--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:
 
@@ -136,29 +140,40 @@ The pill expands to a popover: the per-stage table when green, the caveat list w
 
 Options on the fourth argument: `watch` (re-verify every N ms and pulse on transitions), `warnDrift`, `receiptsHref`, and `theme: "light"` so the pill stays the one foreign object on a dark host. `receipts demo` serves a live three-state example at `http://localhost:8000/badge/light.html`.
 
+One-call framework helpers serve the receipts directory and the browser files together and hand back the mounting snippet: `tamper_signal.flask_ext.attach(app)`, `tamper_signal.fastapi_ext.attach(app)`, and `tamperSignal(app)` from `tamper-signal/express`. Streamlit apps get a server-side-verified pill and table caption via `tamper_signal.streamlit_ext` (labeled as the weaker check it is).
+
 ## Dashboards should show their work
 
 We think any dashboard built on verified data should let you see the data. Not a tooltip, not an export-on-request: a Data tab, right next to the charts, showing the raw verified table the pretty numbers came from. If the chain is intact and the light is green, there is no reason to hide the rows, and if you find yourself wanting to hide them, that's worth sitting with. A chart asks you to believe; a table lets you check. Green light, open table: that's the whole standard.
 
+It ships: `receipts export` writes the canonical table document next to the chain (refusing data that does not match the final receipt), and `mountReceiptTable(el, "/receipts/chain.json")` from `badge/table.js` (npm: `tamper-signal/table`) renders it after re-hashing it in the viewer's browser against the final receipt. VERIFIED means the rows on screen are byte-for-byte the attested data; a stale or edited table.json renders dimmed under a "not the attested data" strip, and a broken chain flags the columns that moved at the break. Live demo: `badge/table.html`.
+
 ![The Data tab: the dashboard flips to a dark raw-table view where a broken chain is localized to the views column](docs/media/data-tab.gif)
 
 *Design preview: install the verification layer and your dashboard grows a Data tab. When the chain breaks, the break is localized to the column and total that no longer verify, right in the table.*
 
+## The console
+
+The light answers "is it fine?"; the console answers "where, exactly, and by how much?" `mountReceiptConsole(el, "/receipts/chain.json")` from `badge/console.js` (npm: `tamper-signal/console`) renders the chain as an inspectable pipeline: links carry the hash they proved, a break severs the link with the break card pinned at it, coverage gaps appear as ghost nodes at their position, and the event log mirrors `receipts verify` line for line. Every attach helper also serves it ready-made at `/tamper-signal/console`. Live demo: `badge/console.html`.
+
+![The verification console: a pipeline of signed receipts where a tampered stage severs the chain at the exact link](docs/media/console.gif)
+
+*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`.
-- **Verification console.** A devtools-for-data window: the receipt chain as an inspectable pipeline, an event log of verify runs, and the break pinned at the severed link.
-
-![The verification console: a pipeline of signed receipts where a tampered stage severs the chain at the exact link](docs/media/console.gif)
 
-*Design preview of the verification console: calm when green, surgical when red.*
 
 ## Relation to OpenLineage, dbt, and Great Expectations
 

package/badge/badge.js

@@ -24,7 +24,7 @@ export const SHORT = (h) => (h && h.length > 10 ? `${h.slice(0, 4)}...${h.slice(
 // --- Canonical JSON, byte-identical to tamper_signal/canonical.py's JCS output. ---
 // Leaves are strings, integers, booleans, or null (no floats). Object keys are
 // sorted; strings use JSON.stringify, whose escaping matches the Python side.
-function canonicalize(value) {
+export function canonicalize(value) {
   if (value === null) return "null";
   const t = typeof value;
   if (t === "boolean") return value ? "true" : "false";
@@ -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;