@bolyra/receipts 0.6.0

package/dist/canonical.d.ts

@@ -0,0 +1 @@
+export declare function canonicalize(obj: unknown): string;

package/dist/canonical.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalize = canonicalize;
+function canonicalize(obj) {
+    return JSON.stringify(obj, (_key, value) => {
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            return Object.keys(value).sort().reduce((sorted, k) => {
+                sorted[k] = value[k];
+                return sorted;
+            }, {});
+        }
+        return value;
+    });
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hashPayload = exports.verifyReceipt = exports.signReceipt = 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; } });
+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; } });

package/dist/receipt.d.ts

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

package/dist/receipt.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAuthReceipt = createAuthReceipt;
+const sha256_1 = require("@noble/hashes/sha256");
+const utils_1 = require("@noble/hashes/utils");
+const canonical_1 = require("./canonical");
+function sha256Hex(data) {
+    const encoder = new TextEncoder();
+    return (0, utils_1.bytesToHex)((0, sha256_1.sha256)(encoder.encode(data)));
+}
+function createAuthReceipt(input, config) {
+    const humanProofHash = sha256Hex((0, canonical_1.canonicalize)(input.humanProof.proof));
+    const agentProofHash = sha256Hex((0, canonical_1.canonicalize)(input.agentProof.proof));
+    const publicSignalsHash = sha256Hex((0, canonical_1.canonicalize)([...input.humanPublicSignals, ...input.agentPublicSignals]));
+    const delegationChainHash = input.delegationChain
+        ? sha256Hex((0, canonical_1.canonicalize)(input.delegationChain))
+        : undefined;
+    return {
+        v: 1,
+        kind: 'bolyra.auth',
+        issuedAt: Math.floor(Date.now() / 1000),
+        issuer: config.issuer,
+        keyId: config.keyId,
+        subject: {
+            rootDid: input.rootDid,
+            actingDid: input.actingDid,
+            credentialCommitment: input.credentialCommitment,
+            effectiveCommitment: input.effectiveCommitment,
+        },
+        decision: {
+            allowed: input.allowed,
+            ...(input.reasonCode !== undefined && { reasonCode: input.reasonCode }),
+            score: input.score,
+            permissionBitmask: input.permissionBitmask,
+            chainDepth: input.chainDepth,
+        },
+        proof: {
+            bundleVersion: input.bundleVersion,
+            nonce: input.nonce,
+            humanProofHash,
+            agentProofHash,
+            publicSignalsHash,
+            ...(delegationChainHash !== undefined && { delegationChainHash }),
+        },
+    };
+}

package/dist/sign.d.ts

@@ -0,0 +1,4 @@
+import type { ReceiptPayload, ReceiptSignerConfig, SignedReceipt } from './types';
+export declare function hashPayload(payload: ReceiptPayload): string;
+export declare function signReceipt(payload: ReceiptPayload, config: ReceiptSignerConfig): SignedReceipt;
+export declare function verifyReceipt(receipt: SignedReceipt, expectedSigner?: string): boolean;

package/dist/sign.js

