@agent-score/commerce 2.0.2 → 2.1.1

package/dist/index.d.mts

@@ -1,21 +1,198 @@
-export { AccountVerification, AgentIdentity, AgentMemoryHint, AgentScoreCore, AssessResult, CreateSessionOnMissing, DenialCode, DenialReason, EvaluateOutcome, OperatorVerification, PolicyCheck, PolicyResult, SignerVerdict, VerifyWalletSignerResult, buildAgentMemoryHint } from './core.mjs';
+import { VerifyWalletSignerResult, DenialReason } from './core.mjs';
+export { AccountVerification, AgentIdentity, AgentMemoryHint, AgentScoreCore, AssessResult, CreateSessionOnMissing, DenialCode, EvaluateOutcome, OperatorVerification, PolicyCheck, PolicyResult, SignerVerdict, buildAgentMemoryHint } from './core.mjs';
 export { P as PaymentSigner, S as SignerNetwork, e as extractPaymentSigner, a as extractPaymentSignerFromAuth, b as extractSignerForPrecheck, r as readX402PaymentHeader } from './signer-3FAit11j.mjs';
-export { F as FIXABLE_DENIAL_REASONS, b as buildContactSupportNextSteps, a as buildSignerMismatchBody, d as denialReasonStatus, c as denialReasonToBody, i as isFixableDenial, v as verificationAgentInstructions } from './_response-BFYN3b6i.mjs';
-import { U as UCPSigningKey, a as UCPProfile } from './checkout-jNUIql6D.mjs';
-export { A as AGENTSCORE_UCP_CAPABILITY, b as AgentScoreGatePolicy, C as Checkout, c as CheckoutContext, d as CheckoutGateConfig, e as CheckoutRailSpec, f as CheckoutRequest, g as CheckoutResult, h as CheckoutValidationError, i as ComposeMppxFn, D as DiscoveryProbeConfig, G as GateDenial, I as IsCachedAddressFn, M as MountUcpRoutesOptions, j as MppxComposeOutcome, O as OnSettledFn, P as PreValidateFn, k as PricingFn, l as PricingResult, R as RecipientsFn, m as ReferenceIdFn, n as RunGateFn, S as SettleOutcome, o as UCPCapabilityBinding, p as UCPPaymentHandlerBinding, q as UCPProfileBody, r as UCPServiceBinding, s as buildUCPProfile, t as getIdentityStatus, u as makeMppxComposeHook, v as mppPaymentHandler, w as pricingResult, x as stripeSptPaymentHandler, y as validationEnvelope, z as validationResponseExpress, B as validationResponseFastify, E as validationResponseHono, F as validationResponseNextjs, H as validationResponseWeb, J as x402PaymentHandler } from './checkout-jNUIql6D.mjs';
+import { q as UCPSigningKey, n as UCPProfile } from './checkout-BRw_caGr.mjs';
+export { A as AGENTSCORE_UCP_CAPABILITY, a as AgentScoreGatePolicy, C as Checkout, b as CheckoutContext, c as CheckoutGateConfig, d as CheckoutRailSpec, e as CheckoutRequest, f as CheckoutResult, g as ComposeMppxFn, D as DiscoveryProbeConfig, G as GateDenial, I as IsCachedAddressFn, M as MountUcpRoutesOptions, h as MppxComposeOutcome, O as OnSettledFn, P as PreValidateFn, i as PricingFn, j as PricingResult, R as RecipientsFn, k as ReferenceIdFn, l as RunGateFn, S as SettleOutcome, U as UCPCapabilityBinding, m as UCPPaymentHandlerBinding, o as UCPProfileBody, p as UCPServiceBinding, r as buildUCPProfile, s as getIdentityStatus, t as makeMppxComposeHook, u as mppPaymentHandler, v as pricingResult, w as stripeSptPaymentHandler, x as validationEnvelope, y as validationResponseExpress, z as validationResponseFastify, B as validationResponseHono, E as validationResponseNextjs, F as validationResponseWeb, H as x402PaymentHandler } from './checkout-BRw_caGr.mjs';
 export { EnforcementMode, GateResult, IdentityStatus, PolicyBlock, buildGateFromPolicy, runGateWithEnforcement, shippingCountryAllowed, shippingStateAllowed, validateShippingAgainstPolicy } from './identity/policy.mjs';
