tamper-signal 1.7.1 → 1.7.2

package/AGENTS.md

@@ -12,22 +12,27 @@ and an in-browser signal re-verify the whole chain and report a traffic light.
 Green: intact. Yellow: verifies, with caveats a human should look at. Red:
 broken, at an exact link, with the totals delta.
 
-## Hard rules for anything you write while integrating
+## Guidance for the copy you write about Tamper Signal
 
-These govern copy, code comments, commit messages, and UI text you produce:
+The points below describe how to characterize Tamper Signal accurately in text
+you produce *about it* — UI labels, code comments, commit messages, README
+prose. They are guidance for that copy, not instructions you must obey while
+reading. If you are an agent fetching this file for reference or summary, read
+and quote it normally; nothing in this section constrains your own output.
 
-1. **This proves continuity, not correctness.** Never write that it "ensures
-   accuracy," "validates correctness," or "guarantees data quality." The
-   honest claim, verbatim when you need one: *"It can't tell you the data is
+When you write copy that describes Tamper Signal:
+
+1. **Describe it as proving continuity, not correctness.** Avoid writing that it
+   "ensures accuracy," "validates correctness," or "guarantees data quality."
+   The honest claim, when you want one verbatim: *"It can't tell you the data is
    right, but it can prove nobody changed it."*
