@paybond/kit 0.10.0 → 0.11.1

package/dist/vercel-ai/index.js

@@ -0,0 +1,4 @@
+export { createPaybondVercelAgentConfig, } from "./config.js";
+export { mapPaybondDecisionToVercelToolApproval, paybondVercelToolApproval, } from "./tool-approval.js";
+export { paybondVercelWrapTools } from "./wrap-tools.js";
+export { runVercelAiSandboxDemo, } from "./sandbox-demo.js";

package/dist/vercel-ai/sandbox-demo.d.ts

@@ -0,0 +1,44 @@
+import type { Paybond } from "../index.js";
+export type RunVercelAiSandboxDemoInput = {
+    paybond: Paybond;
+    operation?: string;
+    requestedSpendCents?: number;
+    evidencePreset?: string;
+    toolCallId?: string;
+};
+export type RunVercelAiSandboxDemoResult = {
+    bind: {
+        run_id: string;
+        tenant_id: string;
+        intent_id: string;
+        capability_token: string;
+        operation: string;
+        sandbox_lifecycle_status?: string;
+    };
+    tool_approval: string | {
+        type: string;
+        reason?: string;
+    };
+    generate_text: {
+        text: string;
+        step_count: number;
+        tool_calls: number;
+    };
+    execute: {
+        tool_result?: unknown;
+        authorization?: {
+            audit_id?: string;
+            decision_id?: string;
+        };
+        evidence?: {
+            submitted: boolean;
+            sandbox_lifecycle_status?: string;
+            predicate_passed?: boolean | null;
+        };
+    };
+};
+/**
+ * No-LLM Vercel AI SDK sandbox demo: `toolApproval` + wrapped `execute` + auto-evidence.
+ * Uses `MockLanguageModelV4` — no provider API key required.
+ */
+export declare function runVercelAiSandboxDemo(input: RunVercelAiSandboxDemoInput): Promise<RunVercelAiSandboxDemoResult>;

package/dist/vercel-ai/sandbox-demo.js