-export { S as SolanaMppRailSpec, b as StripeRailSpec, T as TempoRailSpec, a as TempoSessionRailSpec, X as X402BaseRailSpec } from './rail_spec-XP0wKgJV.mjs';
-export { f as formatUsdCents, l as loadSolanaFeePayer } from './solana-Cds87OTu.mjs';
-import './pricing-CxzwyiO6.mjs';
-import './x402_server-hgQzWQwB.mjs';
+import { H as HeadersLike } from './default_rails-XFCuRddA.mjs';
+export { c as buildDefaultCheckoutRails, d as buildMppxComposeRails, f as formatUsdCents, h as hasMppxHeader, e as hasPaymentHeader, g as hasX402Header, l as loadSolanaFeePayer } from './default_rails-XFCuRddA.mjs';
+import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from './rail_spec-D6qzh3J0.mjs';
+export { c as TempoSessionRailSpec } from './rail_spec-D6qzh3J0.mjs';
+import { Context } from 'hono';
+import './pricing-4n5Ota0D.mjs';
+import './x402_server-Ciz2mls2.mjs';
+
+/**
+ * Universal denial helpers shared across every adapter.
+ *
+ * What lives here:
+ *   - `FIXABLE_DENIAL_REASONS` / `isFixableDenial` — classifier for compliance reasons that can
+ *     be resolved by re-completing KYC (vs sanctions / age failures which are permanent).
+ *   - `denialReasonStatus` — picks the right HTTP status code per denial code (401 for credential
+ *     problems, 503 for transient API errors, 403 for everything else).
+ *   - `buildSignerMismatchBody` — produces the standard 403 body for a non-pass signer_match
+ *     verdict (read via `getSignerVerdict`).
+ *   - `buildContactSupportNextSteps` — standard `next_steps.action: "contact_support"` shape for
+ *     unfixable compliance denials.
+ *   - `verificationAgentInstructions` — the canned `agent_instructions` block for
+ *     identity-verification 403s. Vendors can override individual fields.
+ *
+ * Adapters use `denialReasonStatus` inside their default `onDenied` so vendors get the right
+ * status code for free. The body builders are exported from each adapter so vendors who write
+ * a custom `onDenied` can compose them without copy-paste.
+ */
+
+/**
+ * Compliance denial reasons that can be resolved by re-completing KYC. The API emits these
+ * when KYC is missing/pending/failed; the user can re-verify and retry.
+ *
+ * `jurisdiction_restricted` is NOT in this set — the API only emits it AFTER KYC is verified,
+ * meaning the user's KYC'd country is in the merchant's blocked list (or absent from the
+ * allowed list). Re-doing KYC won't change the country, so it's permanent. Same shape as
+ * `sanctions_flagged` and `age_insufficient` — surface contact_support, don't waste a
+ * /v1/sessions mint.
+ */
+declare const FIXABLE_DENIAL_REASONS: ReadonlySet<string>;
+/**
+ * Returns true when a `wallet_not_trusted` denial's reasons are all fixable via KYC
+ * re-verification. False when any reason is permanent (sanctions, age, jurisdiction_restricted).
+ *
+ * Empty reasons returns false — without a known reason we can't promise a fix, so default to
+ * the bare denial path (vendors can override via custom onDenied if they want different
+ * behavior on empty reasons).
+ */
+declare function isFixableDenial(reasons: readonly string[] | undefined): boolean;
+/**
+ * The right HTTP status code for a denial. `defaultOnDenied` in every adapter uses this so
+ * vendors get correct status codes without writing per-code branches.
+ *
+ *   - 401 for credential problems the agent can recover from (`token_expired`, `invalid_credential`)
+ *   - 503 for transient `api_error`
+ *   - 403 for everything else (identity required, compliance fail, signer mismatch, etc.)
+ */
+declare function denialReasonStatus(reason: DenialReason): 401 | 403 | 503;
+/**
+ * Standard 403 body for a non-pass signer-match verdict. Returns null for `pass` so vendors
+ * can call it unconditionally:
+ *
+ *   const verdict = getSignerVerdict(c);
+ *   if (verdict?.signer_match) {
+ *     const mismatchBody = buildSignerMismatchBody({ result: verdict.signer_match });
+ *     if (mismatchBody) return c.json(mismatchBody, 403);
+ *   }
+ *
+ * Body shape mirrors the gate's denial bodies: top-level error.code, all signer-match fields
+ * (`claimed_operator`, `actual_signer_operator`, `expected_signer`, `actual_signer`,
+ * `linked_wallets`), plus a `next_steps` action describing the recovery path.
+ */
+declare function buildSignerMismatchBody({ result, userMessage, learnMoreUrl, }: {
+    /** Projected signer_match verdict (from `getSignerVerdict(ctx).signer_match`). Only non-pass
+     *  kinds produce a body. */
+    result: VerifyWalletSignerResult;
+    /** Optional override for the human-facing `next_steps.user_message`. */
+    userMessage?: string;
+    /** Optional override for `next_steps.learn_more_url`. Default: AgentScore agent-identity guide. */
+    learnMoreUrl?: string;
+}): Record<string, unknown> | null;
+/**
+ * Standard `next_steps` block for unfixable compliance denials (sanctions, age, etc.). Vendors
+ * spread this into a 403 body alongside the usual `error`/`reasons` fields.
+ *
+ *   return c.json({
+ *     error: { code: 'compliance_denied', message: '...' },
+ *     reasons,
+ *     next_steps: buildContactSupportNextSteps('support@example.com'),
+ *   }, 403);
+ */
+declare function buildContactSupportNextSteps(supportEmail: string, message?: string): {
+    action: 'contact_support';
+    support_email: string;
+    user_message: string;
+};
+/**
+ * The canonical `agent_instructions` block for identity-verification 403s. Tells the agent how to
+ * present the verify_url, poll for the operator_token, and retry the original request. Universal
+ * across every AgentScore-gated merchant — overrides let vendors add merchant-specific steps
+ * (e.g. "include order_id when retrying").
+ */
+declare function verificationAgentInstructions({ userAction, retryStep, extraSteps, pollIntervalSeconds, timeoutSeconds, orderTtl, extra, }?: {
+    /** Override the user-facing message. */
+    userAction?: string;
+    /** Replace the generic "Retry the original merchant request..." step with a merchant-specific
+     *  one (e.g. "Retry POST /purchase with X-Operator-Token AND include order_id..."). When set,
+     *  this REPLACES baseSteps[4] rather than appending — use it instead of `extraSteps[0]` when
+     *  your retry instruction is a refinement of the canonical retry, not an additional step. */
+    retryStep?: string;
+    /** Append additional steps after the retry step. Use this for genuinely additional steps
+     *  (e.g. "After payment the same call returns 200 with the order"), not for re-stating the
+     *  retry — use `retryStep` for that. */
+    extraSteps?: string[];
+    /** Override the poll cadence. Default 5 seconds. */
+    pollIntervalSeconds?: number;
+    /** Override how long the agent should keep polling. Default 3600 seconds (1 hour). */
+    timeoutSeconds?: number;
+    /** Optional `order_ttl` note describing how long pending orders survive. */
+    orderTtl?: string;
+    /** Arbitrary additional fields merged into the instructions object. */
+    extra?: Record<string, unknown>;
+}): {
+    action: 'poll_for_credential';
+    user_action: string;
+    steps: string[];
+    poll_interval_seconds: number;
+    poll_secret_header: 'X-Poll-Secret';
+    retry_token_header: 'X-Operator-Token';
+    timeout_seconds: number;
+    order_ttl?: string;
+    [key: string]: unknown;
+};
+
+/**
+ * Shared DenialReason → response body serialization for all adapters.
+ *
+ * Keeps Hono / Express / Fastify / Web / Next.js defaults aligned — a field added
+ * here shows up in every adapter's 403 body automatically, and there's one place
+ * to test the marshaling.
+ *
+ * Body shape: `{ error: { code, message }, ... }` — matches the canonical AgentScore
+ * error envelope so downstream agents see one consistent `error.code` +
+ * `error.message` pair regardless of which layer produced the denial.
+ */
+
+/**
+ * Build the canonical 4xx body shape for `identity_verification_required`.
+ *
+ * Every merchant maps the gate's auto-minted session fields (verify_url,
+ * session_id, poll_secret, poll_url, agent_instructions) into their own
+ * envelope with a merchant-specific message + error code. This collapses that
+ * mapping into one call:
+ *
+ * ```ts
+ * if (reason.code === 'identity_verification_required') {
+ *   return {
+ *     status: 403,
+ *     body: buildVerificationRequiredBody(reason, {
+ *       message: 'Identity verification is required to call this endpoint.',
+ *       agentInstructions: VERIFICATION_AGENT_INSTRUCTIONS,
+ *     }),
+ *   };
+ * }
+ * ```
+ *
+ * Goods merchants that surface an `order_id` (or similar) from
+ * `createSessionOnMissing.onBeforeSession` get it for free via
+ * `denialReasonToBody(reason)`'s `reason.extra` passthrough — but can also
+ * pass `opts.extra` for fallbacks (e.g. when invoked outside the auto-mint
+ * path and order_id needs to come from the validated context).
+ */
+declare function buildVerificationRequiredBody(reason: DenialReason, opts?: {
+    /** Override the `error.message`. Defaults to the canonical copy. */
+    message?: string;
+    /** Replace `agent_instructions` with merchant-specific copy. When omitted,
+     *  the gate-supplied or default instructions ride through. */
+    agentInstructions?: string;
+    /** Additional fields spread into the body (e.g. fallback `order_id`). */
+    extra?: Record<string, unknown>;
+}): Record<string, unknown>;
+declare function denialReasonToBody(reason: DenialReason): Record<string, unknown>;
 
 /**
  * Google A2A (Agent-to-Agent) v1.0 Agent Card builder.
  *
- * Compose the JSON payload for an A2A v1.0 Agent Card per the canonical proto at
- * https://github.com/a2aproject/A2A/blob/main/specification/a2a.proto. Returned object
- * is the unsigned card body — wrap with an A2A `AgentCardSignature` (RFC 7515 JWS)
- * to sign vendor-side before publishing at /.well-known/agent-card.json.
+ * Compose the JSON payload for an A2A v1.0 Agent Card matching the canonical
+ * `AgentCard` type from `@a2a-js/sdk`. Returned object is the unsigned card body —
+ * wrap with an `A2AAgentCardSignature` (RFC 7515 JWS) to sign vendor-side before
+ * publishing at /.well-known/agent-card.json.
  *
  * Why publish: A2A is a Linux Foundation standard. Signed Agent Cards let any
  * A2A-compatible reader discover an agent's capabilities + protocol bindings without
@@ -24,41 +201,43 @@ import './x402_server-hgQzWQwB.mjs';
  * so platforms detect UCP support without re-fetching the profile.
  *
  * Spec reference: https://a2a-protocol.org/latest/
+ * Authoritative types: https://www.npmjs.com/package/@a2a-js/sdk (interface `AgentCard`).
  */
 /** Canonical UCP A2A extension URI — verifiers look for this exact URI in
  *  `capabilities.extensions[]` to detect UCP support on the agent card. Pinned
  *  to the 2026-04-08 spec snapshot. */
 declare const UCP_A2A_EXTENSION_URI = "https://ucp.dev/2026-04-08/specification/reference";
