@bolyra/receipts 0.6.0 → 0.8.0

package/dist/verify-cli.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const process = __importStar(require("process"));
+const sign_1 = require("./sign");
+// --- Helpers ---
+function usage() {
+    return `Usage: bolyra-receipt-verify <receipt.json> [options]
+
+Options:
+  --stdin               Read receipt JSON from stdin instead of a file
+  --signer <address>    Expected signer address (optional)
+  --max-age <seconds>   Maximum receipt age in seconds (default: 86400)
+  --help                Show this help`;
+}
+function fail(msg) {
+    process.stderr.write(msg + '\n');
+    process.exit(2);
+}
+function truncate(hex) {
+    if (hex.length <= 14)
+        return hex;
+    return hex.slice(0, 8) + '...' + hex.slice(-4);
+}
+// --- Arg parsing ---
+const args = process.argv.slice(2);
+if (args.includes('--help') || args.includes('-h')) {
+    console.log(usage());
+    process.exit(0);
+}
+let filePath;
+let expectedSigner;
+let maxAgeSeconds = 86400;
+let useStdin = false;
+for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--stdin') {
+        useStdin = true;
+    }
+    else if (arg === '--signer') {
+        expectedSigner = args[++i];
+        if (!expectedSigner)
+            fail('--signer requires an address argument');
+    }
+    else if (arg === '--max-age') {
+        const val = args[++i];
+        if (!val)
+            fail('--max-age requires a number argument');
+        maxAgeSeconds = parseInt(val, 10);
+        if (Number.isNaN(maxAgeSeconds) || maxAgeSeconds < 0) {
+            fail('--max-age must be a non-negative integer');
+        }
+    }
+    else if (arg.startsWith('-')) {
+        fail(`Unknown option: ${arg}\n\n${usage()}`);
+    }
+    else {
+        filePath = arg;
+    }
+}
+if (!filePath && !useStdin) {
+    fail(`No input specified. Provide a file path or use --stdin.\n\n${usage()}`);
+}
+// --- Read input ---
+let rawJson;
+try {
+    if (useStdin) {
+        rawJson = fs.readFileSync(0, 'utf-8');
+    }
+    else {
+        rawJson = fs.readFileSync(filePath, 'utf-8');
+    }
+}
+catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    fail(`Cannot read input: ${msg}`);
+}
+let receipt;
+try {
+    receipt = JSON.parse(rawJson);
+}
+catch {
+    fail('Invalid JSON');
+}
+// --- Checks ---
+const checks = [];
+let failed = false;
+function pass(msg) {
+    checks.push(`\u2713 ${msg}`);
+}
+function failCheck(msg) {
+    checks.push(`\u2717 ${msg}`);
+    failed = true;
+}
+// 1. Schema validation
+function validateSchema() {
+    const p = receipt.payload;
+    const s = receipt.signature;
+    const errors = [];
+    if (!p) {
+        errors.push('missing payload');
+    }
+    if (!s) {
+        errors.push('missing signature');
+    }
+    if (errors.length) {
+        failCheck(`Schema: ${errors.join(', ')}`);
+        return false;
+    }
+    if (p.v !== 1)
+        errors.push('payload.v !== 1');
+    if (p.kind !== 'bolyra.auth' && p.kind !== 'bolyra.commerce') {
+        errors.push('payload.kind must be "bolyra.auth" or "bolyra.commerce"');
+    }
+    if (typeof p.issuedAt !== 'number')
+        errors.push('payload.issuedAt not a number');
+    if (typeof p.issuer !== 'string' || !p.issuer)
+        errors.push('payload.issuer missing');
+    if (typeof p.keyId !== 'string' || !p.keyId)
+        errors.push('payload.keyId missing');
+    // subject
+    if (!p.subject) {
+        errors.push('payload.subject missing');
+    }
+    else {
+        for (const k of ['rootDid', 'actingDid', 'credentialCommitment', 'effectiveCommitment']) {
+            if (typeof p.subject[k] !== 'string' || !p.subject[k]) {
+                errors.push(`payload.subject.${k} missing or not a string`);
+            }
+        }
+    }
+    // decision
+    if (!p.decision) {
+        errors.push('payload.decision missing');
+    }
+    else {
+        if (typeof p.decision.allowed !== 'boolean')
+            errors.push('decision.allowed not boolean');
+        if (typeof p.decision.score !== 'number')
+            errors.push('decision.score not a number');
+        if (typeof p.decision.permissionBitmask !== 'string' || !p.decision.permissionBitmask)
+            errors.push('decision.permissionBitmask missing or not a string');
+        if (typeof p.decision.chainDepth !== 'number')
+            errors.push('decision.chainDepth not a number');
+    }
+    // proof
+    if (!p.proof) {
+        errors.push('payload.proof missing');
+    }
+    else {
+        for (const k of ['bundleVersion', 'nonce', 'humanProofHash', 'agentProofHash', 'publicSignalsHash']) {
+            if (!(k in p.proof))
+                errors.push(`proof.${k} missing`);
+        }
+    }
+    // commerce fields: required for bolyra.commerce, forbidden for bolyra.auth
+    if (p.kind === 'bolyra.auth' && p.commerce) {
+        errors.push('auth receipt must not contain commerce fields');
+    }
+    if (p.kind === 'bolyra.commerce') {
+        const c = p.commerce;
+        if (!c) {
+            errors.push('commerce fields missing for bolyra.commerce receipt');
+        }
+        else {
+            if (typeof c.rail !== 'string' || !c.rail)
+                errors.push('commerce.rail missing or not a string');
+            if (typeof c.amount !== 'number')
+                errors.push('commerce.amount not a number');
+            if (typeof c.currency !== 'string' || !c.currency)
+                errors.push('commerce.currency missing or not a string');
+            if (typeof c.merchant !== 'string')
+                errors.push('commerce.merchant not a string');
+            if (typeof c.intentHash !== 'string' || !/^[0-9a-fA-F]{64}$/.test(c.intentHash)) {
+                errors.push('commerce.intentHash must be a 64-char hex string');
+            }
+        }
+    }
+    // signature fields
+    if (s.alg !== 'ES256K')
+        errors.push('signature.alg !== "ES256K"');
+    if (s.keyId !== p.keyId)
+        errors.push('signature.keyId does not match payload.keyId');
+    if (!/^0x[0-9a-fA-F]{40}$/.test(s.signer ?? ''))
+        errors.push('signature.signer invalid format');
+    if (!/^0x[0-9a-fA-F]{64}$/.test(s.payloadHash ?? ''))
+        errors.push('signature.payloadHash invalid format');
+    if (!/^0x[0-9a-fA-F]{130}$/.test(s.value ?? ''))
+        errors.push('signature.value invalid format');
+    if (errors.length) {
+        failCheck(`Schema: ${errors.join('; ')}`);
+        return false;
+    }
+    pass('Schema valid');
+    return true;
+}
+// 2. Timestamp check
+function validateTimestamp() {
+    const nowSec = Math.floor(Date.now() / 1000);
+    const issuedAt = receipt.payload.issuedAt;
+    const allowFutureSeconds = 300;
+    const ageSec = nowSec - issuedAt;
+    const isoStr = new Date(issuedAt * 1000).toISOString();
+    if (issuedAt > nowSec + allowFutureSeconds) {
+        failCheck(`Timestamp: ${isoStr} is ${issuedAt - nowSec}s in the future (max skew: ${allowFutureSeconds}s)`);
+        return;
+    }
+    if (ageSec > maxAgeSeconds) {
+        failCheck(`Timestamp: ${isoStr} (${ageSec}s ago, max-age: ${maxAgeSeconds}s)`);
+        return;
+    }
+    pass(`Timestamp: ${isoStr} (${ageSec}s ago)`);
+}
+// 3. Hash check
+function validateHash() {
+    const computed = (0, sign_1.hashPayload)(receipt.payload);
+    if (computed !== receipt.signature.payloadHash) {
+        failCheck(`Payload hash mismatch (expected ${truncate(receipt.signature.payloadHash)}, got ${truncate(computed)})`);
+        return false;
+    }
+    pass('Payload hash matches');
+    return true;
+}
+// 4. ID check
+function validateId() {
+    const expected = '0x' + receipt.signature.payloadHash.slice(2, 18);
+    if (receipt.id !== expected) {
+        failCheck(`Receipt ID mismatch (expected ${expected}, got ${receipt.id})`);
+        return;
+    }
+    pass('Receipt ID matches');
+}
+// 5. Signature check
+function validateSignature() {
+    const ok = (0, sign_1.verifyReceipt)(receipt, expectedSigner);
+    if (!ok) {
+        failCheck(`Signature invalid${expectedSigner ? ` (expected signer: ${truncate(expectedSigner)})` : ''}`);
+        return;
+    }
+    pass(`Signature valid (signer: ${truncate(receipt.signature.signer)})`);
+}
+// --- Run checks ---
+if (validateSchema()) {
+    validateTimestamp();
+    if (validateHash()) {
+        validateId();
+        validateSignature();
+    }
+}
+// --- Output ---
+for (const line of checks) {
+    console.log(line);
+}
+if (failed) {
+    console.log('FAIL \u2014 receipt is invalid');
+    process.exit(1);
+}
+else {
+    console.log('PASS \u2014 receipt is valid');
+    process.exit(0);
+}

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@bolyra/receipts",
-  "version": "0.6.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",
+  "bin": {
+    "bolyra-receipt-verify": "dist/verify-cli.js"
+  },
   "scripts": {
     "build": "tsc",
+    "prepare": "tsc",
     "test": "jest --passWithNoTests",
     "typecheck": "tsc --noEmit"
   },

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,9 +1,24 @@
 export { canonicalize } from './canonical';