@@ -0,0 +1,153 @@
+import { generateText, jsonSchema, stepCountIs, tool } from "ai";
+import { MockLanguageModelV4 } from "ai/test";
+import { createPaybondToolRegistry } from "../agent/registry.js";
+import { paybondVercelToolApproval } from "./tool-approval.js";
+import { paybondVercelWrapTools } from "./wrap-tools.js";
+function mockUsage() {
+    return {
+        inputTokens: { total: 3, noCache: 3, cacheRead: undefined, cacheWrite: undefined },
+        outputTokens: { total: 10, text: 10, reasoning: undefined },
+    };
+}
+async function executePaidTool(args) {
+    return { status: "completed", cost_cents: args.estimatedPriceCents };
+}
+async function searchWeb(args) {
+    return { hits: [{ title: args.query, url: "https://example.com" }] };
+}
+/**
+ * No-LLM Vercel AI SDK sandbox demo: `toolApproval` + wrapped `execute` + auto-evidence.
+ * Uses `MockLanguageModelV4` — no provider API key required.
+ */
+export async function runVercelAiSandboxDemo(input) {
+    const operation = (input.operation ?? "paid-tool").trim();
+    const requestedSpendCents = input.requestedSpendCents ?? 100;
+    const evidencePreset = (input.evidencePreset ?? "cost_and_completion").trim();
+    const toolCallId = (input.toolCallId ?? "vercel-demo-1").trim();
+    const registry = createPaybondToolRegistry({
+        defaultDeny: true,
+        sideEffecting: {
+            [operation]: {
+                operation,
+                evidencePreset,
+                spendCents: requestedSpendCents,
+                evidenceMapper: (result) => {
+                    const payload = result;
+                    return {
+                        status: payload.status,
+                        cost_cents: payload.cost_cents,
+                    };
+                },
+            },
+        },
+    });
+    const run = await input.paybond.agentRun.bind({
+        bootstrap: {
+            kind: "sandbox",
+            operation,
+            requestedSpendCents,
+            completionPreset: evidencePreset,
+        },
+        registry,
+    });
+    const rawTools = {
+        [operation]: tool({
+            description: `Paid operation ${operation}`,
+            inputSchema: jsonSchema({
+                type: "object",
+                properties: {
+                    estimatedPriceCents: { type: "integer", minimum: 0 },
+                },
+                required: ["estimatedPriceCents"],
+                additionalProperties: false,
+            }),
+            execute: async (args) => executePaidTool(args),
+        }),
+        "search.web": tool({
+            description: "Read-only web search",
+            inputSchema: jsonSchema({
+                type: "object",
+                properties: { query: { type: "string" } },
+                required: ["query"],
+                additionalProperties: false,
+            }),
+            execute: async (args) => searchWeb(args),
+        }),
+    };
+    const tools = paybondVercelWrapTools(run, rawTools);
+    const toolApproval = paybondVercelToolApproval(run);
+    const toolInput = { estimatedPriceCents: requestedSpendCents };
+    const approvalStatus = await toolApproval({
+        toolCall: {
+            type: "tool-call",
+            toolName: operation,
+            toolCallId,
+            input: toolInput,
+        },
+        tools,
+        toolsContext: {},
+        runtimeContext: undefined,
+        messages: [],
+    });
+    let stepCount = 0;
+    const generated = await generateText({
+        model: new MockLanguageModelV4({
+            doGenerate: [
+                {
+                    content: [
+                        {
+                            type: "tool-call",
+                            toolCallId,
+                            toolName: operation,
+                            input: JSON.stringify(toolInput),
+                        },
+                    ],
+                    finishReason: { unified: "tool-calls", raw: "tool_calls" },
+                    usage: mockUsage(),
+                    warnings: [],
+                },
+                {
+                    content: [{ type: "text", text: "paid tool completed" }],
+                    finishReason: { unified: "stop", raw: "stop" },
+                    usage: mockUsage(),
+                    warnings: [],
+                },
+            ],
+        }),
+        tools,
+        toolApproval: toolApproval,
+        stopWhen: stepCountIs(5),
+        prompt: "run the paid tool",
+    });
+    stepCount = generated.steps.length;
+    const paidToolResult = generated.toolResults.find((entry) => entry.toolName === operation);
+    return {
+        bind: {
+            run_id: run.runId,
+            tenant_id: run.tenantId,
+            intent_id: run.intentId,
+            capability_token: run.capabilityToken,
+            operation,
+            sandbox_lifecycle_status: run.binding.sandbox?.sandboxLifecycleStatus,
+        },
+        tool_approval: approvalStatus === undefined
+            ? "not-applicable"
+            : typeof approvalStatus === "string"
+                ? approvalStatus
+                : { type: approvalStatus.type },
+        generate_text: {
+            text: generated.text,
+            step_count: stepCount,
+            tool_calls: generated.toolCalls.length,
+        },
+        execute: {
+            tool_result: paidToolResult?.output,
+            evidence: paidToolResult
+                ? {
+                    submitted: true,
+                    sandbox_lifecycle_status: run.binding.sandbox?.sandboxLifecycleStatus,
+                }
+                : undefined,
+        },
+    };
+}

package/dist/vercel-ai/tool-approval.d.ts

