tamper-signal 1.2.0 → 1.4.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,16 @@ 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)
+## 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 +126,64 @@ 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).
+
+Add `--json` to get a structured verdict instead of the text report. 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,
+  "report": ["human-legible lines"]
+}
+```
+
+`broken_link` and `data_mismatch` are null unless the verdict is red.
+
+### 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.
 
 ## 6. Add the signal to the host UI
 
@@ -159,11 +219,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 +286,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 +359,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.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)
+
 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.
+`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,14 +140,26 @@ 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.*
+
 ## 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.
@@ -154,11 +170,7 @@ Also worth knowing: the signing key lives on your machine, and today that local
 
 - **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";

package/badge/console.js

@@ -0,0 +1,350 @@
+// The verification console: devtools-for-data. The inline light answers "is
+// it fine?"; this window answers "where, exactly, and by how much?" Design
+// reference: designs/02-debug-window.html, notes in designs/02-NOTES.md.
+//
+// mountReceiptConsole(containerEl, chainUrl, opts?)
+//   Runs the same in-browser verification as the badge/signal/table
+//   (verifyReceipts in badge.js) and renders:
+//   - the lamp: state-coded motion (slow breathing green, brisk yellow,
+//     sharp double-blink red; none under prefers-reduced-motion)
+//   - the pipeline: one card per receipt, links carrying the hash they
+//     proved; a break severs the link and pins a break card at the break
+//     with expected/found chips and the totals delta; a coverage-gap caveat
+//     renders as a dashed amber link to a ghost node at the gap's position
+//   - the inspector: click a card for its receipt (kv + raw JSON)
+//   - the event log: one entry per verify run, mirroring the CLI verifier
+//
+//   opts: pubKey (trusted key hex), watch (re-verify every N ms), warnDrift
+//   Returns { el, ready, refresh(), destroy() }.
+
+import {
+  verifyReceipts,
+  SHORT,
+  outputHashOf,
+  inputHashOf,
+  totalsOf,
+  stageNameOf,
+} from "./badge.js";
+
+function el(tag, props = {}, children = []) {
+  const node = document.createElement(tag);
+  Object.assign(node, props);
+  for (const child of [].concat(children)) {
+    if (child == null) continue;
+    node.appendChild(typeof child === "string" ? document.createTextNode(child) : child);
+  }
+  return node;
+}
+
+function injectConsoleStyles() {
+  if (document.getElementById("tamper-console-styles")) return;
+  const css = `
+  .tc{--bg:#0b0f14;--panel:#11161d;--border:#1f2937;--chrome:#161d26;--text:#e5e7eb;
+    --dim:#8b98a5;--faint:#3d4854;--row:#18202b;--green:#34d399;--red:#f87171;
+    --amber:#fbbf24;--cyan:#67e8f9;
+    font-family:ui-monospace,'SF Mono',Menlo,Monaco,'Cascadia Code',monospace;
+    background:var(--bg);border:1px solid var(--border);border-radius:12px;
+    color:var(--text);overflow:hidden;font-size:12px}
+  .tc .tc-head{display:flex;align-items:center;gap:12px;background:var(--chrome);
+    border-bottom:1px solid var(--border);padding:12px 16px}
+  .tc .tc-lamp{width:16px;height:16px;border-radius:50%;flex:none;background:var(--faint)}
+  .tc[data-state="green"] .tc-lamp{background:var(--green);box-shadow:0 0 10px 1px rgba(52,211,153,0.7);
+    animation:tc-breathe 4s ease-in-out infinite}
+  .tc[data-state="yellow"] .tc-lamp{background:var(--amber);box-shadow:0 0 10px 1px rgba(251,191,36,0.7);
+    animation:tc-breathe 1.6s ease-in-out infinite}
+  .tc[data-state="red"] .tc-lamp{background:var(--red);box-shadow:0 0 10px 1px rgba(248,113,113,0.7);
+    animation:tc-blink 1.8s steps(1) infinite}
+  @keyframes tc-breathe{0%,100%{opacity:1}50%{opacity:0.55}}
+  @keyframes tc-blink{0%,12%,24%{opacity:1}6%,18%{opacity:0.25}30%,100%{opacity:1}}
+  @media (prefers-reduced-motion: reduce){.tc .tc-lamp{animation:none !important}}
+  .tc .tc-title{color:var(--dim);letter-spacing:1.2px;font-size:11px}
+  .tc .tc-verdict{font-weight:700}
+  .tc[data-state="green"] .tc-verdict{color:var(--green)}
+  .tc[data-state="yellow"] .tc-verdict{color:var(--amber)}
+  .tc[data-state="red"] .tc-verdict{color:var(--red)}
+  .tc[data-state="unverifiable"] .tc-verdict{color:var(--dim)}
+  .tc .tc-time{margin-left:auto;color:var(--faint);font-size:10px}
+  .tc .tc-reverify{font:10px inherit;font-family:inherit;color:var(--cyan);background:none;
+    border:1px solid var(--border);border-radius:6px;padding:5px 10px;cursor:pointer}
+  .tc .tc-reverify:hover{border-color:var(--faint)}
+  .tc .tc-caveats{padding:8px 16px;font-size:11px;color:var(--amber);
+    border-bottom:1px solid var(--border);background:rgba(251,191,36,0.06)}
+  .tc .tc-rail-wrap{padding:18px 16px 6px;overflow-x:auto}
+  .tc .tc-rail{display:flex;align-items:flex-start;gap:0;min-width:max-content}
+  .tc .tc-node{border:1px solid var(--border);border-radius:10px;background:var(--panel);
+    padding:10px 12px;min-width:148px;cursor:pointer}
+  .tc .tc-node:hover{border-color:var(--faint)}
+  .tc .tc-node.tc-active{border-color:var(--cyan)}
+  .tc .tc-node.tc-ghost{border-style:dashed;border-color:rgba(251,191,36,0.55);
+    color:var(--amber);cursor:default;background:rgba(251,191,36,0.04)}
+  .tc .tc-node .n-name{font-weight:700;font-size:12px}
+  .tc .tc-node .n-kind{color:var(--faint);font-size:9px;letter-spacing:0.6px;text-transform:uppercase}
+  .tc .tc-node .n-row{color:var(--dim);font-size:10.5px;margin-top:5px}
+  .tc .tc-node .hash{color:var(--cyan)}
+  .tc .tc-node .ok{color:var(--green)}
+  .tc .tc-link{display:flex;flex-direction:column;align-items:center;justify-content:center;
+    padding:0 4px;min-width:96px;align-self:stretch}
+  .tc .tc-link .l-line{font-size:11px;white-space:nowrap;color:var(--green)}
+  .tc .tc-link .l-hash{font-size:9.5px;color:var(--faint);margin-top:2px}
+  .tc .tc-link.tc-broken .l-line{color:var(--red);font-weight:700}
+  .tc .tc-link.tc-gap .l-line{color:var(--amber)}
+  .tc .tc-break{margin:10px 16px 4px;border:1px solid rgba(248,113,113,0.4);
+    background:rgba(180,35,24,0.10);border-radius:9px;padding:10px 14px;font-size:11px}
+  .tc .tc-break h4{margin:0 0 6px;color:var(--red);font-size:11px}
+  .tc .tc-break .kv{display:flex;gap:10px;padding:1px 0}
+  .tc .tc-break .kv b{color:var(--faint);font-weight:400;width:70px;flex:none}
+  .tc .tc-break .bad{color:var(--red)}
+  .tc .tc-break .hash{color:var(--cyan)}
+  .tc .tc-break .delta{margin-top:6px;color:var(--red)}
+  .tc .tc-inspect{margin:10px 16px;border:1px solid var(--border);border-radius:9px;
+    background:var(--panel);padding:10px 14px;font-size:11px;display:none}
+  .tc .tc-inspect.open{display:block}
+  .tc .tc-inspect .kv{display:flex;gap:10px;padding:1px 0}
+  .tc .tc-inspect .kv b{color:var(--faint);font-weight:400;width:92px;flex:none}
+  .tc .tc-inspect .hash{color:var(--cyan)}
+  .tc .tc-inspect summary{cursor:pointer;color:var(--faint);font-size:10px;margin-top:6px}
+  .tc .tc-inspect pre{margin:8px 0 0;padding:10px;background:var(--bg);
+    border:1px solid var(--border);border-radius:7px;font-size:10px;line-height:1.5;
+    overflow:auto;max-height:240px}
+  .tc .tc-log{border-top:1px solid var(--border);background:#07090d;
+    padding:10px 16px;max-height:170px;overflow-y:auto}
+  .tc .tc-log .l-head{color:var(--faint);font-size:9.5px;letter-spacing:1px;margin-bottom:6px}
+  .tc .tc-log .entry{font-size:10.5px;line-height:1.7;color:var(--dim);white-space:pre-wrap}
+  .tc .tc-log .t-green{color:var(--green)}
+  .tc .tc-log .t-amber{color:var(--amber)}
+  .tc .tc-log .t-red{color:var(--red)}
+  .tc .tc-log .t-faint{color:var(--faint)}`;
+  document.head.appendChild(el("style", { id: "tamper-console-styles", textContent: css }));
+}
+
+// Parse "coverage gap: receipt numbering jumps 001 -> 003; ..." caveats into
+// the rail position (insert the ghost after the receipt whose prefix is the
+// jump's left side). Returns a map from receipt-array index to gap label.
+function gapPositions(result) {
+  const gaps = new Map();
+  const names = result.chain?.receipts ?? [];
+  for (const caveat of result.caveats ?? []) {
+    const match = /numbering jumps (\d{3}) -> (\d{3})/.exec(caveat);
+    if (!match) continue;
+    const after = names.findIndex((n) => String(n).startsWith(match[1] + "_"));
+    if (after !== -1) gaps.set(after, `between ${match[1]} and ${match[2]}`);
+  }
+  return gaps;
+}
+
+// Mirror the CLI verifier's report shape for the event log.
+function cliLines(result) {
+  const out = [];
+  if (result.state === "unverifiable") {
+    out.push(["t-faint", `! UNVERIFIABLE: ${result.reason}`]);
+    return out;
+  }
+  const rows = result.receipts.length
+    ? totalsOf(result.receipts[result.receipts.length - 1]).row_count ?? "?"
+    : "?";
+  if (result.state === "green") {
+    out.push(["t-green", `✓ CHAIN INTACT: ${result.receipts.length} receipts, ${result.transforms} transforms, final row_count ${rows}`]);
+  } else if (result.state === "yellow") {
+    out.push(["t-amber", `⚠ CHAIN VERIFIES, WITH CAVEATS: ${result.receipts.length} receipts, ${result.transforms} transforms, final row_count ${rows}`]);
+    for (const caveat of result.caveats) out.push(["", `  - ${caveat}`]);
+    out.push(["t-amber", "  A human should look."]);
+  } else {
+    const lr = result.linkResult;
+    if (lr && lr.ok === false) {
+      out.push(["t-red", `✗ CHAIN BROKEN at link ${lr.brokenAt - 1} -> ${lr.brokenAt} (${lr.brokenStage})`]);
+      out.push(["", `  expected input hash ${SHORT(lr.expected)}  (output of ${stageNameOf(result.receipts[lr.brokenAt - 1])})`]);
+      out.push(["", `  found    input hash ${SHORT(lr.found)}`]);
+      if (lr.delta?.length) out.push(["", `  Control totals delta vs upstream: ${lr.delta.join(", ")}`]);
+    } else {
+      out.push(["t-red", `✗ ${result.reason.toUpperCase()}`]);
+    }
+  }
+  return out;
+}
+
+export function mountReceiptConsole(containerEl, chainUrl, opts) {
+  opts = opts || {};
+  injectConsoleStyles();
+
+  const lamp = el("span", { className: "tc-lamp" });
+  const verdictEl = el("span", { className: "tc-verdict" }, "VERIFYING");
+  const time = el("span", { className: "tc-time" });
+  const reverify = el("button", { className: "tc-reverify", type: "button" }, "re-verify");
+  const head = el("div", { className: "tc-head" }, [
+    lamp,
+    el("span", { className: "tc-title" }, "TAMPER SIGNAL · CONSOLE"),
+    verdictEl,
+    time,
+    reverify,
+  ]);
+  const caveatStrip = el("div");
+  const railWrap = el("div", { className: "tc-rail-wrap" });
+  const breakSlot = el("div");
+  const inspect = el("div", { className: "tc-inspect" });
+  const logEntries = el("div");
+  const log = el("div", { className: "tc-log" }, [
+    el("div", { className: "l-head" }, "EVENT LOG · mirrors `receipts verify`"),
+    logEntries,
+  ]);
+  const root = el("div", { className: "tc" }, [head, caveatStrip, railWrap, breakSlot, inspect, log]);
+  root.dataset.state = "unverifiable";
+  containerEl.appendChild(root);
+
+  let destroyed = false;
+  let timer = null;
+  let activeNode = null;
+
+  function inspectReceipt(receipt, card) {
+    if (activeNode) activeNode.classList.remove("tc-active");
+    activeNode = card;
+    card.classList.add("tc-active");
+    inspect.textContent = "";
+    inspect.classList.add("open");
+    const totals = totalsOf(receipt);
+    const kv = (label, value) => el("div", { className: "kv" }, [el("b", {}, label), el("span", {}, value)]);
+    inspect.append(
+      el("div", { className: "kv" }, [
+        el("b", {}, "stage"),
+        el("span", {}, [stageNameOf(receipt), " ", el("span", { className: "hash" }, SHORT(outputHashOf(receipt)))]),
+      ]),
+      kv("kind", receipt.kind ?? "?"),
+      kv("created", receipt.created_at ?? "?"),
+      kv("rows out", String(totals.row_count ?? "?")),
+    );
+    if (receipt.kind === "transform_receipt") {
+      inspect.append(
+        kv("code file", receipt.transform?.code_file ?? "?"),
+        kv("code hash", SHORT(receipt.transform?.code_hash)),
+      );
+    }
+    if (receipt.signature?.key_fingerprint) {
+      inspect.append(kv("signed by", receipt.signature.key_fingerprint));
+    }
+    inspect.append(
+      el("details", {}, [
+        el("summary", {}, "raw receipt JSON"),
+        el("pre", {}, JSON.stringify(receipt, null, 2)),
+      ])
+    );
+  }
+
+  function render(result, durationMs) {
+    root.dataset.state = result.state;
+    verdictEl.textContent = {
+      green: "GREEN · ALL LINKS VERIFIED",
+      yellow: "YELLOW · VERIFIED WITH CAVEATS",
+      red: "RED · CHAIN BROKEN",
+      unverifiable: "UNVERIFIED",
+    }[result.state];
+    if (result.verifiedAt) {
+      time.textContent = `verified ${result.verifiedAt.slice(11, 19)}Z`;
+    }
+
+    // Caveat strip (yellow only; gaps are also drawn on the rail).
+    caveatStrip.textContent = "";
+    if (result.state === "yellow") {
+      caveatStrip.appendChild(
+        el("div", { className: "tc-caveats" }, "⚠ " + result.caveats.join(" · "))
+      );
+    }
+
+    // Pipeline rail.
+    railWrap.textContent = "";
+    breakSlot.textContent = "";
+    inspect.classList.remove("open");
+    activeNode = null;
+    if (result.state !== "unverifiable" && result.receipts?.length) {
+      const rail = el("div", { className: "tc-rail" });
+      const gaps = gapPositions(result);
+      const lr = result.linkResult;
+      result.receipts.forEach((receipt, i) => {
+        if (i > 0) {
+          const broken = lr && lr.ok === false && lr.brokenAt === i;
+          const link = el("div", { className: `tc-link${broken ? " tc-broken" : ""}` }, [
+            el("span", { className: "l-line" }, broken ? "──✗⚡✗──" : "───▶"),
+            el("span", { className: "l-hash" },
+              broken ? "link severed" : `carries ${SHORT(inputHashOf(receipt))}`),
+          ]);
+          rail.appendChild(link);
+        }
+        const totals = totalsOf(receipt);
+        const card = el("div", { className: "tc-node" }, [
+          el("div", { className: "n-kind" }, receipt.kind === "source_manifest" ? "source" : "transform"),
+          el("div", { className: "n-name" }, stageNameOf(receipt)),
+          el("div", { className: "n-row" }, [
+            "out ", el("span", { className: "hash" }, SHORT(outputHashOf(receipt))),
+          ]),
+          el("div", { className: "n-row" }, [
+            `rows ${totals.row_count ?? "?"} · sig `,
+            el("span", { className: "ok" }, result.signaturesValid ? "✓" : "?"),
+          ]),
+        ]);
+        card.addEventListener("click", () => inspectReceipt(receipt, card));
+        rail.appendChild(card);
+
+        if (gaps.has(i)) {
+          rail.appendChild(el("div", { className: "tc-link tc-gap" }, [
+            el("span", { className: "l-line" }, "┄┄?┄┄"),
+            el("span", { className: "l-hash" }, "coverage gap"),
+          ]));
+          rail.appendChild(el("div", { className: "tc-node tc-ghost" }, [
+            el("div", { className: "n-kind" }, "missing"),
+            el("div", { className: "n-name" }, "no receipt emitted"),
+            el("div", { className: "n-row" }, gaps.get(i)),
+          ]));
+        }
+      });
+      railWrap.appendChild(rail);
+
+      // Break card pinned at the break.
+      if (lr && lr.ok === false) {
+        breakSlot.appendChild(el("div", { className: "tc-break" }, [
+          el("h4", {}, `✗ break at link ${lr.brokenAt - 1} -> ${lr.brokenAt} (${lr.brokenStage})`),
+          el("div", { className: "kv" }, [
+            el("b", {}, "expected"),
+            el("span", {}, [el("span", { className: "hash" }, SHORT(lr.expected)),
+              ` (output of ${stageNameOf(result.receipts[lr.brokenAt - 1])}, signed)`]),
+          ]),
+          el("div", { className: "kv" }, [
+            el("b", {}, "found"),
+            el("span", { className: "bad" }, SHORT(lr.found)),
+          ]),
+          lr.delta?.length
+            ? el("div", { className: "delta" }, `totals delta vs upstream: ${lr.delta.join(" · ")}`)
+            : null,
+        ]));
+      }
+    }
+
+    // Event log entry, newest first.
+    const stamp = (result.verifiedAt ?? new Date().toISOString()).slice(11, 19);
+    const entry = el("div", { className: "entry" });
+    entry.appendChild(el("span", { className: "t-faint" }, `${stamp}Z $ verify (${durationMs}ms)\n`));
+    for (const [cls, text] of cliLines(result)) {
+      entry.appendChild(el("span", { className: cls }, text + "\n"));
+    }
+    logEntries.prepend(entry);
+  }
+
+  async function refresh() {
+    const started = performance.now();
+    const result = await verifyReceipts(chainUrl, opts.pubKey, { warnDrift: opts.warnDrift });
+    if (!destroyed) render(result, Math.round(performance.now() - started));
+    return result;
+  }
+
+  reverify.addEventListener("click", refresh);
+  const ready = refresh();
+  if (opts.watch) timer = setInterval(refresh, Math.max(1000, Number(opts.watch) || 0));
+
+  return {
+    el: root,
+    ready,
+    refresh,
+    destroy() {
+      destroyed = true;
+      if (timer) clearInterval(timer);
+      if (root.parentNode) root.parentNode.removeChild(root);
+    },
+  };
+}