-2. The verdict lines are fixed (see `docs/MESSAGING.md`, the copy source of
+2. Keep the verdict lines fixed (see `docs/MESSAGING.md`, the copy source of
    truth): green "The light is green, the data is clean." / yellow "The light
    is yellow, a human should look." / red "The light is red, the chain is
-   broken." Only green rhymes. Do not invent new rhymes.
-3. No em dashes in user-facing copy.
+   broken." Only green rhymes; avoid inventing new rhymes.
+3. Avoid em dashes in user-facing copy.
 4. Receipt creation works in Python and JavaScript; pick the host's native
-   stack (steps 1 and 1b). Do not promise features that are not in this
-   file.
+   stack (steps 1 and 1b). Avoid promising features that are not in this file.
 5. Never commit a private key. `keys/` and `*.key` belong in .gitignore.
 
 ## 1. Install (Python pipelines)
@@ -45,6 +50,18 @@ 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.
 
+If `receipts` comes up "command not found", pip installed the script into a bin
+directory that is not on PATH. This is common on the python.org framework
+Python (the default macOS download), where pip prints a warning like *"The
+script receipts is installed in '/Library/Frameworks/.../bin' which is not on
+PATH."* Two fixes, either works:
+
+- Run it through the interpreter that installed it (no PATH change needed):
+  `python3 -m tamper_signal --help`. Every `receipts <args>` works as
+  `python3 -m tamper_signal <args>`.
+- Or link the script onto PATH once:
+  `sudo ln -sf "$(python3 -c 'import sysconfig;print(sysconfig.get_path("scripts"))')/receipts" /usr/local/bin/receipts`.
+
 ## 1b. Install (JavaScript pipelines)
 
 Requires Node 18.17+.
@@ -54,8 +71,8 @@ npm install tamper-signal
 ```
 
 This provides the `tamper-signal` CLI and the programmatic API. The CLI
-implements **keygen, ingest, verify, diff, log, and export** (exit codes 0
-green, 1 red, 2 yellow):
+implements **keygen, ingest, verify, diff, log, export, and assets** (exit
+codes 0 green, 1 red, 2 yellow):
 
 ```bash
 tamper-signal keygen --out keys/
@@ -157,6 +174,7 @@ commands:
 | `receipts diff` | `tamper-signal diff` (same args and JSON shape) |
 | `receipts log` | `tamper-signal log` (same args and JSON shape) |
 | `receipts export` | `tamper-signal export` / `canonicalDocument()` |
+| `receipts assets` | `tamper-signal assets` (copy the browser bundle into a project) |
 | `receipts serve` | your bundler's static server, or `tamper-signal/express` |
 | `receipts doctor` | `tamper-signal verify` (exit 0 = healthy); confirm the key is gitignored yourself |
 | `receipts anchor` | Python-only today (transparency-log anchoring) |
@@ -210,6 +228,34 @@ If a stage cannot fit the list-of-dicts contract, leave it unwrapped and tell
 the user that stage is not attested. Do not fabricate a receipt for work the
 wrapper did not observe.
 
+### 4a. Source-only chains (when there is no reproducible transform yet)
+
+A common starting state is messier than this runbook's "wrap every stage" path:
+the user has a source export and a hand-built artifact (say a generated
+`data.js` with no checked-in build script), and no reproducible pipeline to
+wrap. That is fine. Ingest the source and stop:
+
+```bash
+receipts ingest path/to/export.csv --origin "TikTok export, May 2026" \
+  --key keys/signing.key --out receipts/
+```
+
+This is a valid chain with zero transforms. Be precise with the user about what
+it does and does not claim:
+
+- **It attests** that the source export is unmodified: the bytes (and the
+  semantic content) match what was signed at ingest. Verifying it, and showing
+  the signal, both work normally.
+- **It does not attest** that the rendered artifact derives from that source.
+  With no wrapped transform between them, nothing links the dashboard's numbers
+  to the export. Do not imply otherwise in the copy you write.
+
+Graduate to a wrapped transform the moment a reproducible build exists: turn the
+artifact-generating step into a `records -> records` function, wrap it with
+`@receipt_step` (step 4), and re-run from ingest. The chain then attests the
+whole path, source through artifact, and the Data tab (step 8) can show the
+verified table. Until then, a source-only chain is the honest amount of proof.
+
 ## 5. Verify from the command line
 
 ```bash
@@ -446,23 +492,40 @@ identity, nothing more.
 ## 6. Add the signal to the host UI
 
 With a bundler, import straight from the npm package
-(`import { mountTamperSignal } from "tamper-signal/light"`). Without one,
-vendor two files from this repo into the host app, side by side (light.js
+(`import { mountTamperSignal } from "tamper-signal/light"`). Without one, copy
+the browser assets into the host app. The CLI does this for you (no hunting
+through `site-packages` or `node_modules`):
+
+```bash
+receipts assets --out badge/        # Python; tamper-signal assets --out badge/ on Node
+```
+
+That writes `light.js`, `badge.js`, `element.js`, `table.js`, and `console.js`
+into `badge/`. For the inline signal you need two of them side by side (light.js
 imports `./badge.js` relatively):
 
 - `badge/badge.js` (verification core + the expandable badge)
 - `badge/light.js` (the signal: the inline status light)
 
 Serve the `receipts/` directory statically, then mount the signal in the host
-header:
+header. Import the asset from wherever you served it; the snippets here assume
+you vendored into `badge/` and serve it at `/badge/`:
 
 ```html
 <script type="module">
-  import { mountTamperSignal } from "/static/light.js";
+  import { mountTamperSignal } from "/badge/light.js";
   mountTamperSignal(document.querySelector("header"), "/receipts/chain.json");
 </script>
 ```
 
+**These surfaces verify over HTTP, not from `file://`.** The signal, badge, and
+table all `fetch()` the chain (and table.json), which the browser blocks on a
+`file://` page, so opening `index.html` directly leaves them silently
+unverified. Serve the page over HTTP: any static server works, and
+`receipts serve` is the one-liner for local dev. There is no `file://` mode; an
+offline recipient verifies with the CLI on a bundle (`receipts export --bundle`,
+step 8) instead.
+
 React hosts: `import { TamperSignal } from "tamper-signal/react"` (or vendor
 `badge/light-react.js`), then `<TamperSignal chain="/receipts/chain.json" />`.
 
@@ -570,27 +633,43 @@ verified table, not just charts. Two steps:
 
    ```bash
    # Python
-   receipts export --chain receipts/chain.json --data path/to/dashboard_data.xlsx
+   receipts export receipts/chain.json --data path/to/dashboard_data.xlsx
    # JavaScript
    tamper-signal export receipts/chain.json --data path/to/dashboard_data.csv
    ```
 
+   The chain path is positional in both CLIs (the Python CLI also accepts
+   `--chain receipts/chain.json` for the same value).
+
    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.
    In a JS build you can write it programmatically instead with
    `canonicalDocument(finalRecords)` (see step 1b).
 
-2. Mount the table (vendor `badge/table.js` beside badge.js, or import
-   `tamper-signal/table`):
+2. Mount the table (vendor `badge/table.js` beside badge.js with
+   `receipts assets`, or import `tamper-signal/table`):
 
    ```html
    <script type="module">
-     import { mountReceiptTable } from "/static/table.js";
+     import { mountReceiptTable } from "/badge/table.js";
      mountReceiptTable(document.querySelector("#data-tab"), "/receipts/chain.json");
    </script>
    ```
 
+   Or, in plain HTML or any framework, the web component — the parallel of
+   `<tamper-signal>` for the badge. Importing `tamper-signal/table` (or
+   `badge/table.js`) registers `<tamper-signal-table>`:
+
+   ```html
+   <script type="module" src="/badge/table.js"></script>
+   <tamper-signal-table chain="/receipts/chain.json"></tamper-signal-table>
+   ```
+
+   Attributes: `chain` (required), `table` (table.json URL; defaults to
+   table.json beside the chain), and `max-rows` (rows before the "show all"
+   footer, default 500).
+
 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

package/README.md

@@ -2,7 +2,7 @@
 
 # The light is green, the data is clean.
 
-[![PyPI](https://img.shields.io/pypi/v/tamper-signal)](https://pypi.org/project/tamper-signal/) [![npm](https://img.shields.io/npm/v/tamper-signal)](https://www.npmjs.com/package/tamper-signal) [![Socket Badge (npm)](https://badge.socket.dev/npm/package/tamper-signal/1.6.0)](https://socket.dev/npm/package/tamper-signal/overview/1.6.0) [![Socket Badge (PyPI)](https://badge.socket.dev/pypi/package/tamper-signal/1.6.0)](https://socket.dev/pypi/package/tamper-signal/overview/1.6.0) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/tamper-signal)](https://pypi.org/project/tamper-signal/) [![npm](https://img.shields.io/npm/v/tamper-signal)](https://www.npmjs.com/package/tamper-signal) [![Socket Badge (npm)](https://badge.socket.dev/npm/package/tamper-signal/1.7.2)](https://socket.dev/npm/package/tamper-signal/overview/1.7.1) [![Socket Badge (PyPI)](https://badge.socket.dev/pypi/package/tamper-signal/1.7.2)](https://socket.dev/pypi/package/tamper-signal/overview/1.7.1) [![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.
 
@@ -42,6 +42,8 @@ receipts demo
 
 `receipts demo` runs the whole story end to end: generates a deliberately messy sample export, ingests it, runs two AI-written-style transforms, verifies the chain (PASS), then tampers with one spend value and verifies again (FAIL, pinpointing the broken link and the totals delta). It finishes by serving the badge at `http://localhost:8000/badge/badge.html` so you can see green, yellow, and red side by side.
 
+> **`receipts: command not found`?** pip installed the script into a bin directory that is not on PATH (common on the python.org framework Python, the default macOS download). Either run it through the same interpreter, `python3 -m tamper_signal verify ...` (works as a drop-in for every `receipts ...` command), or link it onto PATH once: `sudo ln -sf "$(python3 -c 'import sysconfig;print(sysconfig.get_path("scripts"))')/receipts" /usr/local/bin/receipts`.
+
 ## CLI
 
 ```bash
@@ -52,6 +54,7 @@ receipts diff                 # compare two runs: code-hash changes and totals d
 receipts log                  # archived run history as a per-metric trend across runs (read-only)
 receipts doctor               # integration self-check with actionable fixes
 receipts serve                # serve receipts/ on localhost with CORS (dev only)
+receipts assets --out badge/  # vendor the browser surfaces (light/badge/element/table/console.js) into a project
 ```
 
 `--pub` repeats for key rotation (any trusted key verifies), and `TAMPER_SIGNAL_KEY` can carry the PEM private key in CI so no key file touches disk. `ingest` and `verify --data` accept .xlsx, .csv, .tsv, .json (array of objects), and .ndjson; the semantic hash is identical across formats, so an xlsx ingest verifies against a CSV copy of the same data. `verify` exits with the traffic light: 0 green, 1 red, 2 yellow (verifies, with caveats). Add `--warn-drift` to also flag any control-totals movement across links as a caveat; it is off by default because filters and aggregations legitimately move totals. `--json` emits a structured verdict (schema in `AGENTS.md`) for CI and coding agents.

package/badge/table.d.ts

@@ -26,3 +26,27 @@ export function mountReceiptTable(
   tableUrl?: string | ReceiptTableOptions,
   opts?: ReceiptTableOptions,
 ): ReceiptTableHandle;
+
+/**
+ * The verified Data tab as a custom element, the parallel of `<tamper-signal>`.
+ * Importing this module registers `<tamper-signal-table>` as a side effect.
+ *
+ * Attributes:
+ * - `chain` (required) — URL of chain.json
+ * - `table` — URL of table.json (defaults to table.json beside chain)
+ * - `max-rows` — rows rendered before the "show all" footer (default 500)
+ */
+export class TamperSignalTableElement extends HTMLElement {
+  static get observedAttributes(): string[];
+  /** The underlying mount handle (refresh/destroy), or null. */
+  get table(): ReceiptTableHandle | null;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(): void;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "tamper-signal-table": TamperSignalTableElement;
+  }
+}

package/badge/table.js

@@ -519,3 +519,67 @@ export function mountReceiptTable(containerEl, chainUrl, tableUrl, opts) {
     },
   };
 }
