@bolyra/receipts 0.7.0 → 0.8.0

package/README.md

@@ -0,0 +1,105 @@
+# @bolyra/receipts
+
+Tamper-evident signed receipts for Bolyra ZKP verification decisions — secp256k1 / ES256K signatures, canonical JSON, EVM-compatible r‖s‖v encoding.
+
+## Install
+
+```bash
+npm install @bolyra/receipts
+```
+
+## Usage
+
+```typescript
+import { createAuthReceipt, signReceipt, verifyReceipt } from '@bolyra/receipts';
+
+// 1. Build a receipt from a verification result
+const payload = createAuthReceipt(
+  {
+    rootDid: 'did:bolyra:0xabc…',
+    actingDid: 'did:bolyra:0xdef…',
+    credentialCommitment: '0x1234…',
+    effectiveCommitment: '0x1234…',
+    humanProof: verifiedBundle.humanProof,
+    agentProof: verifiedBundle.agentProof,
+    humanPublicSignals: verifiedBundle.humanPublicSignals,
+    agentPublicSignals: verifiedBundle.agentPublicSignals,
+    allowed: true,
+    score: 95,
+    permissionBitmask: 3n,
+    chainDepth: 0,
+    bundleVersion: 1,
+    nonce: '0xdeadbeef',
+  },
+  { issuer: 'https://gateway.example.com', keyId: 'k1' },
+);
+
+// 2. Sign it with your secp256k1 private key
+const signed = signReceipt(payload, {
+  privateKey: process.env.RECEIPT_SIGNING_KEY!,
+  keyId: 'k1',
+});
+
+// 3. Verify later (or on another service)
+const ok = verifyReceipt(signed, '0xYourExpectedSignerAddress');
+console.log(ok); // true
+```
+
+The `signed` object is JSON-serializable and can be stored in a database, forwarded to an audit log, or returned to the caller as proof of the verification decision.
+
+## Hash-chained logs (v0.8.0+)
+
+A signature makes each *receipt* tamper-evident; it does not make a *log* of
+receipts tamper-evident — deleting or reordering whole entries leaves every
+remaining signature valid. `ReceiptChain` closes that gap:
+
+```typescript
+import { ReceiptChain, verifyReceiptChain, GENESIS_PREV_RECEIPT_HASH } from '@bolyra/receipts';
+
+// Writer side: one chain per log. Each signed payload gains
+// chain: { seq, prevReceiptHash } — the fields are INSIDE the signed payload,
+// so they cannot be rewritten without breaking the signature.
+const chain = new ReceiptChain();
+const first = chain.sign(payload1, signerConfig);  // seq 0, prevReceiptHash = genesis sentinel
+const second = chain.sign(payload2, signerConfig); // seq 1, prevReceiptHash = first.receiptHash
+
+// Verifier side: every signature AND the chain links.
+const result = verifyReceiptChain([first, second], { expectedSigner: '0x…' });
+result.ok;       // true
+result.headHash; // pin this externally to detect tail truncation later
+```
+
+Details:
+
+- **Genesis sentinel:** the first receipt in a log has `seq: 0` and
+  `prevReceiptHash: GENESIS_PREV_RECEIPT_HASH` (`0x` + 64 zeros).
+- **`receiptHash`** (envelope field) is `computeReceiptHash(receipt)`:
+  keccak256 over the canonical `{ payload, signature }` — it commits to the
+  exact signature bytes and excludes `id` and itself. Verifiers recompute it;
+  the stored copy is a convenience for linking and anchoring.
+- **Backward compatible:** all fields are additive. Chain-less receipts keep
+  verifying, chained receipts still pass the plain `verifyReceipt()`, and
+  chain verification is a separate step. Logs that START with pre-chaining
+  receipts verify with `{ allowUnchained: true }` (deletions among that
+  unchained prefix are, unavoidably, not detectable). Only a prefix is
+  tolerated: a chain-less receipt after any chained receipt always fails
+  (`unchained-after-chained`) — otherwise a validly signed chain-less receipt
+  could be spliced in undetected.
+- **What chain verification detects from the log alone:** edited receipts,
+  deleted lines, reordered lines, inserted lines, head truncation (missing
+  genesis), and a second chain spliced into the file.
+- **What it provably cannot detect from the log alone:** truncation from the
+  **tail** — a chain cut after any receipt is still internally consistent.
+  Detecting it requires an external expectation: pass `expectedCount` and/or
+  `expectedHeadHash` (e.g. from a periodically anchored checkpoint). The
+  anchoring mechanism and checkpoint cadence are deployment policy —
+  enterprise-configurable, not fixed by this library.
+
+CLI: `bolyra receipt verify-chain audit-log.jsonl` (from
+[`@bolyra/cli`](../cli/README.md)) runs the same verification over a JSONL
+file, with `--signer`, `--expect-count`, `--expect-head`, and
+`--allow-unchained`.
+
+## License
+
+Apache-2.0

