@paybond/kit 0.12.0 → 0.12.1

package/dist/agent-receipt-external-attestations.d.ts

@@ -7,6 +7,7 @@
 import type { AgentReceiptExternalAttestationV1 } from "./agent-receipt.js";
 export declare const AGENT_RECEIPT_EXTERNAL_SOURCE_SEP2828 = "sep2828_mcp";
 export declare const AGENT_RECEIPT_EXTERNAL_SOURCE_X402 = "x402";
+export declare const AGENT_RECEIPT_EXTERNAL_SOURCE_AP2 = "ap2";
 /** SHA-256 hex digest of canonical JSON bytes. */
 export declare function partnerRecordDigestSha256Hex(record: Record<string, unknown>): string;
 /**
@@ -17,6 +18,20 @@ export declare function sep2828RecordsToExternalAttestations(decisionInput: Reco
  * Converts a verified x402 signed delivery receipt into one external attestation entry.
  */
 export declare function x402ReceiptToExternalAttestations(receiptInput: Record<string, unknown>): AgentReceiptExternalAttestationV1[];
+/**
+ * Converts a verified signed AP2 agent mandate into one external attestation entry.
+ */
+export declare function signedMandateToExternalAttestations(signed: Record<string, unknown>, transportBinding?: {
+    external_authorization_id?: string;
+}): AgentReceiptExternalAttestationV1[];
+/**
+ * Converts a verified AP2 protocol authorization receipt into one external attestation entry.
+ */
+export declare function protocolAuthorizationReceiptToExternalAttestations(receipt: Record<string, unknown>): AgentReceiptExternalAttestationV1[];
+/**
+ * Converts a verified AP2 protocol settlement receipt into one external attestation entry.
+ */
+export declare function protocolSettlementReceiptToExternalAttestations(receipt: Record<string, unknown>): AgentReceiptExternalAttestationV1[];
 export type PaybondExternalAttestationInput = {
     kind: "sep2828";
     decision: Record<string, unknown>;
@@ -24,6 +39,18 @@ export type PaybondExternalAttestationInput = {
 } | {
     kind: "x402";
     receipt: Record<string, unknown>;
+} | {
+    kind: "ap2_mandate";
+    signedMandate: Record<string, unknown>;
+    transportBinding?: {
+        external_authorization_id?: string;
+    };
+} | {
+    kind: "ap2_authorization_receipt";
+    receipt: Record<string, unknown>;
+} | {
+    kind: "ap2_settlement_receipt";
+    receipt: Record<string, unknown>;
 } | AgentReceiptExternalAttestationV1;
 /** Resolves pre-built or partner-native attestation inputs into normalized receipt entries. */
 export declare function resolveExternalAttestations(inputs: readonly PaybondExternalAttestationInput[]): AgentReceiptExternalAttestationV1[];

package/dist/agent-receipt-external-attestations.js

@@ -5,13 +5,16 @@
  * These entries are never canonical inside Paybond; they provide interop hooks only.
  */
 import { createHash } from "node:crypto";
+import { readString, verifySignedAgentMandateV1 } from "./agent-mandate.js";
 import { normalizeJson } from "./json-digest.js";
+import { verifyProtocolAuthorizationReceiptV1, verifyProtocolSettlementReceiptV1, } from "./protocol-receipt.js";
 import { stripDigestPrefix } from "./mcp-sep2828-evidence.js";
 import { verifySep2828ReceiptPair } from "./sep2828-signature.js";
 import { buildX402ReceiptDigestPayload, } from "./x402-receipt-evidence.js";
 import { extractSignedX402Receipt, verifySignedX402Receipt } from "./x402-receipt-signature.js";
 export const AGENT_RECEIPT_EXTERNAL_SOURCE_SEP2828 = "sep2828_mcp";
 export const AGENT_RECEIPT_EXTERNAL_SOURCE_X402 = "x402";
+export const AGENT_RECEIPT_EXTERNAL_SOURCE_AP2 = "ap2";
 const SEP2828_SIGNATURE_KEYS = new Set([
     "signature",
     "ed25519_signature_hex",
@@ -104,6 +107,52 @@ export function x402ReceiptToExternalAttestations(receiptInput) {
         },
     ];
 }
+/**
+ * Converts a verified signed AP2 agent mandate into one external attestation entry.
+ */
+export function signedMandateToExternalAttestations(signed, transportBinding) {
+    verifySignedAgentMandateV1(signed);
+    const digest = readString(signed.message_digest_sha256_hex).trim().toLowerCase();
+    const externalAuthorizationId = transportBinding?.external_authorization_id?.trim();
+    const nonce = readString(signed.nonce).trim();
+    const referenceID = externalAuthorizationId || nonce || undefined;
+    return [
+        {
+            source: AGENT_RECEIPT_EXTERNAL_SOURCE_AP2,
+            kind: "agent_mandate_v1",
+            digest_sha256_hex: digest,
+            reference_id: referenceID,
+        },
+    ];
+}
+/**
+ * Converts a verified AP2 protocol authorization receipt into one external attestation entry.
+ */
+export function protocolAuthorizationReceiptToExternalAttestations(receipt) {
+    const verified = verifyProtocolAuthorizationReceiptV1(receipt);
+    return [
+        {
+            source: AGENT_RECEIPT_EXTERNAL_SOURCE_AP2,
+            kind: "protocol_authorization_receipt_v1",
+            digest_sha256_hex: verified.message_digest_sha256_hex,
+            reference_id: verified.intent_id,
+        },
+    ];
+}
+/**
+ * Converts a verified AP2 protocol settlement receipt into one external attestation entry.
+ */
+export function protocolSettlementReceiptToExternalAttestations(receipt) {
+    const verified = verifyProtocolSettlementReceiptV1(receipt);
+    return [
+        {
+            source: AGENT_RECEIPT_EXTERNAL_SOURCE_AP2,
+            kind: "protocol_settlement_receipt_v1",
+            digest_sha256_hex: verified.message_digest_sha256_hex,
+            reference_id: verified.intent_id,
+        },
+    ];
+}
 /** Resolves pre-built or partner-native attestation inputs into normalized receipt entries. */
 export function resolveExternalAttestations(inputs) {
     const out = [];
@@ -118,6 +167,18 @@ export function resolveExternalAttestations(inputs) {
         }
         if (input.kind === "x402") {
             out.push(...x402ReceiptToExternalAttestations(input.receipt));
+            continue;
+        }
+        if (input.kind === "ap2_mandate") {
+            out.push(...signedMandateToExternalAttestations(input.signedMandate, input.transportBinding));
+            continue;
+        }
+        if (input.kind === "ap2_authorization_receipt") {
+            out.push(...protocolAuthorizationReceiptToExternalAttestations(input.receipt));
+            continue;
+        }
+        if (input.kind === "ap2_settlement_receipt") {
+            out.push(...protocolSettlementReceiptToExternalAttestations(input.receipt));
         }
     }
     return out;

package/dist/agent-receipt-pdf-export.d.ts

@@ -0,0 +1,43 @@
+import { type AgentReceiptV1, type VerifyAgentReceiptV1Options } from "./agent-receipt.js";
+export declare const AGENT_RECEIPT_PDF_EXPORT_MANIFEST_SCHEMA_VERSION = 1;
+export declare const AGENT_RECEIPT_PDF_EXPORT_MANIFEST_KIND = "paybond.agent_receipt_pdf_export_manifest_v1";
+export declare const AGENT_RECEIPT_PDF_EXPORT_DERIVED_VIEW_LABEL = "Derived from paybond.agent_receipt_v1";
+export declare const FORBIDDEN_PDF_EXPORT_MANIFEST_FIELDS: readonly ["embedded_receipt_json", "receipt_json", "unsigned_receipt", "canonical_receipt", "user_prompt", "system_prompt", "tool_arguments", "tool_results", "evidence_payload", "payee_signature"];
+export type AgentReceiptPDFExportSourceKind = "gateway_fetch" | "audit_export" | "local_file";
+export type AgentReceiptPDFExportFooterStamp = {
+    label: typeof AGENT_RECEIPT_PDF_EXPORT_DERIVED_VIEW_LABEL;
+    receipt_id: string;
+    message_digest_sha256_hex: string;
+    verify_endpoint?: string;
+};
+export type AgentReceiptPDFExportManifest = {
+    schema_version: typeof AGENT_RECEIPT_PDF_EXPORT_MANIFEST_SCHEMA_VERSION;
+    kind: typeof AGENT_RECEIPT_PDF_EXPORT_MANIFEST_KIND;
+    receipt_id: string;
+    message_digest_sha256_hex: string;
+    source_kind: AgentReceiptPDFExportSourceKind;
+    source_artifact?: string;
+    generated_at_rfc3339: string;
+    renderer_id?: string;
+    pdf_sha256_hex?: string;
+    pdf_page_count?: number;
+    derived_view_label: typeof AGENT_RECEIPT_PDF_EXPORT_DERIVED_VIEW_LABEL;
+    footer_stamp: AgentReceiptPDFExportFooterStamp;
+};
+/** Reject authority-embedding fields and validate against the published Draft 2020-12 schema. */
+export declare function validateAgentReceiptPDFExportManifestJSON(value: unknown): AgentReceiptPDFExportManifest;
+export declare function parseAgentReceiptPDFExportManifestJSON(raw: string | Uint8Array): AgentReceiptPDFExportManifest;
+export type GateAgentReceiptPDFExportInput = {
+    receiptJSON: string | Uint8Array;
+    manifestJSON: string | Uint8Array;
+    pdfBytes?: Uint8Array;
+    verifyOptions?: VerifyAgentReceiptV1Options;
+};
+/**
+ * Enforces the PDF export verification gate before rendering or accepting a derived PDF.
+ * Verify signed JSON first, bind manifest/footer stamps, optionally verify PDF bytes hash.
+ */
+export declare function gateAgentReceiptPDFExport(input: GateAgentReceiptPDFExportInput): Promise<{
+    receipt: AgentReceiptV1;
+    manifest: AgentReceiptPDFExportManifest;
+}>;

package/dist/agent-receipt-pdf-export.js

@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { verifyAgentReceiptV1FromJSON, } from "./agent-receipt.js";
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const AGENT_RECEIPT_DIR = join(MODULE_DIR, "../../agent-receipt");
+export const AGENT_RECEIPT_PDF_EXPORT_MANIFEST_SCHEMA_VERSION = 1;
+export const AGENT_RECEIPT_PDF_EXPORT_MANIFEST_KIND = "paybond.agent_receipt_pdf_export_manifest_v1";
+export const AGENT_RECEIPT_PDF_EXPORT_DERIVED_VIEW_LABEL = "Derived from paybond.agent_receipt_v1";
+export const FORBIDDEN_PDF_EXPORT_MANIFEST_FIELDS = [
+    "embedded_receipt_json",
+    "receipt_json",
+    "unsigned_receipt",
+    "canonical_receipt",
+    "user_prompt",
+    "system_prompt",
+    "tool_arguments",
+    "tool_results",
+    "evidence_payload",
+    "payee_signature",
+];
+let manifestSchemaValidator;
+function manifestSchemaValidate() {
+    if (!manifestSchemaValidator) {
+        const ajv = new Ajv2020({ allErrors: true, strict: false });
+        const schema = JSON.parse(readFileSync(join(AGENT_RECEIPT_DIR, "pdf-export-manifest-schema.json"), "utf8"));
+        manifestSchemaValidator = ajv.compile(schema);
+    }
+    return manifestSchemaValidator;
+}
+function rejectForbiddenPDFExportManifestFields(value) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            rejectForbiddenPDFExportManifestFields(item);
+        }
+        return;
+    }
+    if (!value || typeof value !== "object") {
+        return;
+    }
+    const record = value;
+    for (const [key, child] of Object.entries(record)) {
+        if (FORBIDDEN_PDF_EXPORT_MANIFEST_FIELDS.includes(key)) {
+            throw new Error(`agent receipt pdf export manifest: forbidden field ${JSON.stringify(key)}`);
+        }
+        rejectForbiddenPDFExportManifestFields(child);
+    }
+}
+/** Reject authority-embedding fields and validate against the published Draft 2020-12 schema. */
+export function validateAgentReceiptPDFExportManifestJSON(value) {
+    rejectForbiddenPDFExportManifestFields(value);
+    const validate = manifestSchemaValidate();
+    if (!validate(value)) {
+        throw new Error(`agent receipt pdf export manifest: schema validation failed: ${JSON.stringify(validate.errors ?? [])}`);
+    }
+    return value;
+}
+export function parseAgentReceiptPDFExportManifestJSON(raw) {
+    const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error("agent receipt pdf export manifest: invalid JSON");
+    }
+    return validateAgentReceiptPDFExportManifestJSON(parsed);
+}
+function assertManifestMatchesReceipt(manifest, receipt) {
+    const receiptId = receipt.receipt_id.trim().toLowerCase();
+    const digest = receipt.message_digest_sha256_hex.trim().toLowerCase();
+    if (manifest.receipt_id.trim().toLowerCase() !== receiptId) {
+        throw new Error("agent receipt pdf export gate: manifest receipt_id does not match verified receipt");
+    }
+    if (manifest.message_digest_sha256_hex.trim().toLowerCase() !== digest) {
+        throw new Error("agent receipt pdf export gate: manifest message_digest_sha256_hex does not match verified receipt");
+    }
+    if (manifest.derived_view_label !== AGENT_RECEIPT_PDF_EXPORT_DERIVED_VIEW_LABEL) {
+        throw new Error(`agent receipt pdf export gate: derived_view_label must be ${JSON.stringify(AGENT_RECEIPT_PDF_EXPORT_DERIVED_VIEW_LABEL)}`);
+    }
+    const stamp = manifest.footer_stamp;
+    if (stamp.receipt_id.trim().toLowerCase() !== receiptId) {
+        throw new Error("agent receipt pdf export gate: footer_stamp receipt_id does not match verified receipt");
+    }
+    if (stamp.message_digest_sha256_hex.trim().toLowerCase() !== digest) {
+        throw new Error("agent receipt pdf export gate: footer_stamp message_digest_sha256_hex does not match verified receipt");
+    }
+    if (stamp.label !== AGENT_RECEIPT_PDF_EXPORT_DERIVED_VIEW_LABEL) {
+        throw new Error(`agent receipt pdf export gate: footer_stamp label must be ${JSON.stringify(AGENT_RECEIPT_PDF_EXPORT_DERIVED_VIEW_LABEL)}`);
+    }
+}
+/**
+ * Enforces the PDF export verification gate before rendering or accepting a derived PDF.
+ * Verify signed JSON first, bind manifest/footer stamps, optionally verify PDF bytes hash.
+ */
+export async function gateAgentReceiptPDFExport(input) {
+    const receipt = await verifyAgentReceiptV1FromJSON(input.receiptJSON, input.verifyOptions);
+    const manifest = parseAgentReceiptPDFExportManifestJSON(input.manifestJSON);
+    assertManifestMatchesReceipt(manifest, receipt);
+    if (input.pdfBytes && manifest.pdf_sha256_hex) {
+        const actual = createHash("sha256").update(input.pdfBytes).digest("hex");
+        if (actual !== manifest.pdf_sha256_hex.trim().toLowerCase()) {
+            throw new Error("agent receipt pdf export gate: pdf_sha256_hex mismatch");
+        }
+    }
+    return { receipt, manifest };
+}

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

