@agent-score/commerce 1.0.1 → 1.0.2

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/_denial.ts","../src/core.ts","../src/signer.ts","../src/_response.ts","../src/identity/a2a.ts","../src/identity/ucp.ts","../src/identity/policy.ts"],"sourcesContent":["/**\n * Universal denial helpers shared across every adapter.\n *\n * What lives here:\n *   - `FIXABLE_DENIAL_REASONS` / `isFixableDenial` — classifier for compliance reasons that can\n *     be resolved by re-completing KYC (vs sanctions / age failures which are permanent).\n *   - `denialReasonStatus` — picks the right HTTP status code per denial code (401 for credential\n *     problems, 503 for transient API errors, 403 for everything else).\n *   - `buildSignerMismatchBody` — produces the standard 403 body for a `verifyWalletSignerMatch`\n *     non-pass result.\n *   - `buildContactSupportNextSteps` — standard `next_steps.action: \"contact_support\"` shape for\n *     unfixable compliance denials.\n *   - `verificationAgentInstructions` — the canned `agent_instructions` block for\n *     identity-verification 403s. Vendors can override individual fields.\n *\n * Adapters use `denialReasonStatus` inside their default `onDenied` so vendors get the right\n * status code for free. The body builders are exported from each adapter so vendors who write\n * a custom `onDenied` can compose them without copy-paste.\n */\n\nimport type { DenialReason, VerifyWalletSignerResult } from './core';\n\n/**\n * Compliance denial reasons that can be resolved by re-completing KYC. The API emits these\n * when KYC is missing/pending/failed; the user can re-verify and retry.\n *\n * `jurisdiction_restricted` is NOT in this set — the API only emits it AFTER KYC is verified,\n * meaning the user's KYC'd country is in the merchant's blocked list (or absent from the\n * allowed list). Re-doing KYC won't change the country, so it's permanent. Same shape as\n * `sanctions_flagged` and `age_insufficient` — surface contact_support, don't waste a\n * /v1/sessions mint.\n */\nexport const FIXABLE_DENIAL_REASONS: ReadonlySet<string> = new Set([\n  'kyc_required',\n  'kyc_pending',\n  'kyc_failed',\n]);\n\n/**\n * Returns true when a `wallet_not_trusted` denial's reasons are all fixable via KYC\n * re-verification. False when any reason is permanent (sanctions, age, jurisdiction_restricted).\n *\n * Empty reasons returns false — without a known reason we can't promise a fix, so default to\n * the bare denial path (vendors can override via custom onDenied if they want different\n * behavior on empty reasons).\n */\nexport function isFixableDenial(reasons: readonly string[] | undefined): boolean {\n  if (!reasons || reasons.length === 0) return false;\n  return reasons.every((r) => FIXABLE_DENIAL_REASONS.has(r));\n}\n\n/**\n * The right HTTP status code for a denial. `defaultOnDenied` in every adapter uses this so\n * vendors get correct status codes without writing per-code branches.\n *\n *   - 401 for credential problems the agent can recover from (`token_expired`, `invalid_credential`)\n *   - 503 for transient `api_error`\n *   - 403 for everything else (identity required, compliance fail, signer mismatch, etc.)\n */\nexport function denialReasonStatus(reason: DenialReason): 401 | 403 | 503 {\n  if (reason.code === 'token_expired' || reason.code === 'invalid_credential') return 401;\n  if (reason.code === 'api_error') return 503;\n  return 403;\n}\n\nexport interface SignerMismatchBodyInput {\n  /** Result from `verifyWalletSignerMatch`. The function only emits a body for non-pass results. */\n  result: VerifyWalletSignerResult;\n  /** Optional override for the human-facing `next_steps.user_message`. */\n  userMessage?: string;\n  /** Optional override for `next_steps.learn_more_url`. Default: AgentScore agent-identity guide. */\n  learnMoreUrl?: string;\n}\n\n/**\n * Standard 403 body for a non-pass `verifyWalletSignerMatch` result. Returns null for `pass` /\n * `api_error` so vendors can call it unconditionally:\n *\n *   const result = await verifyWalletSignerMatch(c);\n *   const mismatchBody = buildSignerMismatchBody({ result });\n *   if (mismatchBody) return c.json(mismatchBody, 403);\n *\n * Body shape mirrors the gate's denial bodies: top-level error.code, all signer-match fields\n * (`claimed_operator`, `actual_signer_operator`, `expected_signer`, `actual_signer`,\n * `linked_wallets`), plus a `next_steps` action describing the recovery path.\n */\nexport function buildSignerMismatchBody(input: SignerMismatchBodyInput): Record<string, unknown> | null {\n  const { result } = input;\n  if (result.kind === 'pass' || result.kind === 'api_error') return null;\n\n  const learnMoreUrl = input.learnMoreUrl ?? 'https://docs.agentscore.sh/guides/agent-identity';\n\n  if (result.kind === 'wallet_signer_mismatch') {\n    const linkedWallets = result.linkedWallets ?? [];\n    const userMessage = input.userMessage ?? (linkedWallets.length > 0\n      ? `Sign the payment with one of the wallets linked to this operator: ${linkedWallets.join(', ')}. Then retry.`\n      : 'Sign the payment with the same wallet you claimed via X-Wallet-Address, or switch to X-Operator-Token for rail-independent identity.');\n    return {\n      error: {\n        code: 'wallet_signer_mismatch',\n        message:\n          'Payment signer does not match the wallet claimed via X-Wallet-Address. The signer and the claimed wallet must both resolve to the same AgentScore operator.',\n      },\n      claimed_operator: result.claimedOperator,\n      actual_signer_operator: result.actualSignerOperator ?? null,\n      expected_signer: result.expectedSigner,\n      actual_signer: result.actualSigner,\n      linked_wallets: linkedWallets,\n      next_steps: {\n        action: 'regenerate_payment_from_linked_wallet',\n        user_message: userMessage,\n        learn_more_url: learnMoreUrl,\n      },\n    };\n  }\n\n  // wallet_auth_requires_wallet_signing\n  return {\n    error: {\n      code: 'wallet_auth_requires_wallet_signing',\n      message:\n        'Wallet-auth requires a payment rail that carries a wallet signature (Tempo MPP, x402). Stripe SPT and card rails have no wallet signer; switch to X-Operator-Token to use those.',\n    },\n    next_steps: {\n      action: 'switch_to_operator_token',\n      user_message:\n        input.userMessage ??\n        'Drop the X-Wallet-Address header and retry with X-Operator-Token (works on every payment rail).',\n      learn_more_url: learnMoreUrl,\n    },\n  };\n}\n\n/**\n * Standard `next_steps` block for unfixable compliance denials (sanctions, age, etc.). Vendors\n * spread this into a 403 body alongside the usual `error`/`reasons` fields.\n *\n *   return c.json({\n *     error: { code: 'compliance_denied', message: '...' },\n *     reasons,\n *     next_steps: buildContactSupportNextSteps('support@martinestate.com'),\n *   }, 403);\n */\nexport function buildContactSupportNextSteps(\n  supportEmail: string,\n  message?: string,\n): { action: 'contact_support'; support_email: string; user_message: string } {\n  return {\n    action: 'contact_support',\n    support_email: supportEmail,\n    user_message:\n      message ??\n      `If you believe this denial is in error, contact support at ${supportEmail} with your order details.`,\n  };\n}\n\nexport interface VerificationAgentInstructionsInput {\n  /** Override the user-facing message. */\n  userAction?: string;\n  /** Replace the generic \"Retry the original merchant request...\" step with a merchant-specific\n   *  one (e.g. \"Retry POST /purchase with X-Operator-Token AND include order_id...\"). When set,\n   *  this REPLACES baseSteps[4] rather than appending — use it instead of `extraSteps[0]` when\n   *  your retry instruction is a refinement of the canonical retry, not an additional step. */\n  retryStep?: string;\n  /** Append additional steps after the retry step. Use this for genuinely additional steps\n   *  (e.g. \"After payment the same call returns 200 with the order\"), not for re-stating the\n   *  retry — use `retryStep` for that. */\n  extraSteps?: string[];\n  /** Override the poll cadence. Default 5 seconds. */\n  pollIntervalSeconds?: number;\n  /** Override how long the agent should keep polling. Default 3600 seconds (1 hour). */\n  timeoutSeconds?: number;\n  /** Optional `order_ttl` note describing how long pending orders survive. */\n  orderTtl?: string;\n  /** Arbitrary additional fields merged into the instructions object. */\n  extra?: Record<string, unknown>;\n}\n\n/**\n * The canonical `agent_instructions` block for identity-verification 403s. Tells the agent how to\n * present the verify_url, poll for the operator_token, and retry the original request. Universal\n * across every AgentScore-gated merchant — overrides let vendors add merchant-specific steps\n * (e.g. \"include order_id when retrying\").\n */\nexport function verificationAgentInstructions(input: VerificationAgentInstructionsInput = {}): {\n  action: 'poll_for_credential';\n  user_action: string;\n  steps: string[];\n  poll_interval_seconds: number;\n  poll_secret_header: 'X-Poll-Secret';\n  retry_token_header: 'X-Operator-Token';\n  timeout_seconds: number;\n  order_ttl?: string;\n  [key: string]: unknown;\n} {\n  const baseSteps = [\n    'Present the verify_url directly to the user — it is a complete, ready-to-open URL with the session token already embedded (e.g. https://agentscore.sh/verify?session=sess_...). Do NOT modify or construct the URL yourself.',\n    `Immediately begin polling poll_url every ${input.pollIntervalSeconds ?? 5} seconds with header X-Poll-Secret set to poll_secret. The user will complete verification in their browser while you poll in the background.`,\n    'The user visits the URL, signs in, completes identity verification (photo ID + selfie via Stripe Identity), and closes the tab. They do NOT need to copy or paste anything back to you.',\n    'When your poll returns status \"verified\", extract operator_token from the response. This is a one-time value — save it immediately. Subsequent polls return status \"consumed\" without the token.',\n    input.retryStep ?? 'Retry the original merchant request with header X-Operator-Token set to the operator_token value.',\n  ];\n\n  return {\n    action: 'poll_for_credential',\n    user_action:\n      input.userAction ??\n      'The user must visit verify_url to complete identity verification before this request can proceed',\n    steps: input.extraSteps ? [...baseSteps, ...input.extraSteps] : baseSteps,\n    poll_interval_seconds: input.pollIntervalSeconds ?? 5,\n    poll_secret_header: 'X-Poll-Secret',\n    retry_token_header: 'X-Operator-Token',\n    timeout_seconds: input.timeoutSeconds ?? 3600,\n    ...(input.orderTtl ? { order_ttl: input.orderTtl } : {}),\n    ...(input.extra ?? {}),\n  };\n}\n","import { isFixableDenial } from './_denial';\nimport { normalizeAddress } from './address';\nimport { TTLCache } from './cache';\n\n// Character-based trim avoids a CodeQL polynomial-redos false positive on\n// `/\\/+$/` patterns that report library-input strings.\nfunction stripTrailingSlashes(s: string): string {\n  let end = s.length;\n  while (end > 0 && s.charCodeAt(end - 1) === 47 /* '/' */) end--;\n  return end === s.length ? s : s.slice(0, end);\n}\n\ndeclare const __VERSION__: string;\n\n// ---------------------------------------------------------------------------\n// Public types (framework-agnostic)\n// ---------------------------------------------------------------------------\n\nexport interface AgentIdentity {\n  address?: string;\n  operatorToken?: string;\n}\n\n/**\n * Session metadata returned from `POST /v1/sessions`. Surfaced to the `onBeforeSession`\n * hook so merchants can correlate an AgentScore session with their own resume token\n * (e.g. a pending-order id).\n */\nexport interface SessionMetadata {\n  session_id: string;\n  verify_url: string;\n  poll_secret: string;\n  poll_url: string;\n  expires_at?: string;\n}\n\n/**\n * Configuration for auto-creating a verification session when no identity is present.\n *\n * The static `context` / `productName` options are sent on every session request. For\n * per-request context (e.g. the specific product the agent was trying to buy), pass\n * a `getSessionOptions` callback that returns dynamic values; its return is merged\n * over the static defaults.\n *\n * `onBeforeSession` is a side-effect hook that runs after the session is minted but\n * before the 403 is built. Use it to pre-create a reservation/draft/pending-order\n * row in your DB so agents can resume via a merchant-specific id. Return value is\n * merged into `DenialReason.extra`, so it surfaces in both the default 403 body and\n * in a custom `onDenied` handler.\n */\nexport interface CreateSessionOnMissing<TCtx = unknown> {\n  apiKey: string;\n  baseUrl?: string;\n  context?: string;\n  productName?: string;\n  /** Per-request override of `context` / `productName`. Invoked with the framework context. */\n  getSessionOptions?: (ctx: TCtx) => Promise<{ context?: string; productName?: string }>\n                                  |          { context?: string; productName?: string };\n  /** Side-effect hook that runs after the session is minted. Return value is merged\n   *  into `DenialReason.extra` so custom `onDenied` handlers can include merchant-specific\n   *  fields (e.g. `order_id`) in the 403 response. Hook errors are logged and swallowed —\n   *  a failing side effect should not block the 403 from reaching the agent. */\n  onBeforeSession?: (ctx: TCtx, session: SessionMetadata) => Promise<Record<string, unknown>>\n                                                          |          Record<string, unknown>;\n}\n\nexport interface AgentScoreCoreOptions {\n  /** AgentScore API key. Required. */\n  apiKey: string;\n  /** Require KYC verification. */\n  requireKyc?: boolean;\n  /** Require operator to be clear of sanctions. */\n  requireSanctionsClear?: boolean;\n  /** Minimum operator age bracket (18 or 21). */\n  minAge?: number;\n  /** List of blocked jurisdictions (blocklist). */\n  blockedJurisdictions?: string[];\n  /** List of allowed jurisdictions (allowlist — only these pass). */\n  allowedJurisdictions?: string[];\n  /** If true, allow the request through when the API is unreachable. Defaults to false. */\n  failOpen?: boolean;\n  /** How long to cache results, in seconds. Defaults to 300. */\n  cacheSeconds?: number;\n  /** AgentScore API base URL. Defaults to \"https://api.agentscore.sh\". */\n  baseUrl?: string;\n  /** Optional chain to filter scoring to. */\n  chain?: string;\n  /** Prepended to the default User-Agent as `\"{userAgent} (@agent-score/commerce@{version})\"`. Use to attribute API calls to your app. */\n  userAgent?: string;\n  /** When set and no identity is found, create a verification session instead of denying immediately. */\n  createSessionOnMissing?: CreateSessionOnMissing;\n}\n\nexport type DenialCode =\n  | 'wallet_not_trusted'\n  | 'missing_identity'\n  | 'api_error'\n  | 'payment_required'\n  | 'identity_verification_required'\n  // Wallet-signer binding: claimed X-Wallet-Address must resolve to the same operator as\n  // the payment signer; wallet-auth is rejected on rails with no wallet signer.\n  | 'wallet_signer_mismatch'\n  | 'wallet_auth_requires_wallet_signing'\n  // Granular credential-state denials passed through from /v1/assess.\n  // - `token_expired`: revoked + TTL-expired (the API unifies these). The 401 body carries\n  //   an auto-minted session, forwarded into DenialReason for one-shot recovery.\n  // - `invalid_credential`: the token doesn't exist at all (typo, never minted, fabricated).\n  //   No auto-session is minted by the API for this case — agents should switch to a\n  //   different stored token or drop the header to bootstrap a fresh session.\n  | 'token_expired'\n  | 'invalid_credential';\n\n/**\n * Cross-merchant pattern hint emitted on bootstrap denials and session-create responses.\n * LLM-hosted agents should persist this to long-term memory so future AgentScore encounters skip\n * the cold-start session flow. Contents are the pattern, not secrets.\n */\nexport interface AgentMemoryHint {\n  save_for_future_agentscore_gates: true;\n  pattern_summary: string;\n  quickstart: string;\n  identity_check_endpoint: string;\n  list_wallets_endpoint?: string;\n  identity_paths: { wallet: string; operator_token: string };\n  bootstrap: string;\n  do_not_persist_in_memory: string[];\n  persist_in_credential_store: string[];\n}\n\nexport interface DenialReason {\n  code: DenialCode;\n  /** Human-readable explanation. When omitted, `denialReasonToBody` substitutes a per-code default. */\n  message?: string;\n  decision?: string;\n  reasons?: string[];\n  verify_url?: string;\n  session_id?: string;\n  poll_secret?: string;\n  poll_url?: string;\n  agent_instructions?: string;\n  /** Cross-merchant memory hint. Emitted on bootstrap denials only by default. */\n  agent_memory?: AgentMemoryHint;\n  /** Full assess response when the denial came from `/v1/assess`. Lets consumers access fields\n   *  not promoted to first-class DenialReason properties (e.g., `policy_result`). Undefined for\n   *  denials that did not originate from an assess call (missing_identity, api_error,\n   *  payment_required, identity_verification_required). */\n  data?: AgentScoreData;\n  /** Extra fields returned from the `createSessionOnMissing.onBeforeSession` hook. Merged\n   *  into the default 403 body; custom `onDenied` handlers can spread these into their own\n   *  response shape (e.g. to include a merchant-minted `order_id`). */\n  extra?: Record<string, unknown>;\n  // ---------------------------------------------------------------------------\n  // Wallet-signer-match fields — populated for wallet_signer_mismatch only.\n  // ---------------------------------------------------------------------------\n  /** Operator id resolved from `X-Wallet-Address`. */\n  claimed_operator?: string;\n  /** Operator id the actual payment signer resolves to. `null` when the signer wallet isn't\n   *  linked to any operator (treat as a different identity). */\n  actual_signer_operator?: string | null;\n  /** The wallet the agent claimed via header. Echoed back for self-correction. */\n  expected_signer?: string;\n  /** The wallet that actually signed the payment. */\n  actual_signer?: string;\n  /** Wallets the claimed operator could sign with (if enumerable). Present when non-empty. */\n  linked_wallets?: string[];\n}\n\nexport interface AgentScoreData {\n  decision: string | null;\n  decision_reasons: string[];\n  identity_method?: string;\n  operator_verification?: {\n    level: string;\n    operator_type: string | null;\n    verified_at: string | null;\n  };\n  /** Account-level KYC facts that apply to every operator under the same account.\n   *  Populated when the API returns account_verification (post-KYC operator). */\n  account_verification?: {\n    kyc_level?: string;\n    sanctions_clear?: boolean;\n    age_bracket?: string;\n    jurisdiction?: string;\n    verified_at?: string | null;\n  };\n  resolved_operator?: string | null;\n  /** Wallets linked to the same operator as the resolved identity. Capped at 100 entries\n   *  by the API. Useful for advertising in 402 challenges so wallet-auth agents know which\n   *  alt-signers will satisfy `wallet_signer_mismatch`. */\n  linked_wallets?: string[];\n  verify_url?: string;\n  policy_result?: {\n    all_passed: boolean;\n    checks: Array<{\n      rule: string;\n      passed: boolean;\n      required?: unknown;\n      actual?: unknown;\n    }>;\n  } | null;\n}\n\n/**\n * Outcome from `AgentScoreCore.evaluate()`. Adapters map this to framework-specific responses.\n *\n * - `{ kind: 'allow', data }` — the request passed the policy. `data` is present on a normal\n *   allow; `undefined` when fail-open short-circuited (identity missing, API unreachable,\n *   timeout, or 402 paid-tier required).\n * - `{ kind: 'deny', reason }` — the request was denied. Adapters should render a 403 with the\n *   reason, or invoke the caller's custom denial handler.\n */\nexport type EvaluateOutcome =\n  | { kind: 'allow'; data?: AgentScoreData }\n  | { kind: 'deny'; reason: DenialReason };\n\nexport interface CaptureWalletOptions {\n  /** Operator credential (`opc_...`) that the agent authenticated with. */\n  operatorToken: string;\n  /** Signer wallet recovered from the payment payload. */\n  walletAddress: string;\n  /** Key-derivation family — `\"evm\"` for any EVM chain, `\"solana\"` for Solana. */\n  network: 'evm' | 'solana';\n  /** Optional stable key for the logical payment (e.g., payment intent id, tx hash). When the\n   *  same key is seen again for the same (credential, wallet, network), the server no-ops —\n   *  prevents agent retries from inflating transaction_count. */\n  idempotencyKey?: string;\n}\n\nexport interface VerifyWalletSignerMatchOptions {\n  /** The wallet claimed via `X-Wallet-Address`. */\n  claimedWallet: string;\n  /** The signer wallet recovered from the payment credential. `null` means the rail carries\n   *  no wallet signer (SPT, card) — the helper returns `wallet_auth_requires_wallet_signing`. */\n  signer: string | null;\n  /** Network of the signer. EVM covers every EVM chain; `solana` lives in its own namespace. */\n  network?: 'evm' | 'solana';\n}\n\nexport type VerifyWalletSignerResult =\n  | { kind: 'pass'; claimedOperator: string | null; signerOperator: string | null }\n  | {\n      kind: 'wallet_signer_mismatch';\n      claimedOperator: string | null;\n      actualSignerOperator: string | null;\n      expectedSigner: string;\n      actualSigner: string;\n      linkedWallets: string[];\n      /** JSON-encoded action copy (action + steps + user_message). Spread into the 403 body\n       *  verbatim so agents get a concrete recovery path inside the denial response itself. */\n      agentInstructions: string;\n    }\n  | {\n      kind: 'wallet_auth_requires_wallet_signing';\n      claimedWallet: string;\n      agentInstructions: string;\n    }\n  // Transient — the resolve call to /v1/assess failed or timed out. Caller should\n  // retry or surface as 503. Distinct from wallet_signer_mismatch (which is an actual\n  // security reject) so legitimate users don't get rejected on network flakes.\n  | { kind: 'api_error'; claimedWallet: string };\n\nexport interface AgentScoreCore {\n  /**\n   * Evaluate the request's identity against the configured policy.\n   * @param identity - extracted identity (wallet address and/or operator token)\n   * @param ctx - optional framework-specific context (Hono c, Express req, etc.) passed\n   *   through to `createSessionOnMissing` hooks. Opaque to core.\n   */\n  evaluate(identity: AgentIdentity | undefined, ctx?: unknown): Promise<EvaluateOutcome>;\n  /** Report a wallet seen paying under an operator credential. Fire-and-forget; silently\n   *  swallows non-fatal errors because capture is informational, not on the critical path. */\n  captureWallet(options: CaptureWalletOptions): Promise<void>;\n  /**\n   * Verify the payment signer resolves to the same operator as the claimed `X-Wallet-Address`.\n   *\n   * Returns `pass` when the signer is linked to the same operator as the claimed wallet\n   * (byte-equal wallets pass trivially; other wallets linked to the same operator also pass —\n   * multi-wallet agents work without ergonomic pain). Returns `wallet_signer_mismatch` when\n   * the signer resolves to a different (or no) operator. Returns `wallet_auth_requires_wallet_signing`\n   * when the signer is `null` (SPT, card — rails that carry no wallet signature).\n   *\n   * Call this AFTER the gate evaluates (so the claimed wallet's operator is cached) and\n   * AFTER the payment credential is parsed (so the signer is known). Merchants should call\n   * it before settling payment.\n   */\n  verifyWalletSignerMatch(options: VerifyWalletSignerMatchOptions): Promise<VerifyWalletSignerResult>;\n}\n\n// ---------------------------------------------------------------------------\n// Internal types\n// ---------------------------------------------------------------------------\n\ninterface AssessResult {\n  allow: boolean;\n  decision?: string;\n  reasons?: string[];\n  raw?: unknown;\n}\n\n/**\n * Build the cross-merchant memory hint emitted on bootstrap denials. Base URLs are\n * derived from the gate's AgentScore API base so self-hosted / staging deployments get\n * correct pointers. Contents describe the AgentScore identity substrate in transferable\n * terms; merchant-specific context lives in other `agent_instructions` fields.\n */\n// Canonical production AgentScore API — used as the authoritative source for endpoint pointers\n// emitted to agent memory regardless of how a given merchant configured their gate's baseUrl.\n// Hardcoded so a malicious merchant can't set `baseUrl: \"evil.com\"` and phish agents into\n// sending their credentials to attacker-controlled endpoints.\nconst CANONICAL_AGENTSCORE_API = 'https://api.agentscore.sh';\n\n// JSON-encoded action copy emitted on wallet-signer-match denials. Spread into 403 bodies\n// by merchants so agents get a concrete recovery path inside the denial response itself —\n// no discovery-doc round trip required.\nconst WALLET_SIGNER_MISMATCH_INSTRUCTIONS = JSON.stringify({\n  action: 'resign_or_switch_to_operator_token',\n  steps: [\n    'Preferred: re-submit the payment signed by expected_signer (or any entry in linked_wallets — same-operator wallets are fungible) and retry with the same X-Wallet-Address.',\n    'Alternative: drop X-Wallet-Address and retry with X-Operator-Token. Use a stored opc_... if you have one; otherwise retry this request with NO identity header — the merchant will mint a verification session in the 403 body (verify_url + poll_secret). Share verify_url with the user, poll, receive a fresh opc_...',\n  ],\n  user_message:\n    'The payment signer resolves to a different operator than X-Wallet-Address. Re-sign from expected_signer or any linked_wallets entry, or switch to X-Operator-Token.',\n});\n\nconst WALLET_AUTH_REQUIRES_WALLET_SIGNING_INSTRUCTIONS = JSON.stringify({\n  action: 'switch_to_operator_token',\n  steps: [\n    'This payment rail (Stripe SPT, card) carries no wallet signature — X-Wallet-Address cannot be verified against the payment.',\n    'Drop X-Wallet-Address and retry with X-Operator-Token. If you do not have a stored opc_..., retry with no identity header to receive a verification session.',\n  ],\n  user_message:\n    'Wallet-address identity is only supported on wallet-signing rails (Tempo MPP, x402). On Stripe or card, use X-Operator-Token instead.',\n});\n\n// `invalid_credential` is permanent — the token doesn't exist (typo, never minted, fabricated).\n// Distinct from `token_expired` (which carries an auto-session for one-shot recovery): the\n// API doesn't auto-mint a session here because the client may simply have a different valid\n// token to try. Agents should switch tokens or drop the header to bootstrap a session.\nconst INVALID_CREDENTIAL_INSTRUCTIONS = JSON.stringify({\n  action: 'switch_token_or_restart_session',\n  steps: [\n    'The X-Operator-Token you sent does not match any credential. This is a permanent state — retrying with the same token will keep failing.',\n    'If you have other stored opc_... credentials, retry with one of them.',\n    'Otherwise drop X-Operator-Token and retry with no identity header — the merchant will mint a fresh verification session in the 403 body (verify_url + poll_secret) so the user can re-verify and you can poll for a new operator_token.',\n  ],\n  user_message:\n    'The operator_token is not recognized. Use a different stored token, or restart the verification session flow to mint a new one.',\n});\n\nexport function buildAgentMemoryHint(): AgentMemoryHint {\n  // Memory pointers always point at the canonical production API — merchants must not be\n  // able to redirect the cross-merchant memory surface, since that would be a phishing\n  // vector for the verify URL.\n  const api = CANONICAL_AGENTSCORE_API;\n  return {\n    save_for_future_agentscore_gates: true,\n    pattern_summary:\n      'AgentScore is a cross-merchant identity substrate for agent commerce. Any endpoint that ' +\n      'returns 403 missing_identity / identity_verification_required or 402 challenges referencing AgentScore uses ' +\n      'the same identity system. One KYC works across all AgentScore merchants — no re-verification ' +\n      'per site. Save this pattern (and the endpoints below) to persistent memory so future ' +\n      'AgentScore encounters skip the cold-start session flow.',\n    quickstart: 'https://docs.agentscore.sh/guides/agent-identity',\n    identity_check_endpoint: `${api}/v1/credentials`,\n    identity_paths: {\n      wallet:\n        'If paying from a crypto wallet you have used before on any AgentScore merchant, send ' +\n        '`X-Wallet-Address: 0x...`. Shortest path; no token lifecycle to manage.',\n      operator_token:\n        'For any rail (Stripe SPT, card, or a wallet you have not linked yet), send ' +\n        '`X-Operator-Token: opc_...`. Reusable across merchants until the token expires.',\n    },\n    bootstrap:\n      'If you have neither a linked wallet nor a valid operator_token, follow the session/verify ' +\n      'flow in the per-request `agent_instructions` block. This happens at most once per agent ' +\n      'identity — after first verification, the operator_token and any subsequently used wallet ' +\n      'are reusable everywhere.',\n    do_not_persist_in_memory: ['operator_token', 'poll_secret'],\n    persist_in_credential_store: ['operator_token'],\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Core factory\n// ---------------------------------------------------------------------------\n\nexport function createAgentScoreCore(options: AgentScoreCoreOptions): AgentScoreCore {\n  if (!options.apiKey) {\n    throw new Error('AgentScore API key is required. Get one at https://agentscore.sh/sign-up');\n  }\n\n  const {\n    apiKey,\n    requireKyc,\n    requireSanctionsClear,\n    minAge,\n    blockedJurisdictions,\n    allowedJurisdictions,\n    failOpen = false,\n    cacheSeconds = 300,\n    baseUrl: rawBaseUrl = 'https://api.agentscore.sh',\n    chain: gateChain,\n    userAgent,\n    createSessionOnMissing,\n  } = options;\n\n  const baseUrl = stripTrailingSlashes(rawBaseUrl);\n  const agentMemoryHint = buildAgentMemoryHint();\n\n  const defaultUa = `@agent-score/commerce@${__VERSION__}`;\n  const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;\n\n  const API_TIMEOUT_MS = 10_000;\n\n  const cache = new TTLCache<AssessResult>(cacheSeconds * 1000);\n\n  // Mint a verification session via /v1/sessions and return the resulting\n  // identity_verification_required DenialReason — or undefined if the mint failed (network\n  // error, non-2xx, missing fields). Used for both the missing-identity path and the\n  // fixable-wallet bootstrap path: in both cases the UX is identical (agent polls the\n  // returned poll_url until it gets a fresh opc_... and retries).\n  async function tryMintSessionDenial(ctx: unknown): Promise<DenialReason | undefined> {\n    if (!createSessionOnMissing) return undefined;\n    try {\n      const sessionBody: { context?: string; product_name?: string } = {};\n      if (createSessionOnMissing.context != null) sessionBody.context = createSessionOnMissing.context;\n      if (createSessionOnMissing.productName != null) sessionBody.product_name = createSessionOnMissing.productName;\n\n      if (createSessionOnMissing.getSessionOptions && ctx !== undefined) {\n        try {\n          const dynamic = await createSessionOnMissing.getSessionOptions(ctx);\n          if (dynamic?.context != null) sessionBody.context = dynamic.context;\n          if (dynamic?.productName != null) sessionBody.product_name = dynamic.productName;\n        } catch (err) {\n          console.warn('[gate] createSessionOnMissing.getSessionOptions hook failed:', err instanceof Error ? err.message : err);\n        }\n      }\n\n      const sessionBaseUrl = stripTrailingSlashes(createSessionOnMissing.baseUrl ?? 'https://api.agentscore.sh');\n      const sessionRes = await fetch(`${sessionBaseUrl}/v1/sessions`, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': createSessionOnMissing.apiKey,\n          'Content-Type': 'application/json',\n          Accept: 'application/json',\n          'User-Agent': userAgentHeader,\n        },\n        body: JSON.stringify(sessionBody),\n        signal: AbortSignal.timeout(API_TIMEOUT_MS),\n      });\n\n      if (!sessionRes.ok) return undefined;\n      const data = (await sessionRes.json()) as Record<string, unknown>;\n\n      // Validate required fields before trusting the response. A misbehaving (or mocked-wrong)\n      // API could 200 without session_id/poll_secret/verify_url, which would propagate\n      // `undefined` into the 403 body and leave the agent stuck — treat as session-create\n      // failure and fall back to the caller's bare denial.\n      if (\n        typeof data.session_id !== 'string' ||\n        typeof data.poll_secret !== 'string' ||\n        typeof data.verify_url !== 'string'\n      ) {\n        console.warn('[gate] /v1/sessions returned 200 without required fields — falling back to bare denial');\n        return undefined;\n      }\n\n      // Run onBeforeSession side-effect hook. Errors are swallowed — a failing DB write\n      // (e.g. can't insert pending order) should not block the 403.\n      let extra: Record<string, unknown> | undefined;\n      if (createSessionOnMissing.onBeforeSession && ctx !== undefined) {\n        try {\n          const sessionMeta = {\n            session_id: data.session_id as string,\n            verify_url: data.verify_url as string,\n            poll_secret: data.poll_secret as string,\n            poll_url: data.poll_url as string,\n            expires_at: data.expires_at as string | undefined,\n          };\n          const result = await createSessionOnMissing.onBeforeSession(ctx, sessionMeta);\n          if (result && typeof result === 'object') extra = result;\n        } catch (err) {\n          console.warn('[gate] createSessionOnMissing.onBeforeSession hook failed:', err instanceof Error ? err.message : err);\n        }\n      }\n\n      // The API emits `next_steps` (structured object) on /v1/sessions success. Stringify it\n      // into the gate's `agent_instructions` contract so merchants get the same JSON-encoded\n      // {action, steps, user_message} envelope as every other gate-emitted denial.\n      const apiNextSteps = data.next_steps as Record<string, unknown> | undefined;\n      return {\n        code: 'identity_verification_required',\n        verify_url: data.verify_url as string,\n        session_id: data.session_id as string,\n        poll_secret: data.poll_secret as string,\n        poll_url: data.poll_url as string | undefined,\n        agent_instructions: apiNextSteps ? JSON.stringify(apiNextSteps) : undefined,\n        agent_memory: agentMemoryHint,\n        ...(extra && { extra }),\n      };\n    } catch (err) {\n      // Session-mint failed (network, /v1/sessions returned non-2xx, body parse error,\n      // onBeforeSession threw inside the inner try). Caller falls back to a bare denial —\n      // agents still get a 403 with a probe-strategy hint. Log loudly so a persistent\n      // /v1/sessions outage isn't masked.\n      console.warn('[gate] createSessionOnMissing path failed — falling back to bare denial:', err instanceof Error ? err.message : err);\n      return undefined;\n    }\n  }\n\n  async function evaluate(identity: AgentIdentity | undefined, ctx?: unknown): Promise<EvaluateOutcome> {\n    // Treat \"returned identity object with no usable fields\" the same as \"no identity at all\" —\n    // otherwise a misbehaving custom extractIdentity would send an empty body to /v1/assess.\n    if (!identity || (!identity.address && !identity.operatorToken)) {\n      if (failOpen) return { kind: 'allow' };\n\n      const sessionReason = await tryMintSessionDenial(ctx);\n      if (sessionReason) return { kind: 'deny', reason: sessionReason };\n\n      // Bare missing-identity denial (no session was auto-created). Describe the probe\n      // strategy so agents without memory can recover: try wallet first on signing rails,\n      // fall back to stored opc_..., fall back to session flow (noting that only\n      // auto-session merchants return verify_url + poll data on the retry).\n      const missingIdentityInstructions = JSON.stringify({\n        action: 'probe_identity_then_session',\n        steps: [\n          'If you have a wallet AND this merchant accepts a wallet-signing rail (Tempo MPP or x402 — see openapi.json x-payment-info): send X-Wallet-Address and retry. If the wallet is already linked to an AgentScore operator (via prior SIWE claim or prior captureWallet), this passes in one round trip. If the wallet is unlinked or the account has no KYC, the 403 will include a verify_url — share it with the user to claim the wallet + complete KYC, then retry.',\n          'If step 1 is denied or you already have a stored operator_token (valid + not expired): send X-Operator-Token: opc_... and retry.',\n          'If neither applies: retry with NO identity header. Merchants that auto-create verification sessions (most AgentScore merchants do) return verify_url + session_id + poll_secret in the 403 body — share verify_url with the user, then poll poll_url every 5s with the X-Poll-Secret header until status=verified (the poll returns a one-time operator_token). If the retry returns the same bare 403, this merchant does not support self-service session bootstrapping — direct the user to https://agentscore.sh/sign-up to create an AgentScore identity and mint an operator_token from their dashboard (https://agentscore.sh/dashboard/verify). The user hands the opc_... to you, and you retry with X-Operator-Token.',\n        ],\n        user_message:\n          'Try X-Wallet-Address first if you have a wallet and the merchant accepts Tempo/x402; fall back to a stored X-Operator-Token, then to the session/verify flow described in agent_memory.bootstrap.',\n      });\n      return {\n        kind: 'deny',\n        reason: {\n          code: 'missing_identity',\n          agent_instructions: missingIdentityInstructions,\n          agent_memory: agentMemoryHint,\n        },\n      };\n    }\n\n    // operator_token is opaque + ASCII-only — lowercasing is safe. Wallet addresses go\n    // through normalizeAddress because Solana base58 is case-sensitive and lowercasing\n    // would corrupt the cache key (a Solana cache miss every time, plus collision risk\n    // with mixed-case variants of the same operator).\n    const cacheKey = identity.operatorToken?.toLowerCase() ?? (identity.address ? normalizeAddress(identity.address) : '');\n\n    const cached = cache.get(cacheKey);\n    if (cached) {\n      if (cached.allow) {\n        return { kind: 'allow', data: cached.raw as AgentScoreData };\n      }\n      // Fixable compliance denials (kyc_required, kyc_pending, kyc_failed) get the\n      // same UX as missing_identity: mint a fresh verification session, agent polls\n      // until status=verified, gets a fresh opc_..., retries. Unfixable reasons\n      // (sanctions_flagged, age_insufficient, jurisdiction_restricted) keep the bare\n      // wallet_not_trusted denial. `jurisdiction_restricted` is unfixable: the API\n      // only emits it after KYC is verified (the user's KYC'd country is in the\n      // blocked list — re-doing KYC won't change the country).\n      if (isFixableDenial(cached.reasons)) {\n        const sessionReason = await tryMintSessionDenial(ctx);\n        if (sessionReason) return { kind: 'deny', reason: sessionReason };\n      }\n      return {\n        kind: 'deny',\n        reason: {\n          code: 'wallet_not_trusted',\n          decision: cached.decision,\n          reasons: cached.reasons,\n          verify_url: (cached.raw as Record<string, unknown> | undefined)?.verify_url as string | undefined,\n          data: cached.raw as AgentScoreData | undefined,\n        },\n      };\n    }\n\n    try {\n      const body: Record<string, unknown> = {};\n      if (identity.address) body.address = identity.address;\n      if (identity.operatorToken) body.operator_token = identity.operatorToken;\n      if (gateChain) body.chain = gateChain;\n\n      const policy: Record<string, unknown> = {};\n      if (requireKyc != null) policy.require_kyc = requireKyc;\n      if (requireSanctionsClear != null) policy.require_sanctions_clear = requireSanctionsClear;\n      if (minAge != null) policy.min_age = minAge;\n      if (blockedJurisdictions != null) policy.blocked_jurisdictions = blockedJurisdictions;\n      if (allowedJurisdictions != null) policy.allowed_jurisdictions = allowedJurisdictions;\n      if (Object.keys(policy).length > 0) body.policy = policy;\n\n      const response = await fetch(`${baseUrl}/v1/assess`, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': apiKey,\n          'Content-Type': 'application/json',\n          Accept: 'application/json',\n          'User-Agent': userAgentHeader,\n        },\n        body: JSON.stringify(body),\n        signal: AbortSignal.timeout(API_TIMEOUT_MS),\n      });\n\n      if (response.status === 402) {\n        if (failOpen) return { kind: 'allow' };\n        return { kind: 'deny', reason: { code: 'payment_required' } };\n      }\n\n      // Pass through the API's token_expired 401 (covers both expired and revoked\n      // credentials — the API deliberately doesn't distinguish). The 401 body carries\n      // an auto-minted session (verify_url + session_id + poll_secret + next_steps +\n      // agent_memory) so agents can recover without holding an API key. Forward all of\n      // that into the DenialReason so the gate's 403 body includes the session fields.\n      if (response.status === 401) {\n        try {\n          const errData = (await response.clone().json()) as {\n            error?: { code?: string };\n            session_id?: unknown;\n            poll_secret?: unknown;\n            verify_url?: unknown;\n            poll_url?: unknown;\n            next_steps?: unknown;\n            agent_memory?: unknown;\n          };\n          const code = errData?.error?.code;\n          if (code === 'token_expired') {\n            return {\n              kind: 'deny',\n              reason: {\n                code,\n                data: errData as unknown as AgentScoreData,\n                ...(typeof errData.verify_url === 'string' ? { verify_url: errData.verify_url } : {}),\n                ...(typeof errData.session_id === 'string' ? { session_id: errData.session_id } : {}),\n                ...(typeof errData.poll_secret === 'string' ? { poll_secret: errData.poll_secret } : {}),\n                ...(typeof errData.poll_url === 'string' ? { poll_url: errData.poll_url } : {}),\n                ...(errData.next_steps ? { agent_instructions: JSON.stringify(errData.next_steps) } : {}),\n                ...(errData.agent_memory ? { agent_memory: errData.agent_memory as AgentMemoryHint } : {}),\n              },\n            };\n          }\n          // The API returns this when the operator_token doesn't exist at all (typo,\n          // never minted, fabricated). Distinct from token_expired — no auto-session\n          // is issued because the agent may have other valid tokens to try first.\n          // Without this branch the gate would fall through to api_error → 503 retry,\n          // which loops forever on a permanent state.\n          if (code === 'invalid_credential') {\n            return {\n              kind: 'deny',\n              reason: {\n                code: 'invalid_credential',\n                agent_instructions: INVALID_CREDENTIAL_INSTRUCTIONS,\n                agent_memory: agentMemoryHint,\n              },\n            };\n          }\n          // Unknown 401 code — log so we notice if the API adds a new credential-state\n          // code without us mapping it. Falls through to api_error below.\n          if (code) {\n            console.warn(`[gate] /v1/assess returned 401 ${code} — no specific handler, surfacing as api_error.`);\n          }\n        } catch (err) {\n          // Body wasn't the expected JSON shape. Don't crash the request, but DO log —\n          // a silent swallow here used to mask /v1/sessions schema drift for hours.\n          console.warn('[gate] /v1/assess 401 body parse failed:', err instanceof Error ? err.message : err);\n        }\n      }\n\n      // 4xx with a structured error body that ISN'T 401/402: log it so operators see\n      // misclassifications instead of opaque 503 retries. Most common cause: a merchant\n      // that didn't validate input shape before invoking the gate (invalid_address,\n      // invalid_identity). We still fall through to api_error so behavior is unchanged\n      // for callers — just visible now.\n      if (response.status >= 400 && response.status < 500 && response.status !== 402) {\n        try {\n          const errData = (await response.clone().json()) as { error?: { code?: string; message?: string } };\n          const code = errData?.error?.code;\n          if (code && code !== 'token_expired' && code !== 'invalid_credential') {\n            console.warn(\n              `[gate] /v1/assess returned ${response.status} ${code} — surfacing as api_error. ` +\n              'Validate input shape before invoking the gate to avoid this.',\n            );\n          }\n        } catch {\n          // Body wasn't JSON or didn't have the expected shape — silent fall-through.\n        }\n      }\n\n      if (!response.ok) {\n        throw new Error(`AgentScore API returned ${response.status}`);\n      }\n\n      const data = (await response.json()) as Record<string, unknown>;\n      const decision = data.decision as string | null | undefined;\n      const decisionReasons = (data.decision_reasons as string[]) ?? [];\n      const allow = decision === 'allow' || decision == null;\n\n      cache.set(cacheKey, { allow, decision: decision ?? undefined, reasons: decisionReasons, raw: data });\n\n      if (allow) {\n        return { kind: 'allow', data: data as unknown as AgentScoreData };\n      }\n\n      // Fixable compliance denials (kyc_required, kyc_pending, kyc_failed) get the\n      // same UX as missing_identity: mint a fresh verification session, agent polls\n      // until status=verified, gets a fresh opc_..., retries. Unfixable reasons\n      // (sanctions_flagged, age_insufficient, jurisdiction_restricted) keep the bare\n      // wallet_not_trusted denial. `jurisdiction_restricted` is unfixable: the API\n      // only emits it after KYC is verified (the user's KYC'd country is in the\n      // blocked list — re-doing KYC won't change the country).\n      if (isFixableDenial(decisionReasons)) {\n        const sessionReason = await tryMintSessionDenial(ctx);\n        if (sessionReason) return { kind: 'deny', reason: sessionReason };\n      }\n\n      return {\n        kind: 'deny',\n        reason: {\n          code: 'wallet_not_trusted',\n          decision: decision ?? undefined,\n          reasons: decisionReasons,\n          verify_url: data.verify_url as string | undefined,\n          data: data as unknown as AgentScoreData,\n        },\n      };\n    } catch (err) {\n      // Network failure, AbortSignal timeout, JSON parse error on a 2xx, or the\n      // explicit `throw new Error(...)` for an unhandled non-ok status. Log so ops\n      // can distinguish \"API down\" from \"merchant config wrong\" — without this,\n      // every transient blip looked identical to a misconfigured base URL.\n      console.warn('[gate] /v1/assess call failed — surfacing as api_error:', err instanceof Error ? err.message : err);\n      if (failOpen) return { kind: 'allow' };\n      return { kind: 'deny', reason: { code: 'api_error' } };\n    }\n  }\n\n  async function captureWallet(options: CaptureWalletOptions): Promise<void> {\n    try {\n      const body: Record<string, unknown> = {\n        operator_token: options.operatorToken,\n        wallet_address: options.walletAddress,\n        network: options.network,\n      };\n      if (options.idempotencyKey) body.idempotency_key = options.idempotencyKey;\n      await fetch(`${baseUrl}/v1/credentials/wallets`, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': apiKey,\n          'Content-Type': 'application/json',\n          Accept: 'application/json',\n          'User-Agent': userAgentHeader,\n        },\n        body: JSON.stringify(body),\n        signal: AbortSignal.timeout(API_TIMEOUT_MS),\n      });\n    } catch (err) {\n      // Fire-and-forget: don't throw. Log so a persistent capture outage is visible\n      // to merchant ops — otherwise wallet↔operator linkage silently stops.\n      console.warn('[agentscore-commerce] captureWallet failed:', err instanceof Error ? err.message : err);\n    }\n  }\n\n  /**\n   * Resolve a wallet to its operator id via /v1/assess.\n   *\n   * Returns:\n   *   - `{ ok: true, operator: <id> }` — wallet is linked to that operator\n   *   - `{ ok: true, operator: null }` — wallet is valid but not linked to any operator\n   *   - `{ ok: false }` — the API call failed (network, timeout, non-2xx). Distinguishable so\n   *     callers can emit `api_error` instead of falsely asserting \"no operator linked\".\n   *\n   * Checks the main evaluate() cache before making a fresh call — if the gate already\n   * resolved this wallet during identity evaluation, we have the resolved_operator already.\n   */\n  async function resolveWalletToOperator(\n    walletAddress: string,\n  ): Promise<{ ok: true; operator: string | null; linkedWallets: string[] } | { ok: false }> {\n    // Network-aware: lowercases EVM, preserves Solana base58 case. The DB stores both\n    // formats verbatim in operator_credential_wallets.wallet_address; lowercasing a\n    // Solana address would never match.\n    const wallet = normalizeAddress(walletAddress);\n\n    // Cache lookup — first the plain cache (populated by evaluate() for identity-headered wallets).\n    // Saves a second /v1/assess call when the gate already looked up this wallet.\n    const extractFromCached = (raw: Record<string, unknown>): { operator: string | null; linkedWallets: string[] } => {\n      const op = raw.resolved_operator;\n      const links = raw.linked_wallets;\n      return {\n        operator: typeof op === 'string' ? op : null,\n        linkedWallets: Array.isArray(links) ? (links as unknown[]).filter((w): w is string => typeof w === 'string') : [],\n      };\n    };\n\n    const plainCached = cache.get(wallet);\n    if (plainCached?.raw) {\n      return { ok: true, ...extractFromCached(plainCached.raw as Record<string, unknown>) };\n    }\n    const resolveCached = cache.get(`resolve:${wallet}`);\n    if (resolveCached?.raw) {\n      return { ok: true, ...extractFromCached(resolveCached.raw as Record<string, unknown>) };\n    }\n\n    try {\n      const response = await fetch(`${baseUrl}/v1/assess`, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': apiKey,\n          'Content-Type': 'application/json',\n          Accept: 'application/json',\n          'User-Agent': userAgentHeader,\n        },\n        body: JSON.stringify({ address: walletAddress }),\n        signal: AbortSignal.timeout(API_TIMEOUT_MS),\n      });\n      if (!response.ok) return { ok: false };\n      const data = (await response.json()) as Record<string, unknown>;\n      cache.set(`resolve:${wallet}`, { allow: true, raw: data });\n      return { ok: true, ...extractFromCached(data) };\n    } catch (err) {\n      // Network/timeout/parse on the wallet→operator resolve path. Caller maps\n      // `{ok:false}` to `wallet_signer_mismatch.kind === 'api_error'`, which already\n      // surfaces as 503 — but log here too so multi-wallet match failures aren't\n      // silently indistinguishable from \"operator simply has no linked wallet\".\n      console.warn('[gate] resolveWalletToOperator failed — returning { ok:false }:', err instanceof Error ? err.message : err);\n      return { ok: false };\n    }\n  }\n\n  function reportSignerEvent(kind: 'pass' | 'wallet_signer_mismatch' | 'wallet_auth_requires_wallet_signing' | 'api_error'): void {\n    // Fire-and-forget: surfaces mismatch-catch rate + api_error SLO on the dashboard.\n    // Never blocks, awaits, or throws — telemetry failure must not affect the gate's decision.\n    try {\n      const pending = fetch(`${baseUrl}/v1/telemetry/signer-match`, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': apiKey,\n          'Content-Type': 'application/json',\n          Accept: 'application/json',\n          'User-Agent': userAgentHeader,\n        },\n        body: JSON.stringify({ kind }),\n        signal: AbortSignal.timeout(API_TIMEOUT_MS),\n      });\n      if (pending && typeof pending.catch === 'function') {\n        pending.catch((err) => {\n          console.warn('[agentscore-commerce] signer-match telemetry failed:', err instanceof Error ? err.message : err);\n        });\n      }\n    } catch {\n      // Thrown synchronously (e.g., fetch unavailable in test harness) — swallow silently.\n    }\n  }\n\n  async function verifyWalletSignerMatch(\n    options: VerifyWalletSignerMatchOptions,\n  ): Promise<VerifyWalletSignerResult> {\n    const { claimedWallet, signer } = options;\n\n    if (!signer) {\n      reportSignerEvent('wallet_auth_requires_wallet_signing');\n      return {\n        kind: 'wallet_auth_requires_wallet_signing',\n        claimedWallet,\n        agentInstructions: WALLET_AUTH_REQUIRES_WALLET_SIGNING_INSTRUCTIONS,\n      };\n    }\n\n    // Network-aware normalization: lowercase EVM, preserve Solana base58. The byte-equal\n    // short-circuit and downstream cache-key derivation MUST match how the DB stores\n    // wallets; lowercasing Solana would corrupt both.\n    const claimedNorm = normalizeAddress(claimedWallet);\n    const signerNorm = normalizeAddress(signer);\n\n    // Byte-equal short-circuit — no API lookup; same wallet ≡ same operator by definition.\n    if (claimedNorm === signerNorm) {\n      reportSignerEvent('pass');\n      return { kind: 'pass', claimedOperator: null, signerOperator: null };\n    }\n\n    const [claimedResolve, signerResolve] = await Promise.all([\n      resolveWalletToOperator(claimedNorm),\n      resolveWalletToOperator(signerNorm),\n    ]);\n\n    // Transient API failure on either resolve → emit api_error. Caller should retry or\n    // surface 503 rather than falsely reject a legitimate user on a network flake.\n    if (!claimedResolve.ok || !signerResolve.ok) {\n      reportSignerEvent('api_error');\n      return { kind: 'api_error', claimedWallet: claimedNorm };\n    }\n\n    const claimedOperator = claimedResolve.operator;\n    const signerOperator = signerResolve.operator;\n\n    if (claimedOperator && signerOperator && claimedOperator === signerOperator) {\n      reportSignerEvent('pass');\n      return { kind: 'pass', claimedOperator, signerOperator };\n    }\n\n    reportSignerEvent('wallet_signer_mismatch');\n    return {\n      kind: 'wallet_signer_mismatch',\n      claimedOperator,\n      actualSignerOperator: signerOperator,\n      expectedSigner: claimedNorm,\n      actualSigner: signerNorm,\n      // Populated from /v1/assess.linked_wallets on the claimed wallet — the full set of\n      // wallets the agent CAN sign with to satisfy the claim (same-operator rule).\n      linkedWallets: claimedResolve.linkedWallets,\n      agentInstructions: WALLET_SIGNER_MISMATCH_INSTRUCTIONS,\n    };\n  }\n\n  return { evaluate, captureWallet, verifyWalletSignerMatch };\n}\n","/**\n * Payment-signer extraction.\n *\n * Shared between merchants and the gate — both need to recover the on-chain signer from\n * a payment credential without duplicating code. Three rails carry a wallet signer:\n *\n *   - **Tempo MPP** — `Authorization: Payment <base64>` header; credential `source` is a DID\n *     of the form `did:pkh:eip155:<chain>:<address>`.\n *   - **x402 EIP-3009** (EVM, e.g. Base/Sepolia) — `payment-signature` / `x-payment` header;\n *     decoded payload carries `payload.authorization.from`.\n *   - **x402 SVM** (Solana) — same headers, but `payload.transaction` is a base64-encoded\n *     Solana transaction; the SPL Token TransferChecked instruction's source-account owner\n *     is the signer. Recovered via `@x402/svm`'s `decodeTransactionFromPayload` +\n *     `getTokenPayerFromTransaction`.\n *\n * `mppx` and `@x402/svm` are optional peer dependencies — we import them dynamically so\n * merchants who don't use those rails don't need to install them. The EVM x402 path is pure\n * JSON parsing with no external dep.\n */\n\nexport type SignerNetwork = 'evm' | 'solana';\n\nexport interface PaymentSigner {\n  /** Recovered wallet address (EVM lowercased; Solana base58 preserved verbatim). */\n  address: string;\n  /** Network family — used by `captureWallet` and downstream cross-chain attribution. */\n  network: SignerNetwork;\n}\n\n/**\n * Recover the signer wallet from the incoming payment credential, including the network\n * family. Returns `null` when no wallet signature is present (e.g. Stripe SPT, card-only\n * payments, or no credential yet).\n *\n * @param request - the inbound `Request`\n * @param x402PaymentHeader - the value of `payment-signature` or `x-payment` header, if any.\n *   Extracted separately because some frameworks (Express) don't expose a web `Request` object.\n */\nexport async function extractPaymentSigner(\n  request: Request,\n  x402PaymentHeader?: string,\n): Promise<PaymentSigner | null> {\n  // MPP — Authorization: Payment <base64>\n  const authHeader = request.headers.get('authorization');\n  if (authHeader) {\n    try {\n      const moduleName = 'mppx';\n      const mppx = (await import(moduleName).catch(() => null)) as {\n        Credential?: {\n          extractPaymentScheme: (h: string) => unknown;\n          fromRequest: (r: Request) => unknown;\n        };\n      } | null;\n      if (mppx?.Credential?.extractPaymentScheme(authHeader)) {\n        const credential = mppx.Credential.fromRequest(request);\n        const source = (credential as { source?: string }).source;\n        const match = source?.match(/^did:pkh:eip155:\\d+:(0x[0-9a-fA-F]{40})$/);\n        if (match) return { address: match[1]!.toLowerCase(), network: 'evm' };\n      }\n    } catch (err) {\n      console.warn('[gate] MPP signer extraction failed:', err instanceof Error ? err.message : err);\n    }\n  }\n\n  // x402 — base64 JSON. Network identifier on `accepted.network` selects the extraction\n  // path: `eip155:*` → EIP-3009 `payload.authorization.from`; `solana:*` → SPL Token\n  // payer recovered from the encoded transaction.\n  if (x402PaymentHeader) {\n    try {\n      const decoded = atob(x402PaymentHeader);\n      const parsed = JSON.parse(decoded) as {\n        accepted?: { network?: string };\n        payload?: { authorization?: { from?: string }; transaction?: string };\n      };\n      const network = parsed?.accepted?.network ?? '';\n\n      if (network.startsWith('eip155:')) {\n        const from = parsed?.payload?.authorization?.from;\n        if (typeof from === 'string' && /^0x[0-9a-fA-F]{40}$/.test(from)) {\n          return { address: from.toLowerCase(), network: 'evm' };\n        }\n      } else if (network.startsWith('solana:')) {\n        const transaction = parsed?.payload?.transaction;\n        if (typeof transaction === 'string') {\n          const moduleName = '@x402/svm';\n          const svm = (await import(moduleName).catch(() => null)) as {\n            decodeTransactionFromPayload?: (p: { transaction: string }) => unknown;\n            getTokenPayerFromTransaction?: (tx: unknown) => string | undefined;\n          } | null;\n          if (svm?.decodeTransactionFromPayload && svm.getTokenPayerFromTransaction) {\n            const tx = svm.decodeTransactionFromPayload({ transaction });\n            const payer = svm.getTokenPayerFromTransaction(tx);\n            if (typeof payer === 'string' && payer.length > 0) return { address: payer, network: 'solana' };\n          }\n        }\n      } else {\n        // Back-compat: a payload without an `accepted.network` field still uses EIP-3009\n        // shape if `payload.authorization.from` looks EVM. Older x402 clients emitted these.\n        const from = parsed?.payload?.authorization?.from;\n        if (typeof from === 'string' && /^0x[0-9a-fA-F]{40}$/.test(from)) {\n          return { address: from.toLowerCase(), network: 'evm' };\n        }\n      }\n    } catch (err) {\n      console.warn('[gate] x402 signer extraction failed:', err instanceof Error ? err.message : err);\n    }\n  }\n\n  return null;\n}\n\n/**\n * Address-only convenience over {@link extractPaymentSigner}. Used by the gate adapters\n * (verifyWalletSignerMatch) where only the address matters for operator comparison.\n */\nexport async function extractPaymentSignerAddress(\n  request: Request,\n  x402PaymentHeader?: string,\n): Promise<string | null> {\n  const result = await extractPaymentSigner(request, x402PaymentHeader);\n  return result?.address ?? null;\n}\n\n/**\n * Read the x402 payment header from a `Request`, matching the alternate names merchants might\n * use. Falls back to reading either header directly.\n */\nexport function readX402PaymentHeader(request: Request): string | undefined {\n  return (\n    request.headers.get('payment-signature') ??\n    request.headers.get('x-payment') ??\n    undefined\n  );\n}\n","/**\n * Shared DenialReason → response body serialization for all adapters.\n *\n * Keeps Hono / Express / Fastify / Web / Next.js defaults aligned — a field added\n * here shows up in every adapter's 403 body automatically, and there's one place\n * to test the marshaling.\n *\n * Body shape: `{ error: { code, message }, ... }` — matches the canonical AgentScore\n * core API response shape (`core/api/src/lib/auth.ts`, `lib/rate-limit.ts`, etc.) and\n * martin-estate's pre-commerce shape, so downstream agents see one consistent\n * `error.code` + `error.message` pair regardless of which layer produced the denial.\n */\n\nimport type { DenialCode, DenialReason } from './core.js';\n\n/**\n * JSON-encoded canonical agent_instructions per denial code. Auto-injected by\n * `denialReasonToBody` when the gate produces a DenialReason without explicit\n * `agent_instructions` so every denial carries a machine-readable next step.\n *\n * Codes covered:\n *  - `wallet_not_trusted` — gate never stamps instructions today (the original gap)\n *  - `payment_required` — gate never stamps; merchant tier misconfig, contact-merchant action\n *  - `identity_verification_required` — fallback when API didn't return next_steps\n *  - `token_expired` — fallback when API didn't return next_steps\n *\n * Codes already stamped explicitly upstream in core.ts (`missing_identity`,\n * `invalid_credential`) and codes that don't go through DenialReason\n * (`wallet_signer_mismatch`, `wallet_auth_requires_wallet_signing` — handled by\n * `verifyWalletSignerMatch` result type) are not in this map. `api_error` has\n * its own `next_steps: {action: retry}` fallback below.\n */\nconst WALLET_NOT_TRUSTED_INSTRUCTIONS = JSON.stringify({\n  action: 'contact_support',\n  steps: [\n    'The wallet\\'s operator failed an UNFIXABLE compliance check (sanctions, age, or jurisdiction). `reasons` lists which: `sanctions_flagged` / `age_insufficient` / `jurisdiction_restricted`. KYC re-verification won\\'t change the outcome — the policy denial is structural.',\n    'Surface the denial to the user with the merchant\\'s support contact. Do not retry the same merchant request; do not hand the user a verify_url (verification won\\'t fix this code path).',\n    'Fixable compliance reasons (`kyc_required`, `kyc_pending`, `kyc_failed`) do NOT land on this code — the gate auto-mints a verification session for those and returns `identity_verification_required` with poll endpoints, same shape as `missing_identity`. `jurisdiction_restricted` IS in the unfixable bucket because the API only emits it after KYC is verified (the user\\'s KYC\\'d country is in the blocked list — re-doing KYC won\\'t change the country).',\n  ],\n  user_message:\n    'This purchase is denied by the merchant\\'s compliance policy and cannot be resolved by re-verifying. Contact the merchant\\'s support if you believe this is in error.',\n});\n\nconst PAYMENT_REQUIRED_INSTRUCTIONS = JSON.stringify({\n  action: 'contact_merchant',\n  steps: [\n    'The merchant\\'s AgentScore tier does not include the assess feature, so agent identity cannot be evaluated. This is a merchant-side configuration gap — there is no agent-side recovery.',\n    'Contact the merchant (their support channel — typically listed in /llms.txt or the OpenAPI servers metadata) and request they upgrade their AgentScore plan.',\n  ],\n  user_message:\n    'This merchant\\'s identity gate is misconfigured (AgentScore tier doesn\\'t support assess). Contact the merchant — there\\'s nothing to fix on the agent side.',\n});\n\nconst IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({\n  action: 'deliver_verify_url_and_poll',\n  steps: [\n    'Share verify_url with the user — they complete identity verification on AgentScore.',\n    'If session_id + poll_secret are present in the body, poll poll_url every 5 seconds with header `X-Poll-Secret: <poll_secret>` until status=verified. The poll returns a one-time operator_token.',\n    'Retry the original request with header `X-Operator-Token: <opc_...>`.',\n  ],\n  user_message:\n    'Identity verification is required. Visit verify_url, then poll poll_url for the operator token and retry.',\n});\n\nconst TOKEN_EXPIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({\n  action: 'deliver_verify_url_and_poll',\n  steps: [\n    'The operator token is expired or revoked. AgentScore auto-mints a fresh verification session — complete it to receive a new opc_...',\n    'Share verify_url with the user, then poll poll_url every 5 seconds with header `X-Poll-Secret: <poll_secret>` until status=verified. The poll returns a fresh one-time operator_token.',\n    'Retry the original request with header `X-Operator-Token: <new_opc_...>`.',\n  ],\n  user_message:\n    'Operator token is expired or revoked. A new verification session has been minted — visit verify_url to refresh.',\n});\n\nconst DEFAULT_AGENT_INSTRUCTIONS: Partial<Record<DenialCode, string>> = {\n  wallet_not_trusted: WALLET_NOT_TRUSTED_INSTRUCTIONS,\n  payment_required: PAYMENT_REQUIRED_INSTRUCTIONS,\n  identity_verification_required: IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS,\n  token_expired: TOKEN_EXPIRED_FALLBACK_INSTRUCTIONS,\n};\n\nconst DEFAULT_MESSAGES: Record<DenialCode, string> = {\n  missing_identity:\n    'No identity provided. Send X-Wallet-Address (wallet) or X-Operator-Token (credential).',\n  identity_verification_required:\n    'Identity verification is required to access this resource. Visit verify_url to complete KYC.',\n  wallet_not_trusted:\n    'The wallet does not meet the merchant compliance policy.',\n  api_error:\n    'AgentScore is unreachable. This is transient — retry in a few seconds.',\n  payment_required:\n    'AgentScore tier does not support assess. Contact support.',\n  wallet_signer_mismatch:\n    'Payment signer does not match the wallet claimed via X-Wallet-Address. The signer and the claimed wallet must both resolve to the same AgentScore operator.',\n  wallet_auth_requires_wallet_signing:\n    'X-Wallet-Address was sent with a rail that has no wallet signature (Stripe SPT / card). Switch to X-Operator-Token, or use a wallet-signing rail (Tempo MPP, x402).',\n  token_expired:\n    'The operator token is expired or revoked. A fresh verification session has been minted — visit verify_url to mint a new token.',\n  invalid_credential:\n    'The operator token is not recognized. Switch to a different stored token, or drop the header to bootstrap a fresh session.',\n};\n\n// Field names the gate claims authority over. Merchant-provided `extra` (from the\n// onBeforeSession hook) MUST NOT override these — a buggy or malicious hook could\n// otherwise replace `verify_url` with a phishing URL or drop agent_instructions.\nconst RESERVED_FIELDS = new Set([\n  'error',\n  'decision',\n  'reasons',\n  'verify_url',\n  'session_id',\n  'poll_secret',\n  'poll_url',\n  'agent_instructions',\n  'agent_memory',\n  'claimed_operator',\n  'actual_signer_operator',\n  'expected_signer',\n  'actual_signer',\n  'linked_wallets',\n]);\n\nexport function denialReasonToBody(reason: DenialReason): Record<string, unknown> {\n  const message = reason.message ?? DEFAULT_MESSAGES[reason.code];\n  const body: Record<string, unknown> = { error: { code: reason.code, message } };\n  if (reason.decision) body.decision = reason.decision;\n  if (reason.reasons) body.reasons = reason.reasons;\n  if (reason.verify_url) body.verify_url = reason.verify_url;\n  if (reason.session_id) body.session_id = reason.session_id;\n  if (reason.poll_secret) body.poll_secret = reason.poll_secret;\n  if (reason.poll_url) body.poll_url = reason.poll_url;\n  const instructions = reason.agent_instructions ?? DEFAULT_AGENT_INSTRUCTIONS[reason.code];\n  if (instructions) body.agent_instructions = instructions;\n  if (reason.agent_memory) body.agent_memory = reason.agent_memory;\n  if (reason.claimed_operator) body.claimed_operator = reason.claimed_operator;\n  if (reason.code === 'wallet_signer_mismatch') body.actual_signer_operator = reason.actual_signer_operator ?? null;\n  if (reason.expected_signer) body.expected_signer = reason.expected_signer;\n  if (reason.actual_signer) body.actual_signer = reason.actual_signer;\n  if (reason.linked_wallets && reason.linked_wallets.length > 0) body.linked_wallets = reason.linked_wallets;\n  // api_error denials get a default retry hint so agents know it's transient. Vendors can\n  // override by spreading their own next_steps into a custom onDenied body.\n  if (reason.code === 'api_error' && !(reason.extra && (reason.extra as Record<string, unknown>).next_steps)) {\n    body.next_steps = { action: 'retry', retry_after_seconds: 5 };\n  }\n  if (reason.extra) {\n    for (const [key, value] of Object.entries(reason.extra)) {\n      if (RESERVED_FIELDS.has(key)) {\n        console.warn(`[gate] onBeforeSession returned reserved field \"${key}\" — ignoring to preserve gate authority`);\n        continue;\n      }\n      body[key] = value;\n    }\n  }\n  return body;\n}\n","/**\n * Google A2A (Agent-to-Agent) Signed Agent Cards builder.\n *\n * Compose the JSON payload for an A2A v1.0 Signed Agent Card that includes the\n * agent's AgentScore identity claims. Returned object is the unsigned card body —\n * the merchant (or agent) signs it with their wallet / signing key before publishing.\n *\n * Why publish: A2A is a Linux Foundation standard with 150+ orgs (Microsoft, AWS,\n * Salesforce in production). Signed Agent Cards let any A2A-compatible reader discover\n * an agent's verified-identity claims without per-platform integration. AgentScore\n * publishing operator identity in this format means our identity travels with the agent\n * across A2A-aware ecosystems.\n *\n * Spec reference: https://a2a-protocol.org/latest/\n */\n\nimport type { AgentScoreData } from '../core';\n\nexport interface A2AAgentCardCapabilities {\n  /** Endpoints the agent exposes — `[{ name: \"purchase\", path: \"/purchase\", method: \"POST\" }, ...]`. */\n  endpoints?: { name: string; path?: string; method?: string }[];\n  /** Free-form skill tags — `[\"wine-purchase\", \"regulated-commerce\", ...]`. */\n  skills?: string[];\n}\n\nexport interface A2AAgentCardIdentity {\n  /** Issuer of the identity claims — always `\"https://agentscore.sh\"` for the AgentScore-issued card. */\n  issuer: string;\n  /** Operator id under AgentScore. */\n  operator_id: string;\n  /** KYC tier. */\n  kyc_level: string;\n  /** Sanctions screening result. */\n  sanctions_clear: boolean;\n  /** Age bracket. */\n  age_bracket: string;\n  /** Jurisdiction (ISO-3166-1 alpha-2 or empty). */\n  jurisdiction: string;\n  /** ISO-8601 timestamp of last verification refresh. */\n  verified_at: string | null;\n  /** Verify URL where the identity was minted. */\n  verify_url: string;\n}\n\nexport interface A2AAgentCard {\n  /** A2A protocol version. v1.0 was donated to Linux Foundation. */\n  protocol_version: string;\n  /** Card schema version (this builder emits v1). */\n  card_version: number;\n  /** Agent's display name. */\n  name: string;\n  /** One-line description shown to A2A consumers. */\n  description?: string;\n  /** Agent's canonical URL (homepage, Discord, repo, etc.). */\n  url?: string;\n  /** Agent capabilities — endpoints + skills. */\n  capabilities?: A2AAgentCardCapabilities;\n  /** AgentScore identity claims. Empty `null` when no identity is available (pre-KYC). */\n  identity: A2AAgentCardIdentity | null;\n  /** Vendor-specific extras merged at the top level. */\n  extras?: Record<string, unknown>;\n}\n\nexport interface BuildA2AAgentCardInput {\n  /** Display name for the agent — `\"Martin Estate Wine Concierge\"`, etc. */\n  name: string;\n  /** Optional one-line description. */\n  description?: string;\n  /** Agent's canonical URL. */\n  url?: string;\n  /** Capabilities — endpoints exposed + skill tags. */\n  capabilities?: A2AAgentCardCapabilities;\n  /** AgentScore assess data — what `getAgentScoreData(c)` returns or what `assess()` returned directly.\n   *  Pass `null` to emit a card with no identity claims (publishable but unverified). */\n  data?: AgentScoreData | null;\n  /** Override the default issuer URL. Default `\"https://agentscore.sh\"`. */\n  issuer?: string;\n  /** Override the verify URL. */\n  verifyUrl?: string;\n  /** Vendor-specific extras merged at the card top level. */\n  extras?: Record<string, unknown>;\n}\n\nconst PROTOCOL_VERSION = '1.0';\nconst CARD_VERSION = 1;\n\n/**\n * Compose an A2A Signed Agent Card body with AgentScore identity claims included.\n *\n * Returns the UNSIGNED card. The vendor signs it with their wallet (typically using\n * the same wallet they use for x402 / MPP payments) and publishes the signed envelope\n * to wherever A2A consumers discover cards (a hosted endpoint, on-chain registry,\n * agent-card-server, etc.). Signing is vendor-side because the agent's signing key\n * never leaves their environment.\n *\n * Example:\n * ```ts\n * import { buildA2AAgentCard } from '@agent-score/commerce/identity/hono';\n *\n * app.get('/.well-known/agent-card', async (c) => {\n *   const data = getAgentScoreData(c);\n *   const card = buildA2AAgentCard({\n *     name: 'Martin Estate Wine Concierge',\n *     description: 'Buy regulated wines from Martin Estate via agent payments.',\n *     url: 'https://agents.martinestate.com',\n *     capabilities: {\n *       endpoints: [{ name: 'purchase', path: '/purchase', method: 'POST' }],\n *       skills: ['wine-purchase', 'regulated-commerce'],\n *     },\n *     data,\n *   });\n *   const signed = await yourSign(card);\n *   return c.json(signed);\n * });\n * ```\n */\nexport function buildA2AAgentCard(input: BuildA2AAgentCardInput): A2AAgentCard {\n  const issuer = input.issuer ?? 'https://agentscore.sh';\n\n  let identity: A2AAgentCardIdentity | null = null;\n  if (input.data) {\n    const operatorId = (input.data.resolved_operator as string | undefined) ?? null;\n    if (operatorId) {\n      const operatorVerification = input.data.operator_verification;\n      const accountVerification = input.data.account_verification;\n      identity = {\n        issuer,\n        operator_id: operatorId,\n        kyc_level: accountVerification?.kyc_level ?? operatorVerification?.level ?? 'none',\n        sanctions_clear: accountVerification?.sanctions_clear === true,\n        age_bracket: accountVerification?.age_bracket ?? 'unknown',\n        jurisdiction: accountVerification?.jurisdiction ?? '',\n        verified_at: accountVerification?.verified_at ?? operatorVerification?.verified_at ?? null,\n        verify_url:\n          input.verifyUrl\n          ?? (input.data.verify_url as string | undefined)\n          ?? `${issuer}/verify`,\n      };\n    }\n  }\n\n  const card: A2AAgentCard = {\n    protocol_version: PROTOCOL_VERSION,\n    card_version: CARD_VERSION,\n    name: input.name,\n    identity,\n  };\n  if (input.description !== undefined) card.description = input.description;\n  if (input.url !== undefined) card.url = input.url;\n  if (input.capabilities !== undefined) card.capabilities = input.capabilities;\n  if (input.extras !== undefined) card.extras = input.extras;\n  return card;\n}\n","/**\n * UCP (Universal Commerce Protocol) profile builder.\n *\n * Compose the JSON payload published at `/.well-known/ucp` per the UCP spec, with\n * AgentScore identity claims attached as a capability. Returned object is the unsigned\n * profile body — the merchant signs it (or wraps it in their JWKS-backed envelope)\n * before publishing.\n *\n * Why publish: UCP is the Google-led cross-vendor standard (announced Jan 2026 at NRF\n * with Shopify, Etsy, Wayfair, Target, Walmart, Adyen, Mastercard, Stripe, Visa, Amex,\n * etc.). Every UCP-aware platform discovers a merchant via `/.well-known/ucp`, so\n * shipping this profile means AgentScore-gated merchants are discoverable through the\n * same surface every other UCP merchant uses.\n *\n * Spec reference: https://ucp.dev/\n *\n * UCP profiles do NOT carry KYC / sanctions / age / jurisdiction claims natively —\n * identity in the UCP spec is \"who signed this\" (JWKS-backed). AgentScore claims layer\n * over UCP via a custom capability so consumers who care about verified-buyer identity\n * can read them; consumers who don't care just see a normal UCP profile.\n */\n\nimport type { AgentScoreData } from '../core';\n\nexport interface UCPSigningKey {\n  /** JWK kid (key id). */\n  kid: string;\n  /** JWK kty (key type) — typically `EC`, `RSA`, or `OKP`. */\n  kty: string;\n  /** JWK alg (signing algorithm) — typically `ES256`, `RS256`, or `EdDSA`. */\n  alg?: string;\n  /** JWK use — typically `sig`. */\n  use?: string;\n  /** JWK crv (curve) for EC / OKP keys. */\n  crv?: string;\n  /** JWK x / y / n / e / etc. The full key material; passed through verbatim. */\n  [k: string]: unknown;\n}\n\nexport interface UCPService {\n  /** Transport binding — `rest` / `mcp` / `a2a` / `embedded`. */\n  type: string;\n  /** Service URL (or path for embedded). */\n  url?: string;\n  /** Optional version pin. */\n  version?: string;\n  /** Vendor-specific extras for the binding. */\n  [k: string]: unknown;\n}\n\nexport interface UCPCapability {\n  /** Capability name — `checkout`, `catalog`, `agentscore-identity`, etc. */\n  name: string;\n  /** URL of the JSON Schema describing this capability's payload. */\n  schema?: string;\n  /** Capability version — semver or date-stamp per UCP convention. */\n  version?: string;\n  /** Vendor-specific extras for the capability. */\n  [k: string]: unknown;\n}\n\nexport interface UCPPaymentHandler {\n  /** Handler name — `stripe`, `tempo`, `x402-base`, `x402-solana`, etc. */\n  name: string;\n  /** Handler config — recipient address, profile id, etc. */\n  config?: Record<string, unknown>;\n}\n\nexport interface UCPProfile {\n  /** UCP spec version (date-stamped). */\n  version: string;\n  /** URL of the UCP spec. */\n  spec: string;\n  /** URL of this profile's JSON schema. */\n  schema?: string;\n  /** Display name of the merchant / agent surface. */\n  name?: string;\n  /** Service bindings — REST, MCP, A2A, embedded transports. */\n  services: UCPService[];\n  /** Capabilities offered (with schema URLs). */\n  capabilities: UCPCapability[];\n  /** Payment handlers offered — typically the rails the merchant accepts. */\n  payment_handlers: UCPPaymentHandler[];\n  /** JWKS — REQUIRED by spec. The merchant signs requests with a private key whose\n   *  public counterpart is listed here. Verifiers fetch this profile, find the kid, and\n   *  validate signatures. */\n  signing_keys: UCPSigningKey[];\n  /** Vendor-specific extras at the top level. */\n  [k: string]: unknown;\n}\n\nexport interface BuildUCPProfileInput {\n  /** UCP spec version. Default `\"2026-04-17\"` (current at time of writing). */\n  version?: string;\n  /** Display name for the merchant / agent surface. */\n  name?: string;\n  /** Service transport bindings. At minimum, the agent's primary REST endpoint. */\n  services: UCPService[];\n  /** Capabilities offered. AgentScore identity is auto-added as a capability when `data` is provided. */\n  capabilities?: UCPCapability[];\n  /** Payment handlers — rails the merchant accepts. */\n  payment_handlers?: UCPPaymentHandler[];\n  /** JWKS — public keys the merchant signs requests with. REQUIRED by spec. */\n  signing_keys: UCPSigningKey[];\n  /** AgentScore assess data — adds an `agentscore-identity` capability + claims block when present. */\n  data?: AgentScoreData | null;\n  /** Optional override for the AgentScore capability schema URL. */\n  agentscoreSchemaUrl?: string;\n  /** Vendor-specific extras at the top level. */\n  extras?: Record<string, unknown>;\n}\n\nconst DEFAULT_VERSION = '2026-04-17';\nconst SPEC_URL = 'https://ucp.dev/';\nconst AGENTSCORE_CAPABILITY_NAME = 'agentscore-identity';\nconst AGENTSCORE_CAPABILITY_VERSION = '1';\n\n/**\n * Compose a UCP profile body for `/.well-known/ucp` publication. Merges AgentScore\n * identity claims into the `capabilities` array as an `agentscore-identity` capability\n * so UCP-aware consumers can discover verified-buyer claims alongside the standard\n * UCP transport metadata.\n *\n * Example:\n * ```ts\n * import { buildUCPProfile } from '@agent-score/commerce/identity/hono';\n *\n * app.get('/.well-known/ucp', async (c) => {\n *   const data = getAgentScoreData(c);\n *   return c.json(buildUCPProfile({\n *     name: 'Martin Estate',\n *     services: [{ type: 'rest', url: 'https://agents.martinestate.com' }],\n *     payment_handlers: [\n *       { name: 'tempo', config: { recipient: TEMPO_ADDR } },\n *       { name: 'stripe', config: { profile_id: STRIPE_PROFILE_ID } },\n *     ],\n *     signing_keys: [{ kid: 'me-2026-04', kty: 'EC', alg: 'ES256', crv: 'P-256', x: '...', y: '...' }],\n *     data,\n *   }));\n * });\n * ```\n */\nexport function buildUCPProfile(input: BuildUCPProfileInput): UCPProfile {\n  const baseCapabilities: UCPCapability[] = [...(input.capabilities ?? [])];\n\n  if (input.data) {\n    const operatorId = input.data.resolved_operator;\n    if (operatorId) {\n      const operatorVerification = input.data.operator_verification;\n      const accountVerification = input.data.account_verification;\n      const claims: Record<string, unknown> = {\n        operator_id: operatorId,\n        kyc_level: accountVerification?.kyc_level ?? operatorVerification?.level ?? 'none',\n        sanctions_clear: accountVerification?.sanctions_clear === true,\n        age_bracket: accountVerification?.age_bracket ?? 'unknown',\n        jurisdiction: accountVerification?.jurisdiction ?? '',\n        verified_at: accountVerification?.verified_at ?? operatorVerification?.verified_at ?? null,\n        verify_url: input.data.verify_url ?? null,\n        issuer: 'https://agentscore.sh',\n      };\n      baseCapabilities.push({\n        name: AGENTSCORE_CAPABILITY_NAME,\n        version: AGENTSCORE_CAPABILITY_VERSION,\n        schema: input.agentscoreSchemaUrl ?? 'https://agentscore.sh/schemas/ucp/agentscore-identity.v1.json',\n        claims,\n      });\n    }\n  }\n\n  const profile: UCPProfile = {\n    version: input.version ?? DEFAULT_VERSION,\n    spec: SPEC_URL,\n    services: input.services,\n    capabilities: baseCapabilities,\n    payment_handlers: input.payment_handlers ?? [],\n    signing_keys: input.signing_keys,\n  };\n\n  if (input.name !== undefined) profile.name = input.name;\n  if (input.extras) Object.assign(profile, input.extras);\n\n  return profile;\n}\n\nexport const AGENTSCORE_UCP_CAPABILITY = AGENTSCORE_CAPABILITY_NAME;\n","/**\n * Per-product / per-tier compliance policy helpers.\n *\n * A *policy* is a small bag of fields describing what identity the merchant wants\n * verified for a given resource:\n *\n * - `enforcement`: `\"hard\"` (today's wine path — 403 on miss) or `\"soft\"` (gate\n *   denial is swallowed; the order completes with a degraded `identity_status`).\n *   `null` / absent = no gate at all.\n * - `requireKyc` / `requireSanctionsClear` / `minAge`: passed through to the\n *   per-framework `agentscoreGate(...)` factory.\n * - `allowedJurisdictions`: buyer-verified country list (`[\"US\", \"CA\", ...]`).\n * - `allowedShippingCountries` / `allowedShippingStates`: optional shipping\n *   allowlists. State list is only enforced for US shipments.\n *\n * This module ships three primitives:\n *\n * 1. {@link PolicyBlock} — the typed shape.\n * 2. {@link policyToGateOptions} — translate a block into the options object the\n *    per-framework `agentscoreGate(...)` accepts. Returns `null` when the policy\n *    has no enforcement (treat as \"no gate; anonymous OK\").\n * 3. {@link runGateWithEnforcement} — wrap a per-framework middleware in the\n *    hard/soft enforcement runner. The middleware is given an `onDenied` shim\n *    that captures the denial body and status; the runner returns a structured\n *    {@link GateResult} so the vendor decides how to surface it.\n *\n * All three are additive — vendors using `agentscoreGate(...)` directly are\n * unaffected. The pattern was extracted from `agentscore/store`; see its\n * `store/routes/purchase.py` (Python sibling) for the full per-request flow.\n */\n\nimport type { AgentScoreCoreOptions, DenialReason } from '../core.js';\n\n/** Hard = 403 propagates; soft = swallowed + identity_status=\"unverified\". */\nexport type EnforcementMode = 'hard' | 'soft';\n\n/** Per-order trust level captured at settle time. */\nexport type IdentityStatus = 'verified' | 'unverified' | 'anonymous' | 'denied';\n\n/** Compliance fields a merchant attaches per product / per tier. All optional. */\nexport interface PolicyBlock {\n  enforcement?: EnforcementMode;\n  requireKyc?: boolean;\n  requireSanctionsClear?: boolean;\n  minAge?: number;\n  allowedJurisdictions?: readonly string[];\n  allowedShippingCountries?: readonly string[];\n  allowedShippingStates?: readonly string[];\n}\n\n/**\n * Outcome of running a gate under an enforcement mode.\n *\n * - `verified`: gate accepted; identity is fully verified for the policy.\n * - `unverified`: soft mode swallowed a gate denial; the agent had *some*\n *   identity but didn't meet the policy. Stamp this on the order so\n *   ops/analytics can tell apart soft passes from hard passes.\n * - `anonymous`: no gate ran (policy was null / no enforcement).\n * - `denied`: hard mode rejected; the caller must propagate the 403. The\n *   `denialBody` and `denialStatus` carry the original gate response so the\n *   caller can return it as-is.\n */\nexport interface GateResult {\n  status: IdentityStatus;\n  denialStatus?: number;\n  denialBody?: Record<string, unknown>;\n  denialReason?: DenialReason;\n}\n\n/**\n * Translate a {@link PolicyBlock} into the options the per-framework\n * `agentscoreGate(...)` expects. Returns `null` when the block has no\n * `enforcement` set — the caller should treat that as \"no gate; anonymous OK\".\n *\n * Use a fresh gate per request rather than constructing once at module scope\n * when the policy varies per resource (e.g. per product). Each adapter's gate\n * is cheap to instantiate.\n */\nexport function policyToGateOptions(\n  policy: PolicyBlock | null | undefined,\n  base: { apiKey: string; baseUrl?: string },\n): AgentScoreCoreOptions | null {\n  if (!policy || !policy.enforcement) return null;\n  return {\n    apiKey: base.apiKey,\n    ...(base.baseUrl !== undefined && { baseUrl: base.baseUrl }),\n    ...(policy.requireKyc !== undefined && { requireKyc: policy.requireKyc }),\n    ...(policy.requireSanctionsClear !== undefined && {\n      requireSanctionsClear: policy.requireSanctionsClear,\n    }),\n    ...(policy.minAge !== undefined && { minAge: policy.minAge }),\n    ...(policy.allowedJurisdictions !== undefined && {\n      allowedJurisdictions: [...policy.allowedJurisdictions],\n    }),\n  };\n}\n\n/**\n * Run a per-framework gate middleware respecting the enforcement mode.\n *\n * The vendor passes:\n * - `gate`: their framework's middleware (Hono `MiddlewareHandler`, Express\n *   `(req, res, next) => void`, etc.) — anything that resolves on accept and\n *   throws or returns a `Response` on deny.\n * - `runGate`: a thin adapter that calls the middleware with the framework\n *   context and returns either `{ ok: true }` (gate accepted) or\n *   `{ ok: false, status, body, reason? }` (gate denied with details).\n *\n * `runGateWithEnforcement` wraps that in the hard/soft split:\n *\n * - `gate=null` or `enforcement=null`: no gate fires; status=\"anonymous\".\n * - `enforcement=\"hard\"` + denied: status=\"denied\"; caller propagates denialStatus + denialBody.\n * - `enforcement=\"soft\"` + denied: swallow; status=\"unverified\".\n * - accepted: status=\"verified\".\n */\nexport async function runGateWithEnforcement(\n  enforcement: EnforcementMode | undefined,\n  runGate: (() => Promise<{ ok: true } | { ok: false; status: number; body: Record<string, unknown>; reason?: DenialReason }>) | null,\n): Promise<GateResult> {\n  if (!runGate || !enforcement) return { status: 'anonymous' };\n\n  const outcome = await runGate();\n  if (outcome.ok) return { status: 'verified' };\n\n  if (enforcement === 'hard') {\n    return {\n      status: 'denied',\n      denialStatus: outcome.status,\n      denialBody: outcome.body,\n      ...(outcome.reason !== undefined && { denialReason: outcome.reason }),\n    };\n  }\n  return {\n    status: 'unverified',\n    denialStatus: outcome.status,\n    denialBody: outcome.body,\n    ...(outcome.reason !== undefined && { denialReason: outcome.reason }),\n  };\n}\n\n/** NULL policy / NULL allowlist → ship anywhere. Otherwise country must be in the list. */\nexport function shippingCountryAllowed(country: string, policy: PolicyBlock | null | undefined): boolean {\n  if (!policy?.allowedShippingCountries || policy.allowedShippingCountries.length === 0) return true;\n  const allowed = new Set(policy.allowedShippingCountries.map((c) => c.toUpperCase()));\n  return allowed.has(country.toUpperCase());\n}\n\n/**\n * US-state allowlist (e.g. wine).\n *\n * Only enforced for US shipments — non-US shipments are governed by\n * {@link shippingCountryAllowed} independently.\n */\nexport function shippingStateAllowed(\n  state: string,\n  country: string,\n  policy: PolicyBlock | null | undefined,\n): boolean {\n  if (!policy?.allowedShippingStates || policy.allowedShippingStates.length === 0) return true;\n  if (country.toUpperCase() !== 'US') return true;\n  const allowed = new Set(policy.allowedShippingStates.map((s) => s.toUpperCase()));\n  return allowed.has(state.toUpperCase());\n}\n"],"mappings":";AAgCO,IAAM,yBAA8C,oBAAI,IAAI;AAAA,EACjE;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAUM,SAAS,gBAAgB,SAAiD;AAC/E,MAAI,CAAC,WAAW,QAAQ,WAAW,EAAG,QAAO;AAC7C,SAAO,QAAQ,MAAM,CAAC,MAAM,uBAAuB,IAAI,CAAC,CAAC;AAC3D;AAUO,SAAS,mBAAmB,QAAuC;AACxE,MAAI,OAAO,SAAS,mBAAmB,OAAO,SAAS,qBAAsB,QAAO;AACpF,MAAI,OAAO,SAAS,YAAa,QAAO;AACxC,SAAO;AACT;AAuBO,SAAS,wBAAwB,OAAgE;AACtG,QAAM,EAAE,OAAO,IAAI;AACnB,MAAI,OAAO,SAAS,UAAU,OAAO,SAAS,YAAa,QAAO;AAElE,QAAM,eAAe,MAAM,gBAAgB;AAE3C,MAAI,OAAO,SAAS,0BAA0B;AAC5C,UAAM,gBAAgB,OAAO,iBAAiB,CAAC;AAC/C,UAAM,cAAc,MAAM,gBAAgB,cAAc,SAAS,IAC7D,qEAAqE,cAAc,KAAK,IAAI,CAAC,kBAC7F;AACJ,WAAO;AAAA,MACL,OAAO;AAAA,QACL,MAAM;AAAA,QACN,SACE;AAAA,MACJ;AAAA,MACA,kBAAkB,OAAO;AAAA,MACzB,wBAAwB,OAAO,wBAAwB;AAAA,MACvD,iBAAiB,OAAO;AAAA,MACxB,eAAe,OAAO;AAAA,MACtB,gBAAgB;AAAA,MAChB,YAAY;AAAA,QACV,QAAQ;AAAA,QACR,cAAc;AAAA,QACd,gBAAgB;AAAA,MAClB;AAAA,IACF;AAAA,EACF;AAGA,SAAO;AAAA,IACL,OAAO;AAAA,MACL,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA,YAAY;AAAA,MACV,QAAQ;AAAA,MACR,cACE,MAAM,eACN;AAAA,MACF,gBAAgB;AAAA,IAClB;AAAA,EACF;AACF;AAYO,SAAS,6BACd,cACA,SAC4E;AAC5E,SAAO;AAAA,IACL,QAAQ;AAAA,IACR,eAAe;AAAA,IACf,cACE,WACA,8DAA8D,YAAY;AAAA,EAC9E;AACF;AA8BO,SAAS,8BAA8B,QAA4C,CAAC,GAUzF;AACA,QAAM,YAAY;AAAA,IAChB;AAAA,IACA,4CAA4C,MAAM,uBAAuB,CAAC;AAAA,IAC1E;AAAA,IACA;AAAA,IACA,MAAM,aAAa;AAAA,EACrB;AAEA,SAAO;AAAA,IACL,QAAQ;AAAA,IACR,aACE,MAAM,cACN;AAAA,IACF,OAAO,MAAM,aAAa,CAAC,GAAG,WAAW,GAAG,MAAM,UAAU,IAAI;AAAA,IAChE,uBAAuB,MAAM,uBAAuB;AAAA,IACpD,oBAAoB;AAAA,IACpB,oBAAoB;AAAA,IACpB,iBAAiB,MAAM,kBAAkB;AAAA,IACzC,GAAI,MAAM,WAAW,EAAE,WAAW,MAAM,SAAS,IAAI,CAAC;AAAA,IACtD,GAAI,MAAM,SAAS,CAAC;AAAA,EACtB;AACF;;;AC6FA,IAAM,2BAA2B;AAKjC,IAAM,sCAAsC,KAAK,UAAU;AAAA,EACzD,QAAQ;AAAA,EACR,OAAO;AAAA,IACL;AAAA,IACA;AAAA,EACF;AAAA,EACA,cACE;AACJ,CAAC;AAED,IAAM,mDAAmD,KAAK,UAAU;AAAA,EACtE,QAAQ;AAAA,EACR,OAAO;AAAA,IACL;AAAA,IACA;AAAA,EACF;AAAA,EACA,cACE;AACJ,CAAC;AAMD,IAAM,kCAAkC,KAAK,UAAU;AAAA,EACrD,QAAQ;AAAA,EACR,OAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,cACE;AACJ,CAAC;AAEM,SAAS,uBAAwC;AAItD,QAAM,MAAM;AACZ,SAAO;AAAA,IACL,kCAAkC;AAAA,IAClC,iBACE;AAAA,IAKF,YAAY;AAAA,IACZ,yBAAyB,GAAG,GAAG;AAAA,IAC/B,gBAAgB;AAAA,MACd,QACE;AAAA,MAEF,gBACE;AAAA,IAEJ;AAAA,IACA,WACE;AAAA,IAIF,0BAA0B,CAAC,kBAAkB,aAAa;AAAA,IAC1D,6BAA6B,CAAC,gBAAgB;AAAA,EAChD;AACF;;;ACtVA,eAAsB,qBACpB,SACA,mBAC+B;AAE/B,QAAM,aAAa,QAAQ,QAAQ,IAAI,eAAe;AACtD,MAAI,YAAY;AACd,QAAI;AACF,YAAM,aAAa;AACnB,YAAM,OAAQ,MAAM,OAAO,YAAY,MAAM,MAAM,IAAI;AAMvD,UAAI,MAAM,YAAY,qBAAqB,UAAU,GAAG;AACtD,cAAM,aAAa,KAAK,WAAW,YAAY,OAAO;AACtD,cAAM,SAAU,WAAmC;AACnD,cAAM,QAAQ,QAAQ,MAAM,0CAA0C;AACtE,YAAI,MAAO,QAAO,EAAE,SAAS,MAAM,CAAC,EAAG,YAAY,GAAG,SAAS,MAAM;AAAA,MACvE;AAAA,IACF,SAAS,KAAK;AACZ,cAAQ,KAAK,wCAAwC,eAAe,QAAQ,IAAI,UAAU,GAAG;AAAA,IAC/F;AAAA,EACF;AAKA,MAAI,mBAAmB;AACrB,QAAI;AACF,YAAM,UAAU,KAAK,iBAAiB;AACtC,YAAM,SAAS,KAAK,MAAM,OAAO;AAIjC,YAAM,UAAU,QAAQ,UAAU,WAAW;AAE7C,UAAI,QAAQ,WAAW,SAAS,GAAG;AACjC,cAAM,OAAO,QAAQ,SAAS,eAAe;AAC7C,YAAI,OAAO,SAAS,YAAY,sBAAsB,KAAK,IAAI,GAAG;AAChE,iBAAO,EAAE,SAAS,KAAK,YAAY,GAAG,SAAS,MAAM;AAAA,QACvD;AAAA,MACF,WAAW,QAAQ,WAAW,SAAS,GAAG;AACxC,cAAM,cAAc,QAAQ,SAAS;AACrC,YAAI,OAAO,gBAAgB,UAAU;AACnC,gBAAM,aAAa;AACnB,gBAAM,MAAO,MAAM,OAAO,YAAY,MAAM,MAAM,IAAI;AAItD,cAAI,KAAK,gCAAgC,IAAI,8BAA8B;AACzE,kBAAM,KAAK,IAAI,6BAA6B,EAAE,YAAY,CAAC;AAC3D,kBAAM,QAAQ,IAAI,6BAA6B,EAAE;AACjD,gBAAI,OAAO,UAAU,YAAY,MAAM,SAAS,EAAG,QAAO,EAAE,SAAS,OAAO,SAAS,SAAS;AAAA,UAChG;AAAA,QACF;AAAA,MACF,OAAO;AAGL,cAAM,OAAO,QAAQ,SAAS,eAAe;AAC7C,YAAI,OAAO,SAAS,YAAY,sBAAsB,KAAK,IAAI,GAAG;AAChE,iBAAO,EAAE,SAAS,KAAK,YAAY,GAAG,SAAS,MAAM;AAAA,QACvD;AAAA,MACF;AAAA,IACF,SAAS,KAAK;AACZ,cAAQ,KAAK,yCAAyC,eAAe,QAAQ,IAAI,UAAU,GAAG;AAAA,IAChG;AAAA,EACF;AAEA,SAAO;AACT;AAMA,eAAsB,4BACpB,SACA,mBACwB;AACxB,QAAM,SAAS,MAAM,qBAAqB,SAAS,iBAAiB;AACpE,SAAO,QAAQ,WAAW;AAC5B;AAMO,SAAS,sBAAsB,SAAsC;AAC1E,SACE,QAAQ,QAAQ,IAAI,mBAAmB,KACvC,QAAQ,QAAQ,IAAI,WAAW,KAC/B;AAEJ;;;ACrGA,IAAM,kCAAkC,KAAK,UAAU;AAAA,EACrD,QAAQ;AAAA,EACR,OAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,cACE;AACJ,CAAC;AAED,IAAM,gCAAgC,KAAK,UAAU;AAAA,EACnD,QAAQ;AAAA,EACR,OAAO;AAAA,IACL;AAAA,IACA;AAAA,EACF;AAAA,EACA,cACE;AACJ,CAAC;AAED,IAAM,uDAAuD,KAAK,UAAU;AAAA,EAC1E,QAAQ;AAAA,EACR,OAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,cACE;AACJ,CAAC;AAED,IAAM,sCAAsC,KAAK,UAAU;AAAA,EACzD,QAAQ;AAAA,EACR,OAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,cACE;AACJ,CAAC;AAED,IAAM,6BAAkE;AAAA,EACtE,oBAAoB;AAAA,EACpB,kBAAkB;AAAA,EAClB,gCAAgC;AAAA,EAChC,eAAe;AACjB;AAEA,IAAM,mBAA+C;AAAA,EACnD,kBACE;AAAA,EACF,gCACE;AAAA,EACF,oBACE;AAAA,EACF,WACE;AAAA,EACF,kBACE;AAAA,EACF,wBACE;AAAA,EACF,qCACE;AAAA,EACF,eACE;AAAA,EACF,oBACE;AACJ;AAKA,IAAM,kBAAkB,oBAAI,IAAI;AAAA,EAC9B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAEM,SAAS,mBAAmB,QAA+C;AAChF,QAAM,UAAU,OAAO,WAAW,iBAAiB,OAAO,IAAI;AAC9D,QAAM,OAAgC,EAAE,OAAO,EAAE,MAAM,OAAO,MAAM,QAAQ,EAAE;AAC9E,MAAI,OAAO,SAAU,MAAK,WAAW,OAAO;AAC5C,MAAI,OAAO,QAAS,MAAK,UAAU,OAAO;AAC1C,MAAI,OAAO,WAAY,MAAK,aAAa,OAAO;AAChD,MAAI,OAAO,WAAY,MAAK,aAAa,OAAO;AAChD,MAAI,OAAO,YAAa,MAAK,cAAc,OAAO;AAClD,MAAI,OAAO,SAAU,MAAK,WAAW,OAAO;AAC5C,QAAM,eAAe,OAAO,sBAAsB,2BAA2B,OAAO,IAAI;AACxF,MAAI,aAAc,MAAK,qBAAqB;AAC5C,MAAI,OAAO,aAAc,MAAK,eAAe,OAAO;AACpD,MAAI,OAAO,iBAAkB,MAAK,mBAAmB,OAAO;AAC5D,MAAI,OAAO,SAAS,yBAA0B,MAAK,yBAAyB,OAAO,0BAA0B;AAC7G,MAAI,OAAO,gBAAiB,MAAK,kBAAkB,OAAO;AAC1D,MAAI,OAAO,cAAe,MAAK,gBAAgB,OAAO;AACtD,MAAI,OAAO,kBAAkB,OAAO,eAAe,SAAS,EAAG,MAAK,iBAAiB,OAAO;AAG5F,MAAI,OAAO,SAAS,eAAe,EAAE,OAAO,SAAU,OAAO,MAAkC,aAAa;AAC1G,SAAK,aAAa,EAAE,QAAQ,SAAS,qBAAqB,EAAE;AAAA,EAC9D;AACA,MAAI,OAAO,OAAO;AAChB,eAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,OAAO,KAAK,GAAG;AACvD,UAAI,gBAAgB,IAAI,GAAG,GAAG;AAC5B,gBAAQ,KAAK,mDAAmD,GAAG,8CAAyC;AAC5G;AAAA,MACF;AACA,WAAK,GAAG,IAAI;AAAA,IACd;AAAA,EACF;AACA,SAAO;AACT;;;ACxEA,IAAM,mBAAmB;AACzB,IAAM,eAAe;AAgCd,SAAS,kBAAkB,OAA6C;AAC7E,QAAM,SAAS,MAAM,UAAU;AAE/B,MAAI,WAAwC;AAC5C,MAAI,MAAM,MAAM;AACd,UAAM,aAAc,MAAM,KAAK,qBAA4C;AAC3E,QAAI,YAAY;AACd,YAAM,uBAAuB,MAAM,KAAK;AACxC,YAAM,sBAAsB,MAAM,KAAK;AACvC,iBAAW;AAAA,QACT;AAAA,QACA,aAAa;AAAA,QACb,WAAW,qBAAqB,aAAa,sBAAsB,SAAS;AAAA,QAC5E,iBAAiB,qBAAqB,oBAAoB;AAAA,QAC1D,aAAa,qBAAqB,eAAe;AAAA,QACjD,cAAc,qBAAqB,gBAAgB;AAAA,QACnD,aAAa,qBAAqB,eAAe,sBAAsB,eAAe;AAAA,QACtF,YACE,MAAM,aACF,MAAM,KAAK,cACZ,GAAG,MAAM;AAAA,MAChB;AAAA,IACF;AAAA,EACF;AAEA,QAAM,OAAqB;AAAA,IACzB,kBAAkB;AAAA,IAClB,cAAc;AAAA,IACd,MAAM,MAAM;AAAA,IACZ;AAAA,EACF;AACA,MAAI,MAAM,gBAAgB,OAAW,MAAK,cAAc,MAAM;AAC9D,MAAI,MAAM,QAAQ,OAAW,MAAK,MAAM,MAAM;AAC9C,MAAI,MAAM,iBAAiB,OAAW,MAAK,eAAe,MAAM;AAChE,MAAI,MAAM,WAAW,OAAW,MAAK,SAAS,MAAM;AACpD,SAAO;AACT;;;ACxCA,IAAM,kBAAkB;AACxB,IAAM,WAAW;AACjB,IAAM,6BAA6B;AACnC,IAAM,gCAAgC;AA2B/B,SAAS,gBAAgB,OAAyC;AACvE,QAAM,mBAAoC,CAAC,GAAI,MAAM,gBAAgB,CAAC,CAAE;AAExE,MAAI,MAAM,MAAM;AACd,UAAM,aAAa,MAAM,KAAK;AAC9B,QAAI,YAAY;AACd,YAAM,uBAAuB,MAAM,KAAK;AACxC,YAAM,sBAAsB,MAAM,KAAK;AACvC,YAAM,SAAkC;AAAA,QACtC,aAAa;AAAA,QACb,WAAW,qBAAqB,aAAa,sBAAsB,SAAS;AAAA,QAC5E,iBAAiB,qBAAqB,oBAAoB;AAAA,QAC1D,aAAa,qBAAqB,eAAe;AAAA,QACjD,cAAc,qBAAqB,gBAAgB;AAAA,QACnD,aAAa,qBAAqB,eAAe,sBAAsB,eAAe;AAAA,QACtF,YAAY,MAAM,KAAK,cAAc;AAAA,QACrC,QAAQ;AAAA,MACV;AACA,uBAAiB,KAAK;AAAA,QACpB,MAAM;AAAA,QACN,SAAS;AAAA,QACT,QAAQ,MAAM,uBAAuB;AAAA,QACrC;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AAEA,QAAM,UAAsB;AAAA,IAC1B,SAAS,MAAM,WAAW;AAAA,IAC1B,MAAM;AAAA,IACN,UAAU,MAAM;AAAA,IAChB,cAAc;AAAA,IACd,kBAAkB,MAAM,oBAAoB,CAAC;AAAA,IAC7C,cAAc,MAAM;AAAA,EACtB;AAEA,MAAI,MAAM,SAAS,OAAW,SAAQ,OAAO,MAAM;AACnD,MAAI,MAAM,OAAQ,QAAO,OAAO,SAAS,MAAM,MAAM;AAErD,SAAO;AACT;AAEO,IAAM,4BAA4B;;;AC1GlC,SAAS,oBACd,QACA,MAC8B;AAC9B,MAAI,CAAC,UAAU,CAAC,OAAO,YAAa,QAAO;AAC3C,SAAO;AAAA,IACL,QAAQ,KAAK;AAAA,IACb,GAAI,KAAK,YAAY,UAAa,EAAE,SAAS,KAAK,QAAQ;AAAA,IAC1D,GAAI,OAAO,eAAe,UAAa,EAAE,YAAY,OAAO,WAAW;AAAA,IACvE,GAAI,OAAO,0BAA0B,UAAa;AAAA,MAChD,uBAAuB,OAAO;AAAA,IAChC;AAAA,IACA,GAAI,OAAO,WAAW,UAAa,EAAE,QAAQ,OAAO,OAAO;AAAA,IAC3D,GAAI,OAAO,yBAAyB,UAAa;AAAA,MAC/C,sBAAsB,CAAC,GAAG,OAAO,oBAAoB;AAAA,IACvD;AAAA,EACF;AACF;AAoBA,eAAsB,uBACpB,aACA,SACqB;AACrB,MAAI,CAAC,WAAW,CAAC,YAAa,QAAO,EAAE,QAAQ,YAAY;AAE3D,QAAM,UAAU,MAAM,QAAQ;AAC9B,MAAI,QAAQ,GAAI,QAAO,EAAE,QAAQ,WAAW;AAE5C,MAAI,gBAAgB,QAAQ;AAC1B,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,cAAc,QAAQ;AAAA,MACtB,YAAY,QAAQ;AAAA,MACpB,GAAI,QAAQ,WAAW,UAAa,EAAE,cAAc,QAAQ,OAAO;AAAA,IACrE;AAAA,EACF;AACA,SAAO;AAAA,IACL,QAAQ;AAAA,IACR,cAAc,QAAQ;AAAA,IACtB,YAAY,QAAQ;AAAA,IACpB,GAAI,QAAQ,WAAW,UAAa,EAAE,cAAc,QAAQ,OAAO;AAAA,EACrE;AACF;AAGO,SAAS,uBAAuB,SAAiB,QAAiD;AACvG,MAAI,CAAC,QAAQ,4BAA4B,OAAO,yBAAyB,WAAW,EAAG,QAAO;AAC9F,QAAM,UAAU,IAAI,IAAI,OAAO,yBAAyB,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AACnF,SAAO,QAAQ,IAAI,QAAQ,YAAY,CAAC;AAC1C;AAQO,SAAS,qBACd,OACA,SACA,QACS;AACT,MAAI,CAAC,QAAQ,yBAAyB,OAAO,sBAAsB,WAAW,EAAG,QAAO;AACxF,MAAI,QAAQ,YAAY,MAAM,KAAM,QAAO;AAC3C,QAAM,UAAU,IAAI,IAAI,OAAO,sBAAsB,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAChF,SAAO,QAAQ,IAAI,MAAM,YAAY,CAAC;AACxC;","names":[]}
+{"version":3,"sources":["../src/_denial.ts","../src/core.ts","../src/signer.ts","../src/_response.ts","../src/identity/a2a.ts","../src/identity/ucp.ts","../src/identity/policy.ts"],"sourcesContent":["/**\n * Universal denial helpers shared across every adapter.\n *\n * What lives here:\n *   - `FIXABLE_DENIAL_REASONS` / `isFixableDenial` — classifier for compliance reasons that can\n *     be resolved by re-completing KYC (vs sanctions / age failures which are permanent).\n *   - `denialReasonStatus` — picks the right HTTP status code per denial code (401 for credential\n *     problems, 503 for transient API errors, 403 for everything else).\n *   - `buildSignerMismatchBody` — produces the standard 403 body for a `verifyWalletSignerMatch`\n *     non-pass result.\n *   - `buildContactSupportNextSteps` — standard `next_steps.action: \"contact_support\"` shape for\n *     unfixable compliance denials.\n *   - `verificationAgentInstructions` — the canned `agent_instructions` block for\n *     identity-verification 403s. Vendors can override individual fields.\n *\n * Adapters use `denialReasonStatus` inside their default `onDenied` so vendors get the right\n * status code for free. The body builders are exported from each adapter so vendors who write\n * a custom `onDenied` can compose them without copy-paste.\n */\n\nimport type { DenialReason, VerifyWalletSignerResult } from './core';\n\n/**\n * Compliance denial reasons that can be resolved by re-completing KYC. The API emits these\n * when KYC is missing/pending/failed; the user can re-verify and retry.\n *\n * `jurisdiction_restricted` is NOT in this set — the API only emits it AFTER KYC is verified,\n * meaning the user's KYC'd country is in the merchant's blocked list (or absent from the\n * allowed list). Re-doing KYC won't change the country, so it's permanent. Same shape as\n * `sanctions_flagged` and `age_insufficient` — surface contact_support, don't waste a\n * /v1/sessions mint.\n */\nexport const FIXABLE_DENIAL_REASONS: ReadonlySet<string> = new Set([\n  'kyc_required',\n  'kyc_pending',\n  'kyc_failed',\n]);\n\n/**\n * Returns true when a `wallet_not_trusted` denial's reasons are all fixable via KYC\n * re-verification. False when any reason is permanent (sanctions, age, jurisdiction_restricted).\n *\n * Empty reasons returns false — without a known reason we can't promise a fix, so default to\n * the bare denial path (vendors can override via custom onDenied if they want different\n * behavior on empty reasons).\n */\nexport function isFixableDenial(reasons: readonly string[] | undefined): boolean {\n  if (!reasons || reasons.length === 0) return false;\n  return reasons.every((r) => FIXABLE_DENIAL_REASONS.has(r));\n}\n\n/**\n * The right HTTP status code for a denial. `defaultOnDenied` in every adapter uses this so\n * vendors get correct status codes without writing per-code branches.\n *\n *   - 401 for credential problems the agent can recover from (`token_expired`, `invalid_credential`)\n *   - 503 for transient `api_error`\n *   - 403 for everything else (identity required, compliance fail, signer mismatch, etc.)\n */\nexport function denialReasonStatus(reason: DenialReason): 401 | 403 | 503 {\n  if (reason.code === 'token_expired' || reason.code === 'invalid_credential') return 401;\n  if (reason.code === 'api_error') return 503;\n  return 403;\n}\n\nexport interface SignerMismatchBodyInput {\n  /** Result from `verifyWalletSignerMatch`. The function only emits a body for non-pass results. */\n  result: VerifyWalletSignerResult;\n  /** Optional override for the human-facing `next_steps.user_message`. */\n  userMessage?: string;\n  /** Optional override for `next_steps.learn_more_url`. Default: AgentScore agent-identity guide. */\n  learnMoreUrl?: string;\n}\n\n/**\n * Standard 403 body for a non-pass `verifyWalletSignerMatch` result. Returns null for `pass` /\n * `api_error` so vendors can call it unconditionally:\n *\n *   const result = await verifyWalletSignerMatch(c);\n *   const mismatchBody = buildSignerMismatchBody({ result });\n *   if (mismatchBody) return c.json(mismatchBody, 403);\n *\n * Body shape mirrors the gate's denial bodies: top-level error.code, all signer-match fields\n * (`claimed_operator`, `actual_signer_operator`, `expected_signer`, `actual_signer`,\n * `linked_wallets`), plus a `next_steps` action describing the recovery path.\n */\nexport function buildSignerMismatchBody(input: SignerMismatchBodyInput): Record<string, unknown> | null {\n  const { result } = input;\n  if (result.kind === 'pass' || result.kind === 'api_error') return null;\n\n  const learnMoreUrl = input.learnMoreUrl ?? 'https://docs.agentscore.sh/guides/agent-identity';\n\n  if (result.kind === 'wallet_signer_mismatch') {\n    const linkedWallets = result.linkedWallets ?? [];\n    const userMessage = input.userMessage ?? (linkedWallets.length > 0\n      ? `Sign the payment with one of the wallets linked to this operator: ${linkedWallets.join(', ')}. Then retry.`\n      : 'Sign the payment with the same wallet you claimed via X-Wallet-Address, or switch to X-Operator-Token for rail-independent identity.');\n    return {\n      error: {\n        code: 'wallet_signer_mismatch',\n        message:\n          'Payment signer does not match the wallet claimed via X-Wallet-Address. The signer and the claimed wallet must both resolve to the same AgentScore operator.',\n      },\n      claimed_operator: result.claimedOperator,\n      actual_signer_operator: result.actualSignerOperator ?? null,\n      expected_signer: result.expectedSigner,\n      actual_signer: result.actualSigner,\n      linked_wallets: linkedWallets,\n      next_steps: {\n        action: 'regenerate_payment_from_linked_wallet',\n        user_message: userMessage,\n        learn_more_url: learnMoreUrl,\n      },\n    };\n  }\n\n  // wallet_auth_requires_wallet_signing\n  return {\n    error: {\n      code: 'wallet_auth_requires_wallet_signing',\n      message:\n        'Wallet-auth requires a payment rail that carries a wallet signature (Tempo MPP, x402). Stripe SPT and card rails have no wallet signer; switch to X-Operator-Token to use those.',\n    },\n    next_steps: {\n      action: 'switch_to_operator_token',\n      user_message:\n        input.userMessage ??\n        'Drop the X-Wallet-Address header and retry with X-Operator-Token (works on every payment rail).',\n      learn_more_url: learnMoreUrl,\n    },\n  };\n}\n\n/**\n * Standard `next_steps` block for unfixable compliance denials (sanctions, age, etc.). Vendors\n * spread this into a 403 body alongside the usual `error`/`reasons` fields.\n *\n *   return c.json({\n *     error: { code: 'compliance_denied', message: '...' },\n *     reasons,\n *     next_steps: buildContactSupportNextSteps('support@martinestate.com'),\n *   }, 403);\n */\nexport function buildContactSupportNextSteps(\n  supportEmail: string,\n  message?: string,\n): { action: 'contact_support'; support_email: string; user_message: string } {\n  return {\n    action: 'contact_support',\n    support_email: supportEmail,\n    user_message:\n      message ??\n      `If you believe this denial is in error, contact support at ${supportEmail} with your order details.`,\n  };\n}\n\nexport interface VerificationAgentInstructionsInput {\n  /** Override the user-facing message. */\n  userAction?: string;\n  /** Replace the generic \"Retry the original merchant request...\" step with a merchant-specific\n   *  one (e.g. \"Retry POST /purchase with X-Operator-Token AND include order_id...\"). When set,\n   *  this REPLACES baseSteps[4] rather than appending — use it instead of `extraSteps[0]` when\n   *  your retry instruction is a refinement of the canonical retry, not an additional step. */\n  retryStep?: string;\n  /** Append additional steps after the retry step. Use this for genuinely additional steps\n   *  (e.g. \"After payment the same call returns 200 with the order\"), not for re-stating the\n   *  retry — use `retryStep` for that. */\n  extraSteps?: string[];\n  /** Override the poll cadence. Default 5 seconds. */\n  pollIntervalSeconds?: number;\n  /** Override how long the agent should keep polling. Default 3600 seconds (1 hour). */\n  timeoutSeconds?: number;\n  /** Optional `order_ttl` note describing how long pending orders survive. */\n  orderTtl?: string;\n  /** Arbitrary additional fields merged into the instructions object. */\n  extra?: Record<string, unknown>;\n}\n\n/**\n * The canonical `agent_instructions` block for identity-verification 403s. Tells the agent how to\n * present the verify_url, poll for the operator_token, and retry the original request. Universal\n * across every AgentScore-gated merchant — overrides let vendors add merchant-specific steps\n * (e.g. \"include order_id when retrying\").\n */\nexport function verificationAgentInstructions(input: VerificationAgentInstructionsInput = {}): {\n  action: 'poll_for_credential';\n  user_action: string;\n  steps: string[];\n  poll_interval_seconds: number;\n  poll_secret_header: 'X-Poll-Secret';\n  retry_token_header: 'X-Operator-Token';\n  timeout_seconds: number;\n  order_ttl?: string;\n  [key: string]: unknown;\n} {\n  const baseSteps = [\n    'Present the verify_url directly to the user — it is a complete, ready-to-open URL with the session token already embedded (e.g. https://agentscore.sh/verify?session=sess_...). Do NOT modify or construct the URL yourself.',\n    `Immediately begin polling poll_url every ${input.pollIntervalSeconds ?? 5} seconds with header X-Poll-Secret set to poll_secret. The user will complete verification in their browser while you poll in the background.`,\n    'The user visits the URL, signs in, completes identity verification (photo ID + selfie via Stripe Identity), and closes the tab. They do NOT need to copy or paste anything back to you.',\n    'When your poll returns status \"verified\", extract operator_token from the response. This is a one-time value — save it immediately. Subsequent polls return status \"consumed\" without the token.',\n    input.retryStep ?? 'Retry the original merchant request with header X-Operator-Token set to the operator_token value.',\n  ];\n\n  return {\n    action: 'poll_for_credential',\n    user_action:\n      input.userAction ??\n      'The user must visit verify_url to complete identity verification before this request can proceed',\n    steps: input.extraSteps ? [...baseSteps, ...input.extraSteps] : baseSteps,\n    poll_interval_seconds: input.pollIntervalSeconds ?? 5,\n    poll_secret_header: 'X-Poll-Secret',\n    retry_token_header: 'X-Operator-Token',\n    timeout_seconds: input.timeoutSeconds ?? 3600,\n    ...(input.orderTtl ? { order_ttl: input.orderTtl } : {}),\n    ...(input.extra ?? {}),\n  };\n}\n","import { isFixableDenial } from './_denial';\nimport { normalizeAddress } from './address';\nimport { TTLCache } from './cache';\n\n// Character-based trim avoids a CodeQL polynomial-redos false positive on\n// `/\\/+$/` patterns that report library-input strings.\nfunction stripTrailingSlashes(s: string): string {\n  let end = s.length;\n  while (end > 0 && s.charCodeAt(end - 1) === 47 /* '/' */) end--;\n  return end === s.length ? s : s.slice(0, end);\n}\n\ndeclare const __VERSION__: string;\n\n// ---------------------------------------------------------------------------\n// Public types (framework-agnostic)\n// ---------------------------------------------------------------------------\n\nexport interface AgentIdentity {\n  address?: string;\n  operatorToken?: string;\n}\n\n/**\n * Session metadata returned from `POST /v1/sessions`. Surfaced to the `onBeforeSession`\n * hook so merchants can correlate an AgentScore session with their own resume token\n * (e.g. a pending-order id).\n */\nexport interface SessionMetadata {\n  session_id: string;\n  verify_url: string;\n  poll_secret: string;\n  poll_url: string;\n  expires_at?: string;\n}\n\n/**\n * Configuration for auto-creating a verification session when no identity is present.\n *\n * The static `context` / `productName` options are sent on every session request. For\n * per-request context (e.g. the specific product the agent was trying to buy), pass\n * a `getSessionOptions` callback that returns dynamic values; its return is merged\n * over the static defaults.\n *\n * `onBeforeSession` is a side-effect hook that runs after the session is minted but\n * before the 403 is built. Use it to pre-create a reservation/draft/pending-order\n * row in your DB so agents can resume via a merchant-specific id. Return value is\n * merged into `DenialReason.extra`, so it surfaces in both the default 403 body and\n * in a custom `onDenied` handler.\n */\nexport interface CreateSessionOnMissing<TCtx = unknown> {\n  apiKey: string;\n  baseUrl?: string;\n  context?: string;\n  productName?: string;\n  /** Per-request override of `context` / `productName`. Invoked with the framework context. */\n  getSessionOptions?: (ctx: TCtx) => Promise<{ context?: string; productName?: string }>\n                                  |          { context?: string; productName?: string };\n  /** Side-effect hook that runs after the session is minted. Return value is merged\n   *  into `DenialReason.extra` so custom `onDenied` handlers can include merchant-specific\n   *  fields (e.g. `order_id`) in the 403 response. Hook errors are logged and swallowed —\n   *  a failing side effect should not block the 403 from reaching the agent. */\n  onBeforeSession?: (ctx: TCtx, session: SessionMetadata) => Promise<Record<string, unknown>>\n                                                          |          Record<string, unknown>;\n}\n\nexport interface AgentScoreCoreOptions {\n  /** AgentScore API key. Required. */\n  apiKey: string;\n  /** Require KYC verification. */\n  requireKyc?: boolean;\n  /** Require operator to be clear of sanctions. */\n  requireSanctionsClear?: boolean;\n  /** Minimum operator age bracket (18 or 21). */\n  minAge?: number;\n  /** List of blocked jurisdictions (blocklist). */\n  blockedJurisdictions?: string[];\n  /** List of allowed jurisdictions (allowlist — only these pass). */\n  allowedJurisdictions?: string[];\n  /** If true, allow the request through when the API is unreachable. Defaults to false. */\n  failOpen?: boolean;\n  /** How long to cache results, in seconds. Defaults to 300. */\n  cacheSeconds?: number;\n  /** AgentScore API base URL. Defaults to \"https://api.agentscore.sh\". */\n  baseUrl?: string;\n  /** Optional chain to filter scoring to. */\n  chain?: string;\n  /** Prepended to the default User-Agent as `\"{userAgent} (@agent-score/commerce@{version})\"`. Use to attribute API calls to your app. */\n  userAgent?: string;\n  /** When set and no identity is found, create a verification session instead of denying immediately. */\n  createSessionOnMissing?: CreateSessionOnMissing;\n}\n\nexport type DenialCode =\n  | 'wallet_not_trusted'\n  | 'missing_identity'\n  | 'api_error'\n  | 'payment_required'\n  | 'identity_verification_required'\n  // Wallet-signer binding: claimed X-Wallet-Address must resolve to the same operator as\n  // the payment signer; wallet-auth is rejected on rails with no wallet signer.\n  | 'wallet_signer_mismatch'\n  | 'wallet_auth_requires_wallet_signing'\n  // Granular credential-state denials passed through from /v1/assess.\n  // - `token_expired`: revoked + TTL-expired (the API unifies these). The 401 body carries\n  //   an auto-minted session, forwarded into DenialReason for one-shot recovery.\n  // - `invalid_credential`: the token doesn't exist at all (typo, never minted, fabricated).\n  //   No auto-session is minted by the API for this case — agents should switch to a\n  //   different stored token or drop the header to bootstrap a fresh session.\n  | 'token_expired'\n  | 'invalid_credential';\n\n/**\n * Cross-merchant pattern hint emitted on bootstrap denials and session-create responses.\n * LLM-hosted agents should persist this to long-term memory so future AgentScore encounters skip\n * the cold-start session flow. Contents are the pattern, not secrets.\n */\nexport interface AgentMemoryHint {\n  save_for_future_agentscore_gates: true;\n  pattern_summary: string;\n  quickstart: string;\n  identity_check_endpoint: string;\n  list_wallets_endpoint?: string;\n  identity_paths: { wallet: string; operator_token: string };\n  bootstrap: string;\n  do_not_persist_in_memory: string[];\n  persist_in_credential_store: string[];\n}\n\nexport interface DenialReason {\n  code: DenialCode;\n  /** Human-readable explanation. When omitted, `denialReasonToBody` substitutes a per-code default. */\n  message?: string;\n  decision?: string;\n  reasons?: string[];\n  verify_url?: string;\n  session_id?: string;\n  poll_secret?: string;\n  poll_url?: string;\n  agent_instructions?: string;\n  /** Cross-merchant memory hint. Emitted on bootstrap denials only by default. */\n  agent_memory?: AgentMemoryHint;\n  /** Full assess response when the denial came from `/v1/assess`. Lets consumers access fields\n   *  not promoted to first-class DenialReason properties (e.g., `policy_result`). Undefined for\n   *  denials that did not originate from an assess call (missing_identity, api_error,\n   *  payment_required, identity_verification_required). */\n  data?: AgentScoreData;\n  /** Extra fields returned from the `createSessionOnMissing.onBeforeSession` hook. Merged\n   *  into the default 403 body; custom `onDenied` handlers can spread these into their own\n   *  response shape (e.g. to include a merchant-minted `order_id`). */\n  extra?: Record<string, unknown>;\n  // ---------------------------------------------------------------------------\n  // Wallet-signer-match fields — populated for wallet_signer_mismatch only.\n  // ---------------------------------------------------------------------------\n  /** Operator id resolved from `X-Wallet-Address`. */\n  claimed_operator?: string;\n  /** Operator id the actual payment signer resolves to. `null` when the signer wallet isn't\n   *  linked to any operator (treat as a different identity). */\n  actual_signer_operator?: string | null;\n  /** The wallet the agent claimed via header. Echoed back for self-correction. */\n  expected_signer?: string;\n  /** The wallet that actually signed the payment. */\n  actual_signer?: string;\n  /** Wallets the claimed operator could sign with (if enumerable). Present when non-empty. */\n  linked_wallets?: string[];\n}\n\nexport interface AgentScoreData {\n  decision: string | null;\n  decision_reasons: string[];\n  identity_method?: string;\n  operator_verification?: {\n    level: string;\n    operator_type: string | null;\n    verified_at: string | null;\n  };\n  /** Account-level KYC facts that apply to every operator under the same account.\n   *  Populated when the API returns account_verification (post-KYC operator). */\n  account_verification?: {\n    kyc_level?: string;\n    sanctions_clear?: boolean;\n    age_bracket?: string;\n    jurisdiction?: string;\n    verified_at?: string | null;\n  };\n  resolved_operator?: string | null;\n  /** Wallets linked to the same operator as the resolved identity. Capped at 100 entries\n   *  by the API. Useful for advertising in 402 challenges so wallet-auth agents know which\n   *  alt-signers will satisfy `wallet_signer_mismatch`. */\n  linked_wallets?: string[];\n  verify_url?: string;\n  policy_result?: {\n    all_passed: boolean;\n    checks: Array<{\n      rule: string;\n      passed: boolean;\n      required?: unknown;\n      actual?: unknown;\n    }>;\n  } | null;\n}\n\n/**\n * Outcome from `AgentScoreCore.evaluate()`. Adapters map this to framework-specific responses.\n *\n * - `{ kind: 'allow', data }` — the request passed the policy. `data` is present on a normal\n *   allow; `undefined` when fail-open short-circuited (identity missing, API unreachable,\n *   timeout, or 402 paid-tier required).\n * - `{ kind: 'deny', reason }` — the request was denied. Adapters should render a 403 with the\n *   reason, or invoke the caller's custom denial handler.\n */\nexport type EvaluateOutcome =\n  | { kind: 'allow'; data?: AgentScoreData }\n  | { kind: 'deny'; reason: DenialReason };\n\nexport interface CaptureWalletOptions {\n  /** Operator credential (`opc_...`) that the agent authenticated with. */\n  operatorToken: string;\n  /** Signer wallet recovered from the payment payload. */\n  walletAddress: string;\n  /** Key-derivation family — `\"evm\"` for any EVM chain, `\"solana\"` for Solana. */\n  network: 'evm' | 'solana';\n  /** Optional stable key for the logical payment (e.g., payment intent id, tx hash). When the\n   *  same key is seen again for the same (credential, wallet, network), the server no-ops —\n   *  prevents agent retries from inflating transaction_count. */\n  idempotencyKey?: string;\n}\n\nexport interface VerifyWalletSignerMatchOptions {\n  /** The wallet claimed via `X-Wallet-Address`. */\n  claimedWallet: string;\n  /** The signer wallet recovered from the payment credential. `null` means the rail carries\n   *  no wallet signer (SPT, card) — the helper returns `wallet_auth_requires_wallet_signing`. */\n  signer: string | null;\n  /** Network of the signer. EVM covers every EVM chain; `solana` lives in its own namespace. */\n  network?: 'evm' | 'solana';\n}\n\nexport type VerifyWalletSignerResult =\n  | { kind: 'pass'; claimedOperator: string | null; signerOperator: string | null }\n  | {\n      kind: 'wallet_signer_mismatch';\n      claimedOperator: string | null;\n      actualSignerOperator: string | null;\n      expectedSigner: string;\n      actualSigner: string;\n      linkedWallets: string[];\n      /** JSON-encoded action copy (action + steps + user_message). Spread into the 403 body\n       *  verbatim so agents get a concrete recovery path inside the denial response itself. */\n      agentInstructions: string;\n    }\n  | {\n      kind: 'wallet_auth_requires_wallet_signing';\n      claimedWallet: string;\n      agentInstructions: string;\n    }\n  // Transient — the resolve call to /v1/assess failed or timed out. Caller should\n  // retry or surface as 503. Distinct from wallet_signer_mismatch (which is an actual\n  // security reject) so legitimate users don't get rejected on network flakes.\n  | { kind: 'api_error'; claimedWallet: string };\n\nexport interface AgentScoreCore {\n  /**\n   * Evaluate the request's identity against the configured policy.\n   * @param identity - extracted identity (wallet address and/or operator token)\n   * @param ctx - optional framework-specific context (Hono c, Express req, etc.) passed\n   *   through to `createSessionOnMissing` hooks. Opaque to core.\n   */\n  evaluate(identity: AgentIdentity | undefined, ctx?: unknown): Promise<EvaluateOutcome>;\n  /** Report a wallet seen paying under an operator credential. Fire-and-forget; silently\n   *  swallows non-fatal errors because capture is informational, not on the critical path. */\n  captureWallet(options: CaptureWalletOptions): Promise<void>;\n  /**\n   * Verify the payment signer resolves to the same operator as the claimed `X-Wallet-Address`.\n   *\n   * Returns `pass` when the signer is linked to the same operator as the claimed wallet\n   * (byte-equal wallets pass trivially; other wallets linked to the same operator also pass —\n   * multi-wallet agents work without ergonomic pain). Returns `wallet_signer_mismatch` when\n   * the signer resolves to a different (or no) operator. Returns `wallet_auth_requires_wallet_signing`\n   * when the signer is `null` (SPT, card — rails that carry no wallet signature).\n   *\n   * Call this AFTER the gate evaluates (so the claimed wallet's operator is cached) and\n   * AFTER the payment credential is parsed (so the signer is known). Merchants should call\n   * it before settling payment.\n   */\n  verifyWalletSignerMatch(options: VerifyWalletSignerMatchOptions): Promise<VerifyWalletSignerResult>;\n}\n\n// ---------------------------------------------------------------------------\n// Internal types\n// ---------------------------------------------------------------------------\n\ninterface AssessResult {\n  allow: boolean;\n  decision?: string;\n  reasons?: string[];\n  raw?: unknown;\n}\n\n/**\n * Build the cross-merchant memory hint emitted on bootstrap denials. Base URLs are\n * derived from the gate's AgentScore API base so self-hosted / staging deployments get\n * correct pointers. Contents describe the AgentScore identity substrate in transferable\n * terms; merchant-specific context lives in other `agent_instructions` fields.\n */\n// Canonical production AgentScore API — used as the authoritative source for endpoint pointers\n// emitted to agent memory regardless of how a given merchant configured their gate's baseUrl.\n// Hardcoded so a malicious merchant can't set `baseUrl: \"evil.com\"` and phish agents into\n// sending their credentials to attacker-controlled endpoints.\nconst CANONICAL_AGENTSCORE_API = 'https://api.agentscore.sh';\n\n// JSON-encoded action copy emitted on wallet-signer-match denials. Spread into 403 bodies\n// by merchants so agents get a concrete recovery path inside the denial response itself —\n// no discovery-doc round trip required.\nconst WALLET_SIGNER_MISMATCH_INSTRUCTIONS = JSON.stringify({\n  action: 'resign_or_switch_to_operator_token',\n  steps: [\n    'Preferred: re-submit the payment signed by expected_signer (or any entry in linked_wallets — same-operator wallets are fungible) and retry with the same X-Wallet-Address.',\n    'Alternative: drop X-Wallet-Address and retry with X-Operator-Token. Use a stored opc_... if you have one; otherwise retry this request with NO identity header — the merchant will mint a verification session in the 403 body (verify_url + poll_secret). Share verify_url with the user, poll, receive a fresh opc_...',\n  ],\n  user_message:\n    'The payment signer resolves to a different operator than X-Wallet-Address. Re-sign from expected_signer or any linked_wallets entry, or switch to X-Operator-Token.',\n});\n\nconst WALLET_AUTH_REQUIRES_WALLET_SIGNING_INSTRUCTIONS = JSON.stringify({\n  action: 'switch_to_operator_token',\n  steps: [\n    'This payment rail (Stripe SPT, card) carries no wallet signature — X-Wallet-Address cannot be verified against the payment.',\n    'Drop X-Wallet-Address and retry with X-Operator-Token. If you do not have a stored opc_..., retry with no identity header to receive a verification session.',\n  ],\n  user_message:\n    'Wallet-address identity is only supported on wallet-signing rails (Tempo MPP, x402). On Stripe or card, use X-Operator-Token instead.',\n});\n\n// `invalid_credential` is permanent — the token doesn't exist (typo, never minted, fabricated).\n// Distinct from `token_expired` (which carries an auto-session for one-shot recovery): the\n// API doesn't auto-mint a session here because the client may simply have a different valid\n// token to try. Agents should switch tokens or drop the header to bootstrap a session.\nconst INVALID_CREDENTIAL_INSTRUCTIONS = JSON.stringify({\n  action: 'switch_token_or_restart_session',\n  steps: [\n    'The X-Operator-Token you sent does not match any credential. This is a permanent state — retrying with the same token will keep failing.',\n    'If you have other stored opc_... credentials, retry with one of them.',\n    'Otherwise drop X-Operator-Token and retry with no identity header — the merchant will mint a fresh verification session in the 403 body (verify_url + poll_secret) so the user can re-verify and you can poll for a new operator_token.',\n  ],\n  user_message:\n    'The operator_token is not recognized. Use a different stored token, or restart the verification session flow to mint a new one.',\n});\n\nexport function buildAgentMemoryHint(): AgentMemoryHint {\n  // Memory pointers always point at the canonical production API — merchants must not be\n  // able to redirect the cross-merchant memory surface, since that would be a phishing\n  // vector for the verify URL.\n  const api = CANONICAL_AGENTSCORE_API;\n  return {\n    save_for_future_agentscore_gates: true,\n    pattern_summary:\n      'AgentScore is a cross-merchant identity substrate for agent commerce. Any endpoint that ' +\n      'returns 403 missing_identity / identity_verification_required or 402 challenges referencing AgentScore uses ' +\n      'the same identity system. One KYC works across all AgentScore merchants — no re-verification ' +\n      'per site. Save this pattern (and the endpoints below) to persistent memory so future ' +\n      'AgentScore encounters skip the cold-start session flow.',\n    quickstart: 'https://docs.agentscore.sh/guides/agent-identity',\n    identity_check_endpoint: `${api}/v1/credentials`,\n    identity_paths: {\n      wallet:\n        'If paying from a crypto wallet you have used before on any AgentScore merchant, send ' +\n        '`X-Wallet-Address: 0x...`. Shortest path; no token lifecycle to manage.',\n      operator_token:\n        'For any rail (Stripe SPT, card, or a wallet you have not linked yet), send ' +\n        '`X-Operator-Token: opc_...`. Reusable across merchants until the token expires.',\n    },\n    bootstrap:\n      'If you have neither a linked wallet nor a valid operator_token, follow the session/verify ' +\n      'flow in the per-request `agent_instructions` block. This happens at most once per agent ' +\n      'identity — after first verification, the operator_token and any subsequently used wallet ' +\n      'are reusable everywhere.',\n    do_not_persist_in_memory: ['operator_token', 'poll_secret'],\n    persist_in_credential_store: ['operator_token'],\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Core factory\n// ---------------------------------------------------------------------------\n\nexport function createAgentScoreCore(options: AgentScoreCoreOptions): AgentScoreCore {\n  if (!options.apiKey) {\n    throw new Error('AgentScore API key is required. Get one at https://agentscore.sh/sign-up');\n  }\n\n  const {\n    apiKey,\n    requireKyc,\n    requireSanctionsClear,\n    minAge,\n    blockedJurisdictions,\n    allowedJurisdictions,\n    failOpen = false,\n    cacheSeconds = 300,\n    baseUrl: rawBaseUrl = 'https://api.agentscore.sh',\n    chain: gateChain,\n    userAgent,\n    createSessionOnMissing,\n  } = options;\n\n  const baseUrl = stripTrailingSlashes(rawBaseUrl);\n  const agentMemoryHint = buildAgentMemoryHint();\n\n  const defaultUa = `@agent-score/commerce@${__VERSION__}`;\n  const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;\n\n  const API_TIMEOUT_MS = 10_000;\n\n  const cache = new TTLCache<AssessResult>(cacheSeconds * 1000);\n\n  // Mint a verification session via /v1/sessions and return the resulting\n  // identity_verification_required DenialReason — or undefined if the mint failed (network\n  // error, non-2xx, missing fields). Used for both the missing-identity path and the\n  // fixable-wallet bootstrap path: in both cases the UX is identical (agent polls the\n  // returned poll_url until it gets a fresh opc_... and retries).\n  async function tryMintSessionDenial(ctx: unknown): Promise<DenialReason | undefined> {\n    if (!createSessionOnMissing) return undefined;\n    try {\n      const sessionBody: { context?: string; product_name?: string } = {};\n      if (createSessionOnMissing.context != null) sessionBody.context = createSessionOnMissing.context;\n      if (createSessionOnMissing.productName != null) sessionBody.product_name = createSessionOnMissing.productName;\n\n      if (createSessionOnMissing.getSessionOptions && ctx !== undefined) {\n        try {\n          const dynamic = await createSessionOnMissing.getSessionOptions(ctx);\n          if (dynamic?.context != null) sessionBody.context = dynamic.context;\n          if (dynamic?.productName != null) sessionBody.product_name = dynamic.productName;\n        } catch (err) {\n          console.warn('[gate] createSessionOnMissing.getSessionOptions hook failed:', err instanceof Error ? err.message : err);\n        }\n      }\n\n      const sessionBaseUrl = stripTrailingSlashes(createSessionOnMissing.baseUrl ?? 'https://api.agentscore.sh');\n      const sessionRes = await fetch(`${sessionBaseUrl}/v1/sessions`, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': createSessionOnMissing.apiKey,\n          'Content-Type': 'application/json',\n          Accept: 'application/json',\n          'User-Agent': userAgentHeader,\n        },\n        body: JSON.stringify(sessionBody),\n        signal: AbortSignal.timeout(API_TIMEOUT_MS),\n      });\n\n      if (!sessionRes.ok) return undefined;\n      const data = (await sessionRes.json()) as Record<string, unknown>;\n\n      // Validate required fields before trusting the response. A misbehaving (or mocked-wrong)\n      // API could 200 without session_id/poll_secret/verify_url, which would propagate\n      // `undefined` into the 403 body and leave the agent stuck — treat as session-create\n      // failure and fall back to the caller's bare denial.\n      if (\n        typeof data.session_id !== 'string' ||\n        typeof data.poll_secret !== 'string' ||\n        typeof data.verify_url !== 'string'\n      ) {\n        console.warn('[gate] /v1/sessions returned 200 without required fields — falling back to bare denial');\n        return undefined;\n      }\n\n      // Run onBeforeSession side-effect hook. Errors are swallowed — a failing DB write\n      // (e.g. can't insert pending order) should not block the 403.\n      let extra: Record<string, unknown> | undefined;\n      if (createSessionOnMissing.onBeforeSession && ctx !== undefined) {\n        try {\n          const sessionMeta = {\n            session_id: data.session_id as string,\n            verify_url: data.verify_url as string,\n            poll_secret: data.poll_secret as string,\n            poll_url: data.poll_url as string,\n            expires_at: data.expires_at as string | undefined,\n          };\n          const result = await createSessionOnMissing.onBeforeSession(ctx, sessionMeta);\n          if (result && typeof result === 'object') extra = result;\n        } catch (err) {\n          console.warn('[gate] createSessionOnMissing.onBeforeSession hook failed:', err instanceof Error ? err.message : err);\n        }\n      }\n\n      // The API emits `next_steps` (structured object) on /v1/sessions success. Stringify it\n      // into the gate's `agent_instructions` contract so merchants get the same JSON-encoded\n      // {action, steps, user_message} envelope as every other gate-emitted denial.\n      const apiNextSteps = data.next_steps as Record<string, unknown> | undefined;\n      return {\n        code: 'identity_verification_required',\n        verify_url: data.verify_url as string,\n        session_id: data.session_id as string,\n        poll_secret: data.poll_secret as string,\n        poll_url: data.poll_url as string | undefined,\n        agent_instructions: apiNextSteps ? JSON.stringify(apiNextSteps) : undefined,\n        agent_memory: agentMemoryHint,\n        ...(extra && { extra }),\n      };\n    } catch (err) {\n      // Session-mint failed (network, /v1/sessions returned non-2xx, body parse error,\n      // onBeforeSession threw inside the inner try). Caller falls back to a bare denial —\n      // agents still get a 403 with a probe-strategy hint. Log loudly so a persistent\n      // /v1/sessions outage isn't masked.\n      console.warn('[gate] createSessionOnMissing path failed — falling back to bare denial:', err instanceof Error ? err.message : err);\n      return undefined;\n    }\n  }\n\n  async function evaluate(identity: AgentIdentity | undefined, ctx?: unknown): Promise<EvaluateOutcome> {\n    // Treat \"returned identity object with no usable fields\" the same as \"no identity at all\" —\n    // otherwise a misbehaving custom extractIdentity would send an empty body to /v1/assess.\n    if (!identity || (!identity.address && !identity.operatorToken)) {\n      if (failOpen) return { kind: 'allow' };\n\n      const sessionReason = await tryMintSessionDenial(ctx);\n      if (sessionReason) return { kind: 'deny', reason: sessionReason };\n\n      // Bare missing-identity denial (no session was auto-created). Describe the probe\n      // strategy so agents without memory can recover: try wallet first on signing rails,\n      // fall back to stored opc_..., fall back to session flow (noting that only\n      // auto-session merchants return verify_url + poll data on the retry).\n      const missingIdentityInstructions = JSON.stringify({\n        action: 'probe_identity_then_session',\n        steps: [\n          'If you have a wallet AND this merchant accepts a wallet-signing rail (Tempo MPP or x402 — see openapi.json x-payment-info): send X-Wallet-Address and retry. If the wallet is already linked to an AgentScore operator (via prior SIWE claim or prior captureWallet), this passes in one round trip. If the wallet is unlinked or the account has no KYC, the 403 will include a verify_url — share it with the user to claim the wallet + complete KYC, then retry.',\n          'If step 1 is denied or you already have a stored operator_token (valid + not expired): send X-Operator-Token: opc_... and retry.',\n          'If neither applies: retry with NO identity header. Merchants that auto-create verification sessions (most AgentScore merchants do) return verify_url + session_id + poll_secret in the 403 body — share verify_url with the user, then poll poll_url every 5s with the X-Poll-Secret header until status=verified (the poll returns a one-time operator_token). If the retry returns the same bare 403, this merchant does not support self-service session bootstrapping — direct the user to https://agentscore.sh/sign-up to create an AgentScore identity and mint an operator_token from their dashboard (https://agentscore.sh/dashboard/verify). The user hands the opc_... to you, and you retry with X-Operator-Token.',\n        ],\n        user_message:\n          'Try X-Wallet-Address first if you have a wallet and the merchant accepts Tempo/x402; fall back to a stored X-Operator-Token, then to the session/verify flow described in agent_memory.bootstrap.',\n      });\n      return {\n        kind: 'deny',\n        reason: {\n          code: 'missing_identity',\n          agent_instructions: missingIdentityInstructions,\n          agent_memory: agentMemoryHint,\n        },\n      };\n    }\n\n    // operator_token is opaque + ASCII-only — lowercasing is safe. Wallet addresses go\n    // through normalizeAddress because Solana base58 is case-sensitive and lowercasing\n    // would corrupt the cache key (a Solana cache miss every time, plus collision risk\n    // with mixed-case variants of the same operator).\n    const cacheKey = identity.operatorToken?.toLowerCase() ?? (identity.address ? normalizeAddress(identity.address) : '');\n\n    const cached = cache.get(cacheKey);\n    if (cached) {\n      if (cached.allow) {\n        return { kind: 'allow', data: cached.raw as AgentScoreData };\n      }\n      // Fixable compliance denials (kyc_required, kyc_pending, kyc_failed) get the\n      // same UX as missing_identity: mint a fresh verification session, agent polls\n      // until status=verified, gets a fresh opc_..., retries. Unfixable reasons\n      // (sanctions_flagged, age_insufficient, jurisdiction_restricted) keep the bare\n      // wallet_not_trusted denial. `jurisdiction_restricted` is unfixable: the API\n      // only emits it after KYC is verified (the user's KYC'd country is in the\n      // blocked list — re-doing KYC won't change the country).\n      if (isFixableDenial(cached.reasons)) {\n        const sessionReason = await tryMintSessionDenial(ctx);\n        if (sessionReason) return { kind: 'deny', reason: sessionReason };\n      }\n      return {\n        kind: 'deny',\n        reason: {\n          code: 'wallet_not_trusted',\n          decision: cached.decision,\n          reasons: cached.reasons,\n          verify_url: (cached.raw as Record<string, unknown> | undefined)?.verify_url as string | undefined,\n          data: cached.raw as AgentScoreData | undefined,\n        },\n      };\n    }\n\n    try {\n      const body: Record<string, unknown> = {};\n      if (identity.address) body.address = identity.address;\n      if (identity.operatorToken) body.operator_token = identity.operatorToken;\n      if (gateChain) body.chain = gateChain;\n\n      const policy: Record<string, unknown> = {};\n      if (requireKyc != null) policy.require_kyc = requireKyc;\n      if (requireSanctionsClear != null) policy.require_sanctions_clear = requireSanctionsClear;\n      if (minAge != null) policy.min_age = minAge;\n      if (blockedJurisdictions != null) policy.blocked_jurisdictions = blockedJurisdictions;\n      if (allowedJurisdictions != null) policy.allowed_jurisdictions = allowedJurisdictions;\n      if (Object.keys(policy).length > 0) body.policy = policy;\n\n      const response = await fetch(`${baseUrl}/v1/assess`, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': apiKey,\n          'Content-Type': 'application/json',\n          Accept: 'application/json',\n          'User-Agent': userAgentHeader,\n        },\n        body: JSON.stringify(body),\n        signal: AbortSignal.timeout(API_TIMEOUT_MS),\n      });\n\n      if (response.status === 402) {\n        if (failOpen) return { kind: 'allow' };\n        return { kind: 'deny', reason: { code: 'payment_required' } };\n      }\n\n      // Pass through the API's token_expired 401 (covers both expired and revoked\n      // credentials — the API deliberately doesn't distinguish). The 401 body carries\n      // an auto-minted session (verify_url + session_id + poll_secret + next_steps +\n      // agent_memory) so agents can recover without holding an API key. Forward all of\n      // that into the DenialReason so the gate's 403 body includes the session fields.\n      if (response.status === 401) {\n        try {\n          const errData = (await response.clone().json()) as {\n            error?: { code?: string };\n            session_id?: unknown;\n            poll_secret?: unknown;\n            verify_url?: unknown;\n            poll_url?: unknown;\n            next_steps?: unknown;\n            agent_memory?: unknown;\n          };\n          const code = errData?.error?.code;\n          if (code === 'token_expired') {\n            return {\n              kind: 'deny',\n              reason: {\n                code,\n                data: errData as unknown as AgentScoreData,\n                ...(typeof errData.verify_url === 'string' ? { verify_url: errData.verify_url } : {}),\n                ...(typeof errData.session_id === 'string' ? { session_id: errData.session_id } : {}),\n                ...(typeof errData.poll_secret === 'string' ? { poll_secret: errData.poll_secret } : {}),\n                ...(typeof errData.poll_url === 'string' ? { poll_url: errData.poll_url } : {}),\n                ...(errData.next_steps ? { agent_instructions: JSON.stringify(errData.next_steps) } : {}),\n                ...(errData.agent_memory ? { agent_memory: errData.agent_memory as AgentMemoryHint } : {}),\n              },\n            };\n          }\n          // The API returns this when the operator_token doesn't exist at all (typo,\n          // never minted, fabricated). Distinct from token_expired — no auto-session\n          // is issued because the agent may have other valid tokens to try first.\n          // Without this branch the gate would fall through to api_error → 503 retry,\n          // which loops forever on a permanent state.\n          if (code === 'invalid_credential') {\n            return {\n              kind: 'deny',\n              reason: {\n                code: 'invalid_credential',\n                agent_instructions: INVALID_CREDENTIAL_INSTRUCTIONS,\n                agent_memory: agentMemoryHint,\n              },\n            };\n          }\n          // Unknown 401 code — log so we notice if the API adds a new credential-state\n          // code without us mapping it. Falls through to api_error below.\n          if (code) {\n            console.warn(`[gate] /v1/assess returned 401 ${code} — no specific handler, surfacing as api_error.`);\n          }\n        } catch (err) {\n          // Body wasn't the expected JSON shape. Don't crash the request, but DO log —\n          // a silent swallow here used to mask /v1/sessions schema drift for hours.\n          console.warn('[gate] /v1/assess 401 body parse failed:', err instanceof Error ? err.message : err);\n        }\n      }\n\n      // 4xx with a structured error body that ISN'T 401/402: log it so operators see\n      // misclassifications instead of opaque 503 retries. Most common cause: a merchant\n      // that didn't validate input shape before invoking the gate (invalid_address,\n      // invalid_identity). We still fall through to api_error so behavior is unchanged\n      // for callers — just visible now.\n      if (response.status >= 400 && response.status < 500 && response.status !== 402) {\n        try {\n          const errData = (await response.clone().json()) as { error?: { code?: string; message?: string } };\n          const code = errData?.error?.code;\n          if (code && code !== 'token_expired' && code !== 'invalid_credential') {\n            console.warn(\n              `[gate] /v1/assess returned ${response.status} ${code} — surfacing as api_error. ` +\n              'Validate input shape before invoking the gate to avoid this.',\n            );\n          }\n        } catch {\n          // Body wasn't JSON or didn't have the expected shape — silent fall-through.\n        }\n      }\n\n      if (!response.ok) {\n        throw new Error(`AgentScore API returned ${response.status}`);\n      }\n\n      const data = (await response.json()) as Record<string, unknown>;\n      const decision = data.decision as string | null | undefined;\n      const decisionReasons = (data.decision_reasons as string[]) ?? [];\n      const allow = decision === 'allow' || decision == null;\n\n      cache.set(cacheKey, { allow, decision: decision ?? undefined, reasons: decisionReasons, raw: data });\n\n      if (allow) {\n        return { kind: 'allow', data: data as unknown as AgentScoreData };\n      }\n\n      // Fixable compliance denials (kyc_required, kyc_pending, kyc_failed) get the\n      // same UX as missing_identity: mint a fresh verification session, agent polls\n      // until status=verified, gets a fresh opc_..., retries. Unfixable reasons\n      // (sanctions_flagged, age_insufficient, jurisdiction_restricted) keep the bare\n      // wallet_not_trusted denial. `jurisdiction_restricted` is unfixable: the API\n      // only emits it after KYC is verified (the user's KYC'd country is in the\n      // blocked list — re-doing KYC won't change the country).\n      if (isFixableDenial(decisionReasons)) {\n        const sessionReason = await tryMintSessionDenial(ctx);\n        if (sessionReason) return { kind: 'deny', reason: sessionReason };\n      }\n\n      return {\n        kind: 'deny',\n        reason: {\n          code: 'wallet_not_trusted',\n          decision: decision ?? undefined,\n          reasons: decisionReasons,\n          verify_url: data.verify_url as string | undefined,\n          data: data as unknown as AgentScoreData,\n        },\n      };\n    } catch (err) {\n      // Network failure, AbortSignal timeout, JSON parse error on a 2xx, or the\n      // explicit `throw new Error(...)` for an unhandled non-ok status. Log so ops\n      // can distinguish \"API down\" from \"merchant config wrong\" — without this,\n      // every transient blip looked identical to a misconfigured base URL.\n      console.warn('[gate] /v1/assess call failed — surfacing as api_error:', err instanceof Error ? err.message : err);\n      if (failOpen) return { kind: 'allow' };\n      return { kind: 'deny', reason: { code: 'api_error' } };\n    }\n  }\n\n  async function captureWallet(options: CaptureWalletOptions): Promise<void> {\n    try {\n      const body: Record<string, unknown> = {\n        operator_token: options.operatorToken,\n        wallet_address: options.walletAddress,\n        network: options.network,\n      };\n      if (options.idempotencyKey) body.idempotency_key = options.idempotencyKey;\n      await fetch(`${baseUrl}/v1/credentials/wallets`, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': apiKey,\n          'Content-Type': 'application/json',\n          Accept: 'application/json',\n          'User-Agent': userAgentHeader,\n        },\n        body: JSON.stringify(body),\n        signal: AbortSignal.timeout(API_TIMEOUT_MS),\n      });\n    } catch (err) {\n      // Fire-and-forget: don't throw. Log so a persistent capture outage is visible\n      // to merchant ops — otherwise wallet↔operator linkage silently stops.\n      console.warn('[agentscore-commerce] captureWallet failed:', err instanceof Error ? err.message : err);\n    }\n  }\n\n  /**\n   * Resolve a wallet to its operator id via /v1/assess.\n   *\n   * Returns:\n   *   - `{ ok: true, operator: <id> }` — wallet is linked to that operator\n   *   - `{ ok: true, operator: null }` — wallet is valid but not linked to any operator\n   *   - `{ ok: false }` — the API call failed (network, timeout, non-2xx). Distinguishable so\n   *     callers can emit `api_error` instead of falsely asserting \"no operator linked\".\n   *\n   * Checks the main evaluate() cache before making a fresh call — if the gate already\n   * resolved this wallet during identity evaluation, we have the resolved_operator already.\n   */\n  async function resolveWalletToOperator(\n    walletAddress: string,\n  ): Promise<{ ok: true; operator: string | null; linkedWallets: string[] } | { ok: false }> {\n    // Network-aware: lowercases EVM, preserves Solana base58 case. The DB stores both\n    // formats verbatim in operator_credential_wallets.wallet_address; lowercasing a\n    // Solana address would never match.\n    const wallet = normalizeAddress(walletAddress);\n\n    // Cache lookup — first the plain cache (populated by evaluate() for identity-headered wallets).\n    // Saves a second /v1/assess call when the gate already looked up this wallet.\n    const extractFromCached = (raw: Record<string, unknown>): { operator: string | null; linkedWallets: string[] } => {\n      const op = raw.resolved_operator;\n      const links = raw.linked_wallets;\n      return {\n        operator: typeof op === 'string' ? op : null,\n        linkedWallets: Array.isArray(links) ? (links as unknown[]).filter((w): w is string => typeof w === 'string') : [],\n      };\n    };\n\n    const plainCached = cache.get(wallet);\n    if (plainCached?.raw) {\n      return { ok: true, ...extractFromCached(plainCached.raw as Record<string, unknown>) };\n    }\n    const resolveCached = cache.get(`resolve:${wallet}`);\n    if (resolveCached?.raw) {\n      return { ok: true, ...extractFromCached(resolveCached.raw as Record<string, unknown>) };\n    }\n\n    try {\n      const response = await fetch(`${baseUrl}/v1/assess`, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': apiKey,\n          'Content-Type': 'application/json',\n          Accept: 'application/json',\n          'User-Agent': userAgentHeader,\n        },\n        body: JSON.stringify({ address: walletAddress }),\n        signal: AbortSignal.timeout(API_TIMEOUT_MS),\n      });\n      if (!response.ok) return { ok: false };\n      const data = (await response.json()) as Record<string, unknown>;\n      cache.set(`resolve:${wallet}`, { allow: true, raw: data });\n      return { ok: true, ...extractFromCached(data) };\n    } catch (err) {\n      // Network/timeout/parse on the wallet→operator resolve path. Caller maps\n      // `{ok:false}` to `wallet_signer_mismatch.kind === 'api_error'`, which already\n      // surfaces as 503 — but log here too so multi-wallet match failures aren't\n      // silently indistinguishable from \"operator simply has no linked wallet\".\n      console.warn('[gate] resolveWalletToOperator failed — returning { ok:false }:', err instanceof Error ? err.message : err);\n      return { ok: false };\n    }\n  }\n\n  function reportSignerEvent(kind: 'pass' | 'wallet_signer_mismatch' | 'wallet_auth_requires_wallet_signing' | 'api_error'): void {\n    // Fire-and-forget: surfaces mismatch-catch rate + api_error SLO on the dashboard.\n    // Never blocks, awaits, or throws — telemetry failure must not affect the gate's decision.\n    try {\n      const pending = fetch(`${baseUrl}/v1/telemetry/signer-match`, {\n        method: 'POST',\n        headers: {\n          'X-API-Key': apiKey,\n          'Content-Type': 'application/json',\n          Accept: 'application/json',\n          'User-Agent': userAgentHeader,\n        },\n        body: JSON.stringify({ kind }),\n        signal: AbortSignal.timeout(API_TIMEOUT_MS),\n      });\n      if (pending && typeof pending.catch === 'function') {\n        pending.catch((err) => {\n          console.warn('[agentscore-commerce] signer-match telemetry failed:', err instanceof Error ? err.message : err);\n        });\n      }\n    } catch {\n      // Thrown synchronously (e.g., fetch unavailable in test harness) — swallow silently.\n    }\n  }\n\n  async function verifyWalletSignerMatch(\n    options: VerifyWalletSignerMatchOptions,\n  ): Promise<VerifyWalletSignerResult> {\n    const { claimedWallet, signer } = options;\n\n    if (!signer) {\n      reportSignerEvent('wallet_auth_requires_wallet_signing');\n      return {\n        kind: 'wallet_auth_requires_wallet_signing',\n        claimedWallet,\n        agentInstructions: WALLET_AUTH_REQUIRES_WALLET_SIGNING_INSTRUCTIONS,\n      };\n    }\n\n    // Network-aware normalization: lowercase EVM, preserve Solana base58. The byte-equal\n    // short-circuit and downstream cache-key derivation MUST match how the DB stores\n    // wallets; lowercasing Solana would corrupt both.\n    const claimedNorm = normalizeAddress(claimedWallet);\n    const signerNorm = normalizeAddress(signer);\n\n    // Byte-equal short-circuit — no API lookup; same wallet ≡ same operator by definition.\n    if (claimedNorm === signerNorm) {\n      reportSignerEvent('pass');\n      return { kind: 'pass', claimedOperator: null, signerOperator: null };\n    }\n\n    const [claimedResolve, signerResolve] = await Promise.all([\n      resolveWalletToOperator(claimedNorm),\n      resolveWalletToOperator(signerNorm),\n    ]);\n\n    // Transient API failure on either resolve → emit api_error. Caller should retry or\n    // surface 503 rather than falsely reject a legitimate user on a network flake.\n    if (!claimedResolve.ok || !signerResolve.ok) {\n      reportSignerEvent('api_error');\n      return { kind: 'api_error', claimedWallet: claimedNorm };\n    }\n\n    const claimedOperator = claimedResolve.operator;\n    const signerOperator = signerResolve.operator;\n\n    if (claimedOperator && signerOperator && claimedOperator === signerOperator) {\n      reportSignerEvent('pass');\n      return { kind: 'pass', claimedOperator, signerOperator };\n    }\n\n    reportSignerEvent('wallet_signer_mismatch');\n    return {\n      kind: 'wallet_signer_mismatch',\n      claimedOperator,\n      actualSignerOperator: signerOperator,\n      expectedSigner: claimedNorm,\n      actualSigner: signerNorm,\n      // Populated from /v1/assess.linked_wallets on the claimed wallet — the full set of\n      // wallets the agent CAN sign with to satisfy the claim (same-operator rule).\n      linkedWallets: claimedResolve.linkedWallets,\n      agentInstructions: WALLET_SIGNER_MISMATCH_INSTRUCTIONS,\n    };\n  }\n\n  return { evaluate, captureWallet, verifyWalletSignerMatch };\n}\n","/**\n * Payment-signer extraction.\n *\n * Shared between merchants and the gate — both need to recover the on-chain signer from\n * a payment credential without duplicating code. Three rails carry a wallet signer:\n *\n *   - **Tempo MPP** — `Authorization: Payment <base64>` header; credential `source` is a DID\n *     of the form `did:pkh:eip155:<chain>:<address>`.\n *   - **x402 EIP-3009** (EVM, e.g. Base/Sepolia) — `payment-signature` / `x-payment` header;\n *     decoded payload carries `payload.authorization.from`.\n *   - **x402 SVM** (Solana) — same headers, but `payload.transaction` is a base64-encoded\n *     Solana transaction; the SPL Token TransferChecked instruction's source-account owner\n *     is the signer. Recovered via `@x402/svm`'s `decodeTransactionFromPayload` +\n *     `getTokenPayerFromTransaction`.\n *\n * `mppx` and `@x402/svm` are optional peer dependencies — we import them dynamically so\n * merchants who don't use those rails don't need to install them. The EVM x402 path is pure\n * JSON parsing with no external dep.\n */\n\nexport type SignerNetwork = 'evm' | 'solana';\n\nexport interface PaymentSigner {\n  /** Recovered wallet address (EVM lowercased; Solana base58 preserved verbatim). */\n  address: string;\n  /** Network family — used by `captureWallet` and downstream cross-chain attribution. */\n  network: SignerNetwork;\n}\n\n/**\n * Recover the signer wallet from the incoming payment credential, including the network\n * family. Returns `null` when no wallet signature is present (e.g. Stripe SPT, card-only\n * payments, or no credential yet).\n *\n * @param request - the inbound `Request`\n * @param x402PaymentHeader - the value of `payment-signature` or `x-payment` header, if any.\n *   Extracted separately because some frameworks (Express) don't expose a web `Request` object.\n */\nexport async function extractPaymentSigner(\n  request: Request,\n  x402PaymentHeader?: string,\n): Promise<PaymentSigner | null> {\n  // MPP — Authorization: Payment <base64>\n  const authHeader = request.headers.get('authorization');\n  if (authHeader) {\n    try {\n      const moduleName = 'mppx';\n      const mppx = (await import(moduleName).catch(() => null)) as {\n        Credential?: {\n          extractPaymentScheme: (h: string) => unknown;\n          fromRequest: (r: Request) => unknown;\n        };\n      } | null;\n      if (mppx?.Credential?.extractPaymentScheme(authHeader)) {\n        const credential = mppx.Credential.fromRequest(request);\n        const source = (credential as { source?: string }).source;\n        const match = source?.match(/^did:pkh:eip155:\\d+:(0x[0-9a-fA-F]{40})$/);\n        if (match) return { address: match[1]!.toLowerCase(), network: 'evm' };\n      }\n    } catch (err) {\n      console.warn('[gate] MPP signer extraction failed:', err instanceof Error ? err.message : err);\n    }\n  }\n\n  // x402 — base64 JSON. Network identifier on `accepted.network` selects the extraction\n  // path: `eip155:*` → EIP-3009 `payload.authorization.from`; `solana:*` → SPL Token\n  // payer recovered from the encoded transaction.\n  if (x402PaymentHeader) {\n    try {\n      const decoded = atob(x402PaymentHeader);\n      const parsed = JSON.parse(decoded) as {\n        accepted?: { network?: string };\n        payload?: { authorization?: { from?: string }; transaction?: string };\n      };\n      const network = parsed?.accepted?.network ?? '';\n\n      if (network.startsWith('eip155:')) {\n        const from = parsed?.payload?.authorization?.from;\n        if (typeof from === 'string' && /^0x[0-9a-fA-F]{40}$/.test(from)) {\n          return { address: from.toLowerCase(), network: 'evm' };\n        }\n      } else if (network.startsWith('solana:')) {\n        const transaction = parsed?.payload?.transaction;\n        if (typeof transaction === 'string') {\n          const moduleName = '@x402/svm';\n          const svm = (await import(moduleName).catch(() => null)) as {\n            decodeTransactionFromPayload?: (p: { transaction: string }) => unknown;\n            getTokenPayerFromTransaction?: (tx: unknown) => string | undefined;\n          } | null;\n          if (svm?.decodeTransactionFromPayload && svm.getTokenPayerFromTransaction) {\n            const tx = svm.decodeTransactionFromPayload({ transaction });\n            const payer = svm.getTokenPayerFromTransaction(tx);\n            if (typeof payer === 'string' && payer.length > 0) return { address: payer, network: 'solana' };\n          }\n        }\n      } else {\n        // Back-compat: a payload without an `accepted.network` field still uses EIP-3009\n        // shape if `payload.authorization.from` looks EVM. Older x402 clients emitted these.\n        const from = parsed?.payload?.authorization?.from;\n        if (typeof from === 'string' && /^0x[0-9a-fA-F]{40}$/.test(from)) {\n          return { address: from.toLowerCase(), network: 'evm' };\n        }\n      }\n    } catch (err) {\n      console.warn('[gate] x402 signer extraction failed:', err instanceof Error ? err.message : err);\n    }\n  }\n\n  return null;\n}\n\n/**\n * Address-only convenience over {@link extractPaymentSigner}. Used by the gate adapters\n * (verifyWalletSignerMatch) where only the address matters for operator comparison.\n */\nexport async function extractPaymentSignerAddress(\n  request: Request,\n  x402PaymentHeader?: string,\n): Promise<string | null> {\n  const result = await extractPaymentSigner(request, x402PaymentHeader);\n  return result?.address ?? null;\n}\n\n/**\n * Read the x402 payment header from a `Request`, matching the alternate names merchants might\n * use. Falls back to reading either header directly.\n */\nexport function readX402PaymentHeader(request: Request): string | undefined {\n  return (\n    request.headers.get('payment-signature') ??\n    request.headers.get('x-payment') ??\n    undefined\n  );\n}\n","/**\n * Shared DenialReason → response body serialization for all adapters.\n *\n * Keeps Hono / Express / Fastify / Web / Next.js defaults aligned — a field added\n * here shows up in every adapter's 403 body automatically, and there's one place\n * to test the marshaling.\n *\n * Body shape: `{ error: { code, message }, ... }` — matches the canonical AgentScore\n * core API response shape (`core/api/src/lib/auth.ts`, `lib/rate-limit.ts`, etc.) and\n * martin-estate's pre-commerce shape, so downstream agents see one consistent\n * `error.code` + `error.message` pair regardless of which layer produced the denial.\n */\n\nimport type { DenialCode, DenialReason } from './core.js';\n\n/**\n * JSON-encoded canonical agent_instructions per denial code. Auto-injected by\n * `denialReasonToBody` when the gate produces a DenialReason without explicit\n * `agent_instructions` so every denial carries a machine-readable next step.\n *\n * Codes covered:\n *  - `wallet_not_trusted` — gate never stamps instructions today (the original gap)\n *  - `payment_required` — gate never stamps; merchant tier misconfig, contact-merchant action\n *  - `identity_verification_required` — fallback when API didn't return next_steps\n *  - `token_expired` — fallback when API didn't return next_steps\n *\n * Codes already stamped explicitly upstream in core.ts (`missing_identity`,\n * `invalid_credential`) and codes that don't go through DenialReason\n * (`wallet_signer_mismatch`, `wallet_auth_requires_wallet_signing` — handled by\n * `verifyWalletSignerMatch` result type) are not in this map. `api_error` has\n * its own `next_steps: {action: retry}` fallback below.\n */\nconst WALLET_NOT_TRUSTED_INSTRUCTIONS = JSON.stringify({\n  action: 'contact_support',\n  steps: [\n    'The wallet\\'s operator failed an UNFIXABLE compliance check (sanctions, age, or jurisdiction). `reasons` lists which: `sanctions_flagged` / `age_insufficient` / `jurisdiction_restricted`. KYC re-verification won\\'t change the outcome — the policy denial is structural.',\n    'Surface the denial to the user with the merchant\\'s support contact. Do not retry the same merchant request; do not hand the user a verify_url (verification won\\'t fix this code path).',\n    'Fixable compliance reasons (`kyc_required`, `kyc_pending`, `kyc_failed`) do NOT land on this code — the gate auto-mints a verification session for those and returns `identity_verification_required` with poll endpoints, same shape as `missing_identity`. `jurisdiction_restricted` IS in the unfixable bucket because the API only emits it after KYC is verified (the user\\'s KYC\\'d country is in the blocked list — re-doing KYC won\\'t change the country).',\n  ],\n  user_message:\n    'This purchase is denied by the merchant\\'s compliance policy and cannot be resolved by re-verifying. Contact the merchant\\'s support if you believe this is in error.',\n});\n\nconst PAYMENT_REQUIRED_INSTRUCTIONS = JSON.stringify({\n  action: 'contact_merchant',\n  steps: [\n    'The merchant\\'s AgentScore tier does not include the assess feature, so agent identity cannot be evaluated. This is a merchant-side configuration gap — there is no agent-side recovery.',\n    'Contact the merchant (their support channel — typically listed in /llms.txt or the OpenAPI servers metadata) and request they upgrade their AgentScore plan.',\n  ],\n  user_message:\n    'This merchant\\'s identity gate is misconfigured (AgentScore tier doesn\\'t support assess). Contact the merchant — there\\'s nothing to fix on the agent side.',\n});\n\nconst IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({\n  action: 'deliver_verify_url_and_poll',\n  steps: [\n    'Share verify_url with the user — they complete identity verification on AgentScore.',\n    'If session_id + poll_secret are present in the body, poll poll_url every 5 seconds with header `X-Poll-Secret: <poll_secret>` until status=verified. The poll returns a one-time operator_token.',\n    'Retry the original request with header `X-Operator-Token: <opc_...>`.',\n  ],\n  user_message:\n    'Identity verification is required. Visit verify_url, then poll poll_url for the operator token and retry.',\n});\n\nconst TOKEN_EXPIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({\n  action: 'deliver_verify_url_and_poll',\n  steps: [\n    'The operator token is expired or revoked. AgentScore auto-mints a fresh verification session — complete it to receive a new opc_...',\n    'Share verify_url with the user, then poll poll_url every 5 seconds with header `X-Poll-Secret: <poll_secret>` until status=verified. The poll returns a fresh one-time operator_token.',\n    'Retry the original request with header `X-Operator-Token: <new_opc_...>`.',\n  ],\n  user_message:\n    'Operator token is expired or revoked. A new verification session has been minted — visit verify_url to refresh.',\n});\n\nconst DEFAULT_AGENT_INSTRUCTIONS: Partial<Record<DenialCode, string>> = {\n  wallet_not_trusted: WALLET_NOT_TRUSTED_INSTRUCTIONS,\n  payment_required: PAYMENT_REQUIRED_INSTRUCTIONS,\n  identity_verification_required: IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS,\n  token_expired: TOKEN_EXPIRED_FALLBACK_INSTRUCTIONS,\n};\n\nconst DEFAULT_MESSAGES: Record<DenialCode, string> = {\n  missing_identity:\n    'No identity provided. Send X-Wallet-Address (wallet) or X-Operator-Token (credential).',\n  identity_verification_required:\n    'Identity verification is required to access this resource. Visit verify_url to complete KYC.',\n  wallet_not_trusted:\n    'The wallet does not meet the merchant compliance policy.',\n  api_error:\n    'AgentScore is unreachable. This is transient — retry in a few seconds.',\n  payment_required:\n    'AgentScore tier does not support assess. Contact support.',\n  wallet_signer_mismatch:\n    'Payment signer does not match the wallet claimed via X-Wallet-Address. The signer and the claimed wallet must both resolve to the same AgentScore operator.',\n  wallet_auth_requires_wallet_signing:\n    'X-Wallet-Address was sent with a rail that has no wallet signature (Stripe SPT / card). Switch to X-Operator-Token, or use a wallet-signing rail (Tempo MPP, x402).',\n  token_expired:\n    'The operator token is expired or revoked. A fresh verification session has been minted — visit verify_url to mint a new token.',\n  invalid_credential:\n    'The operator token is not recognized. Switch to a different stored token, or drop the header to bootstrap a fresh session.',\n};\n\n// Field names the gate claims authority over. Merchant-provided `extra` (from the\n// onBeforeSession hook) MUST NOT override these — a buggy or malicious hook could\n// otherwise replace `verify_url` with a phishing URL or drop agent_instructions.\nconst RESERVED_FIELDS = new Set([\n  'error',\n  'decision',\n  'reasons',\n  'verify_url',\n  'session_id',\n  'poll_secret',\n  'poll_url',\n  'agent_instructions',\n  'agent_memory',\n  'claimed_operator',\n  'actual_signer_operator',\n  'expected_signer',\n  'actual_signer',\n  'linked_wallets',\n]);\n\nexport function denialReasonToBody(reason: DenialReason): Record<string, unknown> {\n  const message = reason.message ?? DEFAULT_MESSAGES[reason.code];\n  const body: Record<string, unknown> = { error: { code: reason.code, message } };\n  if (reason.decision) body.decision = reason.decision;\n  if (reason.reasons) body.reasons = reason.reasons;\n  if (reason.verify_url) body.verify_url = reason.verify_url;\n  if (reason.session_id) body.session_id = reason.session_id;\n  if (reason.poll_secret) body.poll_secret = reason.poll_secret;\n  if (reason.poll_url) body.poll_url = reason.poll_url;\n  const instructions = reason.agent_instructions ?? DEFAULT_AGENT_INSTRUCTIONS[reason.code];\n  if (instructions) body.agent_instructions = instructions;\n  if (reason.agent_memory) body.agent_memory = reason.agent_memory;\n  if (reason.claimed_operator) body.claimed_operator = reason.claimed_operator;\n  if (reason.code === 'wallet_signer_mismatch') body.actual_signer_operator = reason.actual_signer_operator ?? null;\n  if (reason.expected_signer) body.expected_signer = reason.expected_signer;\n  if (reason.actual_signer) body.actual_signer = reason.actual_signer;\n  if (reason.linked_wallets && reason.linked_wallets.length > 0) body.linked_wallets = reason.linked_wallets;\n  // api_error denials get a default retry hint so agents know it's transient. Vendors can\n  // override by spreading their own next_steps into a custom onDenied body.\n  if (reason.code === 'api_error' && !(reason.extra && (reason.extra as Record<string, unknown>).next_steps)) {\n    body.next_steps = { action: 'retry', retry_after_seconds: 5 };\n  }\n  if (reason.extra) {\n    for (const [key, value] of Object.entries(reason.extra)) {\n      if (RESERVED_FIELDS.has(key)) {\n        console.warn(`[gate] onBeforeSession returned reserved field \"${key}\" — ignoring to preserve gate authority`);\n        continue;\n      }\n      body[key] = value;\n    }\n  }\n  return body;\n}\n","/**\n * Google A2A (Agent-to-Agent) Signed Agent Cards builder.\n *\n * Compose the JSON payload for an A2A v1.0 Signed Agent Card that includes the\n * agent's AgentScore identity claims. Returned object is the unsigned card body —\n * the merchant (or agent) signs it with their wallet / signing key before publishing.\n *\n * Why publish: A2A is a Linux Foundation standard with 150+ orgs (Microsoft, AWS,\n * Salesforce in production). Signed Agent Cards let any A2A-compatible reader discover\n * an agent's verified-identity claims without per-platform integration. AgentScore\n * publishing operator identity in this format means our identity travels with the agent\n * across A2A-aware ecosystems.\n *\n * Spec reference: https://a2a-protocol.org/latest/\n */\n\nimport type { AgentScoreData } from '../core';\n\nexport interface A2AAgentCardCapabilities {\n  /** Endpoints the agent exposes — `[{ name: \"purchase\", path: \"/purchase\", method: \"POST\" }, ...]`. */\n  endpoints?: { name: string; path?: string; method?: string }[];\n  /** Free-form skill tags — `[\"wine-purchase\", \"regulated-commerce\", ...]`. */\n  skills?: string[];\n}\n\nexport interface A2AAgentCardIdentity {\n  /** Issuer of the identity claims — always `\"https://agentscore.sh\"` for the AgentScore-issued card. */\n  issuer: string;\n  /** Operator id under AgentScore. */\n  operator_id: string;\n  /** KYC tier. */\n  kyc_level: string;\n  /** Sanctions screening result. */\n  sanctions_clear: boolean;\n  /** Age bracket. */\n  age_bracket: string;\n  /** Jurisdiction (ISO-3166-1 alpha-2 or empty). */\n  jurisdiction: string;\n  /** ISO-8601 timestamp of last verification refresh. */\n  verified_at: string | null;\n  /** Verify URL where the identity was minted. */\n  verify_url: string;\n}\n\nexport interface A2AAgentCard {\n  /** A2A protocol version. v1.0 was donated to Linux Foundation. */\n  protocol_version: string;\n  /** Card schema version (this builder emits v1). */\n  card_version: number;\n  /** Agent's display name. */\n  name: string;\n  /** One-line description shown to A2A consumers. */\n  description?: string;\n  /** Agent's canonical URL (homepage, Discord, repo, etc.). */\n  url?: string;\n  /** Agent capabilities — endpoints + skills. */\n  capabilities?: A2AAgentCardCapabilities;\n  /** AgentScore identity claims. Empty `null` when no identity is available (pre-KYC). */\n  identity: A2AAgentCardIdentity | null;\n  /** Vendor-specific extras merged at the top level. */\n  extras?: Record<string, unknown>;\n}\n\nexport interface BuildA2AAgentCardInput {\n  /** Display name for the agent — `\"Martin Estate Wine Concierge\"`, etc. */\n  name: string;\n  /** Optional one-line description. */\n  description?: string;\n  /** Agent's canonical URL. */\n  url?: string;\n  /** Capabilities — endpoints exposed + skill tags. */\n  capabilities?: A2AAgentCardCapabilities;\n  /** AgentScore assess data — what `getAgentScoreData(c)` returns or what `assess()` returned directly.\n   *  Pass `null` to emit a card with no identity claims (publishable but unverified). */\n  data?: AgentScoreData | null;\n  /** Override the default issuer URL. Default `\"https://agentscore.sh\"`. */\n  issuer?: string;\n  /** Override the verify URL. */\n  verifyUrl?: string;\n  /** Vendor-specific extras merged at the card top level. */\n  extras?: Record<string, unknown>;\n}\n\nconst PROTOCOL_VERSION = '1.0';\nconst CARD_VERSION = 1;\n\n/**\n * Compose an A2A Signed Agent Card body with AgentScore identity claims included.\n *\n * Returns the UNSIGNED card. The vendor signs it with their wallet (typically using\n * the same wallet they use for x402 / MPP payments) and publishes the signed envelope\n * to wherever A2A consumers discover cards (a hosted endpoint, on-chain registry,\n * agent-card-server, etc.). Signing is vendor-side because the agent's signing key\n * never leaves their environment.\n *\n * Example:\n * ```ts\n * import { buildA2AAgentCard } from '@agent-score/commerce/identity/hono';\n *\n * app.get('/.well-known/agent-card', async (c) => {\n *   const data = getAgentScoreData(c);\n *   const card = buildA2AAgentCard({\n *     name: 'Martin Estate Wine Concierge',\n *     description: 'Buy regulated wines from Martin Estate via agent payments.',\n *     url: 'https://agents.martinestate.com',\n *     capabilities: {\n *       endpoints: [{ name: 'purchase', path: '/purchase', method: 'POST' }],\n *       skills: ['wine-purchase', 'regulated-commerce'],\n *     },\n *     data,\n *   });\n *   const signed = await yourSign(card);\n *   return c.json(signed);\n * });\n * ```\n */\nexport function buildA2AAgentCard(input: BuildA2AAgentCardInput): A2AAgentCard {\n  const issuer = input.issuer ?? 'https://agentscore.sh';\n\n  let identity: A2AAgentCardIdentity | null = null;\n  if (input.data) {\n    const operatorId = (input.data.resolved_operator as string | undefined) ?? null;\n    if (operatorId) {\n      const operatorVerification = input.data.operator_verification;\n      const accountVerification = input.data.account_verification;\n      identity = {\n        issuer,\n        operator_id: operatorId,\n        kyc_level: accountVerification?.kyc_level ?? operatorVerification?.level ?? 'none',\n        sanctions_clear: accountVerification?.sanctions_clear === true,\n        age_bracket: accountVerification?.age_bracket ?? 'unknown',\n        jurisdiction: accountVerification?.jurisdiction ?? '',\n        verified_at: accountVerification?.verified_at ?? operatorVerification?.verified_at ?? null,\n        verify_url:\n          input.verifyUrl\n          ?? (input.data.verify_url as string | undefined)\n          ?? `${issuer}/verify`,\n      };\n    }\n  }\n\n  const card: A2AAgentCard = {\n    protocol_version: PROTOCOL_VERSION,\n    card_version: CARD_VERSION,\n    name: input.name,\n    identity,\n  };\n  if (input.description !== undefined) card.description = input.description;\n  if (input.url !== undefined) card.url = input.url;\n  if (input.capabilities !== undefined) card.capabilities = input.capabilities;\n  if (input.extras !== undefined) card.extras = input.extras;\n  return card;\n}\n","/**\n * UCP (Universal Commerce Protocol) profile builder.\n *\n * Compose the JSON payload published at `/.well-known/ucp` per the UCP spec, with\n * AgentScore identity claims attached as a capability. Returned object is the unsigned\n * profile body — the merchant signs it (or wraps it in their JWKS-backed envelope)\n * before publishing.\n *\n * Why publish: UCP is the Google-led cross-vendor standard (announced Jan 2026 at NRF\n * with Shopify, Etsy, Wayfair, Target, Walmart, Adyen, Mastercard, Stripe, Visa, Amex,\n * etc.). Every UCP-aware platform discovers a merchant via `/.well-known/ucp`, so\n * shipping this profile means AgentScore-gated merchants are discoverable through the\n * same surface every other UCP merchant uses.\n *\n * Spec reference: https://ucp.dev/\n *\n * UCP profiles do NOT carry KYC / sanctions / age / jurisdiction claims natively —\n * identity in the UCP spec is \"who signed this\" (JWKS-backed). AgentScore claims layer\n * over UCP via a custom capability so consumers who care about verified-buyer identity\n * can read them; consumers who don't care just see a normal UCP profile.\n */\n\nimport type { AgentScoreData } from '../core';\n\nexport interface UCPSigningKey {\n  /** JWK kid (key id). */\n  kid: string;\n  /** JWK kty (key type) — typically `EC`, `RSA`, or `OKP`. */\n  kty: string;\n  /** JWK alg (signing algorithm) — typically `ES256`, `RS256`, or `EdDSA`. */\n  alg?: string;\n  /** JWK use — typically `sig`. */\n  use?: string;\n  /** JWK crv (curve) for EC / OKP keys. */\n  crv?: string;\n  /** JWK x / y / n / e / etc. The full key material; passed through verbatim. */\n  [k: string]: unknown;\n}\n\nexport interface UCPService {\n  /** Transport binding — `rest` / `mcp` / `a2a` / `embedded`. */\n  type: string;\n  /** Service URL (or path for embedded). */\n  url?: string;\n  /** Optional version pin. */\n  version?: string;\n  /** Vendor-specific extras for the binding. */\n  [k: string]: unknown;\n}\n\nexport interface UCPCapability {\n  /** Capability name — `checkout`, `catalog`, `agentscore-identity`, etc. */\n  name: string;\n  /** URL of the JSON Schema describing this capability's payload. */\n  schema?: string;\n  /** Capability version — semver or date-stamp per UCP convention. */\n  version?: string;\n  /** Vendor-specific extras for the capability. */\n  [k: string]: unknown;\n}\n\nexport interface UCPPaymentHandler {\n  /** Handler name — `stripe`, `tempo`, `x402-base`, `x402-solana`, etc. */\n  name: string;\n  /** Handler config — recipient address, profile id, etc. */\n  config?: Record<string, unknown>;\n}\n\nexport interface UCPProfile {\n  /** UCP spec version (date-stamped). */\n  version: string;\n  /** URL of the UCP spec. */\n  spec: string;\n  /** URL of this profile's JSON schema. */\n  schema?: string;\n  /** Display name of the merchant / agent surface. */\n  name?: string;\n  /** Service bindings — REST, MCP, A2A, embedded transports. */\n  services: UCPService[];\n  /** Capabilities offered (with schema URLs). */\n  capabilities: UCPCapability[];\n  /** Payment handlers offered — typically the rails the merchant accepts. */\n  payment_handlers: UCPPaymentHandler[];\n  /** JWKS — REQUIRED by spec. The merchant signs requests with a private key whose\n   *  public counterpart is listed here. Verifiers fetch this profile, find the kid, and\n   *  validate signatures. */\n  signing_keys: UCPSigningKey[];\n  /** Vendor-specific extras at the top level. */\n  [k: string]: unknown;\n}\n\nexport interface BuildUCPProfileInput {\n  /** UCP spec version. Default `\"2026-04-17\"` (current at time of writing). */\n  version?: string;\n  /** Display name for the merchant / agent surface. */\n  name?: string;\n  /** Service transport bindings. At minimum, the agent's primary REST endpoint. */\n  services: UCPService[];\n  /** Capabilities offered. AgentScore identity is auto-added as a capability when `data` is provided. */\n  capabilities?: UCPCapability[];\n  /** Payment handlers — rails the merchant accepts. */\n  payment_handlers?: UCPPaymentHandler[];\n  /** JWKS — public keys the merchant signs requests with. REQUIRED by spec. */\n  signing_keys: UCPSigningKey[];\n  /** AgentScore assess data — adds an `agentscore-identity` capability + claims block when present. */\n  data?: AgentScoreData | null;\n  /** Optional override for the AgentScore capability schema URL. */\n  agentscoreSchemaUrl?: string;\n  /** Vendor-specific extras at the top level. */\n  extras?: Record<string, unknown>;\n}\n\nconst DEFAULT_VERSION = '2026-04-17';\nconst SPEC_URL = 'https://ucp.dev/';\nconst AGENTSCORE_CAPABILITY_NAME = 'agentscore-identity';\nconst AGENTSCORE_CAPABILITY_VERSION = '1';\n\n/**\n * Compose a UCP profile body for `/.well-known/ucp` publication. Merges AgentScore\n * identity claims into the `capabilities` array as an `agentscore-identity` capability\n * so UCP-aware consumers can discover verified-buyer claims alongside the standard\n * UCP transport metadata.\n *\n * Example:\n * ```ts\n * import { buildUCPProfile } from '@agent-score/commerce/identity/hono';\n *\n * app.get('/.well-known/ucp', async (c) => {\n *   const data = getAgentScoreData(c);\n *   return c.json(buildUCPProfile({\n *     name: 'Martin Estate',\n *     services: [{ type: 'rest', url: 'https://agents.martinestate.com' }],\n *     payment_handlers: [\n *       { name: 'tempo', config: { recipient: TEMPO_ADDR } },\n *       { name: 'stripe', config: { profile_id: STRIPE_PROFILE_ID } },\n *     ],\n *     signing_keys: [{ kid: 'me-2026-04', kty: 'EC', alg: 'ES256', crv: 'P-256', x: '...', y: '...' }],\n *     data,\n *   }));\n * });\n * ```\n */\nexport function buildUCPProfile(input: BuildUCPProfileInput): UCPProfile {\n  const baseCapabilities: UCPCapability[] = [...(input.capabilities ?? [])];\n\n  if (input.data) {\n    const operatorId = input.data.resolved_operator;\n    if (operatorId) {\n      const operatorVerification = input.data.operator_verification;\n      const accountVerification = input.data.account_verification;\n      const claims: Record<string, unknown> = {\n        operator_id: operatorId,\n        kyc_level: accountVerification?.kyc_level ?? operatorVerification?.level ?? 'none',\n        sanctions_clear: accountVerification?.sanctions_clear === true,\n        age_bracket: accountVerification?.age_bracket ?? 'unknown',\n        jurisdiction: accountVerification?.jurisdiction ?? '',\n        verified_at: accountVerification?.verified_at ?? operatorVerification?.verified_at ?? null,\n        verify_url: input.data.verify_url ?? null,\n        issuer: 'https://agentscore.sh',\n      };\n      baseCapabilities.push({\n        name: AGENTSCORE_CAPABILITY_NAME,\n        version: AGENTSCORE_CAPABILITY_VERSION,\n        schema: input.agentscoreSchemaUrl ?? 'https://agentscore.sh/schemas/ucp/agentscore-identity.v1.json',\n        claims,\n      });\n    }\n  }\n\n  const profile: UCPProfile = {\n    version: input.version ?? DEFAULT_VERSION,\n    spec: SPEC_URL,\n    services: input.services,\n    capabilities: baseCapabilities,\n    payment_handlers: input.payment_handlers ?? [],\n    signing_keys: input.signing_keys,\n  };\n\n  if (input.name !== undefined) profile.name = input.name;\n  if (input.extras) Object.assign(profile, input.extras);\n\n  return profile;\n}\n\nexport const AGENTSCORE_UCP_CAPABILITY = AGENTSCORE_CAPABILITY_NAME;\n","/**\n * Per-product / per-tier compliance policy helpers.\n *\n * A *policy* is a small bag of fields describing what identity the merchant wants\n * verified for a given resource:\n *\n * - `enforcement`: `\"hard\"` (today's wine path — 403 on miss) or `\"soft\"` (gate\n *   denial is swallowed; the order completes with a degraded `identity_status`).\n *   `null` / absent = no gate at all.\n * - `requireKyc` / `requireSanctionsClear` / `minAge`: passed through to the\n *   per-framework `agentscoreGate(...)` factory.\n * - `allowedJurisdictions`: buyer-verified country list (`[\"US\", \"CA\", ...]`).\n * - `allowedShippingCountries` / `allowedShippingStates`: optional shipping\n *   allowlists. State list is only enforced for US shipments.\n *\n * This module ships three primitives:\n *\n * 1. {@link PolicyBlock} — the typed shape.\n * 2. {@link policyToGateOptions} — translate a block into the options object the\n *    per-framework `agentscoreGate(...)` accepts. Returns `null` when the policy\n *    has no enforcement (treat as \"no gate; anonymous OK\").\n * 3. {@link runGateWithEnforcement} — wrap a per-framework middleware in the\n *    hard/soft enforcement runner. The middleware is given an `onDenied` shim\n *    that captures the denial body and status; the runner returns a structured\n *    {@link GateResult} so the vendor decides how to surface it.\n *\n * All three are additive — vendors using `agentscoreGate(...)` directly are\n * unaffected.\n */\n\nimport type { AgentScoreCoreOptions, DenialReason } from '../core.js';\n\n/** Hard = 403 propagates; soft = swallowed + identity_status=\"unverified\". */\nexport type EnforcementMode = 'hard' | 'soft';\n\n/** Per-order trust level captured at settle time. */\nexport type IdentityStatus = 'verified' | 'unverified' | 'anonymous' | 'denied';\n\n/** Compliance fields a merchant attaches per product / per tier. All optional. */\nexport interface PolicyBlock {\n  enforcement?: EnforcementMode;\n  requireKyc?: boolean;\n  requireSanctionsClear?: boolean;\n  minAge?: number;\n  allowedJurisdictions?: readonly string[];\n  allowedShippingCountries?: readonly string[];\n  allowedShippingStates?: readonly string[];\n}\n\n/**\n * Outcome of running a gate under an enforcement mode.\n *\n * - `verified`: gate accepted; identity is fully verified for the policy.\n * - `unverified`: soft mode swallowed a gate denial; the agent had *some*\n *   identity but didn't meet the policy. Stamp this on the order so\n *   ops/analytics can tell apart soft passes from hard passes.\n * - `anonymous`: no gate ran (policy was null / no enforcement).\n * - `denied`: hard mode rejected; the caller must propagate the 403. The\n *   `denialBody` and `denialStatus` carry the original gate response so the\n *   caller can return it as-is.\n */\nexport interface GateResult {\n  status: IdentityStatus;\n  denialStatus?: number;\n  denialBody?: Record<string, unknown>;\n  denialReason?: DenialReason;\n}\n\n/**\n * Translate a {@link PolicyBlock} into the options the per-framework\n * `agentscoreGate(...)` expects. Returns `null` when the block has no\n * `enforcement` set — the caller should treat that as \"no gate; anonymous OK\".\n *\n * Use a fresh gate per request rather than constructing once at module scope\n * when the policy varies per resource (e.g. per product). Each adapter's gate\n * is cheap to instantiate.\n */\nexport function policyToGateOptions(\n  policy: PolicyBlock | null | undefined,\n  base: { apiKey: string; baseUrl?: string },\n): AgentScoreCoreOptions | null {\n  if (!policy || !policy.enforcement) return null;\n  return {\n    apiKey: base.apiKey,\n    ...(base.baseUrl !== undefined && { baseUrl: base.baseUrl }),\n    ...(policy.requireKyc !== undefined && { requireKyc: policy.requireKyc }),\n    ...(policy.requireSanctionsClear !== undefined && {\n      requireSanctionsClear: policy.requireSanctionsClear,\n    }),\n    ...(policy.minAge !== undefined && { minAge: policy.minAge }),\n    ...(policy.allowedJurisdictions !== undefined && {\n      allowedJurisdictions: [...policy.allowedJurisdictions],\n    }),\n  };\n}\n\n/**\n * Run a per-framework gate middleware respecting the enforcement mode.\n *\n * The vendor passes:\n * - `gate`: their framework's middleware (Hono `MiddlewareHandler`, Express\n *   `(req, res, next) => void`, etc.) — anything that resolves on accept and\n *   throws or returns a `Response` on deny.\n * - `runGate`: a thin adapter that calls the middleware with the framework\n *   context and returns either `{ ok: true }` (gate accepted) or\n *   `{ ok: false, status, body, reason? }` (gate denied with details).\n *\n * `runGateWithEnforcement` wraps that in the hard/soft split:\n *\n * - `gate=null` or `enforcement=null`: no gate fires; status=\"anonymous\".\n * - `enforcement=\"hard\"` + denied: status=\"denied\"; caller propagates denialStatus + denialBody.\n * - `enforcement=\"soft\"` + denied: swallow; status=\"unverified\".\n * - accepted: status=\"verified\".\n */\nexport async function runGateWithEnforcement(\n  enforcement: EnforcementMode | undefined,\n  runGate: (() => Promise<{ ok: true } | { ok: false; status: number; body: Record<string, unknown>; reason?: DenialReason }>) | null,\n): Promise<GateResult> {\n  if (!runGate || !enforcement) return { status: 'anonymous' };\n\n  const outcome = await runGate();\n  if (outcome.ok) return { status: 'verified' };\n\n  if (enforcement === 'hard') {\n    return {\n      status: 'denied',\n      denialStatus: outcome.status,\n      denialBody: outcome.body,\n      ...(outcome.reason !== undefined && { denialReason: outcome.reason }),\n    };\n  }\n  return {\n    status: 'unverified',\n    denialStatus: outcome.status,\n    denialBody: outcome.body,\n    ...(outcome.reason !== undefined && { denialReason: outcome.reason }),\n  };\n}\n\n/** NULL policy / NULL allowlist → ship anywhere. Otherwise country must be in the list. */\nexport function shippingCountryAllowed(country: string, policy: PolicyBlock | null | undefined): boolean {\n  if (!policy?.allowedShippingCountries || policy.allowedShippingCountries.length === 0) return true;\n  const allowed = new Set(policy.allowedShippingCountries.map((c) => c.toUpperCase()));\n  return allowed.has(country.toUpperCase());\n}\n\n/**\n * US-state allowlist (e.g. wine).\n *\n * Only enforced for US shipments — non-US shipments are governed by\n * {@link shippingCountryAllowed} independently.\n */\nexport function shippingStateAllowed(\n  state: string,\n  country: string,\n  policy: PolicyBlock | null | undefined,\n): boolean {\n  if (!policy?.allowedShippingStates || policy.allowedShippingStates.length === 0) return true;\n  if (country.toUpperCase() !== 'US') return true;\n  const allowed = new Set(policy.allowedShippingStates.map((s) => s.toUpperCase()));\n  return allowed.has(state.toUpperCase());\n}\n"],"mappings":"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","names":[]}

package/dist/stripe-multichain/index.d.mts

@@ -187,9 +187,9 @@ declare function createMppxStripe(input: CreateMppxStripeInput): Promise<unknown
  *
  * All three are TTL-bounded (default 300s — long enough for an agent to retry, short
  * enough to bound memory). Backed by Redis when `redisUrl` is set, falls back to
- * in-process Map otherwise. Single-instance servers can use the in-memory cache; ECS
- * Fargate / multi-task deployments need Redis so a deposit lands on whichever task
- * settles it.
+ * in-process Map otherwise. Single-instance servers can use the in-memory cache;
+ * multi-instance deployments need a shared cache (Redis) so a deposit lands on
+ * whichever instance settles it.
  */
 interface PiCacheOptions {
     /** Redis connection URL (e.g. `rediss://…cache.amazonaws.com:6379`). When omitted,

package/dist/stripe-multichain/index.d.ts

@@ -187,9 +187,9 @@ declare function createMppxStripe(input: CreateMppxStripeInput): Promise<unknown
  *
  * All three are TTL-bounded (default 300s — long enough for an agent to retry, short
  * enough to bound memory). Backed by Redis when `redisUrl` is set, falls back to
- * in-process Map otherwise. Single-instance servers can use the in-memory cache; ECS
- * Fargate / multi-task deployments need Redis so a deposit lands on whichever task
- * settles it.
+ * in-process Map otherwise. Single-instance servers can use the in-memory cache;
+ * multi-instance deployments need a shared cache (Redis) so a deposit lands on
+ * whichever instance settles it.
  */
 interface PiCacheOptions {
     /** Redis connection URL (e.g. `rediss://…cache.amazonaws.com:6379`). When omitted,