package/dist/chain.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Receipt hash-chaining — whole-log integrity on top of per-receipt signatures.
+ *
+ * Individual receipts are ES256K-signed and tamper-evident on their own; a log
+ * of receipts is not — deleting or reordering whole lines leaves every
+ * remaining signature valid. Chaining closes that gap:
+ *
+ * - Each chained receipt carries `payload.chain = { seq, prevReceiptHash }`.
+ *   These fields live INSIDE the signed payload, so they cannot be rewritten
+ *   after the fact without breaking the signature.
+ * - `seq` is 0-based and monotonic per log (per writer process).
+ * - `prevReceiptHash` is the previous receipt's canonical hash; the first
+ *   receipt in a log uses the documented sentinel GENESIS_PREV_RECEIPT_HASH
+ *   (32 zero bytes, hex).
+ * - `receiptHash` is attached to the signed-receipt ENVELOPE as a convenience:
+ *   keccak256 over canonicalize({ payload, signature }) — it commits to both
+ *   the payload and the exact signature bytes, and excludes `id` and the
+ *   `receiptHash` field itself. Verifiers never trust it: verifyReceiptChain
+ *   recomputes it and only flags a stored value that disagrees.
+ *
+ * Backward compatibility: all fields are additive. Chain-less receipts keep
+ * signing and verifying exactly as before, chained receipts verify with the
+ * existing per-receipt verifyReceipt(), and chain verification is a separate
+ * step (verifyReceiptChain).
+ *
+ * What chain verification can and cannot detect (be precise with auditors):
+ * - DETECTABLE from the log alone: edits to any receipt (signature), deleted
+ *   lines (prev-hash/seq break), reordered lines, inserted lines, head
+ *   truncation (log no longer starts at genesis), a restarted chain spliced
+ *   into the same file.
+ * - NOT detectable from the log alone: truncation from the TAIL — a chain cut
+ *   after any receipt is still internally consistent. Detecting it requires
+ *   external knowledge: the expected receipt count (expectedCount) or the
+ *   expected head hash (expectedHeadHash), e.g. from a periodically anchored
+ *   checkpoint. Anchoring/checkpoint cadence is deployment policy
+ *   (enterprise-configurable), not part of this library.
+ */
+import type { ReceiptPayload, ReceiptSignerConfig, SignedReceipt } from './types';
+/** Sentinel prevReceiptHash for the first receipt in a log: 32 zero bytes. */
+export declare const GENESIS_PREV_RECEIPT_HASH: string;
+/**
+ * Canonical hash of a signed receipt: keccak256 over
+ * canonicalize({ payload, signature }). Excludes `id` (derivable from
+ * signature.payloadHash) and `receiptHash` itself (to avoid self-reference).
+ */
+export declare function computeReceiptHash(receipt: SignedReceipt): string;
+/**
+ * Stateful writer-side chain: assigns { seq, prevReceiptHash } to each payload
+ * before signing and attaches the resulting receiptHash to the envelope.
+ *
+ * One ReceiptChain per log. State lives with the writer process; a restart
+ * starts a new chain (seq 0, genesis sentinel) — write it to a new log file
+ * if the log must verify as a single chain.
+ *
+ * State advances when a receipt is SIGNED, not when it is durably written.
+ * This is deliberate: if a signed receipt is subsequently lost (a dropped
+ * write), the next receipt links across the gap and chain verification FAILS
+ * — which is the truthful outcome, because the log really is incomplete. A
+ * writer-acknowledged design (advance only after persistence) would instead
+ * make the surviving log verify clean and silently hide the loss.
+ */
+export declare class ReceiptChain {
+    private seq;
+    private prevReceiptHash;
+    /** Sign one payload as the next link. Advances state only on success. */
+    sign(payload: ReceiptPayload, config: ReceiptSignerConfig): SignedReceipt;
+}
+export type ReceiptChainIssueCode = 'malformed-receipt' | 'signature-invalid' | 'missing-chain-fields' | 'unchained-after-chained' | 'genesis-mismatch' | 'chain-restart' | 'seq-mismatch' | 'prev-hash-mismatch' | 'receipt-hash-mismatch' | 'count-mismatch' | 'head-hash-mismatch';
+export interface ReceiptChainIssue {
+    /** 0-based position in the log; -1 for log-level issues (count/head checks). */
+    index: number;
+    receiptId?: string;
+    code: ReceiptChainIssueCode;
+    message: string;
+}
+export interface ChainVerifyOptions {
+    /** Require every signature to recover to this address. */
+    expectedSigner?: string;
+    /**
+     * Externally known receipt count. Without it, truncation from the TAIL of
+     * the log is NOT detectable — a cut chain is still internally consistent.
+     */
+    expectedCount?: number;
+    /** Externally known (anchored) hash of the last receipt — same purpose. */
+    expectedHeadHash?: string;
+    /**
+     * Tolerate a PREFIX of receipts without chain fields (logs that predate
+     * chaining). Their signatures are still verified, but deletion/reordering
+     * among them is NOT detectable. Only the prefix is tolerated: a chain-less
+     * receipt appearing AFTER any chained receipt is always an issue
+     * ('unchained-after-chained') — otherwise any validly signed chain-less
+     * receipt could be spliced into or appended to a chained log undetected.
+     */
+    allowUnchained?: boolean;
+}
+export interface ChainVerifyResult {
+    ok: boolean;
+    total: number;
+    chained: number;
+    unchained: number;
+    issues: ReceiptChainIssue[];
+    /**
+     * Recomputed hash of the last chained receipt — pin/anchor this externally
+     * to make tail truncation detectable on the next verification.
+     */
+    headHash?: string;
+}
+/**
+ * Verify a receipt log as a hash chain: every signature AND the chain links.
+ * Receipts must be passed in log order.
+ */
+export declare function verifyReceiptChain(receipts: SignedReceipt[], options?: ChainVerifyOptions): ChainVerifyResult;