-/** Per spec §4.4.6. Each entry advertises one protocol binding the agent supports.
- *  `supported_interfaces[0]` is the preferred binding (ordered list). */
+/** One transport+URL combination the agent exposes. Lives in `AgentCard.additionalInterfaces[]`
+ *  for multi-binding agents; the PRIMARY transport+URL pair lives on `AgentCard.url` +
+ *  `AgentCard.preferredTransport`. */
 interface A2AAgentInterface {
-    /** Interface URL (https in production). */
-    url: string;
     /** Open string — core values are `JSONRPC`, `GRPC`, `HTTP+JSON`. */
-    protocol_binding: string;
-    /** A2A protocol version, e.g. `"1.0"`. Distinct from the agent's own version. */
-    protocol_version: string;
-    tenant?: string;
+    transport: string;
+    /** Absolute URL where this transport is available. */
+    url: string;
 }
-/** Per spec §4.4.2. The org/service that provides the agent. */
+/** Org/service that provides the agent. */
 interface A2AAgentProvider {
-    url: string;
     organization: string;
+    url: string;
 }
-/** Per spec §4.4.5. A distinct capability or function the agent performs.
- *  Lives at the TOP LEVEL of AgentCard (not inside `capabilities`). */
+/** A distinct capability or function the agent performs. Lives at the TOP LEVEL of
+ *  `AgentCard.skills[]` (not inside `capabilities`). */
 interface A2AAgentSkill {
     id: string;
     name: string;
     description: string;
     tags: string[];
     examples?: string[];
-    input_modes?: string[];
-    output_modes?: string[];
+    inputModes?: string[];
+    outputModes?: string[];
+    /** Security schemes scoped to this skill. List = OR of ANDs (each entry is a set of
+     *  schemes that must all be satisfied). Follows OpenAPI 3.0 Security Requirement Object. */
+    security?: Record<string, string[]>[];
 }