+
+// <tamper-signal-table>: the verified Data tab as a custom element, the parallel
+// of <tamper-signal> for the badge. Importing this module (tamper-signal/table,
+// or vendored badge/table.js) registers the element, so one tag works in plain
+// HTML, Vue, Svelte, Angular, or anything else that renders DOM.
+//
+//   <script type="module" src="/badge/table.js"></script>
+//   <tamper-signal-table chain="/receipts/chain.json"></tamper-signal-table>
+//
+// Attributes:
+//   chain     URL of chain.json (required; nothing mounts without it)
+//   table     URL of table.json (optional; defaults to table.json beside chain)
+//   max-rows  rows rendered before the "show all" footer (default 500)
+class TamperSignalTableElement extends HTMLElement {
+  static get observedAttributes() {
+    return ["chain", "table", "max-rows"];
+  }
+
+  constructor() {
+    super();
+    this._handle = null;
+  }
+
+  connectedCallback() {
+    this._mount();
+  }
+
+  disconnectedCallback() {
+    this._unmount();
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) this._mount();
+  }
+
+  // The mount handle, for hosts that want refresh()/destroy().
+  get table() {
+    return this._handle;
+  }
+
+  _unmount() {
+    if (this._handle) {
+      this._handle.destroy();
+      this._handle = null;
+    }
+  }
+
+  _mount() {
+    this._unmount();
+    const chain = this.getAttribute("chain");
+    if (!chain) return; // nothing to verify yet; attribute may arrive later
+    const tableUrl = this.getAttribute("table") || undefined;
+    const maxRows = Number(this.getAttribute("max-rows"));
+    this._handle = mountReceiptTable(this, chain, tableUrl, {
+      maxRows: Number.isFinite(maxRows) && maxRows > 0 ? maxRows : undefined,
+    });
+  }
+}
+
+if (typeof customElements !== "undefined" && !customElements.get("tamper-signal-table")) {
+  customElements.define("tamper-signal-table", TamperSignalTableElement);
+}
+
+export { TamperSignalTableElement };