package/dist/chain.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * Receipt hash-chaining — whole-log integrity on top of per-receipt signatures.
+ *
+ * Individual receipts are ES256K-signed and tamper-evident on their own; a log
+ * of receipts is not — deleting or reordering whole lines leaves every
+ * remaining signature valid. Chaining closes that gap:
+ *
+ * - Each chained receipt carries `payload.chain = { seq, prevReceiptHash }`.
+ *   These fields live INSIDE the signed payload, so they cannot be rewritten
+ *   after the fact without breaking the signature.
+ * - `seq` is 0-based and monotonic per log (per writer process).
+ * - `prevReceiptHash` is the previous receipt's canonical hash; the first
+ *   receipt in a log uses the documented sentinel GENESIS_PREV_RECEIPT_HASH
+ *   (32 zero bytes, hex).
+ * - `receiptHash` is attached to the signed-receipt ENVELOPE as a convenience:
+ *   keccak256 over canonicalize({ payload, signature }) — it commits to both
+ *   the payload and the exact signature bytes, and excludes `id` and the
+ *   `receiptHash` field itself. Verifiers never trust it: verifyReceiptChain
+ *   recomputes it and only flags a stored value that disagrees.
+ *
+ * Backward compatibility: all fields are additive. Chain-less receipts keep
+ * signing and verifying exactly as before, chained receipts verify with the
+ * existing per-receipt verifyReceipt(), and chain verification is a separate
+ * step (verifyReceiptChain).
+ *
+ * What chain verification can and cannot detect (be precise with auditors):
+ * - DETECTABLE from the log alone: edits to any receipt (signature), deleted
+ *   lines (prev-hash/seq break), reordered lines, inserted lines, head
+ *   truncation (log no longer starts at genesis), a restarted chain spliced
+ *   into the same file.
+ * - NOT detectable from the log alone: truncation from the TAIL — a chain cut
+ *   after any receipt is still internally consistent. Detecting it requires
+ *   external knowledge: the expected receipt count (expectedCount) or the
+ *   expected head hash (expectedHeadHash), e.g. from a periodically anchored
+ *   checkpoint. Anchoring/checkpoint cadence is deployment policy
+ *   (enterprise-configurable), not part of this library.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReceiptChain = exports.GENESIS_PREV_RECEIPT_HASH = void 0;
+exports.computeReceiptHash = computeReceiptHash;
+exports.verifyReceiptChain = verifyReceiptChain;
+const sha3_1 = require("@noble/hashes/sha3");
+const utils_1 = require("@noble/hashes/utils");
+const canonical_1 = require("./canonical");
+const sign_1 = require("./sign");
+/** Sentinel prevReceiptHash for the first receipt in a log: 32 zero bytes. */
+exports.GENESIS_PREV_RECEIPT_HASH = '0x' + '0'.repeat(64);
+/**
+ * Canonical hash of a signed receipt: keccak256 over
+ * canonicalize({ payload, signature }). Excludes `id` (derivable from
+ * signature.payloadHash) and `receiptHash` itself (to avoid self-reference).
+ */
+function computeReceiptHash(receipt) {
+    const canonical = (0, canonical_1.canonicalize)({ payload: receipt.payload, signature: receipt.signature });
+    return '0x' + (0, utils_1.bytesToHex)((0, sha3_1.keccak_256)(new TextEncoder().encode(canonical)));
+}
+/**
+ * Stateful writer-side chain: assigns { seq, prevReceiptHash } to each payload
+ * before signing and attaches the resulting receiptHash to the envelope.
+ *
+ * One ReceiptChain per log. State lives with the writer process; a restart
+ * starts a new chain (seq 0, genesis sentinel) — write it to a new log file
+ * if the log must verify as a single chain.
+ *
+ * State advances when a receipt is SIGNED, not when it is durably written.
+ * This is deliberate: if a signed receipt is subsequently lost (a dropped
+ * write), the next receipt links across the gap and chain verification FAILS
+ * — which is the truthful outcome, because the log really is incomplete. A
+ * writer-acknowledged design (advance only after persistence) would instead
+ * make the surviving log verify clean and silently hide the loss.
+ */
+class ReceiptChain {
+    constructor() {
+        this.seq = 0;
+        this.prevReceiptHash = exports.GENESIS_PREV_RECEIPT_HASH;
+    }
+    /** Sign one payload as the next link. Advances state only on success. */
+    sign(payload, config) {
+        const chained = {
+            ...payload,
+            chain: { seq: this.seq, prevReceiptHash: this.prevReceiptHash },
+        };
+        const receipt = (0, sign_1.signReceipt)(chained, config);
+        const receiptHash = computeReceiptHash(receipt);
+        this.seq += 1;
+        this.prevReceiptHash = receiptHash;
+        return { ...receipt, receiptHash };
+    }
+}
+exports.ReceiptChain = ReceiptChain;
+/**
+ * Verify a receipt log as a hash chain: every signature AND the chain links.
+ * Receipts must be passed in log order.
+ */
+function verifyReceiptChain(receipts, options = {}) {
+    const issues = [];
+    let chained = 0;
+    let unchained = 0;
+    let prev;
+    let headHash;
+    receipts.forEach((receipt, index) => {
+        // 0. Shape guard: collected logs can contain non-receipt entries (e.g.
+        // the gateway's tagged `unsigned: true` raw fallback records). Flag them
+        // as malformed instead of throwing on property access below.
+        if (receipt === null ||
+            typeof receipt !== 'object' ||
+            typeof receipt.payload !== 'object' ||
+            receipt.payload === null ||
+            typeof receipt.signature !== 'object' ||
+            receipt.signature === null) {
+            issues.push({
+                index,
+                code: 'malformed-receipt',
+                message: `entry #${index} is not a signed receipt (missing payload/signature) — a foreign or corrupted log line`,
+            });
+            return;
+        }
+        const id = receipt.id;
+        // 1. Per-receipt signature (chain fields, when present, are signed).
+        if (!(0, sign_1.verifyReceipt)(receipt, options.expectedSigner)) {
+            issues.push({
+                index,
+                receiptId: id,
+                code: 'signature-invalid',
+                message: `receipt ${id ?? `#${index}`} failed ES256K signature verification${options.expectedSigner ? ` against signer ${options.expectedSigner}` : ''}`,
+            });
+        }
+        // 2. Chain fields present?
+        const chain = receipt.payload.chain;
+        if (!chain) {
+            unchained += 1;
+            if (prev !== undefined) {
+                // Never tolerated, even with allowUnchained: after the first chained
+                // receipt every line must chain, or any validly signed chain-less
+                // receipt could be inserted/appended without detection.
+                issues.push({
+                    index,
+                    receiptId: id,
+                    code: 'unchained-after-chained',
+                    message: `receipt ${id ?? `#${index}`} has no chain fields but follows chained receipts — an inserted or appended line (pre-chaining receipts can only form a prefix)`,
+                });
+            }
+            else if (!options.allowUnchained) {
+                issues.push({
+                    index,
+                    receiptId: id,
+                    code: 'missing-chain-fields',
+                    message: `receipt ${id ?? `#${index}`} has no chain fields — deletion or reordering around it is undetectable (re-run with allowUnchained to tolerate a pre-chaining prefix)`,
+                });
+            }
+            return;
+        }
+        chained += 1;
+        // 3. Link check against the previous CHAINED receipt.
+        const actualHash = computeReceiptHash(receipt);
+        if (prev === undefined) {
+            if (chain.seq !== 0 || chain.prevReceiptHash !== exports.GENESIS_PREV_RECEIPT_HASH) {
+                issues.push({
+                    index,
+                    receiptId: id,
+                    code: 'genesis-mismatch',
+                    message: `first chained receipt has seq ${chain.seq} and prevReceiptHash ${chain.prevReceiptHash} — expected seq 0 with the genesis sentinel; receipts before it were likely deleted (head truncation)`,
+                });
+            }
+        }
+        else if (chain.seq === 0 && chain.prevReceiptHash === exports.GENESIS_PREV_RECEIPT_HASH) {
+            issues.push({
+                index,
+                receiptId: id,
+                code: 'chain-restart',
+                message: `receipt ${id ?? `#${index}`} starts a new chain (seq 0, genesis sentinel) mid-log — writer restart or spliced logs; verify each chain from its own log file`,
+            });
+        }
+        else {
+            if (chain.seq !== prev.seq + 1) {
+                issues.push({
+                    index,
+                    receiptId: id,
+                    code: 'seq-mismatch',
+                    message: `receipt ${id ?? `#${index}`} has seq ${chain.seq}, expected ${prev.seq + 1} — receipts were deleted, reordered, or skipped`,
+                });
+            }
+            if (chain.prevReceiptHash !== prev.hash) {
+                issues.push({
+                    index,
+                    receiptId: id,
+                    code: 'prev-hash-mismatch',
+                    message: `receipt ${id ?? `#${index}`} prevReceiptHash does not match the preceding receipt's hash — the log was altered between them (deleted, reordered, or inserted lines)`,
+                });
+            }
+        }
+        // 4. Stored convenience hash, if present, must agree with the recomputed one.
+        if (receipt.receiptHash !== undefined && receipt.receiptHash !== actualHash) {
+            issues.push({
+                index,
+                receiptId: id,
+                code: 'receipt-hash-mismatch',
+                message: `receipt ${id ?? `#${index}`} carries receiptHash ${receipt.receiptHash}, but its content hashes to ${actualHash}`,
+            });
+        }
+        prev = { seq: chain.seq, hash: actualHash };
+        headHash = actualHash;
+    });
+    // 5. External expectations — the only way to detect tail truncation.
+    if (options.expectedCount !== undefined && receipts.length !== options.expectedCount) {
+        issues.push({
+            index: -1,
+            code: 'count-mismatch',
+            message: `log holds ${receipts.length} receipts, expected ${options.expectedCount}${receipts.length < options.expectedCount ? ' — consistent with tail truncation' : ''}`,
+        });
+    }
+    if (options.expectedHeadHash !== undefined && headHash !== options.expectedHeadHash) {
+        issues.push({
+            index: -1,
+            code: 'head-hash-mismatch',
+            message: `last chained receipt hashes to ${headHash ?? '(none)'}, expected head ${options.expectedHeadHash} — consistent with tail truncation or a diverged log`,
+        });
+    }
+    return {
+        ok: issues.length === 0,
+        total: receipts.length,
+        chained,
+        unchained,
+        issues,
+        headHash,
+    };
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { canonicalize } from './canonical';
 export { createAuthReceipt, createCommerceReceipt } from './receipt';
 export { signReceipt, verifyReceipt, hashPayload } from './sign';
-export type { ReceiptPayload, SignedReceipt, ReceiptSignerConfig, AuthReceiptInput, CommerceReceiptInput, CommerceFields, } from './types';
+export { GENESIS_PREV_RECEIPT_HASH, ReceiptChain, computeReceiptHash, verifyReceiptChain, } from './chain';
+export type { ReceiptChainIssue, ReceiptChainIssueCode, ChainVerifyOptions, ChainVerifyResult, } from './chain';
+export type { ReceiptPayload, ReceiptChainFields, SignedReceipt, ReceiptSignerConfig, AuthReceiptInput, CommerceReceiptInput, CommerceFields, } from './types';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hashPayload = exports.verifyReceipt = exports.signReceipt = exports.createCommerceReceipt = exports.createAuthReceipt = exports.canonicalize = void 0;
+exports.verifyReceiptChain = exports.computeReceiptHash = exports.ReceiptChain = exports.GENESIS_PREV_RECEIPT_HASH = exports.hashPayload = exports.verifyReceipt = exports.signReceipt = exports.createCommerceReceipt = exports.createAuthReceipt = exports.canonicalize = void 0;
 var canonical_1 = require("./canonical");
 Object.defineProperty(exports, "canonicalize", { enumerable: true, get: function () { return canonical_1.canonicalize; } });
 var receipt_1 = require("./receipt");
@@ -10,3 +10,8 @@ var sign_1 = require("./sign");
 Object.defineProperty(exports, "signReceipt", { enumerable: true, get: function () { return sign_1.signReceipt; } });
 Object.defineProperty(exports, "verifyReceipt", { enumerable: true, get: function () { return sign_1.verifyReceipt; } });
 Object.defineProperty(exports, "hashPayload", { enumerable: true, get: function () { return sign_1.hashPayload; } });
+var chain_1 = require("./chain");
+Object.defineProperty(exports, "GENESIS_PREV_RECEIPT_HASH", { enumerable: true, get: function () { return chain_1.GENESIS_PREV_RECEIPT_HASH; } });
+Object.defineProperty(exports, "ReceiptChain", { enumerable: true, get: function () { return chain_1.ReceiptChain; } });
+Object.defineProperty(exports, "computeReceiptHash", { enumerable: true, get: function () { return chain_1.computeReceiptHash; } });
+Object.defineProperty(exports, "verifyReceiptChain", { enumerable: true, get: function () { return chain_1.verifyReceiptChain; } });

package/dist/types.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Optional hash-chain fields linking a receipt to its predecessor in a log.
+ * Additive and backward-compatible: chain-less receipts remain valid, and
+ * chained receipts still verify with the plain per-receipt verifyReceipt().
+ * Living inside the signed payload, these fields cannot be rewritten without
+ * breaking the ES256K signature.
+ */
+export interface ReceiptChainFields {
+    /** 0-based, monotonic position in the log (per writer process). */
+    seq: number;
+    /**
+     * computeReceiptHash() of the previous receipt in the log;
+     * GENESIS_PREV_RECEIPT_HASH (32 zero bytes) for the first receipt.
+     */
+    prevReceiptHash: string;
+}
 export interface ReceiptPayload {
     v: 1;
     kind: 'bolyra.auth' | 'bolyra.commerce';
@@ -38,6 +54,8 @@ export interface ReceiptPayload {
     };
     /** Present only when kind === 'bolyra.commerce'. */
     commerce?: CommerceFields;
+    /** Present only on hash-chained receipts (written via ReceiptChain). */
+    chain?: ReceiptChainFields;
 }
 export interface SignedReceipt {
     /** First 16 hex chars of payloadHash. */
@@ -53,6 +71,13 @@ export interface SignedReceipt {
         /** r (32 bytes) + s (32 bytes) + v (1 byte) = 65 bytes (hex). */
         value: string;
     };
+    /**
+     * Convenience copy of computeReceiptHash(this) — keccak256 over the
+     * canonical { payload, signature }. Present on hash-chained receipts; the
+     * next receipt's payload.chain.prevReceiptHash equals it. Verifiers must
+     * recompute rather than trust it (verifyReceiptChain does).
+     */
+    receiptHash?: string;
 }
 export interface ReceiptSignerConfig {
     issuer: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bolyra/receipts",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Signed auth receipts for Bolyra ZKP verification decisions — canonical JSON, secp256k1 sign/verify, EVM-compatible r||s||v signatures.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/chain.ts

@@ -0,0 +1,293 @@
+/**
+ * Receipt hash-chaining — whole-log integrity on top of per-receipt signatures.
+ *
+ * Individual receipts are ES256K-signed and tamper-evident on their own; a log
+ * of receipts is not — deleting or reordering whole lines leaves every
+ * remaining signature valid. Chaining closes that gap:
+ *
+ * - Each chained receipt carries `payload.chain = { seq, prevReceiptHash }`.
+ *   These fields live INSIDE the signed payload, so they cannot be rewritten
+ *   after the fact without breaking the signature.
+ * - `seq` is 0-based and monotonic per log (per writer process).
+ * - `prevReceiptHash` is the previous receipt's canonical hash; the first
+ *   receipt in a log uses the documented sentinel GENESIS_PREV_RECEIPT_HASH
+ *   (32 zero bytes, hex).
+ * - `receiptHash` is attached to the signed-receipt ENVELOPE as a convenience:
+ *   keccak256 over canonicalize({ payload, signature }) — it commits to both
+ *   the payload and the exact signature bytes, and excludes `id` and the
+ *   `receiptHash` field itself. Verifiers never trust it: verifyReceiptChain
+ *   recomputes it and only flags a stored value that disagrees.
+ *
+ * Backward compatibility: all fields are additive. Chain-less receipts keep
+ * signing and verifying exactly as before, chained receipts verify with the
+ * existing per-receipt verifyReceipt(), and chain verification is a separate
+ * step (verifyReceiptChain).
+ *
+ * What chain verification can and cannot detect (be precise with auditors):
+ * - DETECTABLE from the log alone: edits to any receipt (signature), deleted
+ *   lines (prev-hash/seq break), reordered lines, inserted lines, head
+ *   truncation (log no longer starts at genesis), a restarted chain spliced
+ *   into the same file.
+ * - NOT detectable from the log alone: truncation from the TAIL — a chain cut
+ *   after any receipt is still internally consistent. Detecting it requires
+ *   external knowledge: the expected receipt count (expectedCount) or the
+ *   expected head hash (expectedHeadHash), e.g. from a periodically anchored
+ *   checkpoint. Anchoring/checkpoint cadence is deployment policy
+ *   (enterprise-configurable), not part of this library.
+ */
+
+import { keccak_256 } from '@noble/hashes/sha3';
+import { bytesToHex } from '@noble/hashes/utils';
+import { canonicalize } from './canonical';
+import { signReceipt, verifyReceipt } from './sign';
+import type { ReceiptPayload, ReceiptSignerConfig, SignedReceipt } from './types';
+
+/** Sentinel prevReceiptHash for the first receipt in a log: 32 zero bytes. */
+export const GENESIS_PREV_RECEIPT_HASH = '0x' + '0'.repeat(64);
+
+/**
+ * Canonical hash of a signed receipt: keccak256 over
+ * canonicalize({ payload, signature }). Excludes `id` (derivable from
+ * signature.payloadHash) and `receiptHash` itself (to avoid self-reference).
+ */
+export function computeReceiptHash(receipt: SignedReceipt): string {
+  const canonical = canonicalize({ payload: receipt.payload, signature: receipt.signature });
+  return '0x' + bytesToHex(keccak_256(new TextEncoder().encode(canonical)));
+}
+
+/**
+ * Stateful writer-side chain: assigns { seq, prevReceiptHash } to each payload
+ * before signing and attaches the resulting receiptHash to the envelope.
+ *
+ * One ReceiptChain per log. State lives with the writer process; a restart
+ * starts a new chain (seq 0, genesis sentinel) — write it to a new log file
+ * if the log must verify as a single chain.
+ *
+ * State advances when a receipt is SIGNED, not when it is durably written.
+ * This is deliberate: if a signed receipt is subsequently lost (a dropped
+ * write), the next receipt links across the gap and chain verification FAILS
+ * — which is the truthful outcome, because the log really is incomplete. A
+ * writer-acknowledged design (advance only after persistence) would instead
+ * make the surviving log verify clean and silently hide the loss.
+ */
+export class ReceiptChain {
+  private seq = 0;
+  private prevReceiptHash = GENESIS_PREV_RECEIPT_HASH;
+
+  /** Sign one payload as the next link. Advances state only on success. */
+  sign(payload: ReceiptPayload, config: ReceiptSignerConfig): SignedReceipt {
+    const chained: ReceiptPayload = {
+      ...payload,
+      chain: { seq: this.seq, prevReceiptHash: this.prevReceiptHash },
+    };
+    const receipt = signReceipt(chained, config);
+    const receiptHash = computeReceiptHash(receipt);
+    this.seq += 1;
+    this.prevReceiptHash = receiptHash;
+    return { ...receipt, receiptHash };
+  }
+}
+
+export type ReceiptChainIssueCode =
+  | 'malformed-receipt'
+  | 'signature-invalid'
+  | 'missing-chain-fields'
+  | 'unchained-after-chained'
+  | 'genesis-mismatch'
+  | 'chain-restart'
+  | 'seq-mismatch'
+  | 'prev-hash-mismatch'
+  | 'receipt-hash-mismatch'
+  | 'count-mismatch'
+  | 'head-hash-mismatch';
+
+export interface ReceiptChainIssue {
+  /** 0-based position in the log; -1 for log-level issues (count/head checks). */
+  index: number;
+  receiptId?: string;
+  code: ReceiptChainIssueCode;
+  message: string;
+}
+
+export interface ChainVerifyOptions {
+  /** Require every signature to recover to this address. */
+  expectedSigner?: string;
+  /**
+   * Externally known receipt count. Without it, truncation from the TAIL of
+   * the log is NOT detectable — a cut chain is still internally consistent.
+   */
+  expectedCount?: number;
+  /** Externally known (anchored) hash of the last receipt — same purpose. */
+  expectedHeadHash?: string;
+  /**
+   * Tolerate a PREFIX of receipts without chain fields (logs that predate
+   * chaining). Their signatures are still verified, but deletion/reordering
+   * among them is NOT detectable. Only the prefix is tolerated: a chain-less
+   * receipt appearing AFTER any chained receipt is always an issue
+   * ('unchained-after-chained') — otherwise any validly signed chain-less
+   * receipt could be spliced into or appended to a chained log undetected.
+   */
+  allowUnchained?: boolean;
+}
+
+export interface ChainVerifyResult {
+  ok: boolean;
+  total: number;
+  chained: number;
+  unchained: number;
+  issues: ReceiptChainIssue[];
+  /**
+   * Recomputed hash of the last chained receipt — pin/anchor this externally
+   * to make tail truncation detectable on the next verification.
+   */
+  headHash?: string;
+}
+
+/**
+ * Verify a receipt log as a hash chain: every signature AND the chain links.
+ * Receipts must be passed in log order.
+ */
+export function verifyReceiptChain(
+  receipts: SignedReceipt[],
+  options: ChainVerifyOptions = {},
+): ChainVerifyResult {
+  const issues: ReceiptChainIssue[] = [];
+  let chained = 0;
+  let unchained = 0;
+  let prev: { seq: number; hash: string } | undefined;
+  let headHash: string | undefined;
+
+  receipts.forEach((receipt, index) => {
+    // 0. Shape guard: collected logs can contain non-receipt entries (e.g.
+    // the gateway's tagged `unsigned: true` raw fallback records). Flag them
+    // as malformed instead of throwing on property access below.
+    if (
+      receipt === null ||
+      typeof receipt !== 'object' ||
+      typeof receipt.payload !== 'object' ||
+      receipt.payload === null ||
+      typeof receipt.signature !== 'object' ||
+      receipt.signature === null
+    ) {
+      issues.push({
+        index,
+        code: 'malformed-receipt',
+        message: `entry #${index} is not a signed receipt (missing payload/signature) — a foreign or corrupted log line`,
+      });
+      return;
+    }
+
+    const id = receipt.id;
+
+    // 1. Per-receipt signature (chain fields, when present, are signed).
+    if (!verifyReceipt(receipt, options.expectedSigner)) {
+      issues.push({
+        index,
+        receiptId: id,
+        code: 'signature-invalid',
+        message: `receipt ${id ?? `#${index}`} failed ES256K signature verification${options.expectedSigner ? ` against signer ${options.expectedSigner}` : ''}`,
+      });
+    }
+
+    // 2. Chain fields present?
+    const chain = receipt.payload.chain;
+    if (!chain) {
+      unchained += 1;
+      if (prev !== undefined) {
+        // Never tolerated, even with allowUnchained: after the first chained
+        // receipt every line must chain, or any validly signed chain-less
+        // receipt could be inserted/appended without detection.
+        issues.push({
+          index,
+          receiptId: id,
+          code: 'unchained-after-chained',
+          message: `receipt ${id ?? `#${index}`} has no chain fields but follows chained receipts — an inserted or appended line (pre-chaining receipts can only form a prefix)`,
+        });
+      } else if (!options.allowUnchained) {
+        issues.push({
+          index,
+          receiptId: id,
+          code: 'missing-chain-fields',
+          message: `receipt ${id ?? `#${index}`} has no chain fields — deletion or reordering around it is undetectable (re-run with allowUnchained to tolerate a pre-chaining prefix)`,
+        });
+      }
+      return;
+    }
+    chained += 1;
+
+    // 3. Link check against the previous CHAINED receipt.
+    const actualHash = computeReceiptHash(receipt);
+    if (prev === undefined) {
+      if (chain.seq !== 0 || chain.prevReceiptHash !== GENESIS_PREV_RECEIPT_HASH) {
+        issues.push({
+          index,
+          receiptId: id,
+          code: 'genesis-mismatch',
+          message: `first chained receipt has seq ${chain.seq} and prevReceiptHash ${chain.prevReceiptHash} — expected seq 0 with the genesis sentinel; receipts before it were likely deleted (head truncation)`,
+        });
+      }
+    } else if (chain.seq === 0 && chain.prevReceiptHash === GENESIS_PREV_RECEIPT_HASH) {
+      issues.push({
+        index,
+        receiptId: id,
+        code: 'chain-restart',
+        message: `receipt ${id ?? `#${index}`} starts a new chain (seq 0, genesis sentinel) mid-log — writer restart or spliced logs; verify each chain from its own log file`,
+      });
+    } else {
+      if (chain.seq !== prev.seq + 1) {
+        issues.push({
+          index,
+          receiptId: id,
+          code: 'seq-mismatch',
+          message: `receipt ${id ?? `#${index}`} has seq ${chain.seq}, expected ${prev.seq + 1} — receipts were deleted, reordered, or skipped`,
+        });
+      }
+      if (chain.prevReceiptHash !== prev.hash) {
+        issues.push({
+          index,
+          receiptId: id,
+          code: 'prev-hash-mismatch',
+          message: `receipt ${id ?? `#${index}`} prevReceiptHash does not match the preceding receipt's hash — the log was altered between them (deleted, reordered, or inserted lines)`,
+        });
+      }
+    }
+
+    // 4. Stored convenience hash, if present, must agree with the recomputed one.
+    if (receipt.receiptHash !== undefined && receipt.receiptHash !== actualHash) {
+      issues.push({
+        index,
+        receiptId: id,
+        code: 'receipt-hash-mismatch',
+        message: `receipt ${id ?? `#${index}`} carries receiptHash ${receipt.receiptHash}, but its content hashes to ${actualHash}`,
+      });
+    }
+
+    prev = { seq: chain.seq, hash: actualHash };
+    headHash = actualHash;
+  });
+
+  // 5. External expectations — the only way to detect tail truncation.
+  if (options.expectedCount !== undefined && receipts.length !== options.expectedCount) {
+    issues.push({
+      index: -1,
+      code: 'count-mismatch',
+      message: `log holds ${receipts.length} receipts, expected ${options.expectedCount}${receipts.length < options.expectedCount ? ' — consistent with tail truncation' : ''}`,
+    });
+  }
+  if (options.expectedHeadHash !== undefined && headHash !== options.expectedHeadHash) {
+    issues.push({
+      index: -1,
+      code: 'head-hash-mismatch',
+      message: `last chained receipt hashes to ${headHash ?? '(none)'}, expected head ${options.expectedHeadHash} — consistent with tail truncation or a diverged log`,
+    });
+  }
+
+  return {
+    ok: issues.length === 0,
+    total: receipts.length,
+    chained,
+    unchained,
+    issues,
+    headHash,
+  };
+}

package/src/index.ts

@@ -1,8 +1,21 @@
 export { canonicalize } from './canonical';
 export { createAuthReceipt, createCommerceReceipt } from './receipt';
 export { signReceipt, verifyReceipt, hashPayload } from './sign';
+export {
+  GENESIS_PREV_RECEIPT_HASH,
+  ReceiptChain,
+  computeReceiptHash,
+  verifyReceiptChain,
+} from './chain';
+export type {
+  ReceiptChainIssue,
+  ReceiptChainIssueCode,
+  ChainVerifyOptions,
+  ChainVerifyResult,
+} from './chain';
 export type {
   ReceiptPayload,
+  ReceiptChainFields,
   SignedReceipt,
   ReceiptSignerConfig,
   AuthReceiptInput,

package/src/types.ts

@@ -1,3 +1,20 @@
+/**
+ * Optional hash-chain fields linking a receipt to its predecessor in a log.
+ * Additive and backward-compatible: chain-less receipts remain valid, and
+ * chained receipts still verify with the plain per-receipt verifyReceipt().
+ * Living inside the signed payload, these fields cannot be rewritten without
+ * breaking the ES256K signature.
+ */
+export interface ReceiptChainFields {
+  /** 0-based, monotonic position in the log (per writer process). */
+  seq: number;
+  /**
+   * computeReceiptHash() of the previous receipt in the log;
+   * GENESIS_PREV_RECEIPT_HASH (32 zero bytes) for the first receipt.
+   */
+  prevReceiptHash: string;
+}
+
 export interface ReceiptPayload {
   v: 1;
   kind: 'bolyra.auth' | 'bolyra.commerce';
@@ -42,6 +59,9 @@ export interface ReceiptPayload {
 
   /** Present only when kind === 'bolyra.commerce'. */
   commerce?: CommerceFields;
+
+  /** Present only on hash-chained receipts (written via ReceiptChain). */
+  chain?: ReceiptChainFields;
 }
 
 export interface SignedReceipt {
@@ -58,6 +78,13 @@ export interface SignedReceipt {
     /** r (32 bytes) + s (32 bytes) + v (1 byte) = 65 bytes (hex). */
     value: string;
   };
+  /**
+   * Convenience copy of computeReceiptHash(this) — keccak256 over the
+   * canonical { payload, signature }. Present on hash-chained receipts; the
+   * next receipt's payload.chain.prevReceiptHash equals it. Verifiers must
+   * recompute rather than trust it (verifyReceiptChain does).
+   */
+  receiptHash?: string;
 }
 
 export interface ReceiptSignerConfig {