package/badge/table.js

@@ -0,0 +1,255 @@
+// The verified Data tab: render the canonical table document written by
+// `receipts export`, after proving in the viewer's browser that it IS the
+// attested data. Design reference: designs/03-data-tab.html.
+//
+// mountReceiptTable(containerEl, chainUrl, tableUrl?, opts?)
+//   Verifies the chain (same core as the badge and the signal), fetches the
+//   canonical {"headers": [...], "rows": [...]} document, re-serializes it
+//   with the byte-identical JCS from badge.js, hashes it with Web Crypto
+//   SHA-256, and compares against the final receipt's output hash. Only when
+//   they match does the strip say VERIFIED: the rows on screen are then
+//   byte-for-byte the attested data, not a claim about it.
+//
+//   tableUrl defaults to table.json next to chain.json. opts:
+//     maxRows  rows rendered before the "show all" footer (default 500)
+//
+//   Returns { el, ready, refresh(), destroy() }.
+//
+// Honesty notes baked into the states:
+// - chain red: the table renders dimmed with a red strip naming the broken
+//   link; columns whose totals moved at the break are flagged.
+// - table hash mismatch: red strip; the table is NOT the attested data and
+//   renders dimmed. This catches a stale or edited table.json.
+// - chain yellow: amber strip with the caveats; the table still verified
+//   against the final receipt.
+// - fetch/capability failure: grey UNVERIFIED strip, never the yellow color.
+
+import {
+  verifyReceipts,
+  canonicalize,
+  outputHashOf,
+  totalsOf,
+  SHORT,
+  stageNameOf,
+} from "./badge.js";
+
+function el(tag, props = {}, children = []) {
+  const node = document.createElement(tag);
+  Object.assign(node, props);
+  for (const child of [].concat(children)) {
+    if (child == null) continue;
+    node.appendChild(typeof child === "string" ? document.createTextNode(child) : child);
+  }
+  return node;
+}
+
+function injectTableStyles() {
+  if (document.getElementById("tamper-table-styles")) return;
+  const css = `
+  .tt{--tt-bg:#0b0f14;--tt-panel:#11161d;--tt-border:#1f2937;--tt-chrome:#161d26;
+    --tt-text:#e5e7eb;--tt-dim:#8b98a5;--tt-faint:#3d4854;--tt-row:#18202b;
+    --tt-green:#34d399;--tt-red:#f87171;--tt-amber:#fbbf24;--tt-cyan:#67e8f9;
+    font-family:ui-monospace,'SF Mono',Menlo,Monaco,'Cascadia Code',monospace;
+    background:var(--tt-bg);border:1px solid var(--tt-border);border-radius:12px;
+    color:var(--tt-text);overflow:hidden}
+  .tt .tt-strip{display:flex;flex-wrap:wrap;align-items:baseline;gap:6px 12px;
+    background:var(--tt-chrome);border-bottom:1px solid var(--tt-border);
+    padding:10px 14px;font-size:11px;letter-spacing:0.4px}
+  .tt .tt-mark{color:var(--tt-dim);letter-spacing:1.2px}
+  .tt .tt-verdict{font-weight:700}
+  .tt[data-state="green"] .tt-verdict{color:var(--tt-green)}
+  .tt[data-state="yellow"] .tt-verdict{color:var(--tt-amber)}
+  .tt[data-state="red"] .tt-verdict{color:var(--tt-red)}
+  .tt[data-state="unverifiable"] .tt-verdict{color:var(--tt-dim)}
+  .tt .tt-meta{color:var(--tt-dim)}
+  .tt .tt-hash{color:var(--tt-cyan)}
+  .tt .tt-note{padding:8px 14px;font-size:11px;color:var(--tt-amber);
+    border-bottom:1px solid var(--tt-border);background:rgba(251,191,36,0.06)}
+  .tt .tt-note.tt-bad{color:var(--tt-red);background:rgba(180,35,24,0.10)}
+  .tt .tt-scroll{overflow:auto;max-height:440px}
+  .tt table{border-collapse:collapse;width:100%;font-size:11.5px;line-height:1.5}
+  .tt th{position:sticky;top:0;background:var(--tt-panel);color:var(--tt-dim);
+    text-align:left;font-weight:600;padding:8px 12px;border-bottom:1px solid var(--tt-border);
+    white-space:nowrap}
+  .tt th.tt-flag{color:var(--tt-red)}
+  .tt td{padding:6px 12px;border-bottom:1px solid var(--tt-row);white-space:nowrap;color:var(--tt-text)}
+  .tt td.tt-null{color:var(--tt-faint);font-style:italic}
+  .tt td.tt-flagcol{background:rgba(248,113,113,0.06)}
+  .tt[data-trust="false"] .tt-scroll{opacity:0.45}
+  .tt .tt-foot{display:flex;align-items:center;gap:10px;border-top:1px solid var(--tt-border);
+    padding:8px 14px;font-size:10px;color:var(--tt-faint)}
+  .tt .tt-foot button{font:10px inherit;font-family:inherit;color:var(--tt-cyan);
+    background:none;border:1px solid var(--tt-border);border-radius:6px;
+    padding:4px 10px;cursor:pointer}
+  .tt .tt-foot button:hover{border-color:var(--tt-faint)}
+  .tt .tt-tagline{margin-left:auto;color:var(--tt-green)}`;
+  document.head.appendChild(el("style", { id: "tamper-table-styles", textContent: css }));
+}
+
+async function sha256Hex(bytes) {
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// Columns whose totals moved at the broken link; the table flags them.
+function brokenColumns(result) {
+  const { linkResult, receipts } = result;
+  if (!linkResult || linkResult.ok !== false || linkResult.brokenAt == null) return new Set();
+  const up = totalsOf(receipts[linkResult.brokenAt - 1]);
+  const down = totalsOf(receipts[linkResult.brokenAt]);
+  const cols = new Set();
+  for (const key of ["numeric_sums", "null_counts"]) {
+    const a = up[key] ?? {};
+    const b = down[key] ?? {};
+    for (const c of new Set([...Object.keys(a), ...Object.keys(b)])) {
+      if (a[c] !== b[c]) cols.add(c);
+    }
+  }
+  return cols;
+}
+
+export function mountReceiptTable(containerEl, chainUrl, tableUrl, opts) {
+  if (tableUrl && typeof tableUrl === "object") {
+    opts = tableUrl;
+    tableUrl = undefined;
+  }
+  opts = opts || {};
+  const maxRows = opts.maxRows ?? 500;
+  injectTableStyles();
+
+  const root = el("div", { className: "tt" });
+  const verdict = el("span", { className: "tt-verdict" }, "VERIFYING");
+  const meta = el("span", { className: "tt-meta" });
+  const strip = el("div", { className: "tt-strip" }, [
+    el("span", { className: "tt-mark" }, "🧾 DATA · TAMPER SIGNAL"),
+    verdict,
+    meta,
+  ]);
+  const noteSlot = el("div");
+  const scroll = el("div", { className: "tt-scroll" });
+  const foot = el("div", { className: "tt-foot" });
+  root.append(strip, noteSlot, scroll, foot);
+  containerEl.appendChild(root);
+  root.dataset.state = "unverifiable";
+
+  let destroyed = false;
+  let showAll = false;
+
+  function setStrip(state, verdictText, metaText, trusted) {
+    root.dataset.state = state;
+    root.dataset.trust = String(trusted);
+    verdict.textContent = verdictText;
+    meta.textContent = metaText || "";
+  }
+
+  function renderTable(doc, flagged) {
+    scroll.textContent = "";
+    foot.textContent = "";
+    const limit = showAll ? doc.rows.length : Math.min(maxRows, doc.rows.length);
+    const head = el("tr", {}, doc.headers.map((h) =>
+      el("th", { className: flagged.has(h) ? "tt-flag" : "" },
+        flagged.has(h) ? `⚠ ${h}` : h)
+    ));
+    const body = doc.rows.slice(0, limit).map((row) =>
+      el("tr", {}, row.map((cell, i) => {
+        const cls = [
+          cell === null ? "tt-null" : "",
+          flagged.has(doc.headers[i]) ? "tt-flagcol" : "",
+        ].join(" ").trim();
+        return el("td", { className: cls }, cell === null ? "null" : String(cell));
+      }))
+    );
+    scroll.appendChild(el("table", {}, [el("thead", {}, head), el("tbody", {}, body)]));
+
+    foot.appendChild(el("span", {}, `${limit.toLocaleString()} of ${doc.rows.length.toLocaleString()} rows`));
+    if (!showAll && doc.rows.length > maxRows) {
+      const btn = el("button", { type: "button" }, "show all");
+      btn.addEventListener("click", () => {
+        showAll = true;
+        renderTable(doc, flagged);
+      });
+      foot.appendChild(btn);
+    }
+    if (root.dataset.state === "green") {
+      foot.appendChild(el("span", { className: "tt-tagline" }, "green light, open table"));
+    }
+  }
+
+  async function refresh() {
+    const result = await verifyReceipts(chainUrl);
+    if (destroyed) return result;
+
+    const resolvedTableUrl = tableUrl || new URL("table.json", new URL(chainUrl, window.location.href));
+    let doc = null;
+    try {
+      const fetched = await fetch(resolvedTableUrl);
+      if (!fetched.ok) throw new Error(`HTTP ${fetched.status}`);
+      doc = await fetched.json();
+      if (!Array.isArray(doc.headers) || !Array.isArray(doc.rows)) throw new Error("not a table document");
+    } catch (_e) {
+      doc = null;
+    }
+    if (destroyed) return result;
+
+    if (result.state === "unverifiable" || !doc) {
+      setStrip("unverifiable", "UNVERIFIED",
+        !doc ? "could not load table.json (run: receipts export)" : result.reason, false);
+      scroll.textContent = "";
+      foot.textContent = "";
+      if (doc) renderTable(doc, new Set());
+      return result;
+    }
+
+    // Hash the document exactly as Python signed it.
+    let tableHash = null;
+    try {
+      tableHash = await sha256Hex(
+        new TextEncoder().encode(canonicalize({ headers: doc.headers, rows: doc.rows }))
+      );
+    } catch (_e) {
+      setStrip("unverifiable", "UNVERIFIED", "could not hash the table in this browser", false);
+      renderTable(doc, new Set());
+      return result;
+    }
+    const finalReceipt = result.receipts[result.receipts.length - 1];
+    const attested = tableHash === outputHashOf(finalReceipt);
+    const rowsText = `${doc.rows.length.toLocaleString()} rows · sha ${SHORT(tableHash)}`;
+    noteSlot.textContent = "";
+
+    if (result.state === "red") {
+      const flagged = brokenColumns(result);
+      setStrip("red", "CHAIN BROKEN", rowsText, false);
+      noteSlot.appendChild(el("div", { className: "tt-note tt-bad" },
+        `✗ ${result.reason}. Totals fed by this chain cannot be trusted` +
+        (flagged.size ? `; flagged columns moved at the break: ${[...flagged].join(", ")}` : ".")));
+      renderTable(doc, flagged);
+    } else if (!attested) {
+      setStrip("red", "NOT THE ATTESTED DATA", rowsText, false);
+      noteSlot.appendChild(el("div", { className: "tt-note tt-bad" },
+        `✗ This table does not match the final receipt (${stageNameOf(finalReceipt)}): ` +
+        `expected ${SHORT(outputHashOf(finalReceipt))}, found ${SHORT(tableHash)}. ` +
+        "The file may be stale; re-run: receipts export"));
+      renderTable(doc, new Set());
+    } else if (result.state === "yellow") {
+      setStrip("yellow", "VERIFIED, WITH CAVEATS", rowsText, true);
+      noteSlot.appendChild(el("div", { className: "tt-note" },
+        "⚠ " + result.caveats.join(" · ")));
+      renderTable(doc, new Set());
+    } else {
+      setStrip("green", "VERIFIED", rowsText, true);
+      renderTable(doc, new Set());
+    }
+    return result;
+  }
+
+  const ready = refresh();
+  return {
+    el: root,
+    ready,
+    refresh,
+    destroy() {
+      destroyed = true;
+      if (root.parentNode) root.parentNode.removeChild(root);
+    },
+  };
+}

package/node/express.js

@@ -0,0 +1,103 @@
+// Express/Connect attach helper: serve the receipts directory and the browser
+// surfaces in one call. Framework-free internally (plain (req, res, next)
+// handlers), so it also works with Connect, Polka, or bare http routers that
+// accept middleware.
+//
+//   import express from "express";
+//   import { tamperSignal } from "tamper-signal/express";
+//
+//   const app = express();
+//   const signal = tamperSignal(app, { receiptsDir: "receipts/" });
+//   // serve signal.snippet once in your layout, or add the script tag by hand
+//
+// The npm package ships the browser files; they are served from the package
+// itself, side by side, so their relative imports resolve.
+
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ASSET_NAMES = ["badge.js", "light.js", "element.js", "table.js", "console.js"];
+const ASSET_DIR = fileURLToPath(new URL("../badge/", import.meta.url));
+
+const TYPES = { ".json": "application/json", ".js": "text/javascript", ".pub": "text/plain" };
+
+function send(res, path) {
+  const ext = path.slice(path.lastIndexOf("."));
+  res.statusCode = 200;
+  res.setHeader("Content-Type", TYPES[ext] ?? "application/octet-stream");
+  res.setHeader("Cache-Control", "no-store");
+  createReadStream(path).pipe(res);
+}
+
+// Middleware serving one directory, confined: no traversal, files only.
+export function receiptsMiddleware({ receiptsDir = "receipts/" } = {}) {
+  const base = resolve(receiptsDir);
+  return function tamperSignalReceipts(req, res, next) {
+    if (req.method !== "GET" && req.method !== "HEAD") return next();
+    const name = decodeURIComponent(req.url.split("?")[0].replace(/^\/+/, ""));
+    const target = resolve(base, name);
+    // Confine to the directory and its direct files (receipts are flat).
+    if (!name || target !== join(base, basename(name)) || !existsSync(target) || !statSync(target).isFile()) {
+      return next();
+    }
+    send(res, target);
+  };
+}
+
+// Middleware serving the bundled browser assets from the npm package.
+export function assetsMiddleware() {
+  return function tamperSignalAssets(req, res, next) {
+    if (req.method !== "GET" && req.method !== "HEAD") return next();
+    const name = decodeURIComponent(req.url.split("?")[0].replace(/^\/+/, ""));
+    if (!ASSET_NAMES.includes(name)) return next();
+    send(res, join(ASSET_DIR, name));
+  };
+}
+
+export function signalSnippet(chainUrl = "/receipts/chain.json", { assetsPrefix = "/tamper-signal", selector = "header" } = {}) {
+  return (
+    `<script type="module">` +
+    `import { mountTamperSignal } from "${assetsPrefix}/light.js"; ` +
+    `mountTamperSignal(document.querySelector(${JSON.stringify(selector)}) ?? document.body, ${JSON.stringify(chainUrl)});` +
+    `</script>`
+  );
+}
+
+export function consolePage(chainUrl = "/receipts/chain.json", { assetsPrefix = "/tamper-signal" } = {}) {
+  return `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Tamper Signal console</title>
+<style>body{margin:0;background:#07090d;padding:24px}</style></head>
+<body><div id="console"></div>
+<script type="module">
+import { mountReceiptConsole } from "${assetsPrefix}/console.js";
+mountReceiptConsole(document.getElementById("console"), ${JSON.stringify(chainUrl)});
+</script></body></html>
+`;
+}
+
+export function tamperSignal(app, {
+  receiptsDir = "receipts/",
+  urlPrefix = "/receipts",
+  assetsPrefix = "/tamper-signal",
+  selector = "header",
+} = {}) {
+  const chainUrl = `${urlPrefix}/chain.json`;
+  app.use(urlPrefix, receiptsMiddleware({ receiptsDir }));
+  app.use(assetsPrefix, function tamperSignalConsole(req, res, next) {
+    const name = decodeURIComponent(req.url.split("?")[0].replace(/^\/+/, ""));
+    if ((req.method !== "GET" && req.method !== "HEAD") || name !== "console") return next();
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "text/html");
+    res.end(consolePage(chainUrl, { assetsPrefix }));
+  });
+  app.use(assetsPrefix, assetsMiddleware());
+  return {
+    chainUrl,
+    assetsPrefix,
+    consoleUrl: `${assetsPrefix}/console`,
+    snippet: signalSnippet(chainUrl, { assetsPrefix, selector }),
+  };
+}