@@ -0,0 +1,7 @@
+import type { AgentReceiptV1 } from "./agent-receipt.js";
+/** Privacy-sensitive keys that MUST NOT appear anywhere in agent receipt JSON. */
+export declare const FORBIDDEN_AGENT_RECEIPT_FIELDS: readonly ["user_prompt", "system_prompt", "tool_arguments", "tool_results", "evidence_payload", "payee_signature"];
+/** Reject forbidden privacy fields and validate against the published Draft 2020-12 schema. */
+export declare function validateAgentReceiptJSON(value: unknown): AgentReceiptV1;
+/** Parse and validate untrusted agent receipt JSON before signature verification. */
+export declare function parseAgentReceiptJSON(raw: string | Uint8Array): AgentReceiptV1;

package/dist/agent-receipt-prevalidate.js

@@ -0,0 +1,63 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const AGENT_RECEIPT_DIR = join(MODULE_DIR, "../../agent-receipt");
+/** Privacy-sensitive keys that MUST NOT appear anywhere in agent receipt JSON. */
+export const FORBIDDEN_AGENT_RECEIPT_FIELDS = [
+    "user_prompt",
+    "system_prompt",
+    "tool_arguments",
+    "tool_results",
+    "evidence_payload",
+    "payee_signature",
+];
+let schemaValidator;
+function schemaValidate() {
+    if (!schemaValidator) {
+        const ajv = new Ajv2020({ allErrors: true, strict: false });
+        const schema = JSON.parse(readFileSync(join(AGENT_RECEIPT_DIR, "schema.json"), "utf8"));
+        schemaValidator = ajv.compile(schema);
+    }
+    return schemaValidator;
+}
+function rejectForbiddenAgentReceiptFields(value) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            rejectForbiddenAgentReceiptFields(item);
+        }
+        return;
+    }
+    if (!value || typeof value !== "object") {
+        return;
+    }
+    const record = value;
+    for (const [key, child] of Object.entries(record)) {
+        if (FORBIDDEN_AGENT_RECEIPT_FIELDS.includes(key)) {
+            throw new Error(`agent receipt: forbidden field ${JSON.stringify(key)}`);
+        }
+        rejectForbiddenAgentReceiptFields(child);
+    }
+}
+/** Reject forbidden privacy fields and validate against the published Draft 2020-12 schema. */
+export function validateAgentReceiptJSON(value) {
+    rejectForbiddenAgentReceiptFields(value);
+    const validate = schemaValidate();
+    if (!validate(value)) {
+        throw new Error(`agent receipt: schema validation failed: ${JSON.stringify(validate.errors ?? [])}`);
+    }
+    return value;
+}
+/** Parse and validate untrusted agent receipt JSON before signature verification. */
+export function parseAgentReceiptJSON(raw) {
+    const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error("agent receipt: invalid JSON");
+    }
+    return validateAgentReceiptJSON(parsed);
+}