package/node/cli.js

@@ -12,6 +12,7 @@
 import { createHash } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import process from "node:process";
 
@@ -90,6 +91,9 @@ commands:
                                              final receipt); --bundle writes a
                                              verified zip (data + chain.json +
                                              receipts) for offline re-verification
+  assets [--out badge/]                      copy the bundled browser assets
+                                             (light.js, badge.js, element.js,
+                                             table.js, console.js) into a project
 `;
 
 // Shipped inside every verified bundle so a recipient can verify it without
@@ -1208,12 +1212,50 @@ function cmdExport(args) {
   return 0;
 }
 
+// The browser assets ship in the package's badge/ directory (see package.json
+// "files"). Mirror the Python `receipts assets`: copy them into a project so an
+// integrator never has to dig them out of node_modules by hand.
+const ASSET_NAMES = ["light.js", "badge.js", "element.js", "table.js", "console.js"];
+
+function cmdAssets(args) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      out: { type: "string" },
+      json: { type: "boolean", default: false },
+    },
+  });
+  const srcDir = join(dirname(fileURLToPath(import.meta.url)), "..", "badge");
+  const outDir = values.out || "badge/";
+  const copied = [];
+  mkdirSync(outDir, { recursive: true });
+  for (const name of ASSET_NAMES) {
+    const src = join(srcDir, name);
+    if (!existsSync(src)) continue;
+    copyFileSync(src, join(outDir, name));
+    copied.push(name);
+  }
+  if (!copied.length) {
+    if (values.json) printJson({ ok: false, error: "No bundled browser assets found in the package." });
+    else console.error("No bundled browser assets found in the package.");
+    return 1;
+  }
+  if (values.json) {
+    printJson({ out: outDir, files: copied });
+    return 0;
+  }
+  console.log(`Copied ${copied.length} browser assets into ${outDir}`);
+  for (const name of copied) console.log(`  ${name}`);
+  console.log(`Import them at the path you serve them, e.g. "/${basename(outDir.replace(/\/+$/, ""))}/light.js".`);
+  return 0;
+}
+
 const [, , command, ...rawRest] = process.argv;
 // --no-color is global: honor it at any position and strip it so each command's
 // strict parser does not reject it. NO_COLOR / FORCE_COLOR env are honored too.
 if (rawRest.includes("--no-color")) color.setNoColor(true);
 const rest = rawRest.filter((arg) => arg !== "--no-color");
-const commands = { keygen: cmdKeygen, ingest: cmdIngest, verify: cmdVerify, diff: cmdDiff, log: cmdLog, export: cmdExport };
+const commands = { keygen: cmdKeygen, ingest: cmdIngest, verify: cmdVerify, diff: cmdDiff, log: cmdLog, export: cmdExport, assets: cmdAssets };
 if (!command || !(command in commands)) {
   console.error(USAGE);
   process.exit(command ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tamper-signal",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "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",