@paybond/kit 0.12.5 → 0.12.6

package/dist/agent-receipt-pef.js

@@ -0,0 +1,121 @@
+/**
+ * Payment Evidence Frame (PEF) wrapper for agent-receipt audit handoff.
+ *
+ * Inspired by draft-hopley-x402-payment-evidence-frame: content-addressed
+ * `frame_id` over JCS(preimage), with `claim_type=paybond_agent_receipt_v1`.
+ * ARS core signing stays `ed25519-sha256-json-v1`; this adapter owns JCS.
+ *
+ * RFC 9421 detached signatures are reserved (`signature` extension point) and
+ * not populated by the builder in this release.
+ */
+import { createHash } from "node:crypto";
+/** PEF claim taxonomy for Paybond agent receipts (interop adapter). */
+export const PEF_CLAIM_TYPE_AGENT_RECEIPT_V1 = "paybond_agent_receipt_v1";
+/** Canonicalisation URN pinned by the x402 PEF substrate. */
+export const PEF_CANON_VERSION_JCS_RFC8785_V1 = "urn:x402:canonicalisation:jcs-rfc8785-v1";
+export const PEF_VERSION_V1 = "1";
+/** Inner receipt format label carried in the PEF envelope. */
+export const PEF_RECEIPT_FORMAT_AGENT_RECEIPT_V1 = "paybond.agent_receipt_v1";
+function canonicalizeJson(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalizeJson(item));
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        const keys = Object.keys(record).sort();
+        const out = {};
+        for (const key of keys) {
+            out[key] = canonicalizeJson(record[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/** Returns RFC 8785 JCS bytes for an arbitrary JSON value. */
+export function jcsCanonicalBytes(value) {
+    return new TextEncoder().encode(JSON.stringify(canonicalizeJson(value)));
+}
+function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+function sha256Prefixed(hexDigest) {
+    return `sha256:${hexDigest}`;
+}
+/**
+ * Computes `receipt_hash = sha256:` + hex(SHA-256(JCS(receipt))).
+ */
+export function agentReceiptPefReceiptHash(receipt) {
+    return sha256Prefixed(sha256Hex(jcsCanonicalBytes(receipt)));
+}
+/**
+ * Builds the PEF preimage object (excludes `frame_id` and `signature`).
+ */
+export function agentReceiptPefPreimage(input, receiptHash) {
+    const provider = input.frameProviderDid.trim();
+    if (!provider) {
+        throw new Error("pef: frame_provider_did is required");
+    }
+    if (!Number.isInteger(input.frameTimestampMs) || input.frameTimestampMs < 0) {
+        throw new Error("pef: frame_timestamp_ms must be a non-negative integer");
+    }
+    return {
+        canon_version: PEF_CANON_VERSION_JCS_RFC8785_V1,
+        claim_type: PEF_CLAIM_TYPE_AGENT_RECEIPT_V1,
+        frame_provider_did: provider,
+        frame_timestamp_ms: input.frameTimestampMs,
+        pef_version: PEF_VERSION_V1,
+        receipt: input.receipt,
+        receipt_format: PEF_RECEIPT_FORMAT_AGENT_RECEIPT_V1,
+        receipt_hash: receiptHash,
+    };
+}
+/**
+ * Derives `frame_id = sha256:` + hex(SHA-256(JCS(preimage))).
+ */
+export function agentReceiptPefFrameId(preimage) {
+    return sha256Prefixed(sha256Hex(jcsCanonicalBytes(preimage)));
+}
+/**
+ * Builds a content-addressed PEF wrapper around an ARS receipt.
+ *
+ * Does not modify or re-sign the inner ARS envelope.
+ */
+export function buildAgentReceiptPefFrame(input) {
+    const receiptHash = agentReceiptPefReceiptHash(input.receipt);
+    const preimage = agentReceiptPefPreimage(input, receiptHash);
+    const frameId = agentReceiptPefFrameId(preimage);
+    return {
+        canon_version: PEF_CANON_VERSION_JCS_RFC8785_V1,
+        claim_type: PEF_CLAIM_TYPE_AGENT_RECEIPT_V1,
+        frame_id: frameId,
+        frame_provider_did: String(preimage.frame_provider_did),
+        frame_timestamp_ms: input.frameTimestampMs,
+        pef_version: PEF_VERSION_V1,
+        receipt: input.receipt,
+        receipt_format: PEF_RECEIPT_FORMAT_AGENT_RECEIPT_V1,
+        receipt_hash: receiptHash,
+    };
+}
+/**
+ * Recomputes `frame_id` / `receipt_hash` and checks they match the frame.
+ *
+ * @throws Error when hashes do not match
+ */
+export function verifyAgentReceiptPefFrameId(frame) {
+    const expectedReceiptHash = agentReceiptPefReceiptHash(frame.receipt);
+    if (frame.receipt_hash !== expectedReceiptHash) {
+        throw new Error("pef: receipt_hash mismatch");
+    }
+    const preimage = agentReceiptPefPreimage({
+        receipt: frame.receipt,
+        frameProviderDid: frame.frame_provider_did,
+        frameTimestampMs: frame.frame_timestamp_ms,
+    }, expectedReceiptHash);
+    const expectedFrameId = agentReceiptPefFrameId(preimage);
+    if (frame.frame_id !== expectedFrameId) {
+        throw new Error("pef: frame_id mismatch");
+    }
+    if (frame.claim_type !== PEF_CLAIM_TYPE_AGENT_RECEIPT_V1) {
+        throw new Error("pef: unexpected claim_type");
+    }
+}

package/dist/agent-receipt-scitt.d.ts

@@ -0,0 +1,50 @@
+/**
+ * SCITT COSE_Sign1 export adapter for verified ARS digests.
+ *
+ * Wraps the ARS `message_digest_sha256` as a COSE_Sign1 Signed Statement
+ * payload suitable for registration with an external Transparency Service.
+ * ARS itself stays JSON-native; this adapter does not change compose/sign.
+ *
+ * Implements a minimal deterministic CBOR encoder for EdDSA COSE_Sign1
+ * (RFC 9052) without introducing a large COSE dependency.
+ */
+/** Export envelope kind for Kit/Go/Rust parity. */
+export declare const AGENT_RECEIPT_SCITT_EXPORT_KIND_V1 = "paybond.agent_receipt_scitt_export_v1";
+/** Statement kind encoded as the COSE_Sign1 payload (JCS JSON bytes). */
+export declare const AGENT_RECEIPT_SCITT_STATEMENT_KIND_V1 = "paybond.agent_receipt_scitt_statement_v1";
+/** COSE algorithm identifier for EdDSA (RFC 9053). */
+export declare const COSE_ALG_EDDSA = -8;
+export type AgentReceiptScittStatementV1 = {
+    kind: typeof AGENT_RECEIPT_SCITT_STATEMENT_KIND_V1;
+    receipt_id: string;
+    message_digest_sha256_hex: string;
+};
+export type BuildAgentReceiptScittExportInput = {
+    receiptId: string;
+    messageDigestSha256Hex: string;
+    /** 32-byte Ed25519 seed or PKCS8-compatible raw seed via Node crypto. */
+    signingPrivateKeySeedHex: string;
+    /** Issuer claim (iss) for SCITT CWT claims. */
+    issuer: string;
+    /** Optional key id placed in protected header `kid`. */
+    kid?: string;
+};
+export type AgentReceiptScittExportV1 = {
+    kind: typeof AGENT_RECEIPT_SCITT_EXPORT_KIND_V1;
+    receipt_id: string;
+    message_digest_sha256_hex: string;
+    signing_public_key_ed25519_hex: string;
+    issuer: string;
+    kid?: string;
+    /** Tagged COSE_Sign1 (CBOR tag 18) as lowercase hex. */
+    cose_sign1_tag18_hex: string;
+    statement: AgentReceiptScittStatementV1;
+};
+/**
+ * Builds a SCITT-oriented COSE_Sign1 export for a verified ARS message digest.
+ */
+export declare function buildAgentReceiptScittExport(input: BuildAgentReceiptScittExportInput): AgentReceiptScittExportV1;
+/**
+ * Verifies a SCITT export envelope: COSE_Sign1 EdDSA over the statement payload.
+ */
+export declare function verifyAgentReceiptScittExport(exportDoc: AgentReceiptScittExportV1): void;

package/dist/agent-receipt-scitt.js

@@ -0,0 +1,382 @@
+/**
+ * SCITT COSE_Sign1 export adapter for verified ARS digests.
+ *
+ * Wraps the ARS `message_digest_sha256` as a COSE_Sign1 Signed Statement
+ * payload suitable for registration with an external Transparency Service.
+ * ARS itself stays JSON-native; this adapter does not change compose/sign.
+ *
+ * Implements a minimal deterministic CBOR encoder for EdDSA COSE_Sign1
+ * (RFC 9052) without introducing a large COSE dependency.
+ */
+import { createPrivateKey, createPublicKey, sign as nodeSign, verify as nodeVerify } from "node:crypto";
+import { ensureEd25519Sha512Sync } from "./ed25519-sync.js";
+/** Export envelope kind for Kit/Go/Rust parity. */
+export const AGENT_RECEIPT_SCITT_EXPORT_KIND_V1 = "paybond.agent_receipt_scitt_export_v1";
+/** Statement kind encoded as the COSE_Sign1 payload (JCS JSON bytes). */
+export const AGENT_RECEIPT_SCITT_STATEMENT_KIND_V1 = "paybond.agent_receipt_scitt_statement_v1";
+/** COSE algorithm identifier for EdDSA (RFC 9053). */
+export const COSE_ALG_EDDSA = -8;
+/** COSE header label: alg. */
+const COSE_HEADER_ALG = 1;
+/** COSE header label: kid. */
+const COSE_HEADER_KID = 4;
+/** COSE header label: CWT Claims (RFC 9597). */
+const COSE_HEADER_CWT_CLAIMS = 15;
+/** CWT claim: iss. */
+const CWT_CLAIM_ISS = 1;
+/** CWT claim: sub. */
+const CWT_CLAIM_SUB = 2;
+function canonicalizeJson(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalizeJson(item));
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        const keys = Object.keys(record).sort();
+        const out = {};
+        for (const key of keys) {
+            out[key] = canonicalizeJson(record[key]);
+        }
+        return out;
+    }
+    return value;
+}
+function jcsBytes(value) {
+    return new TextEncoder().encode(JSON.stringify(canonicalizeJson(value)));
+}
+function requireHex64(value, field) {
+    const normalized = value.trim().toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(normalized)) {
+        throw new Error(`scitt export: ${field} must be a lowercase 64-char hex digest`);
+    }
+    return normalized;
+}
+function hexToBytes(hex) {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i += 1) {
+        out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+function bytesToHex(bytes) {
+    return Buffer.from(bytes).toString("hex");
+}
+function concatBytes(...parts) {
+    const total = parts.reduce((sum, part) => sum + part.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function encodeCborUint(value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error("scitt export: CBOR uint must be a non-negative integer");
+    }
+    if (value < 24) {
+        return Uint8Array.of(value);
+    }
+    if (value < 0x100) {
+        return Uint8Array.of(24, value);
+    }
+    if (value < 0x10000) {
+        return Uint8Array.of(25, (value >> 8) & 0xff, value & 0xff);
+    }
+    if (value < 0x100000000) {
+        return Uint8Array.of(26, (value >>> 24) & 0xff, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff);
+    }
+    throw new Error("scitt export: CBOR uint too large");
+}
+function encodeCborNint(value) {
+    // Major type 1: -1 - n
+    const n = -1 - value;
+    if (n < 24) {
+        return Uint8Array.of(0x20 | n);
+    }
+    if (n < 0x100) {
+        return Uint8Array.of(0x38, n);
+    }
+    if (n < 0x10000) {
+        return Uint8Array.of(0x39, (n >> 8) & 0xff, n & 0xff);
+    }
+    throw new Error("scitt export: CBOR nint too large");
+}
+function encodeCborInt(value) {
+    if (!Number.isInteger(value)) {
+        throw new Error("scitt export: CBOR int must be an integer");
+    }
+    return value >= 0 ? encodeCborUint(value) : encodeCborNint(value);
+}
+function encodeCborBstr(bytes) {
+    const header = bytes.length < 24
+        ? Uint8Array.of(0x40 | bytes.length)
+        : bytes.length < 0x100
+            ? Uint8Array.of(0x58, bytes.length)
+            : bytes.length < 0x10000
+                ? Uint8Array.of(0x59, (bytes.length >> 8) & 0xff, bytes.length & 0xff)
+                : (() => {
+                    throw new Error("scitt export: CBOR bstr too large");
+                })();
+    return concatBytes(header, bytes);
+}
+function encodeCborTstr(value) {
+    const bytes = new TextEncoder().encode(value);
+    const header = bytes.length < 24
+        ? Uint8Array.of(0x60 | bytes.length)
+        : bytes.length < 0x100
+            ? Uint8Array.of(0x78, bytes.length)
+            : bytes.length < 0x10000
+                ? Uint8Array.of(0x79, (bytes.length >> 8) & 0xff, bytes.length & 0xff)
+                : (() => {
+                    throw new Error("scitt export: CBOR tstr too large");
+                })();
+    return concatBytes(header, bytes);
+}
+function encodeCborArray(items) {
+    const header = items.length < 24
+        ? Uint8Array.of(0x80 | items.length)
+        : Uint8Array.of(0x98, items.length);
+    return concatBytes(header, ...items);
+}
+function encodeCborMap(entries) {
+    // Deterministic: sort by encoded key bytes (RFC 8949 §4.2.1).
+    const encoded = entries.map(([key, value]) => {
+        const keyBytes = typeof key === "number" ? encodeCborInt(key) : encodeCborTstr(key);
+        return { keyBytes, value };
+    });
+    encoded.sort((a, b) => {
+        const min = Math.min(a.keyBytes.length, b.keyBytes.length);
+        for (let i = 0; i < min; i += 1) {
+            const diff = a.keyBytes[i] - b.keyBytes[i];
+            if (diff !== 0) {
+                return diff;
+            }
+        }
+        return a.keyBytes.length - b.keyBytes.length;
+    });
+    const header = encoded.length < 24
+        ? Uint8Array.of(0xa0 | encoded.length)
+        : Uint8Array.of(0xb8, encoded.length);
+    return concatBytes(header, ...encoded.flatMap((entry) => [entry.keyBytes, entry.value]));
+}
+function encodeCborTag(tag, item) {
+    const header = tag < 24
+        ? Uint8Array.of(0xc0 | tag)
+        : tag < 0x100
+            ? Uint8Array.of(0xd8, tag)
+            : (() => {
+                throw new Error("scitt export: CBOR tag too large");
+            })();
+    return concatBytes(header, item);
+}
+function ed25519KeyFromSeed(seedHex) {
+    const seed = hexToBytes(requireHex64(seedHex, "signing_private_key_seed_hex"));
+    const privateKey = createPrivateKey({
+        key: Buffer.concat([
+            Buffer.from("302e020100300506032b657004220420", "hex"),
+            Buffer.from(seed),
+        ]),
+        format: "der",
+        type: "pkcs8",
+    });
+    const pub = createPublicKey(privateKey).export({ type: "spki", format: "der" });
+    return {
+        privateKey,
+        publicKeyHex: pub.subarray(pub.length - 32).toString("hex"),
+    };
+}
+function buildProtectedHeader(issuer, subject, kid) {
+    const cwtClaims = encodeCborMap([
+        [CWT_CLAIM_ISS, encodeCborTstr(issuer)],
+        [CWT_CLAIM_SUB, encodeCborTstr(subject)],
+    ]);
+    const entries = [
+        [COSE_HEADER_ALG, encodeCborInt(COSE_ALG_EDDSA)],
+        [COSE_HEADER_CWT_CLAIMS, cwtClaims],
+    ];
+    if (kid && kid.trim()) {
+        entries.push([COSE_HEADER_KID, encodeCborTstr(kid.trim())]);
+    }
+    return encodeCborMap(entries);
+}
+/**
+ * Builds a SCITT-oriented COSE_Sign1 export for a verified ARS message digest.
+ */
+export function buildAgentReceiptScittExport(input) {
+    ensureEd25519Sha512Sync();
+    const receiptId = input.receiptId.trim();
+    if (!receiptId) {
+        throw new Error("scitt export: receipt_id is required");
+    }
+    const issuer = input.issuer.trim();
+    if (!issuer) {
+        throw new Error("scitt export: issuer is required");
+    }
+    const messageDigest = requireHex64(input.messageDigestSha256Hex, "message_digest_sha256_hex");
+    const statement = {
+        kind: AGENT_RECEIPT_SCITT_STATEMENT_KIND_V1,
+        receipt_id: receiptId,
+        message_digest_sha256_hex: messageDigest,
+    };
+    const payload = jcsBytes(statement);
+    // SCITT subject is receipt_id; iss is the configured issuer.
+    const protectedHeader = buildProtectedHeader(issuer, receiptId, input.kid);
+    const protectedBstr = encodeCborBstr(protectedHeader);
+    const payloadBstr = encodeCborBstr(payload);
+    const sigStructure = encodeCborArray([
+        encodeCborTstr("Signature1"),
+        protectedBstr,
+        encodeCborBstr(new Uint8Array(0)),
+        payloadBstr,
+    ]);
+    const { privateKey, publicKeyHex } = ed25519KeyFromSeed(input.signingPrivateKeySeedHex);
+    const signature = nodeSign(null, Buffer.from(sigStructure), privateKey);
+    const coseSign1 = encodeCborArray([
+        encodeCborBstr(protectedHeader),
+        encodeCborMap([]),
+        encodeCborBstr(payload),
+        encodeCborBstr(new Uint8Array(signature)),
+    ]);
+    const tagged = encodeCborTag(18, coseSign1);
+    const exportDoc = {
+        kind: AGENT_RECEIPT_SCITT_EXPORT_KIND_V1,
+        receipt_id: receiptId,
+        message_digest_sha256_hex: messageDigest,
+        signing_public_key_ed25519_hex: publicKeyHex,
+        issuer,
+        cose_sign1_tag18_hex: bytesToHex(tagged),
+        statement,
+    };
+    if (input.kid?.trim()) {
+        exportDoc.kid = input.kid.trim();
+    }
+    return exportDoc;
+}
+function readCborLength(bytes, offset, additional) {
+    if (additional < 24) {
+        return { length: additional, next: offset };
+    }
+    if (additional === 24) {
+        return { length: bytes[offset], next: offset + 1 };
+    }
+    if (additional === 25) {
+        return {
+            length: (bytes[offset] << 8) | bytes[offset + 1],
+            next: offset + 2,
+        };
+    }
+    throw new Error("scitt export: unsupported CBOR length");
+}
+function decodeCborItem(bytes, offset) {
+    const initial = bytes[offset];
+    const major = initial >> 5;
+    const additional = initial & 0x1f;
+    let cursor = offset + 1;
+    if (major === 0) {
+        const { length, next } = readCborLength(bytes, cursor, additional);
+        return { value: length, next, raw: bytes.subarray(offset, next) };
+    }
+    if (major === 1) {
+        const { length, next } = readCborLength(bytes, cursor, additional);
+        return { value: -1 - length, next, raw: bytes.subarray(offset, next) };
+    }
+    if (major === 2 || major === 3) {
+        const { length, next } = readCborLength(bytes, cursor, additional);
+        const end = next + length;
+        const slice = bytes.subarray(next, end);
+        return {
+            value: major === 2 ? slice : new TextDecoder().decode(slice),
+            next: end,
+            raw: bytes.subarray(offset, end),
+        };
+    }
+    if (major === 4) {
+        const { length, next } = readCborLength(bytes, cursor, additional);
+        cursor = next;
+        const items = [];
+        const start = offset;
+        for (let i = 0; i < length; i += 1) {
+            const decoded = decodeCborItem(bytes, cursor);
+            items.push(decoded.value);
+            cursor = decoded.next;
+        }
+        return { value: items, next: cursor, raw: bytes.subarray(start, cursor) };
+    }
+    if (major === 5) {
+        const { length, next } = readCborLength(bytes, cursor, additional);
+        cursor = next;
+        const map = new Map();
+        const start = offset;
+        for (let i = 0; i < length; i += 1) {
+            const key = decodeCborItem(bytes, cursor);
+            const val = decodeCborItem(bytes, key.next);
+            map.set(key.value, val.value);
+            cursor = val.next;
+        }
+        return { value: map, next: cursor, raw: bytes.subarray(start, cursor) };
+    }
+    if (major === 6) {
+        const { length: tag, next } = readCborLength(bytes, cursor, additional);
+        const inner = decodeCborItem(bytes, next);
+        return {
+            value: { tag, value: inner.value },
+            next: inner.next,
+            raw: bytes.subarray(offset, inner.next),
+        };
+    }
+    throw new Error(`scitt export: unsupported CBOR major type ${major}`);
+}
+function decodeTaggedCoseSign1(taggedHex) {
+    const bytes = hexToBytes(taggedHex.trim().toLowerCase());
+    const decoded = decodeCborItem(bytes, 0);
+    const tagged = decoded.value;
+    if (!tagged || tagged.tag !== 18 || !Array.isArray(tagged.value) || tagged.value.length !== 4) {
+        throw new Error("scitt export: expected CBOR tag 18 COSE_Sign1 array");
+    }
+    const [protectedRaw, , payload, signature] = tagged.value;
+    if (!(protectedRaw instanceof Uint8Array) || !(payload instanceof Uint8Array) || !(signature instanceof Uint8Array)) {
+        throw new Error("scitt export: COSE_Sign1 fields must be bstrs");
+    }
+    return { protectedRaw, payload, signature };
+}
+/**
+ * Verifies a SCITT export envelope: COSE_Sign1 EdDSA over the statement payload.
+ */
+export function verifyAgentReceiptScittExport(exportDoc) {
+    ensureEd25519Sha512Sync();
+    if (exportDoc.kind !== AGENT_RECEIPT_SCITT_EXPORT_KIND_V1) {
+        throw new Error("scitt export: unexpected kind");
+    }
+    const digest = requireHex64(exportDoc.message_digest_sha256_hex, "message_digest_sha256_hex");
+    if (exportDoc.statement.message_digest_sha256_hex !== digest) {
+        throw new Error("scitt export: statement digest mismatch");
+    }
+    if (exportDoc.statement.receipt_id !== exportDoc.receipt_id) {
+        throw new Error("scitt export: statement receipt_id mismatch");
+    }
+    const expectedPayload = jcsBytes(exportDoc.statement);
+    const { protectedRaw, payload, signature } = decodeTaggedCoseSign1(exportDoc.cose_sign1_tag18_hex);
+    if (bytesToHex(payload) !== bytesToHex(expectedPayload)) {
+        throw new Error("scitt export: COSE payload mismatch");
+    }
+    const sigStructure = encodeCborArray([
+        encodeCborTstr("Signature1"),
+        encodeCborBstr(protectedRaw),
+        encodeCborBstr(new Uint8Array(0)),
+        encodeCborBstr(payload),
+    ]);
+    const pub = createPublicKey({
+        key: Buffer.concat([
+            Buffer.from("302a300506032b6570032100", "hex"),
+            Buffer.from(hexToBytes(requireHex64(exportDoc.signing_public_key_ed25519_hex, "signing_public_key_ed25519_hex"))),
+        ]),
+        format: "der",
+        type: "spki",
+    });
+    const ok = nodeVerify(null, Buffer.from(sigStructure), pub, Buffer.from(signature));
+    if (!ok) {
+        throw new Error("scitt export: COSE_Sign1 signature invalid");
+    }
+}

package/dist/agent-receipt.d.ts

@@ -10,6 +10,13 @@ export declare const AGENT_RECEIPT_SIGNING_KEYS_WELL_KNOWN_PATH = "/.well-known/
 export declare const PAYBOND_AGENT_RECEIPT_ATTESTATIONS_HEADER = "x-paybond-agent-receipt-attestations";
 /** Optional agent run id bound to the attestation header for server-side audit. */
 export declare const PAYBOND_AGENT_RECEIPT_SOURCE_RUN_HEADER = "x-paybond-agent-run-id";
+/** AP2 signed-mandate digest kind promoted into authorization.mandate_digest_sha256_hex. */
+export declare const EXTERNAL_ATTESTATION_KIND_AGENT_MANDATE_V1 = "agent_mandate_v1";
+export declare const SETTLEMENT_OUTCOME_SETTLED = "SETTLED";
+export declare const SETTLEMENT_OUTCOME_PENDING_FINALITY = "PENDING_FINALITY";
+export declare const SETTLEMENT_OUTCOME_REVERSED = "REVERSED";
+export declare const SETTLEMENT_OUTCOME_FAILED = "FAILED";
+export type AgentReceiptSettlementOutcome = typeof SETTLEMENT_OUTCOME_SETTLED | typeof SETTLEMENT_OUTCOME_PENDING_FINALITY | typeof SETTLEMENT_OUTCOME_REVERSED | typeof SETTLEMENT_OUTCOME_FAILED;
 export type AgentReceiptAgentV1 = {
     operator_did: string;
     model_family: string;
@@ -35,6 +42,10 @@ export type AgentReceiptAuthorizationV1 = {
     requested_spend_cents: number;
     currency: string;
     reason_codes?: string[];
+    mandate_digest_sha256_hex?: string;
+    mandate_reference_id?: string;
+    /** Reserved ZK policy-compliance proof digest — schema-ready; not emitted by compose yet. */
+    zk_policy_proof_digest_sha256_hex?: string;
 };
 export type AgentReceiptExecutionV1 = {
     run_id: string;
@@ -47,6 +58,8 @@ export type AgentReceiptExecutionV1 = {
     started_at: string;
     completed_at: string;
     duration_ms?: number;
+    /** Reserved TEE attestation digest — schema-ready; not emitted by compose yet. */
+    tee_attestation_digest_sha256_hex?: string;
 };
 export type AgentReceiptMerchantV1 = {
     payee_did: string;
@@ -72,6 +85,8 @@ export type AgentReceiptOutcomeV1 = {
     harbor_state: string;
     spend_reservation_outcome?: "consumed" | "released" | "pending" | "none";
     predicate_passed?: boolean;
+    /** Categorical settlement claim for intent_terminal scope only. */
+    settlement_outcome?: AgentReceiptSettlementOutcome;
 };
 export type AgentReceiptReferencesV1 = {
     intent_id: string;
@@ -90,6 +105,15 @@ export type AgentReceiptOperatorAttestationV1 = {
     message_digest_sha256_hex: string;
     ed25519_signature_hex: string;
 };
+export type AgentReceiptContinuityV1 = {
+    prev_message_digest_sha256_hex?: string;
+    sequence_number: number;
+    run_id: string;
+};
+export declare const AGENT_RECEIPT_VALIDITY_TIER_OPERATIONAL = "operational";
+export declare const AGENT_RECEIPT_VALIDITY_TIER_PRIMARY = "primary";
+export declare const AGENT_RECEIPT_VALIDITY_TIER_ATTESTED = "attested";
+export type AgentReceiptValidityTier = typeof AGENT_RECEIPT_VALIDITY_TIER_OPERATIONAL | typeof AGENT_RECEIPT_VALIDITY_TIER_PRIMARY | typeof AGENT_RECEIPT_VALIDITY_TIER_ATTESTED;
 export type AgentReceiptV1 = {
     schema_version: number;
     kind: string;
@@ -106,6 +130,7 @@ export type AgentReceiptV1 = {
     outcome: AgentReceiptOutcomeV1;
     references: AgentReceiptReferencesV1;
     external_attestations: AgentReceiptExternalAttestationV1[];
+    continuity?: AgentReceiptContinuityV1;
     operator_attestation?: AgentReceiptOperatorAttestationV1;
     signing_algorithm: string;
     message_digest_sha256_hex: string;
@@ -141,11 +166,41 @@ export type VerifyAgentReceiptV1Options = {
      * When true, require any operator_attestation signing key to appear in
      * trustedOperatorPublicKeys (e.g. tenant middleware attach recognition keys). The
      * operator_did binding to authorization.agent.operator_did is always enforced.
+     *
+     * For `trustMode: "tenant_registry"`, defaults to true when an operator_attestation
+     * is present (empty trusted set rejects the attestation). Gateway JWKS / gateway
+     * trust mode leaves this opt-in.
      */
     verifyOperatorAgainstRegistry?: boolean;
     /** Lowercase operator signing pubkeys accepted when the registry check is enabled. */
     trustedOperatorPublicKeys?: readonly string[];
+    /**
+     * Mirror of Gateway `?trust_mode=`. `tenant_registry` defaults operator registry
+     * checks on when an operator_attestation is present.
+     */
+    trustMode?: "gateway" | "tenant_registry";
+    /**
+     * Required validity tier: `operational` (default), `primary`, or `attested`.
+     * `attested` forces operator registry checks.
+     */
+    requiredValidityTier?: AgentReceiptValidityTier | string;
+    /**
+     * When set, require `continuity.prev_message_digest_sha256_hex` to equal this digest.
+     */
+    expectedPriorMessageDigestHex?: string;
 };
+/** Returns the highest validity tier met under the given registry options. */
+export declare function achievedValidityTier(receipt: AgentReceiptV1, options?: Pick<VerifyAgentReceiptV1Options, "trustedOperatorPublicKeys">): AgentReceiptValidityTier;
+/**
+ * Builds the next continuity link from a prior signed action receipt for the same run.
+ * When `prior` is omitted, returns sequence 1 with no prev digest.
+ */
+export declare function continuityFromPrior(runId: string, prior?: AgentReceiptV1 | null): AgentReceiptContinuityV1;
+/**
+ * Validates an ordered set of action receipts that declare continuity.
+ * Receipts without continuity are ignored. Broken links fail closed.
+ */
+export declare function verifyContinuityChain(receipts: readonly AgentReceiptV1[]): void;
 /** Validates structure, receipt_id derivation, digest, and detached Ed25519 signature. */
 export declare function verifyAgentReceiptV1(receipt: AgentReceiptV1, options?: VerifyAgentReceiptV1Options): Promise<AgentReceiptV1>;
 /** Validate raw JSON (schema + forbidden fields) then verify signature. */