tamper-signal 1.2.0

package/node/totals.js

@@ -0,0 +1,134 @@
+// Control totals: the Node port of tamper_signal/totals.py. Hashes say
+// "broken"; totals say "how broken". Numeric sums use exact decimal math
+// (BigInt) and serialize through the same quantizer as cell normalization.
+
+import {
+  coerceDecimal,
+  decimalToPlainString,
+  normalizeCell,
+  normalizeHeader,
+  sumDecimals,
+} from "./canonical.js";
+
+const TYPE_THRESHOLD = 0.9;
+
+function columnsOf(records) {
+  const columns = [];
+  const seen = new Set();
+  for (const record of records) {
+    for (const key of Object.keys(record)) {
+      const name = normalizeHeader(key);
+      if (!seen.has(name)) {
+        seen.add(name);
+        columns.push(name);
+      }
+    }
+  }
+  return columns;
+}
+
+export function controlTotals(records) {
+  const columns = columnsOf(records);
+  const normRecords = records.map((record) => {
+    const out = {};
+    for (const [k, v] of Object.entries(record)) out[normalizeHeader(k)] = v;
+    return out;
+  });
+
+  const nullCounts = {};
+  const numericSums = {};
+  const dateRanges = {};
+
+  for (const column of columns) {
+    const nonNull = [];
+    let nulls = 0;
+    for (const record of normRecords) {
+      const value = record[column] ?? null;
+      if (normalizeCell(value) === null) nulls += 1;
+      else nonNull.push(value);
+    }
+    if (nulls > 0) nullCounts[column] = nulls;
+    if (!nonNull.length) continue;
+
+    const decimals = nonNull.map(coerceDecimal).filter((d) => d !== null);
+    if (decimals.length / nonNull.length >= TYPE_THRESHOLD) {
+      numericSums[column] = decimalToPlainString(sumDecimals(decimals));
+      continue;
+    }
+
+    // Date detection is a type check on real Date instances, mirroring the
+    // Python rule that date-shaped strings stay strings.
+    const isoValues = [];
+    for (const value of nonNull) {
+      if (value instanceof Date) {
+        const normalized = normalizeCell(value);
+        if (typeof normalized === "string") isoValues.push(normalized);
+      }
+    }
+    if (isoValues.length && isoValues.length / nonNull.length >= TYPE_THRESHOLD) {
+      isoValues.sort();
+      dateRanges[column] = { min: isoValues[0], max: isoValues[isoValues.length - 1] };
+    }
+  }
+
+  return {
+    row_count: records.length,
+    column_count: columns.length,
+    numeric_sums: numericSums,
+    date_ranges: dateRanges,
+    null_counts: nullCounts,
+  };
+}
+
+const sortedUnion = (a, b) => [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+
+// Human-legible lines describing only what changed, mirroring totals_delta
+// (including the computed numeric diff, which badge.js omits).
+export function totalsDelta(upstream, downstream) {
+  const lines = [];
+  const upRows = upstream.row_count ?? 0;
+  const downRows = downstream.row_count ?? 0;
+  if (upRows !== downRows) {
+    const d = downRows - upRows;
+    lines.push(`row_count ${upRows} -> ${downRows} (${d >= 0 ? "+" : ""}${d})`);
+  }
+  const upCols = upstream.column_count ?? 0;
+  const downCols = downstream.column_count ?? 0;
+  if (upCols !== downCols) {
+    const d = downCols - upCols;
+    lines.push(`column_count ${upCols} -> ${downCols} (${d >= 0 ? "+" : ""}${d})`);
+  }
+  const us = upstream.numeric_sums ?? {};
+  const ds = downstream.numeric_sums ?? {};
+  for (const column of sortedUnion(us, ds)) {
+    const before = us[column];
+    const after = ds[column];
+    if (before === after) continue;
+    if (before !== undefined && after !== undefined) {
+      const beforeDec = coerceDecimal(before);
+      const afterDec = coerceDecimal(after);
+      if (beforeDec && afterDec) {
+        const diff = sumDecimals([afterDec, { v: -beforeDec.v, exp: beforeDec.exp }]);
+        lines.push(`${column} ${before} -> ${after} (${decimalToPlainString(diff)})`);
+      } else {
+        // Sums in receipt JSON are attacker-controlled; report without a diff.
+        lines.push(`${column} ${before} -> ${after}`);
+      }
+    } else if (after === undefined) {
+      lines.push(`${column} ${before} -> (removed)`);
+    } else {
+      lines.push(`${column} (added) -> ${after}`);
+    }
+  }
+  const un = upstream.null_counts ?? {};
+  const dn = downstream.null_counts ?? {};
+  for (const column of sortedUnion(un, dn)) {
+    const before = un[column] ?? 0;
+    const after = dn[column] ?? 0;
+    if (before !== after) {
+      const d = after - before;
+      lines.push(`null_counts[${column}] ${before} -> ${after} (${d >= 0 ? "+" : ""}${d})`);
+    }
+  }
+  return lines;
+}

package/node/wrapper.js

@@ -0,0 +1,84 @@
+// receiptStep: the Node equivalent of the @receipt_step decorator. Wrap any
+// records -> records transform (sync or async) and every call verifies the
+// existing chain, refuses inputs that do not descend from the chain tail,
+// then signs and appends a receipt.
+//
+//   const clean = receiptStep(
+//     (records) => records.filter((r) => r.campaign_name),
+//     { chainDir: "receipts/", keyPath: "keys/signing.key" }
+//   );
+//   const output = await clean(records);
+
+import { semanticHash } from "./canonical.js";
+import { loadPrivateKey, publicHexFromPrivate } from "./keys.js";
+import {
+  buildTransformReceipt,
+  codeHashOf,
+  loadReceipts,
+  nextReceiptFilename,
+  outputHashOf,
+  readChainFiles,
+  verifyChain,
+  writeChain,
+  writeReceipt,
+} from "./receipts.js";
+
+export class ChainTailMismatch extends Error {}
+
+function toRecords(data, context) {
+  if (Array.isArray(data)) return data;
+  throw new TypeError(
+    `receiptStep ${context} must be an array of plain objects, got ${typeof data}.`
+  );
+}
+
+export function receiptStep(fn, { chainDir = "receipts/", keyPath = "keys/signing.key", codeFile = "<inline>", name } = {}) {
+  const stageName = name ?? (fn.name || "transform"); // anonymous fns have name ""
+  return async function wrapped(records, ...args) {
+    const existing = readChainFiles(chainDir);
+    if (!existing.length) {
+      throw new ChainTailMismatch(`No chain found in ${chainDir}; run \`tamper-signal ingest\` first.`);
+    }
+
+    const privateKey = loadPrivateKey(keyPath);
+    const publicHex = publicHexFromPrivate(privateKey);
+
+    // Verify the existing chain BEFORE extending it.
+    const receipts = loadReceipts(chainDir);
+    const chainResult = verifyChain(receipts, publicHex);
+    if (!chainResult.ok) {
+      throw new ChainTailMismatch(
+        "Existing chain failed verification; refusing to extend it:\n" + chainResult.lines.join("\n")
+      );
+    }
+
+    // Assert the input descends from the chain tail BEFORE running.
+    const tailOutput = outputHashOf(receipts[receipts.length - 1]);
+    const inputHash = semanticHash(toRecords(records, "input"));
+    if (inputHash !== tailOutput) {
+      throw new ChainTailMismatch(
+        "Input data does not match the chain tail output hash.\n" +
+          `  chain tail output: ${tailOutput}\n` +
+          `  provided input:    ${inputHash}\n` +
+          "Refusing to append a receipt for data that did not come from the previous stage."
+      );
+    }
+
+    const output = await fn(records, ...args);
+    const outputRecords = toRecords(output, "output");
+
+    const receipt = buildTransformReceipt({
+      name: stageName,
+      codeHash: codeHashOf(fn),
+      codeFile,
+      inputSemanticHash: inputHash,
+      outputSemanticHash: semanticHash(outputRecords),
+      outputRecords,
+      privateKey,
+    });
+    const filename = nextReceiptFilename(chainDir, stageName);
+    writeReceipt(chainDir, filename, receipt);
+    writeChain(chainDir, [...existing, filename], publicHex);
+    return output;
+  };
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "tamper-signal",
+  "version": "1.2.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/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/welovejeff/tamper-evident-verification.git"
+  },
+  "exports": {
+    ".": "./node/index.js",
+    "./light": "./badge/light.js",
+    "./badge": "./badge/badge.js",
+    "./element": "./badge/element.js",
+    "./react": "./badge/light-react.js"
+  },
+  "bin": {
+    "tamper-signal": "node/cli.js"
+  },
+  "files": [
+    "node/",
+    "badge/badge.js",
+    "badge/light.js",
+    "badge/element.js",
+    "badge/light-react.js",
+    "AGENTS.md"
+  ],
+  "scripts": {
+    "test": "node --test \"node/test/*.test.js\""
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "tamper-evident",
+    "data-integrity",
+    "provenance",
+    "ed25519",
+    "signed-receipts",
+    "data-pipelines",
+    "verification",
+    "hash-chain"
+  ]
+}