@paybond/kit 0.12.4 → 0.12.6

package/dist/agent-receipt-inclusion.js

@@ -0,0 +1,209 @@
+import { createHash } from "node:crypto";
+import { verify } from "@noble/ed25519";
+import { ensureEd25519Sha512Sync } from "./ed25519-sync.js";
+import { AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519, } from "./agent-receipt.js";
+export const AGENT_RECEIPT_TRANSPARENCY_STH_KIND_V1 = "paybond.agent_receipt_transparency_sth_v1";
+export const AGENT_RECEIPT_TRANSPARENCY_INCLUSION_PROOF_KIND_V1 = "paybond.agent_receipt_transparency_inclusion_proof_v1";
+export const AGENT_RECEIPT_TRANSPARENCY_SCHEMA_VERSION = 1;
+const HEX64_RE = /^[0-9a-f]{64}$/;
+const HEX128_RE = /^[0-9a-f]{128}$/;
+function requireHex64(value, field) {
+    const normalized = value.trim().toLowerCase();
+    if (!HEX64_RE.test(normalized)) {
+        throw new Error(`agent receipt transparency: ${field} must be a lowercase 64-byte hex SHA-256 digest`);
+    }
+    return normalized;
+}
+function requireHex128(value, field) {
+    const normalized = value.trim().toLowerCase();
+    if (!HEX128_RE.test(normalized)) {
+        throw new Error(`agent receipt transparency: ${field} must be a lowercase 128-char hex Ed25519 signature`);
+    }
+    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 largestPowerOfTwoLessThan(n) {
+    if (n <= 1) {
+        return 0;
+    }
+    let k = 1;
+    while (k * 2 < n) {
+        k *= 2;
+    }
+    return k;
+}
+/** RFC 6962 leaf hash: SHA-256(0x00 || leafData). */
+export function merkleLeafHashRFC6962(leafData) {
+    return createHash("sha256").update(Buffer.from([0x00])).update(leafData).digest();
+}
+/** RFC 6962 internal node hash: SHA-256(0x01 || left || right). */
+export function merkleNodeHashRFC6962(left, right) {
+    return createHash("sha256")
+        .update(Buffer.from([0x01]))
+        .update(left)
+        .update(right)
+        .digest();
+}
+function reconstructMerkleRoot(leafHash, leafIndex, treeSize, auditPath) {
+    if (treeSize === 1) {
+        return { root: leafHash, consumed: 0 };
+    }
+    const k = largestPowerOfTwoLessThan(treeSize);
+    if (leafIndex < k) {
+        const left = reconstructMerkleRoot(leafHash, leafIndex, k, auditPath);
+        if (left.consumed >= auditPath.length) {
+            throw new Error("agent receipt transparency: audit path too short");
+        }
+        const right = auditPath[left.consumed];
+        return {
+            root: merkleNodeHashRFC6962(left.root, right),
+            consumed: left.consumed + 1,
+        };
+    }
+    const right = reconstructMerkleRoot(leafHash, leafIndex - k, treeSize - k, auditPath);
+    if (right.consumed >= auditPath.length) {
+        throw new Error("agent receipt transparency: audit path too short");
+    }
+    const left = auditPath[right.consumed];
+    return {
+        root: merkleNodeHashRFC6962(left, right.root),
+        consumed: right.consumed + 1,
+    };
+}
+function allowsSigningPublicKeyHex(keyHex, trusted) {
+    if (!trusted || trusted.length === 0) {
+        return true;
+    }
+    const normalized = keyHex.trim().toLowerCase();
+    return trusted.some((item) => item.trim().toLowerCase() === normalized);
+}
+function canonicalSthBytes(sth) {
+    const canonical = {
+        kind: AGENT_RECEIPT_TRANSPARENCY_STH_KIND_V1,
+        schema_version: AGENT_RECEIPT_TRANSPARENCY_SCHEMA_VERSION,
+        tenant_id: sth.tenant_id.trim(),
+        tree_size: sth.tree_size,
+        root_hash_sha256_hex: sth.root_hash_sha256_hex.trim().toLowerCase(),
+        issued_at: sth.issued_at.trim(),
+        signing_algorithm: AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519,
+    };
+    return Buffer.from(JSON.stringify(canonical), "utf8");
+}
+/** Verifies a signed tree head (digest + Ed25519). */
+export async function verifySignedTreeHeadV1(sth, options = {}) {
+    ensureEd25519Sha512Sync();
+    if (sth.kind !== AGENT_RECEIPT_TRANSPARENCY_STH_KIND_V1) {
+        throw new Error(`agent receipt transparency: kind must be ${AGENT_RECEIPT_TRANSPARENCY_STH_KIND_V1}`);
+    }
+    if (sth.schema_version !== AGENT_RECEIPT_TRANSPARENCY_SCHEMA_VERSION) {
+        throw new Error(`agent receipt transparency: schema_version must be ${AGENT_RECEIPT_TRANSPARENCY_SCHEMA_VERSION}`);
+    }
+    if (!sth.tenant_id?.trim()) {
+        throw new Error("agent receipt transparency: tenant_id is required");
+    }
+    if (!Number.isInteger(sth.tree_size) || sth.tree_size < 0) {
+        throw new Error("agent receipt transparency: tree_size must be a non-negative integer");
+    }
+    if (sth.signing_algorithm !== AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519) {
+        throw new Error(`agent receipt transparency: signing_algorithm must be ${AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519}`);
+    }
+    const rootHash = requireHex64(sth.root_hash_sha256_hex, "root_hash_sha256_hex");
+    const messageDigest = requireHex64(sth.message_digest_sha256_hex, "message_digest_sha256_hex");
+    const publicKeyHex = requireHex64(sth.signing_public_key_ed25519_hex, "signing_public_key_ed25519_hex");
+    if (!allowsSigningPublicKeyHex(publicKeyHex, options.expectedSigningPublicKeys)) {
+        throw new Error("agent receipt transparency: signing_public_key_ed25519_hex is not in the configured trusted key set");
+    }
+    const canonical = canonicalSthBytes({
+        ...sth,
+        root_hash_sha256_hex: rootHash,
+    });
+    const digest = createHash("sha256").update(canonical).digest();
+    if (bytesToHex(digest) !== messageDigest) {
+        throw new Error("agent receipt transparency: message digest mismatch");
+    }
+    const signature = hexToBytes(requireHex128(sth.ed25519_signature_hex, "ed25519_signature_hex"));
+    const publicKey = hexToBytes(publicKeyHex);
+    const valid = await verify(signature, digest, publicKey);
+    if (!valid) {
+        throw new Error("agent receipt transparency: ed25519 signature verification failed");
+    }
+    return {
+        ...sth,
+        tenant_id: sth.tenant_id.trim(),
+        root_hash_sha256_hex: rootHash,
+        message_digest_sha256_hex: messageDigest,
+        signing_public_key_ed25519_hex: publicKeyHex,
+        ed25519_signature_hex: sth.ed25519_signature_hex.trim().toLowerCase(),
+        issued_at: sth.issued_at.trim(),
+    };
+}
+/**
+ * Verifies that a receipt message digest is included in a published signed tree head
+ * via an RFC 6962 Merkle inclusion proof.
+ */
+export async function verifyAgentReceiptInclusion(proof, options = {}) {
+    if (proof.kind !== AGENT_RECEIPT_TRANSPARENCY_INCLUSION_PROOF_KIND_V1) {
+        throw new Error(`agent receipt transparency: kind must be ${AGENT_RECEIPT_TRANSPARENCY_INCLUSION_PROOF_KIND_V1}`);
+    }
+    if (proof.schema_version !== AGENT_RECEIPT_TRANSPARENCY_SCHEMA_VERSION) {
+        throw new Error(`agent receipt transparency: schema_version must be ${AGENT_RECEIPT_TRANSPARENCY_SCHEMA_VERSION}`);
+    }
+    if (!proof.tenant_id?.trim()) {
+        throw new Error("agent receipt transparency: tenant_id is required");
+    }
+    if (!proof.receipt_id?.trim()) {
+        throw new Error("agent receipt transparency: receipt_id is required");
+    }
+    if (!Number.isInteger(proof.tree_size) || proof.tree_size <= 0) {
+        throw new Error("agent receipt transparency: tree_size must be a positive integer");
+    }
+    if (!Number.isInteger(proof.leaf_index) ||
+        proof.leaf_index < 0 ||
+        proof.leaf_index >= proof.tree_size) {
+        throw new Error("agent receipt transparency: leaf_index out of range");
+    }
+    const messageDigest = requireHex64(proof.message_digest_sha256_hex, "message_digest_sha256_hex");
+    const leafHashHex = requireHex64(proof.leaf_hash_sha256_hex, "leaf_hash_sha256_hex");
+    const rootHashHex = requireHex64(proof.root_hash_sha256_hex, "root_hash_sha256_hex");
+    const sth = await verifySignedTreeHeadV1(proof.tree_head, options);
+    if (sth.tenant_id !== proof.tenant_id.trim()) {
+        throw new Error("agent receipt transparency: tree_head.tenant_id mismatch");
+    }
+    if (sth.tree_size !== proof.tree_size) {
+        throw new Error("agent receipt transparency: tree_head.tree_size mismatch");
+    }
+    if (sth.root_hash_sha256_hex !== rootHashHex) {
+        throw new Error("agent receipt transparency: tree_head.root_hash mismatch");
+    }
+    const leafHash = merkleLeafHashRFC6962(hexToBytes(messageDigest));
+    if (bytesToHex(leafHash) !== leafHashHex) {
+        throw new Error("agent receipt transparency: leaf_hash does not match message digest");
+    }
+    const auditPath = (proof.audit_path_sha256_hex ?? []).map((entry, index) => hexToBytes(requireHex64(entry, `audit_path_sha256_hex[${index}]`)));
+    const { root, consumed } = reconstructMerkleRoot(leafHash, proof.leaf_index, proof.tree_size, auditPath);
+    if (consumed !== auditPath.length) {
+        throw new Error("agent receipt transparency: audit path too long");
+    }
+    if (bytesToHex(root) !== rootHashHex) {
+        throw new Error("agent receipt transparency: inclusion proof does not match root hash");
+    }
+    return {
+        ...proof,
+        tenant_id: proof.tenant_id.trim(),
+        receipt_id: proof.receipt_id.trim(),
+        message_digest_sha256_hex: messageDigest,
+        leaf_hash_sha256_hex: leafHashHex,
+        root_hash_sha256_hex: rootHashHex,
+        audit_path_sha256_hex: auditPath.map((entry) => bytesToHex(entry)),
+        tree_head: sth,
+    };
+}

package/dist/agent-receipt-owner-disclosure.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Confidential HPKE owner disclosure package for Agent Receipt Standard.
+ *
+ * Separate artifact from the public `paybond.agent_receipt_v1` body. Encrypt /
+ * decrypt helpers are always available library exports; this is not part of the
+ * signed public ARS body.
+ */
+import type { AgentReceiptV1 } from "./agent-receipt.js";
+export declare const AGENT_RECEIPT_OWNER_DISCLOSURE_KIND_V1 = "paybond.agent_receipt_owner_disclosure_v1";
+export declare const AGENT_RECEIPT_OWNER_DISCLOSURE_PLAINTEXT_KIND_V1 = "paybond.agent_receipt_owner_disclosure_plaintext_v1";
+export declare const AGENT_RECEIPT_OWNER_DISCLOSURE_SCHEMA_VERSION = 1;
+export declare const AGENT_RECEIPT_OWNER_DISCLOSURE_HPKE_SUITE = "DHKEM_X25519_HKDF_SHA256/HKDF_SHA256/AES_128_GCM";
+export declare const AGENT_RECEIPT_OWNER_DISCLOSURE_INFO = "paybond.agent_receipt_owner_disclosure_v1";
+export type AgentReceiptOwnerDisclosurePlaintextV1 = {
+    kind: typeof AGENT_RECEIPT_OWNER_DISCLOSURE_PLAINTEXT_KIND_V1;
+    schema_version: number;
+    receipt_id: string;
+    message_digest_sha256_hex: string;
+    tenant_id: string;
+    scope: string;
+    derived_at: string;
+    authorization: unknown;
+    execution?: unknown;
+    evidence?: unknown;
+    outcome: unknown;
+    references: unknown;
+    extensions?: unknown;
+};
+export type AgentReceiptOwnerDisclosureV1 = {
+    kind: typeof AGENT_RECEIPT_OWNER_DISCLOSURE_KIND_V1;
+    schema_version: number;
+    hpke_suite: typeof AGENT_RECEIPT_OWNER_DISCLOSURE_HPKE_SUITE;
+    info: typeof AGENT_RECEIPT_OWNER_DISCLOSURE_INFO;
+    recipient_public_key_x25519_hex: string;
+    encapsulated_key_hex: string;
+    ciphertext_hex: string;
+    aad_sha256_hex: string;
+    receipt_id: string;
+    message_digest_sha256_hex: string;
+    plaintext_content_type: string;
+};
+/** Seal plaintext to a 32-byte X25519 public key. */
+export declare function sealHpkeBaseX25519Aes128Gcm(recipientPublicKey: Uint8Array, info: Uint8Array, aad: Uint8Array, plaintext: Uint8Array): {
+    enc: Buffer;
+    ciphertext: Buffer;
+};
+/** Open HPKE ciphertext for a 32-byte X25519 private key. */
+export declare function openHpkeBaseX25519Aes128Gcm(recipientPrivateKey: Uint8Array, enc: Uint8Array, info: Uint8Array, aad: Uint8Array, ciphertext: Uint8Array): Buffer;
+/** Generate lowercase hex X25519 key pair. */
+export declare function generateX25519KeyPairHex(): {
+    privateKeyHex: string;
+    publicKeyHex: string;
+};
+/**
+ * Derive a hash-only disclosure plaintext from a public ARS receipt.
+ */
+export declare function deriveOwnerDisclosurePlaintext(input: {
+    receipt: AgentReceiptV1;
+    derivedAt?: Date;
+    extensions?: unknown;
+}): AgentReceiptOwnerDisclosurePlaintextV1;
+/** HPKE-encrypt a derived disclosure plaintext to an owner X25519 public key. */
+export declare function encryptOwnerDisclosurePackage(input: {
+    plaintext: AgentReceiptOwnerDisclosurePlaintextV1;
+    recipientPublicKeyX25519Hex: string;
+}): AgentReceiptOwnerDisclosureV1;
+/** Decrypt an HPKE owner disclosure package. */
+export declare function decryptOwnerDisclosurePackage(input: {
+    package: AgentReceiptOwnerDisclosureV1;
+    recipientPrivateKeyX25519Hex: string;
+}): AgentReceiptOwnerDisclosurePlaintextV1;

package/dist/agent-receipt-owner-disclosure.js

@@ -0,0 +1,277 @@
+/**
+ * Confidential HPKE owner disclosure package for Agent Receipt Standard.
+ *
+ * Separate artifact from the public `paybond.agent_receipt_v1` body. Encrypt /
+ * decrypt helpers are always available library exports; this is not part of the
+ * signed public ARS body.
+ */
+import { createCipheriv, createDecipheriv, createHash, createHmac, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, } from "node:crypto";
+import { canonicalAgentReceiptBytes } from "./agent-receipt.js";
+export const AGENT_RECEIPT_OWNER_DISCLOSURE_KIND_V1 = "paybond.agent_receipt_owner_disclosure_v1";
+export const AGENT_RECEIPT_OWNER_DISCLOSURE_PLAINTEXT_KIND_V1 = "paybond.agent_receipt_owner_disclosure_plaintext_v1";
+export const AGENT_RECEIPT_OWNER_DISCLOSURE_SCHEMA_VERSION = 1;
+export const AGENT_RECEIPT_OWNER_DISCLOSURE_HPKE_SUITE = "DHKEM_X25519_HKDF_SHA256/HKDF_SHA256/AES_128_GCM";
+export const AGENT_RECEIPT_OWNER_DISCLOSURE_INFO = "paybond.agent_receipt_owner_disclosure_v1";
+const HPKE_KEM_ID = 0x0020;
+const HPKE_KDF_ID = 0x0001;
+const HPKE_AEAD_ID = 0x0001;
+const HPKE_MODE_BASE = 0x00;
+const HPKE_NH = 32;
+const HPKE_NK = 16;
+const HPKE_NN = 12;
+const HPKE_NSECRET = 32;
+function i2osp(n, length) {
+    const out = Buffer.alloc(length);
+    if (length === 1) {
+        out[0] = n & 0xff;
+    }
+    else if (length === 2) {
+        out.writeUInt16BE(n, 0);
+    }
+    else {
+        throw new Error("hpke: unsupported I2OSP length");
+    }
+    return out;
+}
+function suiteIdKem() {
+    return Buffer.concat([Buffer.from("KEM"), i2osp(HPKE_KEM_ID, 2)]);
+}
+function suiteIdHpke() {
+    return Buffer.concat([
+        Buffer.from("HPKE"),
+        i2osp(HPKE_KEM_ID, 2),
+        i2osp(HPKE_KDF_ID, 2),
+        i2osp(HPKE_AEAD_ID, 2),
+    ]);
+}
+function labeledExtract(suiteId, salt, label, ikm) {
+    const labeledIkm = Buffer.concat([Buffer.from("HPKE-v1"), suiteId, label, ikm]);
+    const effectiveSalt = salt && salt.length > 0 ? salt : Buffer.alloc(HPKE_NH);
+    return createHmac("sha256", effectiveSalt).update(labeledIkm).digest();
+}
+function labeledExpand(suiteId, prk, label, info, length) {
+    const labeledInfo = Buffer.concat([
+        i2osp(length, 2),
+        Buffer.from("HPKE-v1"),
+        suiteId,
+        label,
+        info,
+    ]);
+    // HKDF-Expand
+    const hashLen = HPKE_NH;
+    const n = Math.ceil(length / hashLen);
+    let prev = Buffer.alloc(0);
+    const out = [];
+    for (let i = 1; i <= n; i++) {
+        prev = createHmac("sha256", prk)
+            .update(Buffer.concat([prev, labeledInfo, Buffer.from([i])]))
+            .digest();
+        out.push(prev);
+    }
+    return Buffer.concat(out).subarray(0, length);
+}
+function extractAndExpand(dh, kemContext) {
+    const suiteId = suiteIdKem();
+    const eaePrk = labeledExtract(suiteId, null, Buffer.from("eae_prk"), dh);
+    return labeledExpand(suiteId, eaePrk, Buffer.from("shared_secret"), kemContext, HPKE_NSECRET);
+}
+function x25519Dh(privateKeyRaw, publicKeyRaw) {
+    const priv = createPrivateKey({
+        key: Buffer.concat([
+            Buffer.from("302e020100300506032b656e04220420", "hex"),
+            privateKeyRaw,
+        ]),
+        format: "der",
+        type: "pkcs8",
+    });
+    const pub = createPublicKey({
+        key: Buffer.concat([
+            Buffer.from("302a300506032b656e032100", "hex"),
+            publicKeyRaw,
+        ]),
+        format: "der",
+        type: "spki",
+    });
+    return diffieHellman({ privateKey: priv, publicKey: pub });
+}
+function encap(pkR) {
+    const { privateKey, publicKey } = generateKeyPairSync("x25519");
+    const skE = privateKey.export({ type: "pkcs8", format: "der" }).subarray(-32);
+    const enc = publicKey.export({ type: "spki", format: "der" }).subarray(-32);
+    const dh = x25519Dh(skE, pkR);
+    const kemContext = Buffer.concat([enc, pkR]);
+    return { sharedSecret: extractAndExpand(dh, kemContext), enc };
+}
+function decap(skR, enc) {
+    if (enc.length !== 32) {
+        throw new Error("owner disclosure: encapsulated key must be 32 bytes");
+    }
+    const dh = x25519Dh(skR, enc);
+    const pkR = createPublicKey(createPrivateKey({
+        key: Buffer.concat([
+            Buffer.from("302e020100300506032b656e04220420", "hex"),
+            skR,
+        ]),
+        format: "der",
+        type: "pkcs8",
+    })).export({ type: "spki", format: "der" }).subarray(-32);
+    const kemContext = Buffer.concat([enc, pkR]);
+    return extractAndExpand(dh, kemContext);
+}
+function keyScheduleBase(sharedSecret, info) {
+    const suiteId = suiteIdHpke();
+    const pskIdHash = labeledExtract(suiteId, null, Buffer.from("psk_id_hash"), Buffer.alloc(0));
+    const infoHash = labeledExtract(suiteId, null, Buffer.from("info_hash"), info);
+    const keyScheduleContext = Buffer.concat([
+        Buffer.from([HPKE_MODE_BASE]),
+        pskIdHash,
+        infoHash,
+    ]);
+    const secret = labeledExtract(suiteId, sharedSecret, Buffer.from("secret"), Buffer.alloc(0));
+    const key = labeledExpand(suiteId, secret, Buffer.from("key"), keyScheduleContext, HPKE_NK);
+    const baseNonce = labeledExpand(suiteId, secret, Buffer.from("base_nonce"), keyScheduleContext, HPKE_NN);
+    return { key, baseNonce };
+}
+function nonce(baseNonce, seq = 0) {
+    const out = Buffer.from(baseNonce);
+    for (let i = 0; i < 8; i++) {
+        out[out.length - 1 - i] ^= (seq >>> (8 * i)) & 0xff;
+    }
+    return out;
+}
+/** Seal plaintext to a 32-byte X25519 public key. */
+export function sealHpkeBaseX25519Aes128Gcm(recipientPublicKey, info, aad, plaintext) {
+    if (recipientPublicKey.length !== 32) {
+        throw new Error("owner disclosure: recipient public key must be 32 bytes");
+    }
+    const { sharedSecret, enc } = encap(Buffer.from(recipientPublicKey));
+    const { key, baseNonce } = keyScheduleBase(sharedSecret, Buffer.from(info));
+    const cipher = createCipheriv("aes-128-gcm", key, nonce(baseNonce));
+    cipher.setAAD(Buffer.from(aad));
+    const encrypted = Buffer.concat([cipher.update(Buffer.from(plaintext)), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return { enc, ciphertext: Buffer.concat([encrypted, tag]) };
+}
+/** Open HPKE ciphertext for a 32-byte X25519 private key. */
+export function openHpkeBaseX25519Aes128Gcm(recipientPrivateKey, enc, info, aad, ciphertext) {
+    if (recipientPrivateKey.length !== 32) {
+        throw new Error("owner disclosure: recipient private key must be 32 bytes");
+    }
+    const sharedSecret = decap(Buffer.from(recipientPrivateKey), Buffer.from(enc));
+    const { key, baseNonce } = keyScheduleBase(sharedSecret, Buffer.from(info));
+    const ct = Buffer.from(ciphertext);
+    if (ct.length < 16) {
+        throw new Error("owner disclosure: ciphertext too short");
+    }
+    const body = ct.subarray(0, ct.length - 16);
+    const tag = ct.subarray(ct.length - 16);
+    const decipher = createDecipheriv("aes-128-gcm", key, nonce(baseNonce));
+    decipher.setAAD(Buffer.from(aad));
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(body), decipher.final()]);
+}
+/** Generate lowercase hex X25519 key pair. */
+export function generateX25519KeyPairHex() {
+    const { privateKey, publicKey } = generateKeyPairSync("x25519");
+    const privateKeyHex = privateKey.export({ type: "pkcs8", format: "der" }).subarray(-32).toString("hex");
+    const publicKeyHex = publicKey.export({ type: "spki", format: "der" }).subarray(-32).toString("hex");
+    return { privateKeyHex, publicKeyHex };
+}
+function ownerDisclosureAad(receiptId, messageDigest) {
+    return Buffer.from(createHash("sha256")
+        .update(`${receiptId.trim()}\0${messageDigest.trim().toLowerCase()}`, "utf8")
+        .digest());
+}
+function formatRfc3339Seconds(value) {
+    return value.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/**
+ * Derive a hash-only disclosure plaintext from a public ARS receipt.
+ */
+export function deriveOwnerDisclosurePlaintext(input) {
+    const receipt = input.receipt;
+    const digest = receipt.message_digest_sha256_hex?.trim().toLowerCase() ||
+        createHash("sha256").update(canonicalAgentReceiptBytes(receipt)).digest("hex");
+    const derivedAt = input.derivedAt ?? new Date();
+    const out = {
+        kind: AGENT_RECEIPT_OWNER_DISCLOSURE_PLAINTEXT_KIND_V1,
+        schema_version: AGENT_RECEIPT_OWNER_DISCLOSURE_SCHEMA_VERSION,
+        receipt_id: receipt.receipt_id,
+        message_digest_sha256_hex: digest,
+        tenant_id: receipt.tenant_id,
+        scope: receipt.scope,
+        derived_at: formatRfc3339Seconds(derivedAt),
+        authorization: receipt.authorization,
+        outcome: receipt.outcome,
+        references: receipt.references,
+    };
+    if (receipt.execution) {
+        out.execution = receipt.execution;
+    }
+    if (receipt.evidence) {
+        out.evidence = receipt.evidence;
+    }
+    if (input.extensions !== undefined) {
+        out.extensions = input.extensions;
+    }
+    return out;
+}
+/** HPKE-encrypt a derived disclosure plaintext to an owner X25519 public key. */
+export function encryptOwnerDisclosurePackage(input) {
+    if (input.plaintext.kind !== AGENT_RECEIPT_OWNER_DISCLOSURE_PLAINTEXT_KIND_V1) {
+        throw new Error(`owner disclosure: plaintext kind must be ${AGENT_RECEIPT_OWNER_DISCLOSURE_PLAINTEXT_KIND_V1}`);
+    }
+    const pubHex = input.recipientPublicKeyX25519Hex.trim().toLowerCase();
+    if (pubHex.length !== 64) {
+        throw new Error("owner disclosure: recipient_public_key_x25519_hex must be 32-byte hex");
+    }
+    const body = Buffer.from(JSON.stringify(input.plaintext), "utf8");
+    const aad = ownerDisclosureAad(input.plaintext.receipt_id, input.plaintext.message_digest_sha256_hex);
+    const { enc, ciphertext } = sealHpkeBaseX25519Aes128Gcm(Buffer.from(pubHex, "hex"), Buffer.from(AGENT_RECEIPT_OWNER_DISCLOSURE_INFO, "utf8"), aad, body);
+    return {
+        kind: AGENT_RECEIPT_OWNER_DISCLOSURE_KIND_V1,
+        schema_version: AGENT_RECEIPT_OWNER_DISCLOSURE_SCHEMA_VERSION,
+        hpke_suite: AGENT_RECEIPT_OWNER_DISCLOSURE_HPKE_SUITE,
+        info: AGENT_RECEIPT_OWNER_DISCLOSURE_INFO,
+        recipient_public_key_x25519_hex: pubHex,
+        encapsulated_key_hex: enc.toString("hex"),
+        ciphertext_hex: ciphertext.toString("hex"),
+        aad_sha256_hex: aad.toString("hex"),
+        receipt_id: input.plaintext.receipt_id,
+        message_digest_sha256_hex: input.plaintext.message_digest_sha256_hex.toLowerCase(),
+        plaintext_content_type: `application/json; charset=utf-8; profile=${AGENT_RECEIPT_OWNER_DISCLOSURE_PLAINTEXT_KIND_V1}`,
+    };
+}
+/** Decrypt an HPKE owner disclosure package. */
+export function decryptOwnerDisclosurePackage(input) {
+    const pkg = input.package;
+    if (pkg.kind !== AGENT_RECEIPT_OWNER_DISCLOSURE_KIND_V1) {
+        throw new Error(`owner disclosure: kind must be ${AGENT_RECEIPT_OWNER_DISCLOSURE_KIND_V1}`);
+    }
+    if (pkg.hpke_suite !== AGENT_RECEIPT_OWNER_DISCLOSURE_HPKE_SUITE) {
+        throw new Error(`owner disclosure: unsupported hpke_suite ${JSON.stringify(pkg.hpke_suite)}`);
+    }
+    if (pkg.info !== AGENT_RECEIPT_OWNER_DISCLOSURE_INFO) {
+        throw new Error("owner disclosure: info mismatch");
+    }
+    const privHex = input.recipientPrivateKeyX25519Hex.trim().toLowerCase();
+    const priv = Buffer.from(privHex, "hex");
+    if (priv.length !== 32) {
+        throw new Error("owner disclosure: recipient private key must be 32-byte hex");
+    }
+    const enc = Buffer.from(pkg.encapsulated_key_hex.trim().toLowerCase(), "hex");
+    const ciphertext = Buffer.from(pkg.ciphertext_hex.trim().toLowerCase(), "hex");
+    const aad = ownerDisclosureAad(pkg.receipt_id, pkg.message_digest_sha256_hex);
+    if (aad.toString("hex") !== pkg.aad_sha256_hex.trim().toLowerCase()) {
+        throw new Error("owner disclosure: aad_sha256_hex mismatch");
+    }
+    const plaintextBytes = openHpkeBaseX25519Aes128Gcm(priv, enc, Buffer.from(AGENT_RECEIPT_OWNER_DISCLOSURE_INFO, "utf8"), aad, ciphertext);
+    const plaintext = JSON.parse(plaintextBytes.toString("utf8"));
+    if (plaintext.kind !== AGENT_RECEIPT_OWNER_DISCLOSURE_PLAINTEXT_KIND_V1) {
+        throw new Error("owner disclosure: decrypted kind mismatch");
+    }
+    if (plaintext.receipt_id !== pkg.receipt_id) {
+        throw new Error("owner disclosure: decrypted receipt binding mismatch");
+    }
+    return plaintext;
+}

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

@@ -0,0 +1,69 @@
+/**
+ * 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 type { AgentReceiptV1 } from "./agent-receipt.js";
+/** PEF claim taxonomy for Paybond agent receipts (interop adapter). */
+export declare const PEF_CLAIM_TYPE_AGENT_RECEIPT_V1 = "paybond_agent_receipt_v1";
+/** Canonicalisation URN pinned by the x402 PEF substrate. */
+export declare const PEF_CANON_VERSION_JCS_RFC8785_V1 = "urn:x402:canonicalisation:jcs-rfc8785-v1";
+export declare const PEF_VERSION_V1 = "1";
+/** Inner receipt format label carried in the PEF envelope. */
+export declare const PEF_RECEIPT_FORMAT_AGENT_RECEIPT_V1 = "paybond.agent_receipt_v1";
+export type BuildAgentReceiptPefFrameInput = {
+    /** Full ARS receipt JSON (verified or composed). */
+    receipt: AgentReceiptV1 | Record<string, unknown>;
+    /** DID of the party asserting the frame (audit exporter / Gateway). */
+    frameProviderDid: string;
+    /** Epoch milliseconds for the frame assertion. */
+    frameTimestampMs: number;
+};
+/**
+ * PEF envelope wrapping an ARS receipt for partner audit handoff.
+ *
+ * `signature` is omitted; callers MAY attach an RFC 9421 detached signature
+ * later without changing `frame_id` (signature is excluded from the preimage).
+ */
+export type AgentReceiptPefFrameV1 = {
+    canon_version: typeof PEF_CANON_VERSION_JCS_RFC8785_V1;
+    claim_type: typeof PEF_CLAIM_TYPE_AGENT_RECEIPT_V1;
+    frame_id: string;
+    frame_provider_did: string;
+    frame_timestamp_ms: number;
+    pef_version: typeof PEF_VERSION_V1;
+    receipt: AgentReceiptV1 | Record<string, unknown>;
+    receipt_format: typeof PEF_RECEIPT_FORMAT_AGENT_RECEIPT_V1;
+    receipt_hash: string;
+};
+/** Returns RFC 8785 JCS bytes for an arbitrary JSON value. */
+export declare function jcsCanonicalBytes(value: unknown): Uint8Array;
+/**
+ * Computes `receipt_hash = sha256:` + hex(SHA-256(JCS(receipt))).
+ */
+export declare function agentReceiptPefReceiptHash(receipt: AgentReceiptV1 | Record<string, unknown>): string;
+/**
+ * Builds the PEF preimage object (excludes `frame_id` and `signature`).
+ */
+export declare function agentReceiptPefPreimage(input: BuildAgentReceiptPefFrameInput, receiptHash: string): Record<string, unknown>;
+/**
+ * Derives `frame_id = sha256:` + hex(SHA-256(JCS(preimage))).
+ */
+export declare function agentReceiptPefFrameId(preimage: Record<string, unknown>): string;
+/**
+ * Builds a content-addressed PEF wrapper around an ARS receipt.
+ *
+ * Does not modify or re-sign the inner ARS envelope.
+ */
+export declare function buildAgentReceiptPefFrame(input: BuildAgentReceiptPefFrameInput): AgentReceiptPefFrameV1;
+/**
+ * Recomputes `frame_id` / `receipt_hash` and checks they match the frame.
+ *
+ * @throws Error when hashes do not match
+ */
+export declare function verifyAgentReceiptPefFrameId(frame: AgentReceiptPefFrameV1): void;