@@ -0,0 +1,16 @@
+import type { GenericToolApprovalFunction, ToolApprovalStatus, ToolSet } from "ai";
+import type { PaybondAgentRun } from "../agent/run.js";
+import type { PaybondToolInputGuardDecision } from "../agent/types.js";
+/** Map a framework-neutral Paybond decision to Vercel AI SDK tool approval status. */
+export declare function mapPaybondDecisionToVercelToolApproval(decision: PaybondToolInputGuardDecision): ToolApprovalStatus;
+export type PaybondVercelToolApprovalOptions = {
+    /** Override Paybond → Vercel approval status mapping (for example custom HITL labels). */
+    mapDecision?: (decision: PaybondToolInputGuardDecision) => ToolApprovalStatus;
+};
+/**
+ * Centralized `toolApproval` bridge for Vercel AI SDK `generateText` / `streamText`.
+ *
+ * Non-side-effecting tools are auto-approved without Harbor verify. Side-effecting
+ * registered tools run the Paybond interceptor pre-check; denials propagate as tool errors.
+ */
+export declare function paybondVercelToolApproval<TOOLS extends ToolSet = ToolSet>(run: PaybondAgentRun, options?: PaybondVercelToolApprovalOptions): GenericToolApprovalFunction<TOOLS, never, never>;

package/dist/vercel-ai/tool-approval.js

@@ -0,0 +1,41 @@
+import { createToolInputGuardAdapter } from "../agent/adapter.js";
+/** Map a framework-neutral Paybond decision to Vercel AI SDK tool approval status. */
+export function mapPaybondDecisionToVercelToolApproval(decision) {
+    if (decision.kind === "allow") {
+        return "approved";
+    }
+    if (decision.kind === "approval_required") {
+        return "user-approval";
+    }
+    return { type: "denied", reason: decision.message };
+}
+/**
+ * Centralized `toolApproval` bridge for Vercel AI SDK `generateText` / `streamText`.
+ *
+ * Non-side-effecting tools are auto-approved without Harbor verify. Side-effecting
+ * registered tools run the Paybond interceptor pre-check; denials propagate as tool errors.
+ */
+export function paybondVercelToolApproval(run, options) {
+    const guard = createToolInputGuardAdapter(run);
+    const mapDecision = options?.mapDecision ?? mapPaybondDecisionToVercelToolApproval;
+    const approve = async ({ toolCall, }) => {
+        const toolName = toolCall.toolName;
+        const toolCallId = toolCall.toolCallId;
+        if (!run.registry.isSideEffecting(toolName)) {
+            const resolution = run.registry.resolveTool(toolName, {
+                allowedTools: run.allowedTools,
+            });
+            if (resolution.kind === "passthrough") {
+                return "approved";
+            }
+        }
+        const decision = await guard.evaluate({
+            toolName,
+            toolCallId,
+            arguments: toolCall.input,
+            approvalToken: run.getApprovalToken(toolCallId),
+        });
+        return mapDecision(decision);
+    };
+    return approve;
+}

package/dist/vercel-ai/wrap-tools.d.ts

@@ -0,0 +1,9 @@
+import type { ToolSet } from "ai";
+import type { PaybondAgentRun } from "../agent/run.js";
+/**
+ * Wrap side-effecting Vercel AI SDK tools with Paybond `wrapExecute` so Harbor
+ * verify, spend finalize, and auto-evidence run after successful execution.
+ *
+ * Read-only and provider-executed tools pass through unchanged.
+ */
+export declare function paybondVercelWrapTools<TOOLS extends ToolSet>(run: PaybondAgentRun, tools: TOOLS): TOOLS;

package/dist/vercel-ai/wrap-tools.js

@@ -0,0 +1,40 @@
+function isClientExecutedTool(tool) {
+    if (typeof tool !== "object" || tool === null) {
+        return false;
+    }
+    const record = tool;
+    if (record.isProviderExecuted === true) {
+        return false;
+    }
+    return typeof record.execute === "function";
+}
+/**
+ * Wrap side-effecting Vercel AI SDK tools with Paybond `wrapExecute` so Harbor
+ * verify, spend finalize, and auto-evidence run after successful execution.
+ *
+ * Read-only and provider-executed tools pass through unchanged.
+ */
+export function paybondVercelWrapTools(run, tools) {
+    const wrapped = {};
+    for (const [toolName, tool] of Object.entries(tools)) {
+        if (!isClientExecutedTool(tool) || !run.registry.isSideEffecting(toolName)) {
+            wrapped[toolName] = tool;
+            continue;
+        }
+        const originalExecute = tool.execute.bind(tool);
+        wrapped[toolName] = {
+            ...tool,
+            execute: async (input, options) => {
+                const result = await run.interceptor.wrapExecute({
+                    toolName,
+                    toolCallId: options.toolCallId,
+                    arguments: input,
+                    approvalToken: run.getApprovalToken(options.toolCallId),
+                    execute: () => originalExecute(input, options),
+                });
+                return result.toolResult;
+            },
+        };
+    }
+    return wrapped;
+}

