@bolyra/receipts 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { canonicalize } from './canonical';
-export { createAuthReceipt } from './receipt';
+export { createAuthReceipt, createCommerceReceipt } from './receipt';
 export { signReceipt, verifyReceipt, hashPayload } from './sign';
-export type { ReceiptPayload, SignedReceipt, ReceiptSignerConfig, AuthReceiptInput, } from './types';
+export type { ReceiptPayload, SignedReceipt, ReceiptSignerConfig, AuthReceiptInput, CommerceReceiptInput, CommerceFields, } from './types';

package/dist/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hashPayload = exports.verifyReceipt = exports.signReceipt = exports.createAuthReceipt = exports.canonicalize = void 0;
+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");
 Object.defineProperty(exports, "createAuthReceipt", { enumerable: true, get: function () { return receipt_1.createAuthReceipt; } });
+Object.defineProperty(exports, "createCommerceReceipt", { enumerable: true, get: function () { return receipt_1.createCommerceReceipt; } });
 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; } });

package/dist/receipt.d.ts

@@ -1,5 +1,10 @@
-import type { AuthReceiptInput, ReceiptPayload } from './types';
+import type { AuthReceiptInput, CommerceReceiptInput, ReceiptPayload } from './types';
 export declare function createAuthReceipt(input: AuthReceiptInput, config: {
     issuer: string;
     keyId: string;
+    issuedAt?: number;
+}): ReceiptPayload;
+export declare function createCommerceReceipt(input: CommerceReceiptInput, config: {
+    issuer: string;
+    keyId: string;
 }): ReceiptPayload;

package/dist/receipt.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAuthReceipt = createAuthReceipt;
+exports.createCommerceReceipt = createCommerceReceipt;
 const sha256_1 = require("@noble/hashes/sha256");
 const utils_1 = require("@noble/hashes/utils");
 const canonical_1 = require("./canonical");
@@ -18,7 +19,7 @@ function createAuthReceipt(input, config) {
     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: {
@@ -44,3 +45,11 @@ function createAuthReceipt(input, config) {
         },
     };
 }
+function createCommerceReceipt(input, config) {
+    const base = createAuthReceipt(input, config);
+    return {
+        ...base,
+        kind: 'bolyra.commerce',
+        commerce: input.commerce,
+    };
+}

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 export interface ReceiptPayload {
     v: 1;
-    kind: 'bolyra.auth';
+    kind: 'bolyra.auth' | 'bolyra.commerce';
     /** Unix seconds when the decision was made. */
     issuedAt: number;
     /** Server identifier. */
@@ -36,6 +36,8 @@ export interface ReceiptPayload {
         /** SHA-256 of canonical JSON of delegationChain (if v=2). */
         delegationChainHash?: string;
     };
+    /** Present only when kind === 'bolyra.commerce'. */
+    commerce?: CommerceFields;
 }
 export interface SignedReceipt {
     /** First 16 hex chars of payloadHash. */
@@ -58,6 +60,13 @@ export interface ReceiptSignerConfig {
     /** secp256k1 private key, 32 bytes, hex-encoded, 0x-prefixed. */
     privateKey: string;
 }
+export interface CommerceFields {
+    rail: string;
+    amount: number;
+    currency: string;
+    merchant: string;
+    intentHash: string;
+}
 export interface AuthReceiptInput {
     /** From BolyraAuthContext or equivalent. */
     rootDid: string;
@@ -82,3 +91,6 @@ export interface AuthReceiptInput {
     nonce: string;
     delegationChain?: unknown[];
 }
+export interface CommerceReceiptInput extends AuthReceiptInput {
+    commerce: CommerceFields;
+}

package/dist/verify-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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.7.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/index.ts

@@ -1,9 +1,11 @@
 export { canonicalize } from './canonical';
-export { createAuthReceipt } from './receipt';
+export { createAuthReceipt, createCommerceReceipt } from './receipt';
 export { signReceipt, verifyReceipt, hashPayload } from './sign';
 export type {
   ReceiptPayload,
   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,
+  };
+}

package/src/types.ts

@@ -1,6 +1,6 @@
 export interface ReceiptPayload {
   v: 1;
-  kind: 'bolyra.auth';
+  kind: 'bolyra.auth' | 'bolyra.commerce';
   /** Unix seconds when the decision was made. */
   issuedAt: number;
   /** Server identifier. */
@@ -39,6 +39,9 @@ export interface ReceiptPayload {
     /** SHA-256 of canonical JSON of delegationChain (if v=2). */
     delegationChainHash?: string;
   };
+
+  /** Present only when kind === 'bolyra.commerce'. */
+  commerce?: CommerceFields;
 }
 
 export interface SignedReceipt {
@@ -64,6 +67,14 @@ export interface ReceiptSignerConfig {
   privateKey: string;
 }
 
+export interface CommerceFields {
+  rail: string;
+  amount: number;
+  currency: string;
+  merchant: string;
+  intentHash: string;
+}
+
 export interface AuthReceiptInput {
   /** From BolyraAuthContext or equivalent. */
   rootDid: string;
@@ -84,3 +95,7 @@ export interface AuthReceiptInput {
   nonce: string;
   delegationChain?: unknown[];
 }
+
+export interface CommerceReceiptInput extends AuthReceiptInput {
+  commerce: CommerceFields;
+}

package/src/verify-cli.ts

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+
+import * as fs from 'fs';
+import * as process from 'process';
+import { verifyReceipt, hashPayload } from './sign';
+import type { SignedReceipt } from './types';
+
+// --- Helpers ---
+
+function usage(): string {
+  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: string): never {
+  process.stderr.write(msg + '\n');
+  process.exit(2);
+}
+
+function truncate(hex: string): string {
+  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: string | undefined;
+let expectedSigner: string | undefined;
+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: string;
+try {
+  if (useStdin) {
+    rawJson = fs.readFileSync(0, 'utf-8');
+  } else {
+    rawJson = fs.readFileSync(filePath!, 'utf-8');
+  }
+} catch (err: unknown) {
+  const msg = err instanceof Error ? err.message : String(err);
+  fail(`Cannot read input: ${msg}`);
+}
+
+let receipt: SignedReceipt;
+try {
+  receipt = JSON.parse(rawJson);
+} catch {
+  fail('Invalid JSON');
+}
+
+// --- Checks ---
+
+const checks: string[] = [];
+let failed = false;
+
+function pass(msg: string): void {
+  checks.push(`\u2713 ${msg}`);
+}
+
+function failCheck(msg: string): void {
+  checks.push(`\u2717 ${msg}`);
+  failed = true;
+}
+
+// 1. Schema validation
+function validateSchema(): boolean {
+  const p = receipt.payload;
+  const s = receipt.signature;
+  const errors: string[] = [];
+
+  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'] as const) {
+      if (typeof (p.subject as any)[k] !== 'string' || !(p.subject as any)[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'] as const) {
+      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 as any).commerce) {
+    errors.push('auth receipt must not contain commerce fields');
+  }
+  if (p.kind === 'bolyra.commerce') {
+    const c = (p as any).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(): void {
+  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(): boolean {
+  const computed = 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(): void {
+  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(): void {
+  const ok = 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);
+}