tamper-signal 1.6.0 → 1.7.0

package/README.md

@@ -156,6 +156,12 @@ It ships: `receipts export` writes the canonical table document next to the chai
 
 *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.*
 
+## Take your data with you
+
+Verified data should be portable, proof and all. `receipts export --bundle` (or `tamper-signal export --bundle`) writes a verified bundle: a zip of the data file plus `chain.json` and its receipts, kept byte for byte, so whoever you send it to runs `receipts verify chain.json` and gets the same light, offline. In the browser, the Data tab's "Take your data" control exports the attested data client-side as that bundle or as a bare rows-only file (csv/tsv/json/ndjson; xlsx routes through the Python CLI). Because the semantic hash is format-agnostic, a CSV you export here re-verifies as JSON and the light stays green; numeric-looking text canonicalizes to its number, so leading zeros and trailing decimals do not survive the round trip.
+
+To bring an updated file back, `receipts ingest --as replace|period`. `replace` (the default) re-signs a fresh chain and archives the prior one under `receipts/archive/`. `period` continues the chain's run history as the next period, judged against prior runs through the prior run's signed tolerance band; it continues only under a trusted signer (`--pub` to trust a key other than the chain's) and refuses an untrusted one rather than appending silently. Re-attestation is never silent: the importer's identity is recorded, and an unrecognized signer stays yellow.
+
 ## 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`.

package/badge/table.js

@@ -82,7 +82,20 @@ function injectTableStyles() {
     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)}`;
+  .tt .tt-tagline{margin-left:auto;color:var(--tt-green)}
+  .tt .tt-export{display:flex;flex-wrap:wrap;align-items:center;gap:8px 12px;
+    border-top:1px solid var(--tt-border);padding:8px 14px;font-size:11px;color:var(--tt-dim)}
+  .tt .tt-export .tt-xlabel{color:var(--tt-text);letter-spacing:0.3px}
+  .tt .tt-export label{display:inline-flex;align-items:center;gap:4px;cursor:pointer}
+  .tt .tt-export select{font:11px inherit;font-family:inherit;color:var(--tt-text);
+    background:var(--tt-panel);border:1px solid var(--tt-border);border-radius:6px;padding:3px 6px}
+  .tt .tt-export button{font:11px inherit;font-family:inherit;color:var(--tt-cyan);
+    background:none;border:1px solid var(--tt-border);border-radius:6px;padding:4px 12px;cursor:pointer}
+  .tt .tt-export button:hover:not(:disabled){border-color:var(--tt-faint)}
+  .tt .tt-export button:disabled{color:var(--tt-faint);cursor:not-allowed;opacity:0.6}
+  .tt .tt-export .tt-xnote{flex-basis:100%;color:var(--tt-dim)}
+  .tt .tt-export .tt-xnote.tt-warn{color:var(--tt-amber)}
+  .tt .tt-export .tt-xhint{margin-left:auto;color:var(--tt-faint)}`;
   document.head.appendChild(el("style", { id: "tamper-table-styles", textContent: css }));
 }
 
@@ -108,6 +121,163 @@ function brokenColumns(result) {
   return cols;
 }
 