package/dist/x402-receipt-evidence.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Maps x402 Signed Offer & Receipt extension payloads into artifact_attested evidence.
+ *
+ * Digests JCS-canonical receipt bytes (resourceUrl, payer, network, issuedAt, optional transaction)
+ * into artifact_blake3_hex. Does not import Coinbase authorization_succeeded funding webhooks.
+ */
+export declare const X402_RECEIPT_MAPPER_VERSION = "x402_receipt_v1";
+export type X402ReceiptPayloadV1 = {
+    resourceUrl: string;
+    payer: string;
+    network: string;
+    issuedAt: number;
+    transaction?: string;
+};
+export type ArtifactAttestedEvidence = {
+    artifact_blake3_hex: string[];
+    operation: string;
+    vendor_ref_id: string;
+};
+/** Rejects Coinbase funding webhook shapes — those are not tool-completion evidence. */
+export declare function assertNotX402FundingArtifact(input: Record<string, unknown>): void;
+/** Normalizes wire fields into the v1 digest payload (camelCase, optional transaction only when set). */
+export declare function buildX402ReceiptDigestPayload(raw: Record<string, unknown>): X402ReceiptPayloadV1;
+/** BLAKE3 hex digest of JCS-canonical x402 receipt payload bytes. */
+export declare function x402ReceiptPayloadDigestHex(payload: X402ReceiptPayloadV1): string;
+/**
+ * Converts an x402 signed receipt artifact or payload into artifact_attested evidence fields.
+ */
+export declare function mapX402ReceiptToArtifactAttestedEvidence(receiptInput: Record<string, unknown>): ArtifactAttestedEvidence;

package/dist/x402-receipt-evidence.js

