@paybond/kit 0.11.10 → 0.12.0

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

@@ -0,0 +1,124 @@
+/**
+ * Maps partner attestation artifacts into Agent Receipt `external_attestations` entries.
+ *
+ * Partner digests are SHA-256 of canonical JSON (signature fields stripped for SEP-2828).
+ * These entries are never canonical inside Paybond; they provide interop hooks only.
+ */
+import { createHash } from "node:crypto";
+import { normalizeJson } from "./json-digest.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";
+const SEP2828_SIGNATURE_KEYS = new Set([
+    "signature",
+    "ed25519_signature_hex",
+    "message_digest_sha256_hex",
+    "signing_public_key_ed25519_hex",
+]);
+const SEP2828_ASSERTED_BLOCKS = ["issuerAsserted", "receiptAsserted"];
+function readObject(value) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+function canonicalJsonBytes(value) {
+    return new TextEncoder().encode(JSON.stringify(normalizeJson(value)));
+}
+/** SHA-256 hex digest of canonical JSON bytes. */
+export function partnerRecordDigestSha256Hex(record) {
+    return createHash("sha256").update(Buffer.from(canonicalJsonBytes(record))).digest("hex");
+}
+function stripSep2828SignatureFields(record) {
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (SEP2828_SIGNATURE_KEYS.has(key)) {
+            continue;
+        }
+        if (SEP2828_ASSERTED_BLOCKS.includes(key)) {
+            const asserted = readObject(value);
+            if (!asserted) {
+                continue;
+            }
+            const stripped = {};
+            for (const [innerKey, innerValue] of Object.entries(asserted)) {
+                if (!SEP2828_SIGNATURE_KEYS.has(innerKey)) {
+                    stripped[innerKey] = innerValue;
+                }
+            }
+            if (Object.keys(stripped).length > 0) {
+                out[key] = stripped;
+            }
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+function sep2828RecordDigest(record) {
+    return partnerRecordDigestSha256Hex(stripSep2828SignatureFields(record));
+}
+function x402PayloadDigestSha256Hex(payload) {
+    return partnerRecordDigestSha256Hex(payload);
+}
+/**
+ * Converts verified SEP-2828 decision/outcome records into external attestation entries.
+ */
+export function sep2828RecordsToExternalAttestations(decisionInput, outcomeInput) {
+    verifySep2828ReceiptPair(decisionInput, outcomeInput);
+    const decisionBackLink = readObject(decisionInput.backLink);
+    const referenceID = typeof decisionBackLink?.attestationDigest === "string"
+        ? stripDigestPrefix(decisionBackLink.attestationDigest)
+        : undefined;
+    return [
+        {
+            source: AGENT_RECEIPT_EXTERNAL_SOURCE_SEP2828,
+            kind: "decision_record",
+            digest_sha256_hex: sep2828RecordDigest(decisionInput),
+            reference_id: referenceID,
+        },
+        {
+            source: AGENT_RECEIPT_EXTERNAL_SOURCE_SEP2828,
+            kind: "outcome_record",
+            digest_sha256_hex: sep2828RecordDigest(outcomeInput),
+            reference_id: referenceID,
+        },
+    ];
+}
+/**
+ * Converts a verified x402 signed delivery receipt into one external attestation entry.
+ */
+export function x402ReceiptToExternalAttestations(receiptInput) {
+    const signed = extractSignedX402Receipt(receiptInput);
+    const verifiedPayload = verifySignedX402Receipt(signed);
+    const payload = buildX402ReceiptDigestPayload(verifiedPayload);
+    return [
+        {
+            source: AGENT_RECEIPT_EXTERNAL_SOURCE_X402,
+            kind: "delivery_receipt_v1",
+            digest_sha256_hex: x402PayloadDigestSha256Hex(payload),
+            reference_id: payload.resourceUrl,
+        },
+    ];
+}
+/** Resolves pre-built or partner-native attestation inputs into normalized receipt entries. */
+export function resolveExternalAttestations(inputs) {
+    const out = [];
+    for (const input of inputs) {
+        if ("source" in input && "digest_sha256_hex" in input) {
+            out.push(input);
+            continue;
+        }
+        if (input.kind === "sep2828") {
+            out.push(...sep2828RecordsToExternalAttestations(input.decision, input.outcome));
+            continue;
+        }
+        if (input.kind === "x402") {
+            out.push(...x402ReceiptToExternalAttestations(input.receipt));
+        }
+    }
+    return out;
+}

package/dist/agent-receipt.d.ts

@@ -0,0 +1,134 @@
+export declare const AGENT_RECEIPT_SCHEMA_VERSION = 1;
+export declare const AGENT_RECEIPT_KIND_V1 = "paybond.agent_receipt_v1";
+export declare const AGENT_RECEIPT_VERSION_V1 = "1";
+export declare const AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519 = "ed25519-sha256-json-v1";
+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 type AgentReceiptAgentV1 = {
+    operator_did: string;
+    model_family: string;
+    model_instance_id?: string;
+    config_hash_sha256_hex: string;
+    prompt_hash_sha256_hex: string;
+    deployment_epoch?: number;
+};
+export type AgentReceiptPolicyV1 = {
+    template_id: string;
+    version_seq?: number;
+    content_digest_sha256_hex: string;
+    spend_policy_version?: number;
+};
+export type AgentReceiptAuthorizationV1 = {
+    principal_did: string;
+    actor_subject: string;
+    agent: AgentReceiptAgentV1;
+    decision_id: string;
+    audit_id?: string;
+    policy: AgentReceiptPolicyV1;
+    authorized_at: string;
+    requested_spend_cents: number;
+    currency: string;
+    reason_codes?: string[];
+};
+export type AgentReceiptExecutionV1 = {
+    run_id: string;
+    tool_call_id: string;
+    tool_name: string;
+    operation: string;
+    arguments_digest_sha256_hex: string;
+    result_digest_sha256_hex?: string;
+    outcome: "executed" | "denied" | "skipped" | "failed";
+    started_at: string;
+    completed_at: string;
+    duration_ms?: number;
+};
+export type AgentReceiptMerchantV1 = {
+    payee_did: string;
+    vendor_id?: string;
+    vendor_ref_id?: string;
+};
+export type AgentReceiptEvidenceV1 = {
+    completion_preset_id: string;
+    payload_digest_sha256_hex: string;
+    artifacts_digest_sha256_hex?: string;
+    predicate_passed: boolean;
+    payee_did: string;
+    payee_signature_digest_sha256_hex?: string;
+};
+export type AgentReceiptPaymentV1 = {
+    intent_id: string;
+    settlement_rail: string;
+    funding_method?: string;
+    funding_reference?: string;
+    funding_receipt_digest_sha256_hex?: string;
+};
+export type AgentReceiptOutcomeV1 = {
+    harbor_state: string;
+    spend_reservation_outcome?: "consumed" | "released" | "pending" | "none";
+    predicate_passed?: boolean;
+};
+export type AgentReceiptReferencesV1 = {
+    intent_id: string;
+    ledger_seq?: number;
+    settlement_receipt_id?: string | null;
+};
+export type AgentReceiptExternalAttestationV1 = {
+    source: string;
+    kind: string;
+    digest_sha256_hex: string;
+    reference_id?: string;
+};
+export type AgentReceiptOperatorAttestationV1 = {
+    operator_did: string;
+    signing_public_key_ed25519_hex: string;
+    message_digest_sha256_hex: string;
+    ed25519_signature_hex: string;
+};
+export type AgentReceiptV1 = {
+    schema_version: number;
+    kind: string;
+    receipt_version: string;
+    scope: typeof AGENT_RECEIPT_SCOPE_ACTION | typeof AGENT_RECEIPT_SCOPE_INTENT_TERMINAL;
+    receipt_id: string;
+    issued_at: string;
+    tenant_id: string;
+    authorization: AgentReceiptAuthorizationV1;
+    execution?: AgentReceiptExecutionV1;
+    merchant?: AgentReceiptMerchantV1;
+    evidence?: AgentReceiptEvidenceV1;
+    payment?: AgentReceiptPaymentV1;
+    outcome: AgentReceiptOutcomeV1;
+    references: AgentReceiptReferencesV1;
+    external_attestations: AgentReceiptExternalAttestationV1[];
+    operator_attestation?: AgentReceiptOperatorAttestationV1;
+    signing_algorithm: string;
+    message_digest_sha256_hex: string;
+    signing_public_key_ed25519_hex: string;
+    ed25519_signature_hex: string;
+};
+export type ConfigHashInput = {
+    system_prompt: string;
+    tools_manifest: unknown;
+    policy_snapshot_id: string;
+};
+/** Returns sha256(JCS({ system_prompt, tools_manifest, policy_snapshot_id })). */
+export declare function configHashSha256Hex(input: ConfigHashInput): string;
+/** Returns sha256(normalized_user_prompt). */
+export declare function promptHashSha256Hex(normalizedUserPrompt: string): string;
+/** Returns sha256(JCS(value)). */
+export declare function valueDigestSha256Hex(value: unknown): string;
+/** Returns sha256(intent_id + "\\x00" + tool_call_id) as lowercase hex. */
+export declare function actionReceiptId(intentId: string, toolCallId: string): string;
+/** Returns canonical signing bytes for a normalized receipt body. */
+export declare function canonicalAgentReceiptBytes(receipt: AgentReceiptV1): Uint8Array;
+/**
+ * Returns sha256(canonical receipt bytes) as lowercase hex, ignoring any existing
+ * `message_digest_sha256_hex` on the input. Used to compose unsigned receipt drafts
+ * (Agent Receipt Standard Phase 1) and to compute the digest signers must sign over.
+ */
+export declare function agentReceiptMessageDigestSha256Hex(receipt: AgentReceiptV1): string;
+/** Validates structure, receipt_id derivation, digest, and detached Ed25519 signature. */
+export declare function verifyAgentReceiptV1(receipt: AgentReceiptV1): 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>;