package/node/test/express.test.js

@@ -0,0 +1,72 @@
+// The Express attach helper, exercised framework-free with mock req/res.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { assetsMiddleware, receiptsMiddleware, signalSnippet, tamperSignal } from "../express.js";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const intactDir = join(repoRoot, "examples", "chains", "intact");
+
+function run(middleware, url) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let nexted = false;
+    const res = {
+      statusCode: 0,
+      headers: {},
+      setHeader(k, v) { this.headers[k] = v; },
+      write(c) { chunks.push(c); },
+      end(c) { if (c) chunks.push(c); resolve({ res: this, body: Buffer.concat(chunks.map(Buffer.from)).toString(), nexted }); },
+      emit() {},
+      on() {},
+      once() {},
+      removeListener() {},
+    };
+    middleware({ method: "GET", url }, res, () => { nexted = true; resolve({ res, body: "", nexted: true }); });
+  });
+}
+
+test("receiptsMiddleware serves chain.json with no-store", async () => {
+  const { res, body, nexted } = await run(receiptsMiddleware({ receiptsDir: intactDir }), "/chain.json");
+  assert.equal(nexted, false);
+  assert.equal(res.statusCode, 200);
+  assert.equal(res.headers["Content-Type"], "application/json");
+  assert.equal(res.headers["Cache-Control"], "no-store");
+  assert.ok(JSON.parse(body).receipts.length >= 1);
+});
+
+test("receiptsMiddleware refuses traversal and missing files", async () => {
+  assert.equal((await run(receiptsMiddleware({ receiptsDir: intactDir }), "/../../package.json")).nexted, true);
+  assert.equal((await run(receiptsMiddleware({ receiptsDir: intactDir }), "/nope.json")).nexted, true);
+});
+
+test("assetsMiddleware serves only the bundled surfaces", async () => {
+  const { res, body } = await run(assetsMiddleware(), "/light.js");
+  assert.equal(res.statusCode, 200);
+  assert.match(body, /mountTamperSignal/);
+  assert.equal((await run(assetsMiddleware(), "/evil.js")).nexted, true);
+});
+
+test("tamperSignal wires an app and returns the snippet", () => {
+  const uses = [];
+  const app = { use: (prefix, fn) => uses.push([prefix, fn.name]) };
+  const handle = tamperSignal(app, { receiptsDir: intactDir });
+  assert.deepEqual(uses.map(([p]) => p), ["/receipts", "/tamper-signal", "/tamper-signal"]);
+  assert.equal(handle.chainUrl, "/receipts/chain.json");
+  assert.match(handle.snippet, /mountTamperSignal/);
+  assert.match(signalSnippet(), /light\.js/);
+});
+
+test("tamperSignal serves the console page", async () => {
+  const handlers = [];
+  const app = { use: (prefix, fn) => handlers.push([prefix, fn]) };
+  const handle = tamperSignal(app, { receiptsDir: intactDir });
+  assert.equal(handle.consoleUrl, "/tamper-signal/console");
+  const consoleHandler = handlers.find(([p, f]) => p === "/tamper-signal" && f.name === "tamperSignalConsole")[1];
+  const { res, body } = await run(consoleHandler, "/console");
+  assert.equal(res.statusCode, 200);
+  assert.match(body, /mountReceiptConsole/);
+});

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "tamper-signal",
-  "version": "1.2.0",
+  "version": "1.4.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",
-  "homepage": "https://welovejeff.github.io/tamper-evident-verification/",
+  "homepage": "https://tampersignal.com/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/welovejeff/tamper-evident-verification.git"
@@ -14,6 +14,9 @@
     "./light": "./badge/light.js",
     "./badge": "./badge/badge.js",
     "./element": "./badge/element.js",
+    "./table": "./badge/table.js",
+    "./console": "./badge/console.js",
+    "./express": "./node/express.js",
     "./react": "./badge/light-react.js"
   },
   "bin": {
@@ -24,6 +27,8 @@
     "badge/badge.js",
     "badge/light.js",
     "badge/element.js",
+    "badge/table.js",
+    "badge/console.js",
     "badge/light-react.js",
     "AGENTS.md"
   ],