@@ -0,0 +1,144 @@
+"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 });
+exports.hashPayload = hashPayload;
+exports.signReceipt = signReceipt;
+exports.verifyReceipt = verifyReceipt;
+const secp256k1 = __importStar(require("@noble/secp256k1"));
+const hmac_1 = require("@noble/hashes/hmac");
+const sha256_1 = require("@noble/hashes/sha256");
+const sha3_1 = require("@noble/hashes/sha3");
+const utils_1 = require("@noble/hashes/utils");
+const canonical_1 = require("./canonical");
+// @noble/secp256k1 v2 requires hmacSha256Sync to be set for synchronous signing.
+secp256k1.etc.hmacSha256Sync = (k, ...m) => {
+    const h = hmac_1.hmac.create(sha256_1.sha256, k);
+    for (const msg of m)
+        h.update(msg);
+    return h.digest();
+};
+function hexToBytes(hex) {
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+function utf8ToBytes(str) {
+    return new TextEncoder().encode(str);
+}
+function deriveAddress(publicKeyBytes) {
+    // Uncompressed public key is 65 bytes (04 || x || y).
+    // For Ethereum address we hash the 64-byte x||y (skip the 04 prefix).
+    const uncompressed = publicKeyBytes.length === 65
+        ? publicKeyBytes.slice(1)
+        : publicKeyBytes;
+    const hash = (0, sha3_1.keccak_256)(uncompressed);
+    return '0x' + (0, utils_1.bytesToHex)(hash.slice(hash.length - 20));
+}
+function hashPayload(payload) {
+    const canonical = (0, canonical_1.canonicalize)(payload);
+    const hash = (0, sha3_1.keccak_256)(utf8ToBytes(canonical));
+    return '0x' + (0, utils_1.bytesToHex)(hash);
+}
+function signReceipt(payload, config) {
+    const canonical = (0, canonical_1.canonicalize)(payload);
+    const hash = (0, sha3_1.keccak_256)(utf8ToBytes(canonical));
+    const privateKeyBytes = hexToBytes(config.privateKey);
+    const sig = secp256k1.sign(hash, privateKeyBytes);
+    const r = sig.r.toString(16).padStart(64, '0');
+    const s = sig.s.toString(16).padStart(64, '0');
+    const v = (sig.recovery + 27).toString(16).padStart(2, '0');
+    const signatureHex = '0x' + r + s + v;
+    const publicKey = secp256k1.getPublicKey(privateKeyBytes, false);
+    const signer = deriveAddress(publicKey);
+    const payloadHash = '0x' + (0, utils_1.bytesToHex)(hash);
+    const id = '0x' + payloadHash.slice(2, 18);
+    return {
+        id,
+        payload,
+        signature: {
+            alg: 'ES256K',
+            keyId: config.keyId,
+            signer,
+            payloadHash,
+            value: signatureHex,
+        },
+    };
+}
+function verifyReceipt(receipt, expectedSigner) {
+    try {
+        // Recompute hash from payload
+        const canonical = (0, canonical_1.canonicalize)(receipt.payload);
+        const hash = (0, sha3_1.keccak_256)(utf8ToBytes(canonical));
+        const recomputedHash = '0x' + (0, utils_1.bytesToHex)(hash);
+        // Check hash matches
+        if (recomputedHash !== receipt.signature.payloadHash) {
+            return false;
+        }
+        // Extract r, s, v from 65-byte signature
+        const sigHex = receipt.signature.value.startsWith('0x')
+            ? receipt.signature.value.slice(2)
+            : receipt.signature.value;
+        const rHex = sigHex.slice(0, 64);
+        const sHex = sigHex.slice(64, 128);
+        const vByte = parseInt(sigHex.slice(128, 130), 16);
+        const recoveryBit = vByte - 27;
+        // Recover public key
+        const rs = rHex + sHex;
+        const recovered = secp256k1.Signature
+            .fromCompact(rs)
+            .addRecoveryBit(recoveryBit)
+            .recoverPublicKey(hash);
+        const recoveredAddress = deriveAddress(recovered.toRawBytes(false));
+        // Always check recovered address matches the claimed signer in the receipt.
+        // Without this, an attacker can change receipt.signature.signer to any
+        // address and verifyReceipt still returns true.
+        const claimedSigner = receipt.signature.signer.toLowerCase();
+        const actual = recoveredAddress.toLowerCase();
+        if (claimedSigner !== actual) {
+            return false;
+        }
+        // Optional: also check against an externally expected signer
+        if (expectedSigner && expectedSigner.toLowerCase() !== actual) {
+            return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+export interface ReceiptPayload {
+    v: 1;
+    kind: 'bolyra.auth';
+    /** Unix seconds when the decision was made. */
+    issuedAt: number;
+    /** Server identifier. */
+    issuer: string;
+    /** Signing key identifier for rotation. */
+    keyId: string;
+    subject: {
+        /** Root credential DID. */
+        rootDid: string;
+        /** Acting agent DID (leaf of delegation chain, or root if no chain). */
+        actingDid: string;
+        credentialCommitment: string;
+        effectiveCommitment: string;
+    };
+    decision: {
+        allowed: boolean;
+        reasonCode?: string;
+        score: number;
+        /** Decimal string to avoid BigInt serialization issues. */
+        permissionBitmask: string;
+        chainDepth: number;
+    };
+    proof: {
+        bundleVersion: 1 | 2;
+        /** Decimal string. */
+        nonce: string;
+        /** SHA-256 of canonical JSON of humanProof.proof. */
+        humanProofHash: string;
+        /** SHA-256 of canonical JSON of agentProof.proof. */
+        agentProofHash: string;
+        /** SHA-256 of canonical JSON of all public signals (human + agent). */
+        publicSignalsHash: string;
+        /** SHA-256 of canonical JSON of delegationChain (if v=2). */
+        delegationChainHash?: string;
+    };
+}
+export interface SignedReceipt {
+    /** First 16 hex chars of payloadHash. */
+    id: string;
+    payload: ReceiptPayload;
+    signature: {
+        alg: 'ES256K';
+        keyId: string;
+        /** Ethereum address of the signer (hex, 0x-prefixed). */
+        signer: string;
+        /** keccak256 of canonical JSON payload (hex, 0x-prefixed). */
+        payloadHash: string;
+        /** r (32 bytes) + s (32 bytes) + v (1 byte) = 65 bytes (hex). */
+        value: string;
+    };
+}
+export interface ReceiptSignerConfig {
+    issuer: string;
+    keyId: string;
+    /** secp256k1 private key, 32 bytes, hex-encoded, 0x-prefixed. */
+    privateKey: string;
+}
+export interface AuthReceiptInput {
+    /** From BolyraAuthContext or equivalent. */
+    rootDid: string;
+    actingDid: string;
+    credentialCommitment: string;
+    effectiveCommitment: string;
+    allowed: boolean;
+    reasonCode?: string;
+    score: number;
+    permissionBitmask: string;
+    chainDepth: number;
+    /** Raw proof bundle for hashing. */
+    humanProof: {
+        proof: unknown;
+    };
+    agentProof: {
+        proof: unknown;
+    };
+    humanPublicSignals: string[];
+    agentPublicSignals: string[];
+    bundleVersion: 1 | 2;
+    nonce: string;
+    delegationChain?: unknown[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@bolyra/receipts",
+  "version": "0.6.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",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@noble/secp256k1": "^2.2.0",
+    "@noble/hashes": "^1.7.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^25.9.1",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.2.0",
+    "@types/jest": "^30.0.0"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bolyra/bolyra"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "bolyra",
+    "receipts",
+    "zkp",
+    "secp256k1",
+    "signed-receipts",
+    "auth"
+  ],
+  "license": "Apache-2.0"
+}

package/src/canonical.ts

@@ -0,0 +1,11 @@
+export function canonicalize(obj: unknown): string {
+  return JSON.stringify(obj, (_key, value) => {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      return Object.keys(value).sort().reduce((sorted, k) => {
+        sorted[k] = (value as Record<string, unknown>)[k];
+        return sorted;
+      }, {} as Record<string, unknown>);
+    }
+    return value;
+  });
+}

package/src/index.ts

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

package/src/receipt.ts

@@ -0,0 +1,52 @@
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex } from '@noble/hashes/utils';
+import { canonicalize } from './canonical';
+import type { AuthReceiptInput, ReceiptPayload } from './types';
+
+function sha256Hex(data: string): string {
+  const encoder = new TextEncoder();
+  return bytesToHex(sha256(encoder.encode(data)));
+}
+
+export function createAuthReceipt(
+  input: AuthReceiptInput,
+  config: { issuer: string; keyId: string },
+): ReceiptPayload {
+  const humanProofHash = sha256Hex(canonicalize(input.humanProof.proof));
+  const agentProofHash = sha256Hex(canonicalize(input.agentProof.proof));
+  const publicSignalsHash = sha256Hex(
+    canonicalize([...input.humanPublicSignals, ...input.agentPublicSignals]),
+  );
+  const delegationChainHash = input.delegationChain
+    ? sha256Hex(canonicalize(input.delegationChain))
+    : undefined;
+
+  return {
+    v: 1,
+    kind: 'bolyra.auth',
+    issuedAt: Math.floor(Date.now() / 1000),
+    issuer: config.issuer,
+    keyId: config.keyId,
+    subject: {
+      rootDid: input.rootDid,
+      actingDid: input.actingDid,
+      credentialCommitment: input.credentialCommitment,
+      effectiveCommitment: input.effectiveCommitment,
+    },
+    decision: {
+      allowed: input.allowed,
+      ...(input.reasonCode !== undefined && { reasonCode: input.reasonCode }),
+      score: input.score,
+      permissionBitmask: input.permissionBitmask,
+      chainDepth: input.chainDepth,
+    },
+    proof: {
+      bundleVersion: input.bundleVersion,
+      nonce: input.nonce,
+      humanProofHash,
+      agentProofHash,
+      publicSignalsHash,
+      ...(delegationChainHash !== undefined && { delegationChainHash }),
+    },
+  };
+}

package/src/sign.ts

@@ -0,0 +1,130 @@
+import * as secp256k1 from '@noble/secp256k1';
+import { hmac } from '@noble/hashes/hmac';
+import { sha256 } from '@noble/hashes/sha256';
+import { keccak_256 } from '@noble/hashes/sha3';
+import { bytesToHex } from '@noble/hashes/utils';
+import { canonicalize } from './canonical';
+import type { ReceiptPayload, ReceiptSignerConfig, SignedReceipt } from './types';
+
+// @noble/secp256k1 v2 requires hmacSha256Sync to be set for synchronous signing.
+secp256k1.etc.hmacSha256Sync = (k: Uint8Array, ...m: Uint8Array[]) => {
+  const h = hmac.create(sha256, k);
+  for (const msg of m) h.update(msg);
+  return h.digest();
+};
+
+function hexToBytes(hex: string): Uint8Array {
+  const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+function utf8ToBytes(str: string): Uint8Array {
+  return new TextEncoder().encode(str);
+}
+
+function deriveAddress(publicKeyBytes: Uint8Array): string {
+  // Uncompressed public key is 65 bytes (04 || x || y).
+  // For Ethereum address we hash the 64-byte x||y (skip the 04 prefix).
+  const uncompressed = publicKeyBytes.length === 65
+    ? publicKeyBytes.slice(1)
+    : publicKeyBytes;
+  const hash = keccak_256(uncompressed);
+  return '0x' + bytesToHex(hash.slice(hash.length - 20));
+}
+
+export function hashPayload(payload: ReceiptPayload): string {
+  const canonical = canonicalize(payload);
+  const hash = keccak_256(utf8ToBytes(canonical));
+  return '0x' + bytesToHex(hash);
+}
+
+export function signReceipt(
+  payload: ReceiptPayload,
+  config: ReceiptSignerConfig,
+): SignedReceipt {
+  const canonical = canonicalize(payload);
+  const hash = keccak_256(utf8ToBytes(canonical));
+  const privateKeyBytes = hexToBytes(config.privateKey);
+
+  const sig = secp256k1.sign(hash, privateKeyBytes);
+  const r = sig.r.toString(16).padStart(64, '0');
+  const s = sig.s.toString(16).padStart(64, '0');
+  const v = (sig.recovery + 27).toString(16).padStart(2, '0');
+  const signatureHex = '0x' + r + s + v;
+
+  const publicKey = secp256k1.getPublicKey(privateKeyBytes, false);
+  const signer = deriveAddress(publicKey);
+
+  const payloadHash = '0x' + bytesToHex(hash);
+  const id = '0x' + payloadHash.slice(2, 18);
+
+  return {
+    id,
+    payload,
+    signature: {
+      alg: 'ES256K',
+      keyId: config.keyId,
+      signer,
+      payloadHash,
+      value: signatureHex,
+    },
+  };
+}
+
+export function verifyReceipt(
+  receipt: SignedReceipt,
+  expectedSigner?: string,
+): boolean {
+  try {
+    // Recompute hash from payload
+    const canonical = canonicalize(receipt.payload);
+    const hash = keccak_256(utf8ToBytes(canonical));
+    const recomputedHash = '0x' + bytesToHex(hash);
+
+    // Check hash matches
+    if (recomputedHash !== receipt.signature.payloadHash) {
+      return false;
+    }
+
+    // Extract r, s, v from 65-byte signature
+    const sigHex = receipt.signature.value.startsWith('0x')
+      ? receipt.signature.value.slice(2)
+      : receipt.signature.value;
+
+    const rHex = sigHex.slice(0, 64);
+    const sHex = sigHex.slice(64, 128);
+    const vByte = parseInt(sigHex.slice(128, 130), 16);
+    const recoveryBit = vByte - 27;
+
+    // Recover public key
+    const rs = rHex + sHex;
+    const recovered = secp256k1.Signature
+      .fromCompact(rs)
+      .addRecoveryBit(recoveryBit)
+      .recoverPublicKey(hash);
+
+    const recoveredAddress = deriveAddress(recovered.toRawBytes(false));
+
+    // Always check recovered address matches the claimed signer in the receipt.
+    // Without this, an attacker can change receipt.signature.signer to any
+    // address and verifyReceipt still returns true.
+    const claimedSigner = receipt.signature.signer.toLowerCase();
+    const actual = recoveredAddress.toLowerCase();
+    if (claimedSigner !== actual) {
+      return false;
+    }
+
+    // Optional: also check against an externally expected signer
+    if (expectedSigner && expectedSigner.toLowerCase() !== actual) {
+      return false;
+    }
+
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/types.ts

@@ -0,0 +1,86 @@
+export interface ReceiptPayload {
+  v: 1;
+  kind: 'bolyra.auth';
+  /** Unix seconds when the decision was made. */
+  issuedAt: number;
+  /** Server identifier. */
+  issuer: string;
+  /** Signing key identifier for rotation. */
+  keyId: string;
+
+  subject: {
+    /** Root credential DID. */
+    rootDid: string;
+    /** Acting agent DID (leaf of delegation chain, or root if no chain). */
+    actingDid: string;
+    credentialCommitment: string;
+    effectiveCommitment: string;
+  };
+
+  decision: {
+    allowed: boolean;
+    reasonCode?: string;
+    score: number;
+    /** Decimal string to avoid BigInt serialization issues. */
+    permissionBitmask: string;
+    chainDepth: number;
+  };
+
+  proof: {
+    bundleVersion: 1 | 2;
+    /** Decimal string. */
+    nonce: string;
+    /** SHA-256 of canonical JSON of humanProof.proof. */
+    humanProofHash: string;
+    /** SHA-256 of canonical JSON of agentProof.proof. */
+    agentProofHash: string;
+    /** SHA-256 of canonical JSON of all public signals (human + agent). */
+    publicSignalsHash: string;
+    /** SHA-256 of canonical JSON of delegationChain (if v=2). */
+    delegationChainHash?: string;
+  };
+}
+
+export interface SignedReceipt {
+  /** First 16 hex chars of payloadHash. */
+  id: string;
+  payload: ReceiptPayload;
+  signature: {
+    alg: 'ES256K';
+    keyId: string;
+    /** Ethereum address of the signer (hex, 0x-prefixed). */
+    signer: string;
+    /** keccak256 of canonical JSON payload (hex, 0x-prefixed). */
+    payloadHash: string;
+    /** r (32 bytes) + s (32 bytes) + v (1 byte) = 65 bytes (hex). */
+    value: string;
+  };
+}
+
+export interface ReceiptSignerConfig {
+  issuer: string;
+  keyId: string;
+  /** secp256k1 private key, 32 bytes, hex-encoded, 0x-prefixed. */
+  privateKey: string;
+}
+
+export interface AuthReceiptInput {
+  /** From BolyraAuthContext or equivalent. */
+  rootDid: string;
+  actingDid: string;
+  credentialCommitment: string;
+  effectiveCommitment: string;
+  allowed: boolean;
+  reasonCode?: string;
+  score: number;
+  permissionBitmask: string;
+  chainDepth: number;
+  /** Raw proof bundle for hashing. */
+  humanProof: { proof: unknown };
+  agentProof: { proof: unknown };
+  humanPublicSignals: string[];
+  agentPublicSignals: string[];
+  bundleVersion: 1 | 2;
+  nonce: string;
+  delegationChain?: unknown[];
+}