@paybond/kit 0.11.11 → 0.12.0

package/dist/agent/types.d.ts

@@ -1,3 +1,4 @@
+import type { AgentReceiptExternalAttestationV1 } from "../agent-receipt.js";
 /** Context passed to evidence mappers after a successful side-effecting tool call. */
 export type PaybondToolCallContext = {
     toolName: string;
@@ -9,6 +10,8 @@ export type PaybondToolCallContext = {
 export type PaybondSpendResolver<TArgs = unknown> = (args: TArgs) => number | undefined;
 /** Customize auto-evidence payload extraction from a tool result. */
 export type PaybondEvidenceMapper<TResult = unknown> = (result: TResult, ctx: PaybondToolCallContext) => Record<string, unknown>;
+/** Optional partner attestation material for Agent Receipt `external_attestations`. */
+export type PaybondExternalAttestationMapper<TResult = unknown> = (result: TResult, ctx: PaybondToolCallContext) => PaybondExternalAttestationInput | PaybondExternalAttestationInput[] | undefined;
 /** Policy for one registered side-effecting tool. */
 export type PaybondSideEffectingToolPolicy<TArgs = unknown, TResult = unknown> = {
     /** Harbor `allowed_tools` operation; defaults to the registry key (tool name). */
@@ -17,6 +20,7 @@ export type PaybondSideEffectingToolPolicy<TArgs = unknown, TResult = unknown> =
     /** Required completion catalog preset id for auto-evidence. */
     evidencePreset: string;
     evidenceMapper?: PaybondEvidenceMapper<TResult>;
+    externalAttestationMapper?: PaybondExternalAttestationMapper<TResult>;
 };
 export type PaybondToolRegistryConfig = {
     sideEffecting?: Record<string, PaybondSideEffectingToolPolicy>;
@@ -29,6 +33,7 @@ export type PaybondSideEffectingToolEntry = {
     spendCents?: number | PaybondSpendResolver;
     evidencePreset: string;
     evidenceMapper?: PaybondEvidenceMapper;
+    externalAttestationMapper?: PaybondExternalAttestationMapper;
 };
 export type PaybondToolResolution = {
     kind: "passthrough";
@@ -50,6 +55,8 @@ export declare class PaybondToolRegistryValidationError extends Error {
 import type { PaybondToolRegistry } from "./registry.js";
 import type { PaybondPolicySnapshot } from "../policy/snapshot.js";
 import type { PaybondPolicyReloadBindConfig } from "../policy/reload.js";
+import type { AgentReceiptV1 } from "../agent-receipt.js";
+import type { PaybondExternalAttestationInput } from "../agent-receipt-external-attestations.js";
 /** Spend authorization input forwarded to the run-bound guard. */
 export type PaybondRunGuardAuthInput = {
     operation: string;
@@ -63,6 +70,54 @@ export type PaybondRunGuardAuthInput = {
     agentSubject?: string;
     approvalToken?: string;
     idempotencyKey?: string;
+    /** Agent Receipt Standard context forwarded to Gateway `/verify` for audit correlation. */
+    modelFamily?: string;
+    configHashHex?: string;
+    promptHashHex?: string;
+};
+/**
+ * Materials to auto-compute `config_hash_hex` as `sha256(JCS({ system_prompt, tools_manifest,
+ * policy_snapshot_id }))` per the Agent Receipt Standard spec. `policySnapshotId` defaults to
+ * the bound policy snapshot digest (without the `sha256:` prefix) when omitted.
+ */
+export type PaybondRunConfigHashMaterials = {
+    systemPrompt: string;
+    toolsManifest: unknown;
+    policySnapshotId?: string;
+};
+/**
+ * Optional agent identity/config context for {@link PaybondAgentRun.bind}. Threaded onto every
+ * spend verify call and used to compose the unsigned Agent Receipt Standard draft returned from
+ * {@link PaybondToolInterceptor.wrapExecute}. Raw prompts are hashed locally and never retained
+ * or transmitted; only `promptHashHex` is kept on the resolved binding.
+ */
+export type PaybondRunAgentContextInput = {
+    modelFamily: string;
+    modelInstanceId?: string;
+    /** Precomputed sha256 hex digest; mutually exclusive with {@link configHashMaterials}. */
+    configHashHex?: string;
+    /** Auto-computed into `configHashHex` at bind time when `configHashHex` is omitted. */
+    configHashMaterials?: PaybondRunConfigHashMaterials;
+    /** Precomputed sha256 hex digest; mutually exclusive with {@link normalizedUserPrompt}. */
+    promptHashHex?: string;
+    /** Hashed locally at bind time into `promptHashHex`; never stored or transmitted raw. */
+    normalizedUserPrompt?: string;
+    /** Agent receipt `authorization.principal_did`; omitted from receipt drafts when unset. */
+    principalDid?: string;
+    /** Agent receipt `authorization.agent.operator_did`; omitted from receipt drafts when unset. */
+    operatorDid?: string;
+    /** Agent receipt `authorization.policy.template_id`; omitted from receipt drafts when unset. */
+    policyTemplateId?: string;
+};
+/** Resolved agent context stored on the run binding after bind-time hash computation. */
+export type PaybondRunAgentContext = {
+    modelFamily: string;
+    modelInstanceId?: string;
+    configHashHex?: string;
+    promptHashHex?: string;
+    principalDid?: string;
+    operatorDid?: string;
+    policyTemplateId?: string;
 };
 /** Spend authorization result from Harbor verify. */
 export type PaybondRunGuardAuthResult = {
@@ -116,6 +171,10 @@ export type PaybondInterceptEvidenceResult = {
     predicatePassed?: boolean | null;
     sandboxLifecycleStatus?: string;
     intentState?: string;
+    /** sha256 hex digest of the submitted evidence payload, when returned by Harbor. */
+    payloadDigestSha256Hex?: string;
+    /** sha256 hex digest of submitted evidence artifacts, when returned by Harbor. */
+    artifactsDigestSha256Hex?: string;
 };
 export type PaybondInterceptWrapExecuteResult<TResult> = {
     toolResult: TResult;
@@ -126,6 +185,12 @@ export type PaybondInterceptWrapExecuteResult<TResult> = {
         policyDigest?: string;
     };
     evidence?: PaybondInterceptEvidenceResult;
+    /**
+     * Unsigned Agent Receipt Standard draft (Phase 1: composed locally, never signed or persisted).
+     * Omitted when required context (agentContext hashes, principal/operator DID, policy template,
+     * decision id) is unavailable — receipt composition is always best-effort and never throws.
+     */
+    receiptDraft?: AgentReceiptV1;
 };
 export type PaybondInterceptWrapExecuteInput<TResult> = {
     toolName: string;
@@ -241,6 +306,7 @@ export type PaybondTraceEvidenceSubmittedEvent = {
     evidencePreset?: string;
     sandboxLifecycleStatus?: string;
     predicatePassed?: boolean | null;
+    externalAttestations?: AgentReceiptExternalAttestationV1[];
     recordedAt: string;
 };
 export type PaybondTraceSpendFinalizedEvent = {
@@ -275,6 +341,8 @@ export type PaybondRunBinding = {
     policySnapshot?: PaybondPolicySnapshot;
     /** Optional trace sink for dev observability (see {@link PaybondAgentRunBindInput.traceSink}). */
     onTrace?: PaybondTraceSink;
+    /** Resolved Agent Receipt Standard context, when bound with {@link PaybondAgentRunBindInput.agentContext}. */
+    agentContext?: PaybondRunAgentContext;
 };
 export type PaybondAgentRunBindInput = {
     bootstrap?: PaybondRunBindingSandboxBootstrapInput;
@@ -295,6 +363,8 @@ export type PaybondAgentRunBindInput = {
     traceSink?: PaybondTraceSink;
     /** @deprecated Use {@link PaybondAgentRunBindInput.traceSink}. */
     onTrace?: PaybondTraceSink;
+    /** Optional Agent Receipt Standard agent identity/config context (see {@link PaybondRunAgentContextInput}). */
+    agentContext?: PaybondRunAgentContextInput;
 };
 export declare class PaybondAgentRunBindError extends Error {
     constructor(message: string);

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

@@ -0,0 +1,29 @@
+/**
+ * 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 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";
+/** SHA-256 hex digest of canonical JSON bytes. */
+export declare function partnerRecordDigestSha256Hex(record: Record<string, unknown>): string;
+/**
+ * Converts verified SEP-2828 decision/outcome records into external attestation entries.
+ */
+export declare function sep2828RecordsToExternalAttestations(decisionInput: Record<string, unknown>, outcomeInput: Record<string, unknown>): AgentReceiptExternalAttestationV1[];
+/**
+ * Converts a verified x402 signed delivery receipt into one external attestation entry.
+ */
+export declare function x402ReceiptToExternalAttestations(receiptInput: Record<string, unknown>): AgentReceiptExternalAttestationV1[];
+export type PaybondExternalAttestationInput = {
+    kind: "sep2828";
+    decision: Record<string, unknown>;
+    outcome: Record<string, unknown>;
+} | {
+    kind: "x402";
+    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

@@ -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>;