-/** Per spec §4.4.4. A protocol extension the agent supports.
- *  Lives in `capabilities.extensions[]`. `description` and `required` are
- *  spec-mandated fields, not optional. */
+/** A protocol extension the agent supports. Lives in `capabilities.extensions[]`.
+ *  Canonical type marks `description` and `required` optional, but we keep them in the
+ *  builder to make UCP discovery deterministic. */
 interface A2AAgentCardExtension {
     uri: string;
     description: string;
@@ -83,24 +262,16 @@ declare function ucpA2AExtension(capabilities?: Record<string, Array<{
 }>>, options?: {
     required?: boolean;
 }): A2AAgentCardExtension;
-/** Per spec §4.4.3. Optional capabilities the agent supports.
- *
- *  Per the canonical proto, `capabilities` declares: streaming, push_notifications,
- *  extensions (the protocol extensions the agent supports), and extended_agent_card.
- *  REST-style endpoint metadata does NOT belong here — A2A uses `supported_interfaces`
- *  on the AgentCard for protocol bindings, and `skills` (top-level) for capability
- *  descriptions. */
+/** Optional capabilities the agent supports. */
 interface A2AAgentCardCapabilities {
-    streaming?: boolean;
-    push_notifications?: boolean;
     extensions?: A2AAgentCardExtension[];
-    extended_agent_card?: boolean;
+    pushNotifications?: boolean;
+    stateTransitionHistory?: boolean;
+    streaming?: boolean;
 }
-/** Per spec §4.4.7. JWS signature embedded in an Agent Card.
- *
- *  Multiple signatures MAY be attached to a single card. Verifiers reconstruct the
- *  card body without `signatures` to verify each entry. Format follows RFC 7515 JSON
- *  Web Signature (JWS). */
+/** JWS signature embedded in an Agent Card. Multiple signatures MAY be attached;
+ *  verifiers reconstruct the card body without `signatures` to verify each entry.
+ *  Format follows RFC 7515. */
 interface A2AAgentCardSignature {
     /** Base64url-encoded JSON of the protected JWS header. REQUIRED. */
     protected: string;
@@ -109,35 +280,38 @@ interface A2AAgentCardSignature {
     /** Optional unprotected JWS header values. */
     header?: Record<string, unknown>;
 }
-/** Per spec §4.4.1. A2A v1.0 Agent Card body.
- *
- *  Per spec §4.4.7, JWS signatures may be embedded directly in the card via the
- *  `signatures` field; verifiers reconstruct the card body without `signatures` and
- *  verify each entry. Per-vendor identity attestation can also be expressed via a
- *  vendor extension entry inside `capabilities.extensions[]`. */
+/** A2A v1.0 Agent Card body, matching `AgentCard` from `@a2a-js/sdk`. */
 interface A2AAgentCard {
     name: string;
     description: string;
-    /** Ordered; first entry is preferred. */
-    supported_interfaces: A2AAgentInterface[];
-    /** Agent's own version, e.g. `"1.0.0"`. Distinct from the A2A protocol version,
-     *  which lives on each `A2AAgentInterface.protocol_version`. */
+    /** Preferred endpoint URL — MUST support `preferredTransport`. */
+    url: string;
+    /** Transport at the primary `url`. Defaults to `JSONRPC` per spec when omitted by a reader. */
+    preferredTransport?: string;
+    /** A2A protocol version, e.g. `"1.0"`. Distinct from the agent's own `version`. */
+    protocolVersion: string;
+    /** Additional transport+URL bindings beyond the primary. */
+    additionalInterfaces?: A2AAgentInterface[];
+    /** Agent's own version, e.g. `"1.0.0"`. */
     version: string;
     capabilities: A2AAgentCardCapabilities;
-    default_input_modes: string[];
-    default_output_modes: string[];
-    /** Per spec §4.4.1 (proto field 12, REQUIRED): the agent must declare ≥1 skill.
-     *  The convenience builder `buildA2AAgentCard` enforces non-empty. */
+    defaultInputModes: string[];
+    defaultOutputModes: string[];
+    /** REQUIRED non-empty. */
     skills: A2AAgentSkill[];
     provider?: A2AAgentProvider;
-    documentation_url?: string;
-    /** Per spec §4.4.1 (proto field 14, optional): URL to an icon for the agent. */
-    icon_url?: string;
-    /** Per spec §4.4.1 (proto field 13, optional) + §4.4.7: JWS signatures embedded
-     *  in the card. Compute over the canonical card body MINUS this field, then attach. */
+    documentationUrl?: string;
+    iconUrl?: string;
+    /** Agent can provide an extended card with additional details to authenticated users.
+     *  Defaults to `false`. */
+    supportsAuthenticatedExtendedCard?: boolean;
+    /** JWS signatures embedded in the card. Compute over the canonical card body MINUS
+     *  this field, then attach. */
     signatures?: A2AAgentCardSignature[];
-    security_schemes?: Record<string, unknown>;
-    security_requirements?: unknown[];
+    /** OpenAPI 3.0 security requirement objects (OR of ANDs). */
+    security?: Record<string, string[]>[];
+    /** Map of security scheme definitions (key = scheme name). */
+    securitySchemes?: Record<string, unknown>;
     /** Vendor-specific extras merged at top level. */
     [k: string]: unknown;
 }
@@ -146,55 +320,61 @@ interface BuildA2AAgentCardInput {
     name: string;
     /** Agent purpose/description. REQUIRED per spec. */
     description: string;
-    /** The primary interface URL — becomes `supported_interfaces[0].url` (with
-     *  `protocol_binding=HTTP+JSON`, `protocol_version=1.0` by default). For
-     *  multi-binding agents, construct `A2AAgentCard` directly. */
+    /** Primary endpoint URL — becomes `AgentCard.url`. The transport at this URL is
+     *  declared via `preferredTransport` (default `HTTP+JSON`). For multi-binding agents,
+     *  pass `additionalInterfaces` for the secondary transports. */
     url: string;
     /** Top-level skill declarations — what the agent can do. REQUIRED per spec
      *  (proto field 12 [field_behavior=REQUIRED]); must have ≥1 entry. */
     skills: A2AAgentSkill[];
-    /** Agent's own version, e.g. `"1.0.0"`. Distinct from the A2A protocol version. */
+    /** Agent's own version, e.g. `"1.0.0"`. Distinct from the A2A `protocolVersion`. */
     version?: string;
+    /** Transport for the primary `url`. Defaults to `"HTTP+JSON"` for our merchants; the
+     *  canonical A2A spec default when omitted by a reader is `"JSONRPC"`. */
+    preferredTransport?: string;
+    /** A2A protocol version. Defaults to `"1.0"`. */
+    protocolVersion?: string;
+    /** Additional transport+URL bindings beyond the primary. */
+    additionalInterfaces?: A2AAgentInterface[];
     /** A2A v1.0 capability extensions. Build the UCP entry with `ucpA2AExtension()`. */
     extensions?: A2AAgentCardExtension[];
-    /** Capability flag: agent supports streaming responses. */
+    /** Capability flag: agent supports streaming responses (SSE). */
     streaming?: boolean;
     /** Capability flag: agent supports push notifications for async task updates. */
-    push_notifications?: boolean;
-    /** Capability flag: agent serves an extended (more detailed) card when authenticated. */
-    extended_agent_card?: boolean;
+    pushNotifications?: boolean;
+    /** Capability flag: agent provides task state-transition history. */
+    stateTransitionHistory?: boolean;
+    /** AgentCard top-level flag: agent serves an extended card to authenticated users. */
+    supportsAuthenticatedExtendedCard?: boolean;
     /** Provider org for the agent. */
     provider?: A2AAgentProvider;
     /** URL to additional human-readable documentation. */
-    documentation_url?: string;
+    documentationUrl?: string;
     /** URL to an icon for the agent. */
-    icon_url?: string;
-    /** JWS signatures embedded in the card (per spec §4.4.7). */
+    iconUrl?: string;
+    /** JWS signatures embedded in the card. */
     signatures?: A2AAgentCardSignature[];
     /** Default input media types (defaults to `["application/json"]`). */
-    default_input_modes?: string[];
+    defaultInputModes?: string[];
     /** Default output media types (defaults to `["application/json"]`). */
-    default_output_modes?: string[];
-    /** Override the protocol binding for the auto-built primary interface (default `"HTTP+JSON"`). */
-    protocol_binding?: string;
-    /** Override the A2A protocol version for the auto-built primary interface (default `"1.0"`). */
-    a2a_protocol_version?: string;
+    defaultOutputModes?: string[];
+    /** OpenAPI 3.0 security requirement objects (OR of ANDs). */
+    security?: Record<string, string[]>[];
     /** Per-scheme security details (key = scheme name). */
-    security_schemes?: Record<string, unknown>;
-    /** Required security requirements for invoking the agent. */
-    security_requirements?: unknown[];
+    securitySchemes?: Record<string, unknown>;
     /** Vendor-specific extras merged at the card top level. */
     extras?: Record<string, unknown>;
 }
 /**
- * Compose an A2A v1.0 Agent Card body per the canonical proto.
+ * Compose an A2A v1.0 Agent Card body matching `AgentCard` from `@a2a-js/sdk`.
  *
  * Returns the UNSIGNED card. To attach identity claims, sign the serialized body
- * as an RFC 7515 JWS (`AgentCardSignature`). Vendors can also add an identity-flavored
+ * as an RFC 7515 JWS (`A2AAgentCardSignature`). Vendors can also add an identity-flavored
  * extension to `capabilities.extensions[]`.
  *
- * The single `url` argument becomes the primary `supported_interfaces[0].url`
- * (with `protocol_binding=HTTP+JSON`, `protocol_version=1.0` by default).
+ * The `url` argument becomes the top-level `AgentCard.url`; `preferredTransport`
+ * declares the transport at that URL (default `HTTP+JSON`). For multi-binding agents,
+ * pass `additionalInterfaces`.
  *
  * Example:
  * ```ts
@@ -214,6 +394,8 @@ interface BuildA2AAgentCardInput {
  * ```
  */
 declare function buildA2AAgentCard(input: BuildA2AAgentCardInput): A2AAgentCard;
+declare const A2A_PROTOCOL_VERSION = "1.0";
+declare const A2A_DEFAULT_TRANSPORT = "JSONRPC";
 
 /**
  * UCP profile signing helpers (JWKS + JWS).
@@ -388,6 +570,7 @@ declare function loadUCPSigningKeyFromEnv({ envJwkVar, envKidVar, envAlgVar, def
  * hashes. This helper exposes the canonical hash so every consumer agrees on
  * the shape.
  */
+
 /**
  * sha256 hex digest of a plaintext operator token.
  *
@@ -396,5 +579,353 @@ declare function loadUCPSigningKeyFromEnv({ envJwkVar, envKidVar, envAlgVar, def
  * durable storage.
  */
 declare function hashOperatorToken(plaintext: string): string;
+type OwnerScope = {
+    walletAddress?: string;
+    operatorTokenHash?: string;
+};
+/**
+ * Pull the canonical owner identity from request headers so caller-scoped
+ * lookups never see the plaintext operator token. Reads `X-Wallet-Address` and
+ * `X-Operator-Token`; returns the wallet address verbatim and the
+ * sha256 hash of the token. Either or both may be undefined.
+ *
+ * Use at owner-scoped resource queries (`GET /orders/:id`, `GET /receipts/:id`,
+ * ...) so persistence + lookup agree on the hashed column shape and plaintext
+ * tokens never leave the request.
+ */
+declare function extractOwnerScope(input: Request | HeadersLike): OwnerScope;
+
+/**
+ * Cross-module typed errors.
+ *
+ * Lives in its own module so `payment/` and `stripe-multichain/` helpers can
+ * throw `CheckoutValidationError` without importing from `checkout.ts`. (In
+ * the python sibling this avoids a checkout → payment → checkout cycle; in
+ * node it sidesteps tsup's per-entry class duplication.)
+ *
+ * Re-exported from `checkout.ts` and the top-level entry to preserve the
+ * public import path.
+ */
+/**
+ * Raised to short-circuit a Checkout flow with a 4xx/5xx envelope. The
+ * framework catches this at request-flow boundaries (`preValidate`, recipient
+ * minting, settlement dispatch) and emits `{ error, next_steps }` via
+ * `buildValidationError` so merchants don't construct response bodies
+ * themselves.
+ */
+declare class CheckoutValidationError extends Error {
+    readonly code: string;
+    readonly action: string;
+    readonly status: number;
+    readonly extra: Record<string, unknown> | undefined;
+    constructor(opts: {
+        code: string;
+        message: string;
+        action?: string;
+        status?: number;
+        extra?: Record<string, unknown>;
+    });
+}
+
+/**
+ * Short-TTL body-hash quote cache for the compute-first + exact-x402 pattern
+ * (see {@link computeFirstCheckout}).
+ *
+ * Standard x402-fetch retry semantics resign the buyer's ORIGINAL request body
+ * — there's no `result_id` echo channel through the protocol. The cache is
+ * therefore keyed by a stable content-hash of the request body. Same body →
+ * same hash → same cache slot. The probe leg writes (run-work → cache); the
+ * settle leg reads (cache hit → settle exact at the cached price → return the
+ * cached body).
+ *
+ * Default in-memory `Map`; optional `redisUrl` lazy-imports `ioredis` for
+ * multi-instance deployments. `ioredis` is an optional peer dep.
+ */
+interface QuoteCacheOptions {
+    /** Quote lifetime in milliseconds. Default `5 * 60_000` (5 min). */
+    ttlMs?: number;
+    /** Redis connection URL. Default: `process.env.REDIS_URL`. When unset or the
+     *  lazy `ioredis` import fails, falls back to in-process `Map`. */
+    redisUrl?: string;
+    /** Per-instance key prefix so multiple caches sharing a Redis don't collide. */
+    keyPrefix?: string;
+}
+interface CachedQuote {
+    body: Record<string, unknown>;
+    priceCents: number;
+    /** Per-rail deposit addresses minted on the probe leg. The settle leg replays
+     *  these instead of re-minting (avoids second Stripe PaymentIntent for the
+     *  same logical purchase). Empty object when no `mintRecipients` hook is wired. */
+    recipients: Record<string, string>;
+}
+interface QuoteCache {
+    /** Build a stable content-hash key from a per-merchant prefix and a request body.
+     *  Property order in the body does NOT affect the hash (keys are sorted recursively). */
+    bodyHashKey(prefix: string, body: Record<string, unknown>): string;
+    read(key: string): Promise<CachedQuote | null>;
+    write(key: string, body: Record<string, unknown>, priceCents: number, recipients?: Record<string, string>): Promise<void>;
+    /** Clear all entries. Primarily for tests. */
+    clear(): Promise<void>;
+}
+/** Build a fresh cache. Each call owns its own state (memory map + Redis
+ *  client). */
+declare function createQuoteCache(opts?: QuoteCacheOptions): QuoteCache;
+
+/**
+ * `computeFirstCheckout` — variable-cost pay-per-result merchant helper using
+ * compute-first + exact-x402 (no upto, no Permit2, no Settlement-Overrides).
+ *
+ * Flow (per request):
+ *
+ *   1. PROBE leg (no payment header)
+ *      - Validate input
+ *      - Look up cache by content-hash of the request body
+ *      - On cache miss: run `runWork(body)`
+ *        - 0 results → return 200 immediately with `no_charge` envelope (no 402)
+ *        - Else → cache `{body, priceCents}` keyed by body hash → emit 402 with
+ *          EXACT price (`actual_results × unitPriceCents`) on every advertised rail
+ *      - On cache hit: emit 402 with cached price
+ *
+ *   2. SETTLE leg (X-Payment / Authorization: Payment header attached)
+ *      - Look up cache by re-hashing the same body
+ *      - Cache miss → 400 `stale_quote` with `next_steps.action: 're_probe'`
+ *      - x402 path → `verifyX402Request` + `processX402Settle({scheme:'exact'})`
+ *      - MPP path → `composeMppxRequest`
+ *      - Return cached result body in the canonical 200 envelope
+ *
+ * Works on every exact-mode rail today (x402-exact Base, tempo/charge,
+ * solana/charge, Stripe SPT). The tradeoff vs. upto is that the work runs on
+ * the unpaid probe leg — so rate-limiting is load-bearing (use
+ * `@agent-score/commerce/middleware/hono` `rateLimitHono` or the per-framework
+ * equivalent).
+ */
+
+interface WorkOutcome {
+    /** Number of billable units returned by `runWork` (results, tokens, bytes, …).
+     *  Used to compute the exact price `unitPriceCents × resultCount` advertised
+     *  in the 402. Zero short-circuits the probe to 200 no-charge. */
+    resultCount: number;
+    /** Body returned to the buyer on the settle leg. Cached verbatim and served
+     *  from cache on retry; the merchant does NOT re-run `runWork`. */
+    body: Record<string, unknown>;
+}
+interface ComputeFirstWorkContext {
+    /** Raw Web Fetch `Request` for the probe leg — useful when the work hook
+     *  needs to dispatch by header (e.g. agent identity) or read query params. */
+    request: Request;
+}
+interface ComputeFirstMintContext {
+    request: Request;
+    body: Record<string, unknown>;
+    /** Final price in cents (`unitPriceCents × resultCount`). Useful when minting
+     *  payment-provider sessions (Stripe Multichain PaymentIntent) that need the
+     *  exact charge amount up front. */
+    priceCents: number;
+}
+interface ComputeFirstMppContext {
+    request: Request;
+    /** Cached body that will be returned to the buyer on settle success. The
+     *  merchant doesn't need to re-run the work; it's already done. */
+    cachedBody: Record<string, unknown>;
+    /** Exact price in cents (`unitPriceCents × resultCount`). Build mppx
+     *  intents at this amount. */
+    priceCents: number;
+    /** Dollar-string of the price at the helper's configured precision (e.g.
+     *  `"0.03"`, `"0.001234"`). Useful for `tempo/charge` / `stripe/charge`
+     *  intents which take a USD string. */
+    priceUsd: string;
+    /** Minted (or static) recipients per rail. The merchant uses these to build
+     *  the per-rail intents. */
+    recipients: MintedRecipients;
+}
+interface ComputeFirstSettledContext {
+    request: Request;
+    /** Which rail family captured the payment. `'x402'` = x402-exact on Base.
+     *  `'mpp'` = one of Tempo / Solana / Stripe SPT via mppx — disambiguate with
+     *  `mppMethod` when you need per-MPP-rail dispatch (e.g. firing the Stripe
+     *  testnet deposit simulator with the right `network`). */
+    rail: 'x402' | 'mpp';
+    /** When `rail === 'mpp'`, the specific intent that mppx settled
+     *  (`'tempo/charge'`, `'solana/charge'`, `'stripe/charge'`). Undefined when
+     *  the receipt method couldn't be extracted or for non-MPP rails. */
+    mppMethod?: string;
+    /** Cached body that will be returned to the buyer. */
+    cachedBody: Record<string, unknown>;
+    priceCents: number;
+    priceUsd: string;
+    recipients: MintedRecipients;
+    signer?: {
+        address: string;
+        network: 'evm' | 'solana';
+    };
+    paymentIntentId?: string;
+}
+interface MintedRecipients {
+    tempo?: string;
+    x402_base?: string;
+    solana_mpp?: string;
+}
+interface ComputeFirstRails {
+    tempo?: TempoRailSpec;
+    x402_base?: X402BaseRailSpec;
+    solana_mpp?: SolanaMppRailSpec;
+    stripe?: StripeRailSpec;
+}
+interface ComputeFirstOptions {
+    /** Merchant-facing name (used in cache prefix, response envelope, product id). */
+    name: string;
+    /** Public URL of the endpoint, including scheme + host. */
+    url: string;
+    /** Price per billable unit, in cents. Fractional values supported (per-token
+     *  / per-byte unit pricing); precision is auto-derived from the fractional
+     *  digits unless `decimals` is set explicitly. */
+    unitPriceCents: number;
+    /** Override the auto-derived dollar-precision. Default: `2` for integer
+     *  cents, else `2 + decimal digits of unitPriceCents`. */
+    decimals?: number;
+    /** Per-rail config. Pass only the rails you support. At least one rail required. */
+    rails: ComputeFirstRails;
+    /** Required: registered x402 server (from `createX402Server`). The helper
+     *  uses it to build x402 `accepts[]` entries (correct USDC contract +
+     *  EIP-712 domain name per network) and to call `processX402Settle` on the
+     *  settle leg. */
+    x402Server: unknown;
+    /** MPP compose hook for the Tempo / Solana / Stripe SPT rails. Called on
+     *  BOTH legs of the round-trip:
+     *
+     *  - **Probe leg** (no payment header): the merchant builds per-rail intents
+     *    at the exact cached price and calls `composeMppxRequest(mppx, intents,
+     *    request)` — mppx returns a 402 challenge whose `WWW-Authenticate`
+     *    header carries the proper per-rail `request=<base64-intent>` values
+     *    the agent needs to sign. Return `{status: 402, headers}` where
+     *    `headers` is `mppxChallengeHeaders(result)` — the helper merges them
+     *    into the 402 response so pay / mppx-clients can settle on any
+     *    advertised MPP rail.
+     *  - **Settle leg** (`Authorization: Payment` header attached): mppx
+     *    verifies + composes. Return `{status: 200, ...}` with `txHash` and
+     *    signer info for the success envelope.
+     *
+     *  Omit to skip MPP entirely — the helper then advertises only x402-exact
+     *  in the 402 and rejects MPP-header settles with 503 `mpp_unavailable`. */
+    composeMppx?: (ctx: ComputeFirstMppContext) => Promise<{
+        status: number;
+        raw?: unknown;
+        headers?: Record<string, string>;
+        txHash?: string;
+        signerAddress?: string;
+        signerNetwork?: 'evm' | 'solana';
+    }>;
+    /** Optional side-effect hook fired after a successful settle on either rail
+     *  (x402 or MPP), before the response is sent. Use this for Stripe testnet
+     *  deposit simulation, audit logging, captureWallet writeback, or any other
+     *  post-settle work that shouldn't block the response. Errors are caught
+     *  and logged but don't fail the request — the buyer still gets their data. */
+    onSettled?: (ctx: ComputeFirstSettledContext) => Promise<void> | void;
+    /** Optional input validator. Throw a `CheckoutValidationError` for typed
+     *  4xx envelopes; any other error becomes a 500. */
+    validateInput?: (body: Record<string, unknown>) => void;
+    /** The per-request work. Probe leg calls this once; settle leg replays the
+     *  cached output. */
+    runWork: (body: Record<string, unknown>, ctx: ComputeFirstWorkContext) => Promise<WorkOutcome>;
+    /** Optional per-call recipient mint hook. Stripe-multichain merchants mint
+     *  per-PI deposit addresses; static-recipient merchants leave this unset
+     *  and the rail recipient configured in `rails` is used verbatim. */
+    mintRecipients?: (ctx: ComputeFirstMintContext) => Promise<MintedRecipients>;
+    /** Quote cache instance. Default: in-memory cache with 5-min TTL. Pass a
+     *  Redis-backed cache (via `createQuoteCache({redisUrl})`) for multi-task
+     *  deployments. */
+    cache?: QuoteCache;
+    /** Override default cache TTL (only used when `cache` is not provided). */
+    cacheTtlMs?: number;
+    /** App URL used in success `next_steps.order_status_url`. Defaults to the
+     *  origin of `url` + `/health`. */
+    appUrl?: string;
+    /** Override the on-success body. Default returns a canonical
+     *  `{id, endpoint, payment_status, charged_usd, rail, signer?, result, ...}`
+     *  envelope matching the fixed-price `Checkout` shape. */
+    buildSuccessBody?: (args: SuccessBodyArgs) => Record<string, unknown>;
+}
+interface SuccessBodyArgs {
+    referenceId: string;
+    endpoint: string;
+    chargedUsd: string;
+    rail: string;
+    paymentIntentId?: string;
+    signer?: {
+        address: string;
+        network: 'evm' | 'solana';
+    };
+    cachedBody: Record<string, unknown>;
+}
+interface ComputeFirstHandler {
+    /** Hono adapter — pass `(c) => handler.handleHono(c)` into your route. */
+    handleHono(c: Context): Promise<Response>;
+    /** Web Fetch adapter — pass `handler.handleWeb` directly as a route handler. */
+    handleWeb(req: Request): Promise<Response>;
+}
+declare function computeFirstCheckout(opts: ComputeFirstOptions): ComputeFirstHandler;
+
+/** Factory for the standard `onDenied` callback shape used by Checkout's
+ *  gate config. Replaces the ~100-line switch every consumer codebase
+ *  (sayer, martin, sandbox) wrote by hand.
+ *
+ *  The shape is framework-neutral (`{status, body, headers?}`) — matches
+ *  `Checkout`'s `onDenied` signature directly. For per-framework gate
+ *  middleware (`agentscoreGate(...)`) the merchant adapts at the call site
+ *  with `c.json(body, status, headers)` / equivalent.
+ */
+
+interface CreateDefaultOnDeniedOptions {
+    /** Display name used in the wallet_not_trusted body ("Identity check did
+     *  not satisfy policy for <merchantName>"). */
+    merchantName: string;
+    /** Support email surfaced in `next_steps.action: "contact_support"`. */
+    supportEmail: string;
+    /** Optional override for the support-context blurb. Defaults to
+     *  "Contact support if you believe this denial is in error.". */
+    supportContext?: string;
+    /** Optional override for the payment_required error message. Defaults to
+     *  "AgentScore tier does not support assess. Contact support.". */
+    paymentRequiredMessage?: string;
+    /** Optional override for the wallet_not_trusted (unfixable) error message.
+     *  Defaults to `"Identity check did not satisfy policy for <merchantName>."`. */
+    walletNotTrustedMessage?: string;
+}
+interface DefaultOnDeniedResult {
+    status: number;
+    body: Record<string, unknown>;
+    headers?: Record<string, string>;
+}
+/** Build the canonical `onDenied(ctx, reason)` callback. Returns
+ *  framework-neutral `{status, body, headers?}` matching `Checkout`'s
+ *  `onDenied` signature. The `ctx` arg is ignored — pass `_ctx`-style if
+ *  unused.
+ *
+ *  Branch table (matches the hand-rolled version in every consumer):
+ *   - `wallet_signer_mismatch` / `wallet_auth_requires_wallet_signing` →
+ *     `buildSignerMismatchBody(...)`, status 403
+ *   - `wallet_not_trusted` → custom compliance_denied body + contact-support
+ *     next steps, status 403
+ *   - `payment_required` → denial body + compliance_error message, status 403
+ *   - `token_expired` / `invalid_credential` → 401
+ *   - `api_error` → 503 + `Cache-Control: no-store`
+ *   - default → 403
+ */
+declare function createDefaultOnDenied(opts: CreateDefaultOnDeniedOptions): (reason: DenialReason) => DefaultOnDeniedResult;
+/** Canonical `onDenied` for read-only resource gates (e.g. `GET /orders/:id`).
+ *
+ *  Collapses every denial code to **401 `unauthorized`** while still spreading
+ *  `denialReasonToBody(reason)` so `agent_instructions` / `verify_url` /
+ *  session-mint fields ride through for the agent's recovery path. Stamps
+ *  `Cache-Control: no-store` because RFC 7234 makes 4xx responses
+ *  heuristically cacheable; transient denials (api_error, token_expired)
+ *  must not be replayed by a shared cache.
+ *
+ *  Pair with `agentscoreGate({ onDenied: defaultReadOnlyOnDenied })` on routes
+ *  where the resource owner is the only authorized identity (full compliance
+ *  policy already ran at /purchase time; the read-back leg only needs
+ *  presence-of-valid-credential).
+ */
+declare function defaultReadOnlyOnDenied(reason: DenialReason): DefaultOnDeniedResult;
 
-export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardSignature, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, type GeneratedUCPKey, type JWKSResponse, type SignedUCPProfile, UCPProfile, UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, buildA2AAgentCard, buildJWKSResponse, generateUCPSigningKey, hashOperatorToken, loadUCPSigningKeyFromEnv, signUCPProfile, ucpA2AExtension, verifyUCPProfile };
+export { type A2AAgentCard, type A2AAgentCardCapabilities, type A2AAgentCardExtension, type A2AAgentCardSignature, type A2AAgentInterface, type A2AAgentProvider, type A2AAgentSkill, A2A_DEFAULT_TRANSPORT, A2A_PROTOCOL_VERSION, type CachedQuote, CheckoutValidationError, type ComputeFirstHandler, type ComputeFirstMintContext, type ComputeFirstMppContext, type ComputeFirstOptions, type ComputeFirstRails, type ComputeFirstSettledContext, type ComputeFirstWorkContext, type CreateDefaultOnDeniedOptions, type DefaultOnDeniedResult, DenialReason, FIXABLE_DENIAL_REASONS, type GeneratedUCPKey, type JWKSResponse, type MintedRecipients, type OwnerScope, type QuoteCache, type QuoteCacheOptions, type SignedUCPProfile, SolanaMppRailSpec, StripeRailSpec, type SuccessBodyArgs, TempoRailSpec, UCPProfile, UCPSigningKey, UCPVerificationError, UCP_A2A_EXTENSION_URI, VerifyWalletSignerResult, type WorkOutcome, X402BaseRailSpec, buildA2AAgentCard, buildContactSupportNextSteps, buildJWKSResponse, buildSignerMismatchBody, buildVerificationRequiredBody, computeFirstCheckout, createDefaultOnDenied, createQuoteCache, defaultReadOnlyOnDenied, denialReasonStatus, denialReasonToBody, extractOwnerScope, generateUCPSigningKey, hashOperatorToken, isFixableDenial, loadUCPSigningKeyFromEnv, signUCPProfile, ucpA2AExtension, verificationAgentInstructions, verifyUCPProfile };