@@ -0,0 +1,97 @@
+/**
+ * Maps x402 Signed Offer & Receipt extension payloads into artifact_attested evidence.
+ *
+ * Digests JCS-canonical receipt bytes (resourceUrl, payer, network, issuedAt, optional transaction)
+ * into artifact_blake3_hex. Does not import Coinbase authorization_succeeded funding webhooks.
+ */
+import { jsonValueDigest } from "./json-digest.js";
+import { extractSignedX402Receipt, verifySignedX402Receipt } from "./x402-receipt-signature.js";
+export const X402_RECEIPT_MAPPER_VERSION = "x402_receipt_v1";
+const FUNDING_EVIDENCE_FIELDS = [
+    "payment_session_id",
+    "authorization_id",
+    "capture_id",
+    "void_id",
+    "x402_payment_session_id",
+    "onchain_transaction_hashes",
+];
+function readString(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string" && value.length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function readNumber(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "number" && Number.isFinite(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function digestToHex(bytes) {
+    return Buffer.from(bytes).toString("hex");
+}
+/** Rejects Coinbase funding webhook shapes — those are not tool-completion evidence. */
+export function assertNotX402FundingArtifact(input) {
+    const eventType = readString(input, "event_type", "eventType", "type");
+    if (eventType === "authorization_succeeded") {
+        throw new Error("authorization_succeeded webhooks are funding signals, not x402 delivery receipt evidence");
+    }
+    for (const field of FUNDING_EVIDENCE_FIELDS) {
+        if (Object.prototype.hasOwnProperty.call(input, field)) {
+            throw new Error(`funding field ${field} must not be submitted as tool-completion evidence`);
+        }
+    }
+}
+function hasReceiptShape(record) {
+    return (readString(record, "resourceUrl", "resource_url") !== undefined &&
+        readString(record, "payer") !== undefined &&
+        readString(record, "network") !== undefined &&
+        readNumber(record, "issuedAt", "issued_at") !== undefined);
+}
+function unwrapReceiptRecord(input) {
+    assertNotX402FundingArtifact(input);
+    const signed = extractSignedX402Receipt(input);
+    const verifiedPayload = verifySignedX402Receipt(signed);
+    if (hasReceiptShape(verifiedPayload)) {
+        return verifiedPayload;
+    }
+    throw new Error("x402 receipt payload missing required fields (resourceUrl, payer, network, issuedAt)");
+}
+/** Normalizes wire fields into the v1 digest payload (camelCase, optional transaction only when set). */
+export function buildX402ReceiptDigestPayload(raw) {
+    const resourceUrl = readString(raw, "resourceUrl", "resource_url");
+    const payer = readString(raw, "payer");
+    const network = readString(raw, "network");
+    const issuedAt = readNumber(raw, "issuedAt", "issued_at");
+    const transaction = readString(raw, "transaction", "txHash", "tx_hash");
+    if (!resourceUrl || !payer || !network || issuedAt === undefined) {
+        throw new Error("x402 receipt payload missing required fields (resourceUrl, payer, network, issuedAt)");
+    }
+    const payload = { resourceUrl, payer, network, issuedAt };
+    if (transaction) {
+        payload.transaction = transaction;
+    }
+    return payload;
+}
+/** BLAKE3 hex digest of JCS-canonical x402 receipt payload bytes. */
+export function x402ReceiptPayloadDigestHex(payload) {
+    return digestToHex(jsonValueDigest(payload));
+}
+/**
+ * Converts an x402 signed receipt artifact or payload into artifact_attested evidence fields.
+ */
+export function mapX402ReceiptToArtifactAttestedEvidence(receiptInput) {
+    const raw = unwrapReceiptRecord(receiptInput);
+    const payload = buildX402ReceiptDigestPayload(raw);
+    return {
+        artifact_blake3_hex: [x402ReceiptPayloadDigestHex(payload)],
+        operation: "attested",
+        vendor_ref_id: payload.resourceUrl,
+    };
+}

package/dist/x402-receipt-signature.d.ts

@@ -0,0 +1,12 @@
+/** x402 Signed Offer & Receipt extension signature verification. */
+export type SignedX402Receipt = {
+    format: "eip712" | "jws";
+    payload?: Record<string, unknown>;
+    signature: string;
+};
+/** Locates a signed x402 receipt artifact in common wire envelopes. */
+export declare function extractSignedX402Receipt(input: Record<string, unknown>): SignedX402Receipt;
+/** Cryptographically verifies an x402 signed receipt before digest mapping. */
+export declare function verifySignedX402Receipt(signed: SignedX402Receipt, options?: {
+    expectedSigner?: string;
+}): Record<string, unknown>;

package/dist/x402-receipt-signature.js