+// ---------------------------------------------------------------------------
+// "Take your data": client-side export of the attested data.
+//
+// The browser only holds the canonical table document, so it reconstructs a
+// native-format file from that data (column- and row-sorted, normalized) — the
+// attested data, not the user's original file byte-for-byte. A verified bundle
+// also carries chain.json and the receipts (fetched as raw bytes so the
+// recipient can re-verify), packaged with a store-only zip writer that mirrors
+// node/zip.js. xlsx is not offered here; it goes through the Python CLI.
+// ---------------------------------------------------------------------------
+
+const _CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(bytes) {
+  let c = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) c = _CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+// Store-only (no compression) zip. Entry bytes are kept verbatim so the
+// bundled chain.json and receipts stay byte-identical to the server's copies —
+// receipt_hashes commit to raw bytes, and any transform would verify as broken.
+function makeStoredZip(entries) {
+  const enc = new TextEncoder();
+  const parts = [];
+  const central = [];
+  let offset = 0;
+  for (const { name, bytes } of entries) {
+    const nameBytes = enc.encode(name);
+    const crc = crc32(bytes);
+    const size = bytes.length;
+    const local = new DataView(new ArrayBuffer(30));
+    local.setUint32(0, 0x04034b50, true);
+    local.setUint16(4, 20, true);
+    local.setUint16(8, 0, true);
+    local.setUint16(12, 0x21, true);
+    local.setUint32(14, crc, true);
+    local.setUint32(18, size, true);
+    local.setUint32(22, size, true);
+    local.setUint16(26, nameBytes.length, true);
+    const localHeader = new Uint8Array(local.buffer);
+    parts.push(localHeader, nameBytes, bytes);
+    const cd = new DataView(new ArrayBuffer(46));
+    cd.setUint32(0, 0x02014b50, true);
+    cd.setUint16(4, 20, true);
+    cd.setUint16(6, 20, true);
+    cd.setUint16(14, 0x21, true); // DOS date at offset 14 (offset 12 is the time field, left 0)
+    cd.setUint32(16, crc, true);
+    cd.setUint32(20, size, true);
+    cd.setUint32(24, size, true);
+    cd.setUint16(28, nameBytes.length, true);
+    cd.setUint32(42, offset, true);
+    central.push(new Uint8Array(cd.buffer), nameBytes);
+    offset += localHeader.length + nameBytes.length + size;
+  }
+  let centralSize = 0;
+  for (const c of central) centralSize += c.length;
+  const eocd = new DataView(new ArrayBuffer(22));
+  eocd.setUint32(0, 0x06054b50, true);
+  eocd.setUint16(8, entries.length, true);
+  eocd.setUint16(10, entries.length, true);
+  eocd.setUint32(12, centralSize, true);
+  eocd.setUint32(16, offset, true);
+  const all = [...parts, ...central, new Uint8Array(eocd.buffer)];
+  let total = 0;
+  for (const c of all) total += c.length;
+  const out = new Uint8Array(total);
+  let p = 0;
+  for (const c of all) {
+    out.set(c, p);
+    p += c.length;
+  }
+  return out;
+}
+
+function cellText(cell) {
+  if (cell === null || cell === undefined) return "";
+  if (cell === true) return "true";
+  if (cell === false) return "false";
+  return String(cell);
+}
+
+// Reconstruct a native-format file from the canonical document. Values are the
+// attested values; format is the recipient's choice. Re-ingesting any of these
+// yields the same Semantic hash, since canonicalization is format-agnostic.
+function serializeDoc(doc, format) {
+  const { headers, rows } = doc;
+  if (format === "json") {
+    return JSON.stringify(rows.map((r) => Object.fromEntries(headers.map((h, i) => [h, r[i]]))), null, 2) + "\n";
+  }
+  if (format === "ndjson") {
+    return rows.map((r) => JSON.stringify(Object.fromEntries(headers.map((h, i) => [h, r[i]])))).join("\n") + "\n";
+  }
+  const sep = format === "tsv" ? "\t" : ",";
+  const quote = (v) => {
+    const s = cellText(v);
+    if (format === "tsv") return s.replace(/[\t\r\n]/g, " ");
+    return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+  };
+  const lines = [headers.map(quote).join(sep)];
+  for (const row of rows) lines.push(row.map(quote).join(sep));
+  return lines.join("\n") + "\n";
+}
+
+const EXPORT_EXT = { csv: "csv", tsv: "tsv", json: "json", ndjson: "ndjson" };
+
+function triggerDownload(filename, bytes, mime) {
+  const blob = new Blob([bytes], { type: mime });
+  const url = URL.createObjectURL(blob);
+  const a = el("a", { href: url, download: filename });
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+
+// Shipped inside every verified bundle so a recipient can verify it without
+// prior knowledge of Tamper Signal. Kept in sync with the CLIs (tamper_signal/
+// cli.py BUNDLE_README, node/cli.js BUNDLE_README).
+const BUNDLE_README = `# Verified data bundle (Tamper Signal)
+
+This zip is a verified export from Tamper Signal. It holds the data file plus
+chain.json and the receipt files that prove it.
+
+## Verify it yourself, offline
+
+Install either stack (chains are interchangeable across them):
+
+    pip install tamper-signal       # Python 3.11+, command: receipts
+    npm install -g tamper-signal    # Node 18.17+, command: tamper-signal
+
+Then, from the folder you unzipped this into:
+
+    receipts verify chain.json
+
+The exit code is the traffic light: 0 green (intact), 2 yellow (verifies, with
+caveats), 1 red (broken, at the exact link, with the totals that moved).
+
+## What a green light proves
+
+Continuity, not correctness. It proves this data descends unchanged from the
+signed source, not that the source was right to begin with. Green means nobody
+changed the data between the export and you.
+
+https://tampersignal.com
+`;
+
+let _ttSeq = 0;
+
 export function mountReceiptTable(containerEl, chainUrl, tableUrl, opts) {
   if (tableUrl && typeof tableUrl === "object") {
     opts = tableUrl;
@@ -128,12 +298,102 @@ export function mountReceiptTable(containerEl, chainUrl, tableUrl, opts) {
   const noteSlot = el("div");
   const scroll = el("div", { className: "tt-scroll" });
   const foot = el("div", { className: "tt-foot" });
-  root.append(strip, noteSlot, scroll, foot);
+  const exportBar = el("div", { className: "tt-export" });
+  root.append(strip, noteSlot, scroll, foot, exportBar);
   containerEl.appendChild(root);
   root.dataset.state = "unverifiable";
 
+  const uid = String(_ttSeq++);
   let destroyed = false;
   let showAll = false;
+  let currentDoc = null;
+  let currentAttested = false;
+
+  // "Take your data": rebuilt each refresh from the current verdict. The
+  // verified-bundle option is offered only when the data is attested and the
+  // light is green or yellow; rows-only is always available but never claims
+  // proof.
+  function renderExport() {
+    exportBar.textContent = "";
+    const state = root.dataset.state;
+    const doc = currentDoc;
+    if (!doc) {
+      exportBar.appendChild(el("span", { className: "tt-xnote" },
+        "Export unavailable: verification did not complete."));
+      return;
+    }
+    const bundleOk = currentAttested && (state === "green" || state === "yellow");
+    const typeName = `tt-xtype-${uid}`;
+    const bundleRadio = el("input",
+      { type: "radio", name: typeName, value: "bundle", checked: bundleOk, disabled: !bundleOk });
+    const rowsRadio = el("input",
+      { type: "radio", name: typeName, value: "rows", checked: !bundleOk });
+    const fmt = el("select", {}, Object.keys(EXPORT_EXT).map((f) => el("option", { value: f }, f)));
+    const btn = el("button", { type: "button" }, "Download");
+    const note = el("div", { className: "tt-xnote" });
+
+    exportBar.append(
+      el("span", { className: "tt-xlabel" }, "Take your data"),
+      el("label", {}, [bundleRadio, "Verified bundle"]),
+      el("label", {}, [rowsRadio, "Rows only"]),
+      fmt,
+      btn,
+      el("span", { className: "tt-xhint" }, "xlsx: use the receipts export command"),
+      note,
+    );
+
+    function updateNote() {
+      note.className = "tt-xnote";
+      if (rowsRadio.checked) {
+        note.textContent = "Rows only: no chain or receipts. A recipient can't verify this file.";
+      } else if (state === "yellow") {
+        note.className = "tt-xnote tt-warn";
+        note.textContent = "The chain has caveats; a recipient will see a yellow light.";
+      } else if (!bundleOk) {
+        note.className = "tt-xnote tt-warn";
+        note.textContent = "Verified bundle unavailable: this table is not the attested data.";
+      } else {
+        note.textContent = "Verified bundle: data plus chain.json and receipts. The recipient verifies it offline.";
+      }
+    }
+    bundleRadio.addEventListener("change", updateNote);
+    rowsRadio.addEventListener("change", updateNote);
+    updateNote();
+
+    btn.addEventListener("click", async () => {
+      const rowsOnly = rowsRadio.checked;
+      const ext = EXPORT_EXT[fmt.value];
+      const dataBytes = new TextEncoder().encode(serializeDoc(doc, fmt.value));
+      const label = btn.textContent;
+      btn.disabled = true;
+      btn.textContent = "Preparing…";
+      try {
+        if (rowsOnly) {
+          triggerDownload(`data-rows-only.${ext}`, dataBytes, "application/octet-stream");
+        } else {
+          const base = new URL(chainUrl, window.location.href);
+          const chainBytes = new Uint8Array(await (await fetch(base)).arrayBuffer());
+          const chainDoc = JSON.parse(new TextDecoder().decode(chainBytes));
+          const entries = [
+            { name: "README.md", bytes: new TextEncoder().encode(BUNDLE_README) },
+            { name: `data.${ext}`, bytes: dataBytes },
+            { name: "chain.json", bytes: chainBytes },
+          ];
+          for (const name of chainDoc.receipts || []) {
+            const bytes = new Uint8Array(await (await fetch(new URL(name, base))).arrayBuffer());
+            entries.push({ name, bytes });
+          }
+          triggerDownload("data-verified.zip", makeStoredZip(entries), "application/zip");
+        }
+      } catch (_e) {
+        note.className = "tt-xnote tt-warn";
+        note.textContent = "Could not build the download. Try again.";
+      } finally {
+        btn.textContent = label;
+        btn.disabled = false;
+      }
+    });
+  }
 
   function setStrip(state, verdictText, metaText, trusted) {
     root.dataset.state = state;
@@ -197,6 +457,9 @@ export function mountReceiptTable(containerEl, chainUrl, tableUrl, opts) {
       scroll.textContent = "";
       foot.textContent = "";
       if (doc) renderTable(doc, new Set());
+      currentDoc = doc;
+      currentAttested = false;
+      renderExport();
       return result;
     }
 
@@ -239,6 +502,9 @@ export function mountReceiptTable(containerEl, chainUrl, tableUrl, opts) {
       setStrip("green", "VERIFIED", rowsText, true);
       renderTable(doc, new Set());
     }
+    currentDoc = doc;
+    currentAttested = attested;
+    renderExport();
     return result;
   }
 

package/node/cli.js

@@ -5,12 +5,12 @@
 //   tamper-signal keygen --out keys/
 //   tamper-signal ingest export.csv --origin "..." --key keys/signing.key --out receipts/
 //   tamper-signal verify receipts/chain.json [--pub keys/signing.pub] [--data current.csv] [--warn-drift]
-//   tamper-signal export receipts/chain.json --data current.csv [--out receipts/table.json]
+//   tamper-signal export receipts/chain.json --data current.csv [--out receipts/table.json] [--bundle]
 //
 // Exit codes are the traffic light: 0 green, 1 red, 2 yellow.
 
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { parseArgs } from "node:util";
 import process from "node:process";
@@ -30,6 +30,7 @@ import {
 import { decimalToPlainString, parseDecimal } from "./canonical.js";
 import { generateKeys, loadPrivateKey, loadPublicKeyHex, publicHexFromPrivate } from "./keys.js";
 import { loadRecords } from "./load.js";
+import { makeStoredZip } from "./zip.js";
 import {
   CHAIN_FILENAME,
   SOURCE_RECEIPT_NAME,
@@ -42,7 +43,7 @@ import {
   verifyChain,
 } from "./receipts.js";
 import { controlTotals, groupedNumericColumns, structuredTotalsDelta } from "./totals.js";
-import { ingestFile } from "./wrapper.js";
+import { UntrustedSignerError, appendPeriod, ingestFile } from "./wrapper.js";
 
 const USAGE = `usage: tamper-signal <command>
 
@@ -50,12 +51,18 @@ commands:
   keygen --out keys/                         generate an Ed25519 signing keypair
   ingest <file> --origin "..." [--key keys/signing.key] [--out receipts/]
                 [--band 5%] [--settle 72h] [--bucket-column <name>]
+                [--as replace|period] [--pub key.pub ...]
                                              create a signed source manifest
                                              (.csv, .tsv, .json, .ndjson);
                                              --band/--settle/--bucket-column
                                              sign a tolerance declaration into
                                              the manifest (band default 0.05,
-                                             settle default 72h)
+                                             settle default 72h). --as replace
+                                             (default) re-signs a fresh chain
+                                             (prior chain archived); --as period
+                                             continues run history under a
+                                             trusted signer (--pub to trust a
+                                             key other than the chain's)
   verify <chain.json> [--pub key.pub ...] [--data <file>] [--warn-drift] [--json]
                                              verify a chain (exit 0 green, 1 red, 2 yellow)
   diff [A] [B] [--chain receipts/] [--json]  compare two runs: per-stage
@@ -76,10 +83,43 @@ commands:
                                              collapse last-wins); each metric
                                              shows its value and the delta vs
                                              the previous row. Read-only; exit 0
-  export <chain.json> --data <file> [--out receipts/table.json]
+  export <chain.json> --data <file> [--out receipts/table.json] [--bundle]
                                              write the canonical table document
                                              (refuses unless --data matches the
-                                             final receipt)
+                                             final receipt); --bundle writes a
+                                             verified zip (data + chain.json +
+                                             receipts) for offline re-verification
+`;
+
+// Shipped inside every verified bundle so a recipient can verify it without
+// prior knowledge of Tamper Signal. Kept in sync with the Python CLI and the
+// browser export (tamper_signal/cli.py BUNDLE_README, badge/table.js).
+const BUNDLE_README = `# Verified data bundle (Tamper Signal)
+
+This zip is a verified export from Tamper Signal. It holds the data file plus
+chain.json and the receipt files that prove it.
+
+## Verify it yourself, offline
+
+Install either stack (chains are interchangeable across them):
+
+    pip install tamper-signal       # Python 3.11+, command: receipts
+    npm install -g tamper-signal    # Node 18.17+, command: tamper-signal
+
+Then, from the folder you unzipped this into:
+
+    receipts verify chain.json
+
+The exit code is the traffic light: 0 green (intact), 2 yellow (verifies, with
+caveats), 1 red (broken, at the exact link, with the totals that moved).
+
+## What a green light proves
+
+Continuity, not correctness. It proves this data descends unchanged from the
+signed source, not that the source was right to begin with. Green means nobody
+changed the data between the export and you.
+
+https://tampersignal.com
 `;
 
 function cmdKeygen(args) {
@@ -112,6 +152,96 @@ function isUnsnapshottedReset(chainDir) {
   }
 }
 
+// Before a replace reset, copy the prior chain.json and its receipts into
+// <chainDir>/archive/<tail>/ so the prior chain is preserved, not silently
+// overwritten (R9). Content-addressed by the prior chain tail; idempotent and
+// collision-free. Best-effort: never throws, never blocks ingest.
+function archivePriorChain(chainDir) {
+  const chainPath = join(chainDir, CHAIN_FILENAME);
+  if (!existsSync(chainPath)) return;
+  let chain;
+  let tail;
+  try {
+    chain = readChain(chainPath);
+    tail = chainTailHash(chainDir, chain);
+  } catch {
+    return;
+  }
+  const dest = join(chainDir, "archive", tail);
+  if (existsSync(dest)) return;
+  try {
+    mkdirSync(dest, { recursive: true });
+    copyFileSync(chainPath, join(dest, CHAIN_FILENAME));
+    for (const name of chain.receipts ?? []) {
+      const src = join(chainDir, name);
+      if (existsSync(src)) copyFileSync(src, join(dest, name));
+    }
+  } catch {
+    // best-effort audit trail; ingest proceeds regardless
+  }
+}
+
+// `ingest --as period`: continue the chain's run history under a trusted signer.
+function cmdIngestPeriod(values, file) {
+  // Like replace, compute the unsnapshotted-reset condition and preserve the
+  // prior chain before appendPeriod's ingest overwrites chain.json. A refused
+  // untrusted import leaves the prior chain untouched, so the archive is an
+  // idempotent no-op in that case.
+  const unsnapshottedReset = isUnsnapshottedReset(values.out);
+  archivePriorChain(values.out);
+
+  const trusted = (values.pub ?? []).map((p) => loadPublicKeyHex(p)).filter(Boolean);
+  let result;
+  try {
+    result = appendPeriod({
+      file,
+      declaredOrigin: values.origin,
+      chainDir: values.out,
+      keyPath: values.key,
+      trustedPubHexes: trusted,
+      band: values.band ?? null,
+      settle: values.settle ?? null,
+      bucketColumn: values["bucket-column"] ?? null,
+    });
+  } catch (err) {
+    if (err instanceof UntrustedSignerError) {
+      console.error(`✗ Refusing to append a period: ${err.message}`);
+      return 1;
+    }
+    console.error(err.message);
+    return 1;
+  }
+  if (unsnapshottedReset) {
+    console.error("warning: previous run was never verified; its totals will not enter history");
+  }
+  const totals = result.manifest.control_totals;
+  console.log(`Imported next period: ${result.manifest.source.filename}`);
+  console.log(`  evidence_hash ${result.manifest.source.evidence_hash}`);
+  console.log(`  semantic_hash ${result.manifest.semantic_hash}`);
+  console.log(`  rows ${totals.row_count}, columns ${totals.column_count}`);
+  const grouped = groupedNumericColumns(result.records);
+  if (grouped.length) {
+    console.error("");
+    for (const { column, example } of grouped) {
+      console.error(`  warning: column "${column}" looks numeric (e.g. "${example}") but is missing from numeric_sums.`);
+    }
+    console.error("  Grouped numbers don't parse as plain decimals, so these columns are left out of the control totals'");
+    console.error("  numeric_sums -- a data-receipt-column on them can never flag a change. Add a normalize step that");
+    console.error("  strips the separators before ingest. Only plain decimals (no thousands grouping) are summed.");
+  }
+  if (result.caveats.length) {
+    console.log("  the light is yellow, a human should look:");
+    for (const caveat of result.caveats) console.log(`    - ${caveat}`);
+    return 2;
+  }
+  console.log(
+    result.compared
+      ? "  in band against the prior run (the light stays green)"
+      : "  recorded as the first period (no prior run to compare)",
+  );
+  return 0;
+}
+
 function cmdIngest(args) {
   const { values, positionals } = parseArgs({
     args,
@@ -123,6 +253,8 @@ function cmdIngest(args) {
       band: { type: "string" },
       settle: { type: "string" },
       "bucket-column": { type: "string" },
+      as: { type: "string", default: "replace" },
+      pub: { type: "string", multiple: true, default: [] },
     },
   });
   const file = positionals[0];
@@ -134,10 +266,13 @@ function cmdIngest(args) {
     // The env var silently outranks --key; say so where it matters.
     console.error("Signing with TAMPER_SIGNAL_KEY from the environment (overrides --key)");
   }
+  if ((values.as ?? "replace") === "period") return cmdIngestPeriod(values, file);
   // Compute the unsnapshotted-reset condition from the OUTGOING chain before
   // ingestFile overwrites chain.json; emit the warning only after ingest
   // validation passes (below), so an invalid flag exits 1 with no warning.
   const unsnapshottedReset = isUnsnapshottedReset(values.out);
+  // Preserve the prior chain before the reset overwrites it (R9).
+  archivePriorChain(values.out);
   // ingestFile resets the chain to a fresh source manifest; the same call is
   // the programmatic entry point and the foundation of rebuildChain. Invalid
   // tolerance values and a non-qualifying --bucket-column throw before
@@ -909,6 +1044,7 @@ function cmdExport(args) {
     options: {
       data: { type: "string" },
       out: { type: "string" },
+      bundle: { type: "boolean" },
     },
   });
   const chainPath = positionals[0];
@@ -951,6 +1087,29 @@ function cmdExport(args) {
     return 1;
   }
 
+  if (values.bundle) {
+    // Verified bundle: the original data file plus chain.json and its receipts,
+    // packaged so a recipient can `tamper-signal verify chain.json` offline.
+    // Entry bytes are stored verbatim (chain.json's receipt_hashes commit to the
+    // raw receipt bytes), mirroring the on-disk chain_dir layout flat at the root.
+    const dataName = basename(values.data);
+    const receiptNames = chain.receipts ?? [];
+    const entries = [
+      { name: "README.md", bytes: new TextEncoder().encode(BUNDLE_README) }, // verify instructions
+      { name: dataName, bytes: readFileSync(values.data) },
+      { name: CHAIN_FILENAME, bytes: readFileSync(chainPath) },
+      ...receiptNames.map((name) => ({ name, bytes: readFileSync(join(chainDir, name)) })),
+    ];
+    const stem = dataName.replace(/\.[^.]+$/, "");
+    const bundlePath = values.out || join(chainDir, `${stem}-verified.zip`);
+    writeFileSync(bundlePath, makeStoredZip(entries));
+    console.log(`Exported verified bundle: ${bundlePath}`);
+    console.log(`  data ${dataName}, ${receiptNames.length} receipts + ${CHAIN_FILENAME}`);
+    console.log(`  semantic_hash ${dataHash} (matches final receipt)`);
+    console.log(`  recipient: unzip, then \`tamper-signal verify ${CHAIN_FILENAME}\``);
+    return 0;
+  }
+
   const outPath = values.out || join(chainDir, "table.json");
   writeFileSync(outPath, JSON.stringify(document, null, 2) + "\n");
   console.log(`Exported verified table: ${outPath}`);

package/node/index.d.ts

@@ -446,6 +446,45 @@ export interface RebuildChainOptions {
  */
 export function rebuildChain(options: RebuildChainOptions): Promise<DataRecord[]>;
 
+/** Thrown by appendPeriod when the importer's key is not trusted by the chain. */
+export class UntrustedSignerError extends Error {}
+
+export interface AppendPeriodOptions {
+  /** Path to the source file (.csv/.tsv/.json/.ndjson/.jsonl). */
+  file: string;
+  declaredOrigin?: string;
+  chainDir?: string;
+  keyPath?: string;
+  /** Public key hexes to trust in addition to the chain's own key (--pub). */
+  trustedPubHexes?: string[];
+  /** Override the inherited tolerance band, e.g. "5%" or "0.05". */
+  band?: string | null;
+  /** Override the inherited settling window, e.g. "72h" or "3d". */
+  settle?: string | null;
+  /** Override the inherited bucket column. */
+  bucketColumn?: string | null;
+}
+
+export interface AppendPeriodResult extends IngestFileResult {
+  /** Cross-run judgment caveats (yellow), empty when in band. */
+  caveats: string[];
+  /** Additive caveat detail records. */
+  details: unknown[];
+  /** Baseline-advancement guard recorded in the archived snapshot. */
+  breached: Record<string, string[]>;
+  /** True when a prior trusted snapshot was found to compare against. */
+  compared: boolean;
+}
+
+/**
+ * Import a file as the next period of an existing chain's run history. Continues
+ * history only under a trusted signer (the chain's key or one in
+ * `trustedPubHexes`); an untrusted signer throws UntrustedSignerError. Inherits
+ * the prior run's signed tolerance unless overridden, judges the new run against
+ * prior trusted snapshots, and archives the snapshot with the breached guard.
+ */
+export function appendPeriod(options: AppendPeriodOptions): AppendPeriodResult;
+
 // --- CLI --json payload shapes ---------------------------------------------
 // Documented contracts for the `diff --json` and `log --json` stdout payloads.
 // Byte-identical across the Node and Python CLIs.

package/node/index.js

@@ -74,6 +74,8 @@ export {
   ChainTailMismatch,
   DEFAULT_BAND,
   DEFAULT_SETTLE_HOURS,
+  UntrustedSignerError,
+  appendPeriod,
   ingestFile,
   parseBand,
   parseSettle,

package/node/test/append_period.test.js

@@ -0,0 +1,134 @@
+// Append-period import (U5): JS parity for continuing an existing chain's run
+// history under a trusted signer, judging against prior snapshots; refusing an
+// untrusted signer. Mirrors tests/test_append_period.py.
+
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+
+import { archiveRunSnapshot } from "../history.js";
+import { generateKeys, loadPrivateKey, publicHexFromPrivate } from "../keys.js";
+import { loadReceipts, readChain } from "../receipts.js";
+import { UntrustedSignerError, appendPeriod, ingestFile } from "../wrapper.js";
+
+const P1 = "day,amount\n2026-05-01,10\n2026-05-02,20\n";
+const P2_INBAND = "day,amount\n2026-05-01,10\n2026-05-02,20\n2026-05-03,30\n";
+const P2_BREACH = "day,amount\n2026-05-01,1000\n2026-05-02,20\n";
+
+// Keys + an ingested chain with a band and bucket column, plus a first-period
+// snapshot archived to history/ for the next period to compare against.
+function seedPeriodOne(csv = P1) {
+  const dir = mkdtempSync(join(tmpdir(), "append-"));
+  generateKeys(dir);
+  const keyPath = join(dir, "signing.key");
+  const chainDir = join(dir, "receipts/");
+  const dataPath = join(dir, "data.csv");
+  writeFileSync(dataPath, csv);
+  ingestFile({ file: dataPath, declaredOrigin: "t", chainDir, keyPath, band: "5%", bucketColumn: "day" });
+  const chain = readChain(join(chainDir, "chain.json"));
+  const receipts = loadReceipts(chainDir);
+  const privateKey = loadPrivateKey(keyPath);
+  archiveRunSnapshot(chainDir, chain, receipts, {
+    privateKey,
+    trustedKeys: [publicHexFromPrivate(privateKey)],
+  });
+  return { dir, keyPath, chainDir, dataPath };
+}
+
+test("appendPeriod under the chain key compares and inherits the band", () => {
+  const { keyPath, chainDir, dataPath } = seedPeriodOne();
+  writeFileSync(dataPath, P2_INBAND);
+  const res = appendPeriod({ file: dataPath, declaredOrigin: "t", chainDir, keyPath });
+
+  assert.equal(res.compared, true);
+  assert.equal(res.records.length, 3);
+  assert.equal(res.manifest.tolerance.band, "0.05");
+  assert.equal(res.manifest.tolerance.bucket_column, "day");
+  assert.deepEqual(res.caveats, []);
+});
+
+test("appendPeriod surfaces a moved settled bucket as a caveat", () => {
+  const { keyPath, chainDir, dataPath } = seedPeriodOne();
+  writeFileSync(dataPath, P2_BREACH);
+  const res = appendPeriod({ file: dataPath, declaredOrigin: "t", chainDir, keyPath });
+
+  assert.equal(res.compared, true);
+  assert.ok(res.caveats.length > 0, "expected a drift caveat for the changed settled bucket");
+});
+
+test("appendPeriod refuses an untrusted signer and leaves the chain intact", () => {
+  const { dir, chainDir, dataPath } = seedPeriodOne();
+  const originalKey = readChain(join(chainDir, "chain.json")).public_key;
+  const otherDir = mkdtempSync(join(tmpdir(), "other-"));
+  generateKeys(otherDir);
+  writeFileSync(dataPath, P2_INBAND);
+
+  assert.throws(
+    () => appendPeriod({ file: dataPath, declaredOrigin: "t", chainDir, keyPath: join(otherDir, "signing.key") }),
+    UntrustedSignerError,
+  );
+  assert.equal(readChain(join(chainDir, "chain.json")).public_key, originalKey);
+});
+
+test("appendPeriod trusts a signer passed via trustedPubHexes", () => {
+  const { chainDir, dataPath } = seedPeriodOne();
+  const otherDir = mkdtempSync(join(tmpdir(), "other-"));
+  generateKeys(otherDir);
+  const otherKeyPath = join(otherDir, "signing.key");
+  const otherHex = publicHexFromPrivate(loadPrivateKey(otherKeyPath));
+  writeFileSync(dataPath, P2_INBAND);
+
+  const res = appendPeriod({
+    file: dataPath,
+    declaredOrigin: "t",
+    chainDir,
+    keyPath: otherKeyPath,
+    trustedPubHexes: [otherHex],
+  });
+  assert.equal(res.compared, true);
+  assert.equal(readChain(join(chainDir, "chain.json")).public_key, otherHex);
+});
+
+test("the period CLI archives the prior chain and reports evidence_hash", () => {
+  const { keyPath, chainDir, dataPath } = seedPeriodOne();
+  writeFileSync(dataPath, P2_INBAND);
+  const cli = fileURLToPath(new URL("../cli.js", import.meta.url));
+  const out = execFileSync(
+    "node",
+    [cli, "ingest", dataPath, "--origin", "t", "--as", "period", "--key", keyPath, "--out", chainDir],
+    { encoding: "utf8" },
+  );
+  assert.match(out, /evidence_hash/); // parity with replace output
+  const archiveDir = join(chainDir, "archive");
+  assert.ok(existsSync(archiveDir) && readdirSync(archiveDir).length > 0, "prior chain archived");
+});
+
+test("the export --bundle CLI ships a README with verify instructions", () => {
+  const { chainDir, dataPath } = seedPeriodOne();
+  const cli = fileURLToPath(new URL("../cli.js", import.meta.url));
+  execFileSync(
+    "node",
+    [cli, "export", join(chainDir, "chain.json"), "--data", dataPath, "--bundle"],
+    { encoding: "utf8" },
+  );
+  // data.csv -> data-verified.zip beside the chain; entries are stored
+  // uncompressed, so the README text appears verbatim in the archive bytes.
+  const zip = readFileSync(join(chainDir, "data-verified.zip")).toString("latin1");
+  assert.ok(zip.includes("README.md"), "bundle lists README.md");
+  assert.ok(zip.includes("receipts verify chain.json"), "README carries verify instructions");
+});
+
+test("appendPeriod refuses when no chain exists", () => {
+  const dir = mkdtempSync(join(tmpdir(), "append-empty-"));
+  generateKeys(dir);
+  const dataPath = join(dir, "data.csv");
+  writeFileSync(dataPath, P1);
+  assert.throws(
+    () => appendPeriod({ file: dataPath, declaredOrigin: "t", chainDir: join(dir, "receipts/"), keyPath: join(dir, "signing.key") }),
+    UntrustedSignerError,
+  );
+});

package/node/test/zip.test.js

@@ -0,0 +1,84 @@
+// The store-only zip writer used by `tamper-signal export --bundle`. The bundle
+// must preserve entry bytes exactly (chain.json's receipt_hashes commit to raw
+// receipt bytes), so these tests round-trip bytes through a minimal store-only
+// reader and assert the archive structure is well-formed.
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+
+import { makeStoredZip } from "../zip.js";
+
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+// Minimal store-only extractor: walk local file headers and slice out the
+// (uncompressed) bytes. Sufficient to prove the writer's offsets and sizes.
+function extractStored(zip) {
+  const view = new DataView(zip.buffer, zip.byteOffset, zip.byteLength);
+  const out = {};
+  let i = 0;
+  while (i + 4 <= zip.length && view.getUint32(i, true) === 0x04034b50) {
+    const method = view.getUint16(i + 8, true);
+    const size = view.getUint32(i + 22, true);
+    const nameLen = view.getUint16(i + 26, true);
+    const extraLen = view.getUint16(i + 28, true);
+    const nameStart = i + 30;
+    const name = dec.decode(zip.subarray(nameStart, nameStart + nameLen));
+    const dataStart = nameStart + nameLen + extraLen;
+    assert.equal(method, 0, "entries are stored, not compressed");
+    out[name] = zip.subarray(dataStart, dataStart + size);
+    i = dataStart + size;
+  }
+  return out;
+}
+
+test("makeStoredZip preserves entry bytes exactly", () => {
+  const entries = [
+    { name: "report.csv", bytes: enc.encode("a,b\n1,2\n") },
+    { name: "chain.json", bytes: enc.encode('{"receipts":["000_source.json"]}\n') },
+    { name: "000_source.json", bytes: enc.encode('{"kind":"source"}\n') },
+  ];
+  const zip = makeStoredZip(entries);
+  const extracted = extractStored(zip);
+
+  for (const { name, bytes } of entries) {
+    assert.deepEqual(extracted[name], bytes, `bytes round-trip for ${name}`);
+  }
+});
+
+test("makeStoredZip writes a valid end-of-central-directory record", () => {
+  const entries = [{ name: "a.txt", bytes: enc.encode("hello") }];
+  const zip = makeStoredZip(entries);
+  const view = new DataView(zip.buffer, zip.byteOffset, zip.byteLength);
+
+  // EOCD signature sits 22 bytes from the end (no archive comment).
+  const eocd = zip.length - 22;
+  assert.equal(view.getUint32(eocd, true), 0x06054b50, "EOCD signature present");
+  assert.equal(view.getUint16(eocd + 10, true), entries.length, "total entry count");
+});
+
+test("makeStoredZip is deterministic for identical input", () => {
+  const entries = [{ name: "x", bytes: enc.encode("same") }];
+  assert.deepEqual(makeStoredZip(entries), makeStoredZip(entries));
+});
+
+// The browser Data tab inlines its own copy of this writer (badge/table.js can't
+// import from node/), so guard against the two drifting: the inline copy must
+// produce byte-identical archives. This caught a central-directory date-field
+// offset bug the DOM-less unit tests could not reach.
+test("the inline badge/table.js ZIP writer matches node/zip.js byte for byte", async () => {
+  const src = readFileSync(new URL("../../badge/table.js", import.meta.url), "utf8");
+  const start = src.indexOf("const _CRC_TABLE");
+  const end = src.indexOf("function cellText");
+  assert.ok(start !== -1 && end > start, "could not locate the inline ZIP writer in badge/table.js");
+  const code = src.slice(start, end) + "\nexport { makeStoredZip };\n";
+  const inline = await import("data:text/javascript," + encodeURIComponent(code));
+
+  const entries = [
+    { name: "report.csv", bytes: enc.encode("a,b\n1,2\n3,4\n") },
+    { name: "chain.json", bytes: enc.encode('{"receipts":["000_source.json"]}\n') },
+    { name: "000_source.json", bytes: enc.encode('{"kind":"source"}\n') },
+  ];
+  assert.deepEqual(inline.makeStoredZip(entries), makeStoredZip(entries));
+});

package/node/wrapper.js

@@ -286,3 +286,84 @@ export async function rebuildChain({
   }
   return current;
 }
+
+export class UntrustedSignerError extends Error {}
+
+// Import a file as the next period of an existing chain's run history. Mirrors
+// tamper_signal.wrapper.append_period: continues history only under a trusted
+// signer (the chain's key or one passed via trustedPubHexes); a snapshot signed
+// under an untrusted key would be silently dropped by verification, so an
+// untrusted signer is refused rather than appended. Inherits the prior run's
+// signed tolerance unless overridden, re-ingests the file, judges the new run
+// against prior trusted snapshots, and archives the snapshot with the breached
+// guard computed before the write.
+export function appendPeriod({
+  file,
+  declaredOrigin = "",
+  chainDir = "receipts/",
+  keyPath = "keys/signing.key",
+  trustedPubHexes = [],
+  band = null,
+  settle = null,
+  bucketColumn = null,
+} = {}) {
+  if (!file) throw new TypeError("appendPeriod requires a `file` path.");
+  const chainPath = join(chainDir, CHAIN_FILENAME);
+  let priorChain;
+  try {
+    priorChain = readChain(chainPath);
+  } catch {
+    throw new UntrustedSignerError(
+      `no existing chain at ${chainPath} to continue; use replace to start a chain`,
+    );
+  }
+  const priorKey = priorChain.public_key;
+  const importerHex = publicHexFromPrivate(loadPrivateKey(keyPath));
+  const trusted = new Set([priorKey, ...trustedPubHexes].filter(Boolean));
+  if (!trusted.has(importerHex)) {
+    throw new UntrustedSignerError(
+      "append-period continues history only under a trusted signer; the importer key " +
+        "is neither the chain's key nor passed as trusted. Use replace to re-attest " +
+        "under a new identity, or pass the prior signer's public key.",
+    );
+  }
+
+  // Inherit the prior run's signed tolerance unless the caller overrides it.
+  if (band === null && settle === null && bucketColumn === null) {
+    let priorTol = null;
+    try {
+      priorTol = loadReceipts(chainDir)[0]?.tolerance ?? null;
+    } catch {
+      priorTol = null;
+    }
+    if (priorTol && typeof priorTol === "object") {
+      if (typeof priorTol.band === "string") band = priorTol.band;
+      if (Number.isInteger(priorTol.settle_hours)) settle = `${priorTol.settle_hours}h`;
+      if (typeof priorTol.bucket_column === "string") bucketColumn = priorTol.bucket_column;
+    }
+  }
+
+  const result = ingestFile({ file, declaredOrigin, chainDir, keyPath, band, settle, bucketColumn });
+
+  // Judge against prior trusted snapshots BEFORE archiving this run, so the
+  // breached guard is recorded in the snapshot we write.
+  const trustedKeys = [...new Set([...trusted, importerHex])].sort();
+  const chain = readChain(chainPath);
+  const receipts = loadReceipts(chainDir);
+  const items = loadSnapshots(chainDir, { trustedKeys });
+  const judgment = judgeCrossRun(receipts, chain, items.map((item) => item.snapshot));
+  const breached = Object.keys(judgment.breached).length ? judgment.breached : null;
+  archiveRunSnapshot(chainDir, chain, receipts, {
+    privateKey: loadPrivateKey(keyPath),
+    trustedKeys,
+    breached,
+  });
+
+  return {
+    ...result,
+    caveats: judgment.caveats,
+    details: judgment.details,
+    breached: judgment.breached,
+    compared: items.length > 0,
+  };
+}

package/node/zip.js

@@ -0,0 +1,108 @@
+// Minimal store-only (no compression) ZIP writer. Pure JS, zero dependencies,
+// usable in both Node and the browser. Entry bytes are stored verbatim: a
+// verified bundle carries chain.json plus receipt files whose bytes are
+// committed by chain.json's receipt_hashes, so any transform (compression,
+// re-encoding, line-ending rewrite) would verify as a broken chain. Store-only
+// keeps the bytes exact.
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+function crc32(bytes) {
+  let c = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+const encoder = new TextEncoder();
+
+// Fixed 1980-01-01 timestamp keeps the zip deterministic (same inputs -> same
+// bytes), which matters for reproducible bundles and stable tests.
+const DOS_TIME = 0;
+const DOS_DATE = 0x21; // (year 1980 << 9) | (month 1 << 5) | day 1
+
+/**
+ * Build a store-only zip from `entries` ([{ name, bytes: Uint8Array }]).
+ * Returns the zip as a Uint8Array. Names use forward slashes; callers pass the
+ * exact in-archive path. Bytes are stored uncompressed and unmodified.
+ */
+export function makeStoredZip(entries) {
+  const parts = [];
+  const central = [];
+  let offset = 0;
+
+  for (const { name, bytes } of entries) {
+    const nameBytes = encoder.encode(name);
+    const crc = crc32(bytes);
+    const size = bytes.length;
+
+    const local = new DataView(new ArrayBuffer(30));
+    local.setUint32(0, 0x04034b50, true); // local file header signature
+    local.setUint16(4, 20, true); // version needed to extract
+    local.setUint16(6, 0, true); // general purpose flags
+    local.setUint16(8, 0, true); // method 0 = store
+    local.setUint16(10, DOS_TIME, true);
+    local.setUint16(12, DOS_DATE, true);
+    local.setUint32(14, crc, true);
+    local.setUint32(18, size, true); // compressed size
+    local.setUint32(22, size, true); // uncompressed size
+    local.setUint16(26, nameBytes.length, true);
+    local.setUint16(28, 0, true); // extra field length
+    const localHeader = new Uint8Array(local.buffer);
+    parts.push(localHeader, nameBytes, bytes);
+
+    const cd = new DataView(new ArrayBuffer(46));
+    cd.setUint32(0, 0x02014b50, true); // central directory header signature
+    cd.setUint16(4, 20, true); // version made by
+    cd.setUint16(6, 20, true); // version needed to extract
+    cd.setUint16(8, 0, true); // flags
+    cd.setUint16(10, 0, true); // method 0 = store
+    cd.setUint16(12, DOS_TIME, true);
+    cd.setUint16(14, DOS_DATE, true);
+    cd.setUint32(16, crc, true);
+    cd.setUint32(20, size, true);
+    cd.setUint32(24, size, true);
+    cd.setUint16(28, nameBytes.length, true);
+    cd.setUint16(30, 0, true); // extra length
+    cd.setUint16(32, 0, true); // comment length
+    cd.setUint16(34, 0, true); // disk number start
+    cd.setUint16(36, 0, true); // internal attributes
+    cd.setUint32(38, 0, true); // external attributes
+    cd.setUint32(42, offset, true); // relative offset of local header
+    central.push(new Uint8Array(cd.buffer), nameBytes);
+
+    offset += localHeader.length + nameBytes.length + size;
+  }
+
+  const centralStart = offset;
+  let centralSize = 0;
+  for (const c of central) centralSize += c.length;
+
+  const eocd = new DataView(new ArrayBuffer(22));
+  eocd.setUint32(0, 0x06054b50, true); // end of central directory signature
+  eocd.setUint16(4, 0, true); // number of this disk
+  eocd.setUint16(6, 0, true); // disk with central directory
+  eocd.setUint16(8, entries.length, true); // entries on this disk
+  eocd.setUint16(10, entries.length, true); // total entries
+  eocd.setUint32(12, centralSize, true);
+  eocd.setUint32(16, centralStart, true);
+  eocd.setUint16(20, 0, true); // comment length
+
+  const all = [...parts, ...central, new Uint8Array(eocd.buffer)];
+  let total = 0;
+  for (const c of all) total += c.length;
+  const out = new Uint8Array(total);
+  let p = 0;
+  for (const c of all) {
+    out.set(c, p);
+    p += c.length;
+  }
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tamper-signal",
-  "version": "1.6.0",
+  "version": "1.7.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",
@@ -64,7 +64,7 @@
     "AGENTS.md"
   ],
   "scripts": {
-    "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 node/test/totals.test.js node/test/pipeline.test.js node/test/history.test.js node/test/diff.test.js node/test/log.test.js node/test/judgment.test.js node/test/theme.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 node/test/totals.test.js node/test/pipeline.test.js node/test/history.test.js node/test/diff.test.js node/test/log.test.js node/test/judgment.test.js node/test/theme.test.js node/test/zip.test.js node/test/append_period.test.js"
   },
   "engines": {
     "node": ">=18.17"