package/dist/agent-receipt.d.ts

@@ -5,6 +5,11 @@ export declare const AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519 = "ed25519-sha256-j
 export declare const AGENT_RECEIPT_SCOPE_ACTION = "action";
 export declare const AGENT_RECEIPT_SCOPE_INTENT_TERMINAL = "intent_terminal";
 export declare const AGENT_RECEIPT_WELL_KNOWN_PATH = "/.well-known/agent-receipt-v1.json";
+export declare const AGENT_RECEIPT_SIGNING_KEYS_WELL_KNOWN_PATH = "/.well-known/agent-receipt-signing-keys.json";
+/** Gateway evidence proxy header carrying Kit-verified external attestation digests. */
+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";
 export type AgentReceiptAgentV1 = {
     operator_did: string;
     model_family: string;
@@ -128,7 +133,22 @@ export declare function canonicalAgentReceiptBytes(receipt: AgentReceiptV1): Uin
  * (Agent Receipt Standard Phase 1) and to compute the digest signers must sign over.
  */
 export declare function agentReceiptMessageDigestSha256Hex(receipt: AgentReceiptV1): string;
+/** Optional trust-anchor checks during agent receipt verification. */
+export type VerifyAgentReceiptV1Options = {
+    /** Lowercase signing_public_key_ed25519_hex values accepted when non-empty. */
+    expectedSigningPublicKeys?: readonly string[];
+    /**
+     * 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.
+     */
+    verifyOperatorAgainstRegistry?: boolean;
+    /** Lowercase operator signing pubkeys accepted when the registry check is enabled. */
+    trustedOperatorPublicKeys?: readonly string[];
+};
 /** Validates structure, receipt_id derivation, digest, and detached Ed25519 signature. */
-export declare function verifyAgentReceiptV1(receipt: AgentReceiptV1): Promise<AgentReceiptV1>;
+export declare function verifyAgentReceiptV1(receipt: AgentReceiptV1, options?: VerifyAgentReceiptV1Options): Promise<AgentReceiptV1>;
+/** Validate raw JSON (schema + forbidden fields) then verify signature. */
+export declare function verifyAgentReceiptV1FromJSON(raw: string | Uint8Array | Record<string, unknown>, options?: VerifyAgentReceiptV1Options): Promise<AgentReceiptV1>;
 /** Attach an optional operator counter-signature over the Gateway message digest. */
 export declare function attachOperatorAttestationV1(receipt: AgentReceiptV1, operatorPrivateKeyHex: string, operatorDid: string): Promise<AgentReceiptV1>;

package/dist/agent-receipt.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { verify } from "@noble/ed25519";
 import { ensureEd25519Sha512Sync } from "./ed25519-sync.js";
+import { parseAgentReceiptJSON, validateAgentReceiptJSON } from "./agent-receipt-prevalidate.js";
 export const AGENT_RECEIPT_SCHEMA_VERSION = 1;
 export const AGENT_RECEIPT_KIND_V1 = "paybond.agent_receipt_v1";
 export const AGENT_RECEIPT_VERSION_V1 = "1";
@@ -8,6 +9,11 @@ export const AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519 = "ed25519-sha256-json-v1";
 export const AGENT_RECEIPT_SCOPE_ACTION = "action";
 export const AGENT_RECEIPT_SCOPE_INTENT_TERMINAL = "intent_terminal";
 export const AGENT_RECEIPT_WELL_KNOWN_PATH = "/.well-known/agent-receipt-v1.json";
+export const AGENT_RECEIPT_SIGNING_KEYS_WELL_KNOWN_PATH = "/.well-known/agent-receipt-signing-keys.json";
+/** Gateway evidence proxy header carrying Kit-verified external attestation digests. */
+export 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 const PAYBOND_AGENT_RECEIPT_SOURCE_RUN_HEADER = "x-paybond-agent-run-id";
 const SCOPE_TOKEN_RE = /^[a-z0-9][a-z0-9._:/-]{0,127}$/;
 const HEX64_RE = /^[0-9a-f]{64}$/;
 const CURRENCY_RE = /^[a-z]{3}$/;
@@ -145,6 +151,9 @@ function normalizeReceipt(receipt) {
         outcome,
         references,
         external_attestations: externalAttestations,
+        operator_attestation: receipt.operator_attestation
+            ? normalizeOperatorAttestation(receipt.operator_attestation)
+            : undefined,
         signing_algorithm: receipt.signing_algorithm.trim().toLowerCase() || AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519,
         message_digest_sha256_hex: receipt.message_digest_sha256_hex.trim().toLowerCase(),
         signing_public_key_ed25519_hex: receipt.signing_public_key_ed25519_hex.trim().toLowerCase(),
@@ -153,6 +162,18 @@ function normalizeReceipt(receipt) {
     verifyReceiptId(normalized);
     return normalized;
 }
+function normalizeOperatorAttestation(attestation) {
+    const operatorDid = attestation.operator_did.trim();
+    if (!operatorDid) {
+        throw new Error("agent receipt: operator_attestation.operator_did is required");
+    }
+    return {
+        operator_did: operatorDid,
+        signing_public_key_ed25519_hex: attestation.signing_public_key_ed25519_hex.trim().toLowerCase(),
+        message_digest_sha256_hex: attestation.message_digest_sha256_hex.trim().toLowerCase(),
+        ed25519_signature_hex: attestation.ed25519_signature_hex.trim().toLowerCase(),
+    };
+}
 function normalizeAuthorization(authorization) {
     const principalDid = authorization.principal_did.trim();
     const actorSubject = authorization.actor_subject.trim();
@@ -496,10 +517,27 @@ export function canonicalAgentReceiptBytes(receipt) {
 export function agentReceiptMessageDigestSha256Hex(receipt) {
     return sha256Hex(canonicalAgentReceiptBytes(receipt));
 }
+function allowsSigningPublicKeyHex(signingPublicKeyHex, expectedSigningPublicKeys) {
+    if (!expectedSigningPublicKeys || expectedSigningPublicKeys.length === 0) {
+        return true;
+    }
+    const normalized = signingPublicKeyHex.trim().toLowerCase();
+    return expectedSigningPublicKeys.some((value) => value.trim().toLowerCase() === normalized);
+}
+function allowsOperatorPublicKeyHex(operatorPublicKeyHex, trustedOperatorPublicKeys) {
+    if (!trustedOperatorPublicKeys || trustedOperatorPublicKeys.length === 0) {
+        return false;
+    }
+    const normalized = operatorPublicKeyHex.trim().toLowerCase();
+    return trustedOperatorPublicKeys.some((value) => value.trim().toLowerCase() === normalized);
+}
 /** Validates structure, receipt_id derivation, digest, and detached Ed25519 signature. */
-export async function verifyAgentReceiptV1(receipt) {
+export async function verifyAgentReceiptV1(receipt, options = {}) {
     ensureEd25519Sha512Sync();
     const normalized = normalizeReceipt(receipt);
+    if (!allowsSigningPublicKeyHex(normalized.signing_public_key_ed25519_hex, options.expectedSigningPublicKeys)) {
+        throw new Error("agent receipt: signing_public_key_ed25519_hex is not in the configured trusted key set");
+    }
     const canonical = marshalCanonicalAgentReceipt(normalized);
     const digest = createHash("sha256").update(canonical).digest();
     const digestHex = sha256Hex(canonical);
@@ -519,10 +557,17 @@ export async function verifyAgentReceiptV1(receipt) {
     if (!valid) {
         throw new Error("agent receipt: ed25519 signature verification failed");
     }
-    await verifyOperatorAttestation(normalized, digest);
+    await verifyOperatorAttestation(normalized, digest, options);
     return normalized;
 }
-async function verifyOperatorAttestation(receipt, gatewayDigest) {
+/** Validate raw JSON (schema + forbidden fields) then verify signature. */
+export async function verifyAgentReceiptV1FromJSON(raw, options = {}) {
+    const receipt = typeof raw === "object" && !(raw instanceof Uint8Array) && !Array.isArray(raw)
+        ? validateAgentReceiptJSON(raw)
+        : parseAgentReceiptJSON(raw);
+    return verifyAgentReceiptV1(receipt, options);
+}
+async function verifyOperatorAttestation(receipt, gatewayDigest, options = {}) {
     const attestation = receipt.operator_attestation;
     if (!attestation) {
         return;
@@ -531,10 +576,17 @@ async function verifyOperatorAttestation(receipt, gatewayDigest) {
     if (!operatorDid) {
         throw new Error("agent receipt: operator_attestation.operator_did is required");
     }
+    if (operatorDid !== receipt.authorization.agent.operator_did.trim()) {
+        throw new Error("agent receipt: operator_attestation.operator_did must match authorization.agent.operator_did");
+    }
     requireHex64(attestation.message_digest_sha256_hex, "operator_attestation.message_digest_sha256_hex");
     if (attestation.message_digest_sha256_hex !== receipt.message_digest_sha256_hex) {
         throw new Error("agent receipt: operator_attestation message_digest_sha256_hex must match gateway digest");
     }
+    if (options.verifyOperatorAgainstRegistry &&
+        !allowsOperatorPublicKeyHex(attestation.signing_public_key_ed25519_hex, options.trustedOperatorPublicKeys)) {
+        throw new Error("agent receipt: operator_attestation signing key is not in the configured tenant operator registry");
+    }
     const publicKey = hexToBytes(attestation.signing_public_key_ed25519_hex);
     const signature = hexToBytes(attestation.ed25519_signature_hex);
     if (publicKey.length !== 32 || signature.length !== 64) {
@@ -549,6 +601,13 @@ async function verifyOperatorAttestation(receipt, gatewayDigest) {
 export async function attachOperatorAttestationV1(receipt, operatorPrivateKeyHex, operatorDid) {
     ensureEd25519Sha512Sync();
     const verified = await verifyAgentReceiptV1(receipt);
+    const normalizedOperatorDid = operatorDid.trim();
+    if (!normalizedOperatorDid) {
+        throw new Error("agent receipt: operator_did is required");
+    }
+    if (normalizedOperatorDid !== verified.authorization.agent.operator_did.trim()) {
+        throw new Error("agent receipt: operator_did must match authorization.agent.operator_did");
+    }
     const digest = hexToBytes(verified.message_digest_sha256_hex);
     const privateKey = hexToBytes(operatorPrivateKeyHex);
     if (privateKey.length !== 64 && privateKey.length !== 32) {
@@ -561,7 +620,7 @@ export async function attachOperatorAttestationV1(receipt, operatorPrivateKeyHex
     return {
         ...verified,
         operator_attestation: {
-            operator_did: operatorDid.trim(),
+            operator_did: normalizedOperatorDid,
             signing_public_key_ed25519_hex: Buffer.from(publicKey).toString("hex"),
             message_digest_sha256_hex: verified.message_digest_sha256_hex,
             ed25519_signature_hex: Buffer.from(signature).toString("hex"),

package/dist/cli/command-spec.js

@@ -29,6 +29,16 @@ export const COMMAND_PATHS = [
     "dev trace",
     "dev loop",
     "dev up",
+    "shopify doctor",
+    "shopify link",
+    "shopify dev",
+    "shopify webhook trigger",
+    "shopify checkout smoke",
+    "shopify order show",
+    "shopify capture ready",
+    "shopify payments doctor",
+    "shopify payments smoke",
+    "shopify payments session show",
     "version",
     "diagnose",
     "config get",
@@ -196,7 +206,8 @@ export const COMMAND_EXAMPLES = {
     ],
     "doctor": [
         "paybond doctor",
-        "paybond doctor --agent --format json"
+        "paybond doctor --agent --format json",
+        "paybond doctor --shopify"
     ],
     "dev": [
         "paybond dev smoke --offline",
@@ -216,6 +227,7 @@ export const COMMAND_EXAMPLES = {
     "dev loop": [
         "paybond dev loop",
         "paybond dev loop --offline",
+        "paybond dev loop --preset shopping --shopify",
         "paybond dev loop --format json"
     ],
     "dev up": [
@@ -223,6 +235,43 @@ export const COMMAND_EXAMPLES = {
         "paybond dev up --port 18089",
         "paybond dev up --down"
     ],
+    "shopify doctor": [
+        "paybond shopify doctor",
+        "paybond shopify doctor --format json"
+    ],
+    "shopify link": [
+        "paybond shopify link"
+    ],
+    "shopify dev": [
+        "paybond shopify dev",
+        "paybond shopify dev --tunnel https://example.ngrok-free.app"
+    ],
+    "shopify webhook trigger": [
+        "paybond shopify webhook trigger --topic orders/paid --gateway https://api.paybond.ai",
+        "paybond shopify webhook trigger --address http://127.0.0.1:8081/webhooks/sandbox/shopify --dry-run"
+    ],
+    "shopify checkout smoke": [
+        "paybond shopify checkout smoke --shop paybond-agent-commerce-dev.myshopify.com",
+        "paybond shopify checkout smoke --offline --format json"
+    ],
+    "shopify order show": [
+        "paybond shopify order show gid://shopify/Order/123 --shop paybond-agent-commerce-dev.myshopify.com"
+    ],
+    "shopify capture ready": [
+        "paybond shopify capture ready",
+        "paybond shopify capture ready --format json"
+    ],
+    "shopify payments doctor": [
+        "paybond shopify payments doctor",
+        "paybond shopify payments doctor --format json"
+    ],
+    "shopify payments smoke": [
+        "paybond shopify payments smoke --shop paybond-agent-commerce-dev.myshopify.com",
+        "paybond shopify payments smoke --offline --format json"
+    ],
+    "shopify payments session show": [
+        "paybond shopify payments session show paybond-smoke-payment-session --shop paybond-agent-commerce-dev.myshopify.com"
+    ],
     "version": [
         "paybond version",
         "paybond version --verbose --format json"