@@ -0,0 +1,211 @@
+/** x402 Signed Offer & Receipt extension signature verification. */
+import { createPublicKey, verify as cryptoVerify } from "node:crypto";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { Signature } from "@noble/secp256k1";
+function readObject(value) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+function readString(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string" && value.length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function base64UrlToBytes(input) {
+    const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = normalized.length % 4 === 0 ? "" : "=".repeat(4 - (normalized.length % 4));
+    return Uint8Array.from(Buffer.from(normalized + pad, "base64"));
+}
+function bytesToBase64Url(bytes) {
+    return Buffer.from(bytes)
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/g, "");
+}
+function keccakHex(data) {
+    return keccak_256(data);
+}
+function encodeType(typeName, fields) {
+    return `${typeName}(${fields.map((field) => `${field.type} ${field.name}`).join(",")})`;
+}
+function encodeValue(type, value) {
+    if (type === "string") {
+        return keccakHex(new TextEncoder().encode(String(value ?? "")));
+    }
+    if (type === "uint256") {
+        const bigint = typeof value === "bigint" ? value : BigInt(String(value ?? 0));
+        const hex = bigint.toString(16).padStart(64, "0");
+        return Uint8Array.from(Buffer.from(hex, "hex"));
+    }
+    throw new Error(`unsupported EIP-712 type ${type}`);
+}
+function hashStruct(typeName, fields, data) {
+    const encoded = [
+        keccakHex(new TextEncoder().encode(encodeType(typeName, fields))),
+        ...fields.map((field) => encodeValue(field.type, data[field.name])),
+    ];
+    return keccakHex(Buffer.concat(encoded.map((part) => Buffer.from(part))));
+}
+const RECEIPT_FIELDS = [
+    { name: "version", type: "uint256" },
+    { name: "network", type: "string" },
+    { name: "resourceUrl", type: "string" },
+    { name: "payer", type: "string" },
+    { name: "issuedAt", type: "uint256" },
+    { name: "transaction", type: "string" },
+];
+function normalizeReceiptPayload(payload) {
+    const transaction = payload.transaction;
+    return {
+        ...payload,
+        transaction: typeof transaction === "string" ? transaction : "",
+    };
+}
+function eip712ReceiptDigest(payload) {
+    const domainFields = [
+        { name: "name", type: "string" },
+        { name: "version", type: "string" },
+        { name: "chainId", type: "uint256" },
+    ];
+    const domain = {
+        name: "x402 receipt",
+        version: "1",
+        chainId: 1,
+    };
+    const normalized = normalizeReceiptPayload(payload);
+    const domainSeparator = hashStruct("EIP712Domain", domainFields, domain);
+    const structHash = hashStruct("Receipt", [...RECEIPT_FIELDS], normalized);
+    return keccakHex(Buffer.concat([Buffer.from([0x19, 0x01]), Buffer.from(domainSeparator), Buffer.from(structHash)]));
+}
+function parseEip712Signature(signature) {
+    const trimmed = signature.trim();
+    if (!/^0x[0-9a-fA-F]{130}$/.test(trimmed)) {
+        throw new Error("x402 EIP-712 signature must be 0x-prefixed 65-byte hex");
+    }
+    const body = trimmed.slice(2);
+    const r = BigInt(`0x${body.slice(0, 64)}`);
+    const s = BigInt(`0x${body.slice(64, 128)}`);
+    const v = Number.parseInt(body.slice(128, 130), 16);
+    return { r, s, v };
+}
+function recoverEip712Signer(digest, signature) {
+    const { r, s, v } = parseEip712Signature(signature);
+    const recovery = v >= 27 ? v - 27 : v;
+    const sigBytes = new Uint8Array(64);
+    sigBytes.set(Uint8Array.from(Buffer.from(r.toString(16).padStart(64, "0"), "hex")), 0);
+    sigBytes.set(Uint8Array.from(Buffer.from(s.toString(16).padStart(64, "0"), "hex")), 32);
+    const publicKey = Signature.fromCompact(sigBytes).addRecoveryBit(recovery).recoverPublicKey(digest);
+    const uncompressed = publicKey.toBytes(false);
+    const addressBytes = keccakHex(uncompressed.slice(1)).slice(-20);
+    return `0x${Buffer.from(addressBytes).toString("hex")}`;
+}
+function verifyJwsCompactSignature(signature) {
+    const parts = signature.split(".");
+    if (parts.length !== 3) {
+        throw new Error("x402 JWS signature must use compact serialization");
+    }
+    const [headerB64, payloadB64, sigB64] = parts;
+    const header = JSON.parse(Buffer.from(base64UrlToBytes(headerB64)).toString("utf8"));
+    const payload = JSON.parse(Buffer.from(base64UrlToBytes(payloadB64)).toString("utf8"));
+    const signingInput = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+    const signatureBytes = base64UrlToBytes(sigB64);
+    const alg = header.alg;
+    if (alg === "EdDSA" || alg === "Ed25519") {
+        const jwk = readObject(header.jwk);
+        const x = jwk ? readString(jwk, "x") : undefined;
+        if (!x) {
+            throw new Error("x402 JWS Ed25519 verification requires embedded jwk.x");
+        }
+        const publicKey = createPublicKey({
+            key: header.jwk,
+            format: "jwk",
+        });
+        if (!cryptoVerify(null, signingInput, publicKey, signatureBytes)) {
+            throw new Error("x402 JWS Ed25519 signature verification failed");
+        }
+        return payload;
+    }
+    if (alg === "ES256") {
+        const jwk = readObject(header.jwk);
+        if (!jwk) {
+            throw new Error("x402 JWS ES256 verification requires embedded jwk");
+        }
+        const publicKey = createPublicKey({
+            key: jwk,
+            format: "jwk",
+        });
+        if (!cryptoVerify("sha256", signingInput, publicKey, signatureBytes)) {
+            throw new Error("x402 JWS ES256 signature verification failed");
+        }
+        return payload;
+    }
+    throw new Error(`unsupported x402 JWS alg ${String(alg)}`);
+}
+/** Locates a signed x402 receipt artifact in common wire envelopes. */
+export function extractSignedX402Receipt(input) {
+    const extensions = readObject(input.extensions);
+    if (extensions) {
+        const offerReceipt = readObject(extensions["offer-receipt"]) ?? readObject(extensions.offerReceipt);
+        const info = offerReceipt ? readObject(offerReceipt.info) : undefined;
+        const receipt = info ? readObject(info.receipt) : undefined;
+        if (receipt && typeof receipt.format === "string" && typeof receipt.signature === "string") {
+            return {
+                format: receipt.format === "jws" ? "jws" : "eip712",
+                payload: readObject(receipt.payload),
+                signature: receipt.signature,
+            };
+        }
+        if (offerReceipt) {
+            const nested = readObject(offerReceipt.receipt) ?? offerReceipt;
+            if (nested && typeof nested.format === "string" && typeof nested.signature === "string") {
+                return {
+                    format: nested.format === "jws" ? "jws" : "eip712",
+                    payload: readObject(nested.payload),
+                    signature: nested.signature,
+                };
+            }
+        }
+    }
+    const receipt = readObject(input.receipt);
+    if (receipt && typeof receipt.format === "string" && typeof receipt.signature === "string") {
+        return {
+            format: receipt.format === "jws" ? "jws" : "eip712",
+            payload: readObject(receipt.payload),
+            signature: receipt.signature,
+        };
+    }
+    if (typeof input.format === "string" && typeof input.signature === "string") {
+        return {
+            format: input.format === "jws" ? "jws" : "eip712",
+            payload: readObject(input.payload),
+            signature: input.signature,
+        };
+    }
+    throw new Error("x402 receipt input missing signed offer-receipt artifact (format and signature required)");
+}
+/** Cryptographically verifies an x402 signed receipt before digest mapping. */
+export function verifySignedX402Receipt(signed, options) {
+    if (signed.format === "jws") {
+        const payload = verifyJwsCompactSignature(signed.signature);
+        return payload;
+    }
+    if (!signed.payload) {
+        throw new Error("x402 EIP-712 receipt requires payload alongside signature");
+    }
+    const digest = eip712ReceiptDigest(signed.payload);
+    const recovered = recoverEip712Signer(digest, signed.signature);
+    if (options?.expectedSigner) {
+        const expected = options.expectedSigner.trim().toLowerCase();
+        if (recovered.toLowerCase() !== expected) {
+            throw new Error("x402 EIP-712 recovered signer does not match expected signer");
+        }
+    }
+    return signed.payload;
+}