-export { createAuthReceipt } from './receipt';
+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,
+  CommerceReceiptInput,
+  CommerceFields,
 } from './types';

package/src/receipt.ts

@@ -1,7 +1,7 @@
 import { sha256 } from '@noble/hashes/sha256';
 import { bytesToHex } from '@noble/hashes/utils';
 import { canonicalize } from './canonical';
-import type { AuthReceiptInput, ReceiptPayload } from './types';
+import type { AuthReceiptInput, CommerceReceiptInput, ReceiptPayload } from './types';
 
 function sha256Hex(data: string): string {
   const encoder = new TextEncoder();
@@ -10,7 +10,7 @@ function sha256Hex(data: string): string {
 
 export function createAuthReceipt(
   input: AuthReceiptInput,
-  config: { issuer: string; keyId: string },
+  config: { issuer: string; keyId: string; issuedAt?: number },
 ): ReceiptPayload {
   const humanProofHash = sha256Hex(canonicalize(input.humanProof.proof));
   const agentProofHash = sha256Hex(canonicalize(input.agentProof.proof));
@@ -24,7 +24,7 @@ export function createAuthReceipt(
   return {
     v: 1,
     kind: 'bolyra.auth',
-    issuedAt: Math.floor(Date.now() / 1000),
+    issuedAt: config.issuedAt ?? Math.floor(Date.now() / 1000),
     issuer: config.issuer,
     keyId: config.keyId,
     subject: {
@@ -50,3 +50,15 @@ export function createAuthReceipt(
     },
   };
 }
+
+export function createCommerceReceipt(
+  input: CommerceReceiptInput,
+  config: { issuer: string; keyId: string },
+): ReceiptPayload {
+  const base = createAuthReceipt(input, config);
+  return {
+    ...base,
+    kind: 'bolyra.commerce',
+    commerce: input.commerce,
+  };
+}