@agent-score/commerce 1.8.1 → 2.0.0

package/dist/discovery/index.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,24 +17,42 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/discovery/index.ts
 var discovery_exports = {};
 __export(discovery_exports, {
+  PURCHASE_MODE_NOTES: () => PURCHASE_MODE_NOTES,
   agentscoreDenialSchemas: () => agentscoreDenialSchemas,
   agentscoreOpenApiSnippets: () => agentscoreOpenApiSnippets,
   agentscorePaymentRequiredSchema: () => agentscorePaymentRequiredSchema,
   agentscoreSecuritySchemes: () => agentscoreSecuritySchemes,
   applyNoindexHeader: () => applyNoindexHeader,
+  bootstrapUcpSigningKey: () => bootstrapUcpSigningKey,
+  buildAgentscoreOnboardingSteps: () => buildAgentscoreOnboardingSteps,
   buildDiscoveryProbeResponse: () => buildDiscoveryProbeResponse,
   buildLlmsTxt: () => buildLlmsTxt,
+  buildMerchantIndexJson: () => buildMerchantIndexJson,
+  buildRedemptionSkillMd: () => buildRedemptionSkillMd,
+  buildSignedJwksResponse: () => buildSignedJwksResponse,
+  buildSignedUcpResponse: () => buildSignedUcpResponse,
   buildSkillMd: () => buildSkillMd,
+  buildSuccessNextSteps: () => buildSuccessNextSteps,
   buildWellKnownMpp: () => buildWellKnownMpp,
   buildWellKnownX402: () => buildWellKnownX402,
   compatibleClientsByRails: () => compatibleClientsByRails,
   createBazaarDiscovery: () => createBazaarDiscovery,
+  defaultA2aServices: () => defaultA2aServices,
   defaultDiscoveryPaths: () => defaultDiscoveryPaths,
+  echoRequestIdHeaderHono: () => echoRequestIdHeaderHono,
   isDiscoveryPath: () => isDiscoveryPath,
   isDiscoveryProbeRequest: () => isDiscoveryProbeRequest,
   llmsTxtIdentitySection: () => llmsTxtIdentitySection,
@@ -40,11 +60,22 @@ __export(discovery_exports, {
   noindexNonDiscoveryPaths: () => noindexNonDiscoveryPaths,
   noindexNonDiscoveryPathsExpress: () => noindexNonDiscoveryPathsExpress,
   noindexNonDiscoveryPathsFastify: () => noindexNonDiscoveryPathsFastify,
+  purchaseModeNote: () => purchaseModeNote,
   sampleX402AcceptForNetwork: () => sampleX402AcceptForNetwork,
+  signedResponseExpress: () => signedResponseExpress,
+  signedResponseFastify: () => signedResponseFastify,
+  signedResponseHono: () => signedResponseHono,
+  signedResponseNextjs: () => signedResponseNextjs,
+  signedResponseWeb: () => signedResponseWeb,
   siwxSecurityScheme: () => siwxSecurityScheme,
+  standardEndpointDescriptions: () => standardEndpointDescriptions,
+  wellKnownCorsPreflightHeaders: () => wellKnownCorsPreflightHeaders,
+  wellKnownPreflightResponse: () => wellKnownPreflightResponse,
   wrapNoindexResponse: () => wrapNoindexResponse,
   xGuidanceExtension: () => xGuidanceExtension,
-  xPaymentInfoExtension: () => xPaymentInfoExtension
+  xPaymentInfoExtension: () => xPaymentInfoExtension,
+  xPaymentInfoFromCheckout: () => xPaymentInfoFromCheckout,
+  xServiceInfoExtension: () => xServiceInfoExtension
 });
 module.exports = __toCommonJS(discovery_exports);
 
@@ -158,32 +189,52 @@ function lookupRail(name) {
 }
 
 // src/payment/directive.ts
-function buildPaymentRequestBlob(input) {
-  const railDef = input.rail ? lookupRail(input.rail) : void 0;
-  const decimals = input.decimals ?? railDef?.decimals ?? 6;
-  const currency = input.currency ?? railDef?.currency ?? "usd";
-  const chainId = input.chainId ?? railDef?.chainId;
-  const amountNum = typeof input.amountUsd === "string" ? Number(input.amountUsd) : input.amountUsd;
-  const amountRaw = BigInt(Math.round(amountNum * 10 ** decimals)).toString();
-  const blob = { amount: amountRaw, currency, decimals };
-  if (input.recipient) blob.recipient = input.recipient;
+function buildPaymentRequestBlob({
+  rail,
+  amountUsd,
+  currency,
+  decimals,
+  recipient,
+  chainId,
+  networkId
+}) {
+  const railDef = rail ? lookupRail(rail) : void 0;
+  const decimalsResolved = decimals ?? railDef?.decimals ?? 6;
+  const currencyResolved = currency ?? railDef?.currency ?? "usd";
+  const chainIdResolved = chainId ?? railDef?.chainId;
+  const amountNum = typeof amountUsd === "string" ? Number(amountUsd) : amountUsd;
+  const amountRaw = BigInt(Math.round(amountNum * 10 ** decimalsResolved)).toString();
+  const blob = { amount: amountRaw, currency: currencyResolved, decimals: decimalsResolved };
+  if (recipient) blob.recipient = recipient;
   const methodDetails = {};
-  if (chainId !== void 0) methodDetails.chainId = chainId;
-  if (input.networkId) methodDetails.networkId = input.networkId;
+  if (chainIdResolved !== void 0) methodDetails.chainId = chainIdResolved;
+  if (networkId) methodDetails.networkId = networkId;
   if (Object.keys(methodDetails).length > 0) blob.methodDetails = methodDetails;
   return Buffer.from(JSON.stringify(blob)).toString("base64url");
 }
-function paymentDirective(input) {
-  const railDef = input.rail ? lookupRail(input.rail) : void 0;
-  const method = input.method ?? railDef?.method ?? "unknown";
-  const intent = input.intent ?? "charge";
-  const expires = input.expires ?? new Date(Date.now() + 5 * 60 * 1e3).toISOString();
-  return `Payment id="${input.id}", realm="${input.realm}", method="${method}", intent="${intent}", expires="${expires}", request="${input.request}"`;
+function paymentDirective({
+  rail,
+  id,
+  realm,
+  method,
+  intent,
+  expires,
+  request
+}) {
+  const railDef = rail ? lookupRail(rail) : void 0;
+  const methodResolved = method ?? railDef?.method ?? "unknown";
+  const intentResolved = intent ?? "charge";
+  const expiresResolved = expires ?? new Date(Date.now() + 5 * 60 * 1e3).toISOString();
+  return `Payment id="${id}", realm="${realm}", method="${methodResolved}", intent="${intentResolved}", expires="${expiresResolved}", request="${request}"`;
 }
 
 // src/payment/wwwauthenticate.ts
-function paymentRequiredHeader(input) {
-  return Buffer.from(JSON.stringify(input)).toString("base64");
+function paymentRequiredHeader({
+  x402Version,
+  accepts,
+  resource
+}) {
+  return Buffer.from(JSON.stringify({ x402Version, accepts, ...resource ? { resource } : {} })).toString("base64");
 }
 
 // src/discovery/probe.ts
@@ -311,26 +362,36 @@ async function dynamicImport(moduleName) {
 }
 
 // src/discovery/well_known_mpp.ts
-function buildWellKnownMpp(input) {
+function buildWellKnownMpp({
+  name,
+  description,
+  url,
+  openapi,
+  endpoints,
+  catalog,
+  purchase,
+  shipping,
+  extra
+}) {
   return {
-    name: input.name,
-    ...input.description ? { description: input.description } : {},
-    url: input.url,
-    ...input.openapi ? { openapi: input.openapi } : {},
-    endpoints: input.endpoints,
-    ...input.catalog ? { catalog: input.catalog } : {},
+    name,
+    ...description ? { description } : {},
+    url,
+    ...openapi ? { openapi } : {},
+    endpoints,
+    ...catalog ? { catalog } : {},
     purchase: {
-      ...input.purchase.required_fields ? { required_fields: input.purchase.required_fields } : {},
-      ...input.purchase.optional_fields ? { optional_fields: input.purchase.optional_fields } : {},
-      ...input.purchase.extra ?? {},
-      ...input.purchase.identity ? { identity: input.purchase.identity } : {},
-      ...input.purchase.identity_paths ? { identity_paths: input.purchase.identity_paths } : {},
-      payment_methods: input.purchase.methods,
-      ...input.purchase.x402 ? { x402: input.purchase.x402 } : {},
-      ...input.purchase.compliance ? { compliance: input.purchase.compliance } : {}
+      ...purchase.required_fields ? { required_fields: purchase.required_fields } : {},
+      ...purchase.optional_fields ? { optional_fields: purchase.optional_fields } : {},
+      ...purchase.extra ?? {},
+      ...purchase.identity ? { identity: purchase.identity } : {},
+      ...purchase.identity_paths ? { identity_paths: purchase.identity_paths } : {},
+      payment_methods: purchase.methods,
+      ...purchase.x402 ? { x402: purchase.x402 } : {},
+      ...purchase.compliance ? { compliance: purchase.compliance } : {}
     },
-    ...input.shipping ? { shipping: input.shipping } : {},
-    ...input.extra ?? {}
+    ...shipping ? { shipping } : {},
+    ...extra ?? {}
   };
 }
 
@@ -343,11 +404,13 @@ function buildWellKnownX402(input) {
 }
 
 // src/discovery/llms_txt.ts
-function llmsTxtIdentitySection(input = {}) {
-  if (!input.agentscore) {
+function llmsTxtIdentitySection({
+  agentscore,
+  compliance
+} = {}) {
+  if (!agentscore) {
     return "";
   }
-  const compliance = input.compliance;
   const complianceNote = compliance ? `
 
 Compliance: ${[
@@ -452,31 +515,37 @@ function llmsTxtPaymentSectionVerbose(input) {
     lines.push("Mint a SharedPaymentToken scoped to the `profile_id` from the 402 body, then submit via `Authorization: Payment` with `method=stripe/charge`. Either your own Stripe account or `link-cli spend-request create --credential-type shared_payment_token --network-id <profileId> ...` for Stripe Link wallets.");
     lines.push("");
   }
-  lines.push("IMPORTANT: Use the CLIs above. Raw on-chain transfers (e.g. `tempo wallet transfer`, sending USDC manually to deposit addresses) bypass the protocol handshake and the order will not complete.");
+  lines.push("IMPORTANT: Use the CLIs above. Raw on-chain transfers (e.g. `tempo wallet transfer`, sending USDC manually to deposit addresses) bypass the protocol handshake and the request will not complete.");
   if (hasBase || hasSolana) {
     lines.push("IMPORTANT: Pay the exact amount in the 402 challenge. Overpayments and underpayments cannot be matched.");
   }
   lines.push("");
   return lines.join("\n");
 }
-function buildLlmsTxt(input) {
-  const parts = [`# ${input.merchantName}`];
-  if (input.tagline) {
-    parts.push(`> ${input.tagline}`);
+function buildLlmsTxt({
+  merchantName,
+  tagline,
+  sections,
+  agentscoreIdentity,
+  payment
+}) {
+  const parts = [`# ${merchantName}`];
+  if (tagline) {
+    parts.push(`> ${tagline}`);
   }
   parts.push("");
-  for (const s of input.sections) {
+  for (const s of sections) {
     parts.push(`## ${s.heading}`);
     parts.push("");
     parts.push(s.content);
     parts.push("");
   }
-  if (input.agentscoreIdentity) {
-    parts.push(llmsTxtIdentitySection(input.agentscoreIdentity));
+  if (agentscoreIdentity) {
+    parts.push(llmsTxtIdentitySection(agentscoreIdentity));
     parts.push("");
   }
-  if (input.payment) {
-    parts.push(llmsTxtPaymentSection(input.payment));
+  if (payment) {
+    parts.push(llmsTxtPaymentSection(payment));
   }
   return parts.join("\n");
 }
@@ -577,21 +646,88 @@ function agentscorePaymentRequiredSchema() {
     }
   };
 }
-function xPaymentInfoExtension(input) {
-  return { "x-payment-info": { price: input.price, protocols: input.protocols } };
+function xPaymentInfoExtension({
+  price,
+  protocols,
+  description
+}) {
+  return {
+    "x-payment-info": {
+      authMode: "payment",
+      price,
+      protocols,
+      ...description !== void 0 && { description }
+    }
+  };
 }
 function xGuidanceExtension(text) {
   return { "x-guidance": text };
 }
-function agentscoreOpenApiSnippets(opts = {}) {
+function xServiceInfoExtension(opts) {
+  return {
+    "x-service-info": {
+      categories: opts.categories,
+      ...opts.docs !== void 0 && { docs: opts.docs }
+    }
+  };
+}
+function xPaymentInfoFromCheckout(opts) {
+  const protocols = [];
+  const extras = opts.protocolExtras ?? {};
+  for (const spec of Object.values(opts.checkout.rails)) {
+    const isStripe2 = !("recipient" in spec);
+    const network = typeof spec.network === "string" ? spec.network : "";
+    const tokenCurrency = (typeof spec.currency === "string" ? spec.currency : "") || (typeof spec.token === "string" ? spec.token : "");
+    if (isStripe2) {
+      protocols.push({ mpp: { method: "stripe", intent: "charge", currency: "usd", ...extras.stripe ?? {} } });
+    } else if (network.startsWith("eip155:")) {
+      protocols.push({
+        x402: {
+          scheme: "exact",
+          network: "base",
+          asset: "USDC",
+          ...extras.base ?? {}
+        }
+      });
+    } else if (network.startsWith("solana:")) {
+      protocols.push({
+        mpp: {
+          method: "solana",
+          intent: "charge",
+          ...tokenCurrency ? { currency: tokenCurrency } : {},
+          ...extras.solana ?? {}
+        }
+      });
+    } else {
+      protocols.push({
+        mpp: {
+          method: "tempo",
+          intent: "charge",
+          ...tokenCurrency ? { currency: tokenCurrency } : {},
+          ...extras.tempo ?? {}
+        }
+      });
+    }
+  }
+  return xPaymentInfoExtension({
+    price: opts.price,
+    protocols,
+    ...opts.description !== void 0 && { description: opts.description }
+  });
+}
+function agentscoreOpenApiSnippets({
+  security = true,
+  denials = true,
+  paymentRequired = true
+} = {}) {
   const out = {};
-  if (opts.security !== false) {
+  if (security) {
     out.securitySchemes = agentscoreSecuritySchemes();
   }
-  if (opts.denials !== false || opts.paymentRequired !== false) {
+  if (denials || paymentRequired) {
     out.schemas = {
-      ...opts.denials !== false ? agentscoreDenialSchemas() : {},
-      ...opts.paymentRequired !== false ? agentscorePaymentRequiredSchema() : {}
+      ...denials ? agentscoreDenialSchemas() : {},
+      ...paymentRequired ? agentscorePaymentRequiredSchema() : {}
     };
   }
   return out;
@@ -869,21 +1005,908 @@ function buildSkillMd(input) {
   ].filter((s) => s !== "");
   return sections.join("\n\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
 }
+
+// src/discovery/agentscore_content.ts
+var PURCHASE_MODE_NOTES = Object.freeze({
+  redemption_only: "Requires a single-use redemption code (printed on a mailer or other out-of-band delivery). Submit the code in the request body as `redemption_code`. Without a valid code the order is rejected.",
+  coupon_applicable: "Codes are optional. Without one, settle at list price. With a valid code the discount is applied automatically (percent_off, fixed_off, or fixed_settle).",
+  paid_only: "Codes are NOT accepted. Settle at the listed price. Submitting a `redemption_code` field returns 400 codes_not_accepted."
+});
+function purchaseModeNote(mode) {
+  return PURCHASE_MODE_NOTES[mode] ?? "";
+}
+function buildAgentscoreOnboardingSteps(opts) {
+  const { merchantName, appUrl, acceptedRails, requiresKyc = false, vendorType = "goods" } = opts;
+  const railWordMap = {
+    tempo: "Tempo USDC",
+    "x402-base": "x402 USDC on Base",
+    "solana-mpp": "Solana SPL USDC",
+    "stripe-spt": "Stripe Shared Payment Token"
+  };
+  const railsHuman = acceptedRails.map((r) => railWordMap[r] ?? r).join(", ");
+  const chainPairs = [
+    ["tempo", "tempo"],
+    ["x402-base", "base"],
+    ["solana-mpp", "solana"]
+  ];
+  const flags = chainPairs.filter(([rail]) => acceptedRails.includes(rail)).map(([, flag]) => flag);
+  const chainFlags = flags.length > 0 ? flags.join(" | ") : "tempo|base";
+  const compatibleHints = [
+    ["tempo", "`tempo request` works for tempo USDC.e"],
+    ["x402-base", "`x402-proxy` / `purl` work for Base x402"],
+    ["stripe-spt", "`@stripe/link-cli` works for Stripe SPT"]
+  ];
+  const compatibleFragment = compatibleHints.filter(([rail]) => acceptedRails.includes(rail)).map(([, hint]) => hint).join(", ");
+  const installStep = `Install agentscore-pay if you don't already have a compatible client for your funded chain: \`npm i -g @agent-score/pay\` (or \`brew install agentscore/tap/agentscore-pay\`). ${merchantName} accepts: ${railsHuman}. agentscore-pay speaks every supported rail; ` + (compatibleFragment ? `the rails table also lists per-rail \`compatible_clients\` \u2014 ${compatibleFragment}. ` : "") + "Any spec-compliant client for an individual rail works too.";
+  const bootstrapStep = `First-run only: bootstrap wallet + Passport. Run \`agentscore-pay agent-guide --json\` for the canonical cold-start path \u2014 it walks \`agentscore-pay init\` (creates keystore + per-chain wallet), \`agentscore-pay passport login\` (one-time KYC${requiresKyc ? "; required for this merchant" : ""}; the human completes a verify URL once and pay caches the operator_token), and \`agentscore-pay balance\` to see which chain has USDC. Skip if your wallet+Passport are already provisioned.`;
+  const stripeFallbackStep = "If your only payment method is a Stripe / Link card (no crypto), install `@stripe/link-cli` instead of agentscore-pay and use it on the SPT rail. Identity gating still applies \u2014 the merchant's 403 with `verify_url` lets you bootstrap a Passport even with no crypto wallet involved.";
+  const returningUserStep = "Returning user note: if you've paid an AgentScore-gated merchant before from this wallet, the wallet is already in your Passport's `linked_wallets[]` and identity flows through automatically with no re-KYC prompt. Paying from a NEW wallet while you already hold an `opc_...` token returns 403 `wallet_signer_mismatch`; the body lists `linked_wallets[]` and `agent_instructions.action: resign_or_switch_to_operator_token` with three deterministic recoveries (switch to a linked wallet, drop the operator_token to re-KYC the new wallet, or pre-claim the new wallet via SIWE on agentscore.sh/verify).";
+  const pickRailStep = `Pick the rail your wallet is funded for. The 402 advertises ${acceptedRails.length} rail${acceptedRails.length === 1 ? "" : "s"}. \`agentscore-pay balance\` (without \`--chain\`) lists every chain's USDC; pay rejects with \`multi_rail_ambiguity\` if you don't pass \`--chain\` on a multi-rail challenge.`;
+  const placeOrderStep = `Place the order: \`agentscore-pay pay POST ${appUrl}/purchase --chain <${chainFlags}> -d '<body>' --max-spend <amount>\` for crypto rails. For Stripe SPT, follow the handoff hint pay emits and use \`@stripe/link-cli\` instead. Either way pay handles the 402 retry, signing, and Passport attachment; branch on the structured CliError \`code\` on non-zero exit (insufficient_balance, multi_rail_ambiguity, config_error for missing wallet/Passport, etc.).`;
+  const makeCallStep = `Make the paid call: \`agentscore-pay pay POST ${appUrl}/<endpoint> --chain <${chainFlags}> --max-spend <amount>\`; pay handles 402 retry, rail selection, signing, and Passport attachment. Branch on the structured CliError \`code\` on non-zero exit (insufficient_balance, multi_rail_ambiguity, config_error for missing wallet/Passport, etc.).`;
+  const acceptsStripe = acceptedRails.includes("stripe-spt");
+  if (vendorType === "api") {
+    return [
+      installStep,
+      bootstrapStep,
+      ...acceptsStripe ? [stripeFallbackStep] : [],
+      returningUserStep,
+      pickRailStep,
+      makeCallStep
+    ];
+  }
+  return [
+    installStep,
+    bootstrapStep,
+    ...acceptsStripe ? [stripeFallbackStep] : [],
+    returningUserStep,
+    `Browse the catalog: \`curl ${appUrl}/catalog\`.`,
+    "Read each product's `purchase_mode` and `purchase_note` to decide whether a redemption code is required, optional, or rejected.",
+    pickRailStep,
+    placeOrderStep
+  ];
+}
+function standardEndpointDescriptions(opts) {
+  if (opts?.kind === "api") {
+    return {
+      "POST /<endpoint>": "Per-call paid endpoint. Returns 402 on the discovery leg with payment rails; 400 on body rejection; 403 + recovery payload when identity is required; 200 with the call result on success.",
+      "GET /usage": "Per-credential usage / billing summary. Identity-scoped."
+    };
+  }
+  const out = {
+    "GET /catalog": "List purchasable products.",
+    "GET /catalog/{slug}": "Single product detail.",
+    "POST /purchase": "Place an order. Returns 402 on the discovery leg with payment rails; 400 on body rejection; 403 + recovery payload when identity is required; 200 with order confirmation on success.",
+    "GET /orders/{id}": "Order detail (PII). Identity-scoped."
+  };
+  if (opts?.includeOrderStatusRoute) {
+    out["GET /orders/{id}/status"] = "Payment status only (no PII).";
+  }
+  return out;
+}
+function buildMerchantIndexJson(opts) {
+  return {
+    name: opts.name,
+    description: opts.description,
+    docs: opts.docs,
+    endpoints: opts.endpoints,
+    audience: "agents",
+    supported_rails: opts.supportedRails,
+    ...opts.extra ?? {}
+  };
+}
+function buildSuccessNextSteps(opts) {
+  const out = {
+    action: "done",
+    user_message: opts.userMessage ?? "Payment complete. Your AgentScore Passport is now active across every AgentScore-gated merchant."
+  };
+  if (opts.orderStatusUrl) out.order_status_url = opts.orderStatusUrl;
+  if (opts.fulfillmentEta !== void 0) out.fulfillment_eta = opts.fulfillmentEta;
+  return out;
+}
+
+// src/discovery/redemption_md.ts
+var DEFAULT_BODY_SHAPE = `{
+     "product_slug": "<slug>",
+     "redemption_code": "<code>",
+     "email": "user@example.com",
+     "shipping": { "name": "...", "address_1": "...", "city": "...", "state": "CA", "zip": "94573" }
+   }`;
+var DEFAULT_BODY_RULES = `## Body rules
+
+- \`quantity\` is fixed at 1; one product per code.
+- \`shipping.country\` defaults to \`"US"\`; non-US shipping is rejected for
+  redemption-eligible products.
+- \`shipping.state\` must be a 2-letter US state code; \`unsupported_jurisdiction\`
+  400 if the state isn't on the merchant's allowlist.
+- \`email\` must be valid; the merchant returns 422 on malformed input.`;
+function buildRedemptionSkillMd(opts) {
+  const {
+    merchantName,
+    appUrl,
+    endpointPath = "/purchase",
+    skuIntro,
+    deliveryIntro,
+    bodyShape,
+    bodyRules,
+    extraRecoveryRows,
+    peerMerchantPointer
+  } = opts;
+  const skuText = skuIntro ?? "The code redeems a product or paid call at this merchant which you'll find in the merchant's catalog or per-endpoint documentation with `purchase_mode = redemption_only`.";
+  const deliveryText = deliveryIntro ?? `You're reading this because the user you're working for received a single-use redemption code from ${merchantName} (printed on a mailer, emailed, surfaced in-app, or distributed out-of-band). This page tells you, the agent, exactly how to turn that code into a settled call.`;
+  const renderedBodyShape = bodyShape ?? DEFAULT_BODY_SHAPE;
+  const renderedBodyRules = bodyRules !== void 0 ? bodyRules : DEFAULT_BODY_RULES;
+  const bodyRulesSection = renderedBodyRules ? `
+${renderedBodyRules}
+` : "";
+  const extraRows = extraRecoveryRows ? `
+${extraRecoveryRows.trimEnd()}` : "";
+  const peerSection = peerMerchantPointer ? `
+## Don't have a code?
+
+This page is the redemption flow for single-use codes. If you're looking to buy or call without a code, see: ${peerMerchantPointer}
+` : "";
+  return `# Redeeming an AgentScore code at ${merchantName}
+
+${deliveryText}
+
+${skuText} The 402 challenge on ${endpointPath} tells you the actual settle amount
+after the code is applied; discounts can range from a partial amount off list
+down to free.
+
+## Cold-start bootstrap (skip if your wallet + Passport are already set up)
+
+If \`agentscore-pay\` isn't installed yet, install it (\`npm i -g @agent-score/pay\`
+or \`brew install agentscore/tap/agentscore-pay\`), then run \`agentscore-pay
+agent-guide --json\` for the canonical cold-start path. That walks
+\`agentscore-pay init\` (creates keystore + per-chain wallet),
+\`agentscore-pay passport login\` (one-time KYC; opens a verify URL the human
+completes, after which pay caches the \`operator_token\`), and
+\`agentscore-pay balance\` to confirm funds. Fund enough to cover the
+post-discount settle amount the 402 advertises; for $0 codes the merchant
+skips the on-chain settle entirely so funds aren't required, but the wallet
+still needs to exist so the credential can be signed.
+
+You don't have to use \`agentscore-pay\` specifically; any spec-compliant client
+for the merchant's accepted rails (Tempo MPP, x402 Base, Solana MPP, Stripe SPT)
+works. The 402 challenge lists every accepted rail in \`accepted_methods\`.
+
+## TL;DR
+
+1. Ask the user for their redemption code, plus any merchant-specific fields the
+   body requires (email, shipping address for goods merchants, identifiers for
+   API merchants, etc.).
+2. Discover the redemption-eligible target. Goods merchants: \`GET ${appUrl}/catalog\`
+   and find the product whose \`purchase_mode\` is \`redemption_only\`. API merchants:
+   read the per-endpoint docs for the route that accepts \`redemption_code\`.
+   Read any \`purchase_note\` for product-specific rules.
+3. \`POST ${appUrl}${endpointPath}\` with body:
+   \`\`\`json
+   ${renderedBodyShape}
+   \`\`\`
+4. If you get **403 \`operator_verification_required\`**, surface the body's
+   \`verify_url\` to the user for one-time KYC and poll \`poll_url\` with
+   \`poll_secret\`. After verification, retry with \`X-Operator-Token\` attached.
+   If you already have an \`opc_...\` from a prior AgentScore-gated merchant,
+   attach it on the first call and skip this step.
+5. On **402**, the body carries \`accepted_methods\` and \`agent_instructions.how_to_pay\`.
+   Settle with \`agentscore-pay pay POST ${appUrl}${endpointPath} --chain <rail> -d '<body>'
+   --max-spend <amount>\`; pay handles 402 retry, rail selection, signing, and
+   Passport attachment. Pass \`--max-spend\` >= the amount in the 402.
+6. **200**; the call settled. Response carries a receipt \`id\` (order id for goods,
+   request id for API), \`next_steps.order_status_url\` (or usage dashboard URL),
+   and an \`agent_memory\` block you should persist (the cross-merchant pattern
+   hint, NOT the operator_token or poll_secret). For $0 redemptions \`tx_hash\`
+   is \`null\`; the credential is still authenticated and the code is burned
+   single-use.
+${bodyRulesSection}
+## Code rules
+
+- Codes are case-insensitive (server uppercases on receipt), single-use, and
+  burned atomically against \`(code, operator_token)\` OR \`(code, signer_address)\`
+  for token-less wallet flows. A second attempt returns 400 \`redemption_already_used\`.
+- Submit the code in the JSON body as \`"redemption_code"\`; never as a header.
+
+## Recovery on common errors
+
+| HTTP | error.code | What it means | What to do |
+|---|---|---|---|
+| 403 | \`operator_verification_required\` | User has no Passport / KYC pending | Surface \`verify_url\`; poll \`poll_url\` with \`poll_secret\`; retry with \`X-Operator-Token\` |
+| 403 | \`wallet_signer_mismatch\` | Operator token + signer wallet aren't linked to the same identity | Switch to a wallet in \`linked_wallets[]\`, or drop the operator_token to re-KYC the new wallet |
+| 400 | \`invalid_body\` | JSON parse failed | Fix the JSON and retry |
+| 400 | \`missing_fields\` | Required field absent | Add the field per \`error.message\` and retry |
+| 400 | \`product_not_found\` | Identifier doesn't match an active product / endpoint | Re-check the catalog or endpoint docs and use the exact slug / route |
+| 400 | \`product_out_of_stock\` | Goods-only: stock 0 | Tell the user; no retry possible |
+| 400 | \`invalid_redemption_code\` | Code unknown / expired | Ask the user for the code as printed; do not invent variants |
+| 400 | \`redemption_already_used\` | Code burned | Tell the user; codes are single-use |
+| 400 | \`codes_not_accepted\` | Target is \`paid_only\` and rejects codes | Drop \`redemption_code\` and retry, or pick a different target |
+| 402 | (challenge) | Identity OK; payment required | Run \`agentscore-pay pay\` against the same URL |${extraRows}
+${peerSection}`;
+}
+
+// src/identity/ucp.ts
+function ucpSigningKeyFromJWKImpl(jwk) {
+  if (!jwk || typeof jwk !== "object") {
+    throw new Error(`UCPSigningKey.fromJWK expected a non-null object; got ${typeof jwk}.`);
+  }
+  if (typeof jwk.kid !== "string" || !jwk.kid) {
+    throw new Error("UCPSigningKey.fromJWK: JWK missing required field `kid` (or non-string).");
+  }
+  if (typeof jwk.kty !== "string" || !jwk.kty) {
+    throw new Error("UCPSigningKey.fromJWK: JWK missing required field `kty` (or non-string).");
+  }
+  if (jwk.kty !== "OKP" && jwk.kty !== "EC" && jwk.kty !== "RSA") {
+    throw new Error(
+      `UCPSigningKey.fromJWK: kty=${JSON.stringify(jwk.kty)} is not a supported asymmetric key type (expected OKP, EC, or RSA). Symmetric \`oct\` keys are rejected because they cannot publicly verify a JWS in the trust-mode UCP flow.`
+    );
+  }
+  if ((jwk.kty === "EC" || jwk.kty === "OKP") && (typeof jwk.crv !== "string" || !jwk.crv)) {
+    throw new Error(`UCPSigningKey.fromJWK: kty=${jwk.kty} requires a non-empty \`crv\` field (e.g., "P-256" for EC, "Ed25519" for OKP).`);
+  }
+  return jwk;
+}
+var UCPSigningKey = {
+  fromJWK: ucpSigningKeyFromJWKImpl
+};
+var DEFAULT_VERSION = "2026-04-08";
+var AGENTSCORE_CAPABILITY_NAME = "sh.agentscore.identity";
+var AGENTSCORE_CAPABILITY_VERSION = "2026-04-08";
+var AGENTSCORE_DEFAULT_SPEC_URL = "https://agentscore.sh/specification/identity";
+var AGENTSCORE_DEFAULT_SCHEMA_URL = "https://agentscore.sh/schemas/ucp/sh-agentscore-identity-v1.json";
+var AGENTSCORE_EXTENDS = ["dev.ucp.shopping.checkout", "dev.ucp.shopping.cart"];
+var RESERVED_TOP_LEVEL = /* @__PURE__ */ new Set([
+  "ucp",
+  "signing_keys",
+  "signature",
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
+var RESERVED_UCP_FIELDS = /* @__PURE__ */ new Set([
+  "version",
+  "name",
+  "services",
+  "capabilities",
+  "payment_handlers",
+  "supported_versions",
+  "__proto__",
+  "constructor",
+  "prototype"
+]);
+function buildUCPProfile(input) {
+  for (const [name, bindings] of Object.entries(input.services ?? {})) {
+    for (const binding of bindings) {
+      if ((binding.transport === "rest" || binding.transport === "mcp" || binding.transport === "a2a") && (binding.endpoint === void 0 || binding.endpoint === null || binding.endpoint === "")) {
+        throw new Error(
+          `buildUCPProfile: service "${name}" transport=${binding.transport} requires \`endpoint\`. Per UCP spec service.json business_schema, rest/mcp/a2a bindings MUST carry an endpoint URL.`
+        );
+      }
+    }
+  }
+  const paymentHandlers = {};
+  for (const [name, bindings] of Object.entries(input.payment_handlers ?? {})) {
+    paymentHandlers[name] = bindings.map((binding) => {
+      if (Array.isArray(binding.available_instruments) && binding.available_instruments.length === 0) {
+        const { available_instruments: _drop, ...rest } = binding;
+        return rest;
+      }
+      return binding;
+    });
+  }
+  const capabilities = {};
+  for (const [name, bindings] of Object.entries(input.capabilities ?? {})) {
+    capabilities[name] = [...bindings];
+  }
+  if (input.agentscore_gate) {
+    const gateConfig = { ...input.agentscore_gate };
+    const agentscoreBinding = {
+      version: AGENTSCORE_CAPABILITY_VERSION,
+      spec: input.agentscore_spec_url ?? AGENTSCORE_DEFAULT_SPEC_URL,
+      schema: input.agentscore_schema_url ?? AGENTSCORE_DEFAULT_SCHEMA_URL,
+      extends: AGENTSCORE_EXTENDS
+    };
+    if (Object.keys(gateConfig).length > 0) agentscoreBinding.config = gateConfig;
+    const existing = capabilities[AGENTSCORE_CAPABILITY_NAME];
+    if (existing) existing.push(agentscoreBinding);
+    else capabilities[AGENTSCORE_CAPABILITY_NAME] = [agentscoreBinding];
+  }
+  const ucp = {
+    version: input.version ?? DEFAULT_VERSION,
+    services: input.services ?? {},
+    capabilities,
+    payment_handlers: paymentHandlers
+  };
+  if (input.name !== void 0) ucp.name = input.name;
+  if (input.supported_versions !== void 0) ucp.supported_versions = input.supported_versions;
+  if (input.ucp_extras) {
+    for (const k of Object.keys(input.ucp_extras)) {
+      if (RESERVED_UCP_FIELDS.has(k)) {
+        throw new Error(`buildUCPProfile: ucp_extras key "${k}" collides with a reserved \`ucp\` field; rejected.`);
+      }
+    }
+    Object.assign(ucp, input.ucp_extras);
+  }
+  const profile = {
+    ucp,
+    signing_keys: input.signing_keys
+  };
+  if (input.extras) {
+    for (const k of Object.keys(input.extras)) {
+      if (RESERVED_TOP_LEVEL.has(k)) {
+        throw new Error(`buildUCPProfile: extras key "${k}" collides with a reserved profile field; rejected.`);
+      }
+    }
+    Object.assign(profile, input.extras);
+  }
+  return profile;
+}
+var HANDLER_VERSION = "2026-04-08";
+var SPEC_BASE = "https://agentscore.sh/specification/payment-handlers";
+var SCHEMA_BASE = "https://agentscore.sh/schemas/payment-handlers";
+var CAIP2_TO_UCP_NETWORK = {
+  "eip155:8453": "base-8453",
+  "eip155:84532": "base-84532",
+  "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp": "solana-mainnet-beta",
+  "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1": "solana-devnet"
+};
+function ucpNetworkName(caip2OrUcp, fallback) {
+  if (caip2OrUcp === void 0) return fallback;
+  return CAIP2_TO_UCP_NETWORK[caip2OrUcp] ?? caip2OrUcp;
+}
+function staticRecipient(r) {
+  return typeof r === "string" && r.length > 0 ? r : void 0;
+}
+function tempoToNetworkEntry(spec) {
+  const entry = {
+    network: spec.testnet ? "tempo-testnet" : spec.network ?? "tempo-mainnet",
+    chain_id: spec.chainId ?? 4217
+  };
+  const recipient = staticRecipient(spec.recipient);
+  if (recipient !== void 0) entry.recipient = recipient;
+  return entry;
+}
+function solanaMppToNetworkEntry(spec) {
+  const entry = {
+    network: ucpNetworkName(spec.network, "solana-mainnet-beta")
+  };
+  const recipient = staticRecipient(spec.recipient);
+  if (recipient !== void 0) entry.recipient = recipient;
+  return entry;
+}
+function tempoSessionToNetworkEntry(spec) {
+  const entry = {
+    network: spec.testnet ? "tempo-testnet" : "tempo-mainnet",
+    escrow_contract: spec.escrowContract
+  };
+  const recipient = staticRecipient(spec.recipient);
+  if (recipient !== void 0) entry.recipient = recipient;
+  return entry;
+}
+function isTempoRailSpec(s) {
+  return !("escrowContract" in s) && !("rpcUrl" in s) && !("tokenProgram" in s);
+}
+function isTempoSessionRailSpec(s) {
+  return "escrowContract" in s && "store" in s;
+}
+function mppRailToNetworkEntry(spec) {
+  if (isTempoSessionRailSpec(spec)) return tempoSessionToNetworkEntry(spec);
+  if ("rpcUrl" in spec || "tokenProgram" in spec || (spec.network?.startsWith("solana:") ?? false)) {
+    return solanaMppToNetworkEntry(spec);
+  }
+  if (isTempoRailSpec(spec)) return tempoToNetworkEntry(spec);
+  return tempoToNetworkEntry(spec);
+}
+function mppPaymentHandler({
+  networks: networks2
+}) {
+  return {
+    "sh.agentscore.payment.mpp": [{
+      id: "mpp",
+      version: HANDLER_VERSION,
+      spec: `${SPEC_BASE}/mpp`,
+      schema: `${SCHEMA_BASE}/mpp.json`,
+      config: { networks: networks2.map(mppRailToNetworkEntry) }
+    }]
+  };
+}
+function x402RailToNetworkEntry(spec) {
+  const entry = {
+    network: ucpNetworkName(spec.network, "base-8453")
+  };
+  const recipient = staticRecipient(spec.recipient);
+  if (recipient !== void 0) entry.recipient = recipient;
+  return entry;
+}
+function x402PaymentHandler({
+  networks: networks2
+}) {
+  return {
+    "sh.agentscore.payment.x402": [{
+      id: "x402",
+      version: HANDLER_VERSION,
+      spec: `${SPEC_BASE}/x402`,
+      schema: `${SCHEMA_BASE}/x402.json`,
+      config: { networks: networks2.map(x402RailToNetworkEntry) }
+    }]
+  };
+}
+function stripeSptPaymentHandler({
+  spec
+}) {
+  return {
+    "sh.agentscore.payment.stripe_spt": [{
+      id: "stripe-spt",
+      version: HANDLER_VERSION,
+      spec: `${SPEC_BASE}/stripe_spt`,
+      schema: `${SCHEMA_BASE}/stripe_spt.json`,
+      config: { rail: "stripe-spt", profile_id: spec.profileId ?? null }
+    }]
+  };
+}
+
+// src/identity/ucp-jwks.ts
+var JOSE_INSTALL_HINT = "Install the optional peer dependency: `npm install jose@^6` (or `bun add jose`). Tested against jose v6.x.";
+var ALLOWED_ALGS = ["EdDSA", "ES256"];
+var PROFILE_TYP = "agentscore-profile+jws";
+async function loadJose() {
+  try {
+    return await import("jose");
+  } catch (err) {
+    throw new Error(
+      `UCP signing requires the \`jose\` library, which is an optional peer dependency. ${JOSE_INSTALL_HINT}
+Original error: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function canonicalizeProfile(profile) {
+  const stripped = { ...profile };
+  delete stripped.signature;
+  return stableStringify(stripped);
+}
+function stableStringify(value) {
+  if (value === void 0) {
+    throw new Error(
+      "stableStringify: undefined values are not allowed in canonicalized JSON. Object fields with no value must be omitted."
+    );
+  }
+  if (typeof value === "function" || typeof value === "symbol") {
+    throw new Error(`stableStringify: ${typeof value} values are not allowed in canonicalized JSON.`);
+  }
+  if (typeof value === "bigint") {
+    throw new Error("stableStringify: BigInt values are not allowed; use a decimal string.");
+  }
+  if (value instanceof Date) {
+    throw new Error(
+      "stableStringify: Date instances are not allowed; serialize to an ISO string before passing."
+    );
+  }
+  if (value instanceof Map || value instanceof Set || value instanceof WeakMap || value instanceof WeakSet) {
+    throw new Error(
+      `stableStringify: ${value.constructor.name} values are not allowed; convert to a plain object/array first.`
+    );
+  }
+  if (ArrayBuffer.isView(value)) {
+    throw new Error("stableStringify: typed arrays are not allowed; convert to a plain array first.");
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(
+        `UCP profile canonicalization rejects non-finite Number ${value}. Use a decimal string for any value that may be NaN/Infinity.`
+      );
+    }
+    if (!Number.isInteger(value)) {
+      throw new Error(
+        `UCP profile canonicalization rejects non-integer Number ${value}. Use a decimal string (e.g. "9.99") for monetary or fractional fields to preserve cross-language byte-parity.`
+      );
+    }
+    if (!Number.isSafeInteger(value)) {
+      throw new Error(
+        `stableStringify: integer ${value} exceeds Number.MAX_SAFE_INTEGER. For values >2^53, use a decimal string to preserve cross-language byte parity.`
+      );
+    }
+  }
+  if (typeof value === "string") {
+    if (value.includes("\u2028") || value.includes("\u2029")) {
+      throw new Error(
+        "stableStringify: strings containing U+2028 (LINE SEPARATOR) or U+2029 (PARAGRAPH SEPARATOR) are not allowed; cross-language byte parity requires neither be present (Node JSON.stringify on older V8 escapes them; Python json.dumps with ensure_ascii=False does not)."
+      );
+    }
+    return JSON.stringify(value);
+  }
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const obj = value;
+  const keys = Object.keys(obj).sort((a, b) => {
+    const aPoints = [...a].map((c) => c.codePointAt(0));
+    const bPoints = [...b].map((c) => c.codePointAt(0));
+    const len = Math.min(aPoints.length, bPoints.length);
+    for (let i = 0; i < len; i += 1) {
+      if (aPoints[i] !== bPoints[i]) return aPoints[i] - bPoints[i];
+    }
+    return aPoints.length - bPoints.length;
+  });
+  for (const k of keys) {
+    if (k.includes("\u2028") || k.includes("\u2029")) {
+      throw new Error(
+        "stableStringify: object keys containing U+2028 (LINE SEPARATOR) or U+2029 (PARAGRAPH SEPARATOR) are not allowed; cross-language byte parity (Node JSON.stringify on older V8 escapes them; Python json.dumps with ensure_ascii=False does not)."
+      );
+    }
+  }
+  const pairs = keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`);
+  return `{${pairs.join(",")}}`;
+}
+async function generateUCPSigningKey(opts) {
+  const jose = await loadJose();
+  const alg = opts.alg ?? "EdDSA";
+  const { privateKey, publicKey } = await jose.generateKeyPair(alg, { extractable: true });
+  const exportedJwk = await jose.exportJWK(publicKey);
+  const publicJWK = {
+    kid: opts.kid,
+    alg,
+    use: "sig",
+    ...exportedJwk
+  };
+  return { privateKey, publicJWK };
+}
+async function signUCPProfile(profile, {
+  signingKey,
+  kid,
+  alg = "EdDSA"
+}) {
+  const jose = await loadJose();
+  if (!ALLOWED_ALGS.includes(alg)) {
+    throw new Error(
+      `signUCPProfile: alg ${JSON.stringify(alg)} is not in the supported set [${ALLOWED_ALGS.join(", ")}].`
+    );
+  }
+  if (typeof kid !== "string" || !kid) {
+    throw new Error("signUCPProfile: kid must be a non-empty string.");
+  }
+  const kids = (profile.signing_keys ?? []).map((k) => k.kid);
+  if (!kids.includes(kid)) {
+    throw new Error(
+      `signUCPProfile: kid ${JSON.stringify(kid)} is not present in profile.signing_keys[] (declared kids: ${JSON.stringify(kids)}). Verifiers will not find the key.`
+    );
+  }
+  const canonicalBody = canonicalizeProfile(profile);
+  const payloadBytes = new TextEncoder().encode(canonicalBody);
+  const signature = await new jose.CompactSign(payloadBytes).setProtectedHeader({ alg, kid, typ: PROFILE_TYP }).sign(signingKey);
+  return { ...profile, signature };
+}
+function buildJWKSResponse(keys) {
+  return { keys };
+}
+var DEFAULT_LOAD_OPTS = {
+  envJwkVar: "UCP_SIGNING_KEY_JWK_PRIVATE",
+  envKidVar: "UCP_SIGNING_KEY_KID",
+  envAlgVar: "UCP_SIGNING_KEY_ALG",
+  defaultKid: "merchant-default",
+  defaultAlg: "EdDSA"
+};
+function readEnvTrimmed(name) {
+  const raw = process.env[name];
+  if (raw === void 0) return void 0;
+  const trimmed = raw.trim();
+  return trimmed === "" ? void 0 : trimmed;
+}
+function detectAlgFromJwk(jwk) {
+  if (jwk.kty === "OKP" && jwk.crv === "Ed25519") return "EdDSA";
+  if (jwk.kty === "EC" && jwk.crv === "P-256") return "ES256";
+  return null;
+}
+var envLoaderCache = /* @__PURE__ */ new Map();
+function cacheKey(opts) {
+  return `${opts.envJwkVar}|${opts.envKidVar}|${opts.envAlgVar}|${opts.defaultKid}|${opts.defaultAlg}`;
+}
+async function buildEnvSigningKey(opts) {
+  const kidDefault = readEnvTrimmed(opts.envKidVar) ?? opts.defaultKid;
+  const rawAlg = (readEnvTrimmed(opts.envAlgVar) ?? "").toUpperCase();
+  const algFallback = rawAlg === "ES256" ? "ES256" : opts.defaultAlg;
+  const envJwk = readEnvTrimmed(opts.envJwkVar);
+  if (envJwk) {
+    let jwkDict;
+    try {
+      jwkDict = JSON.parse(envJwk);
+    } catch (err) {
+      throw new Error(
+        `${opts.envJwkVar} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    if (!jwkDict || typeof jwkDict !== "object" || Array.isArray(jwkDict) || Object.keys(jwkDict).length === 0) {
+      throw new Error(`${opts.envJwkVar} must be a non-empty JWK object.`);
+    }
+    const detectedAlg = detectAlgFromJwk(jwkDict);
+    if (!detectedAlg) {
+      throw new Error(
+        `${opts.envJwkVar} has unsupported kty/crv (got kty=${String(jwkDict.kty)} crv=${String(jwkDict.crv)}); expected OKP+Ed25519 or EC+P-256.`
+      );
+    }
+    const canonicalPrivateJwk = detectedAlg === "EdDSA" ? { kty: jwkDict.kty, crv: jwkDict.crv, x: jwkDict.x, d: jwkDict.d } : { kty: jwkDict.kty, crv: jwkDict.crv, x: jwkDict.x, y: jwkDict.y, d: jwkDict.d };
+    const { importJWK } = await import("jose");
+    const { createPublicKey } = await import("crypto");
+    let privateKey;
+    let publicNodeKey;
+    try {
+      privateKey = await importJWK(
+        canonicalPrivateJwk,
+        detectedAlg
+      );
+      publicNodeKey = createPublicKey({ key: canonicalPrivateJwk, format: "jwk" });
+    } catch (err) {
+      const className = err instanceof Error ? err.constructor.name : typeof err;
+      const code = err && typeof err === "object" && "code" in err ? String(err.code) : null;
+      const codeSuffix = code ? ` [${code}]` : "";
+      throw new Error(
+        `${opts.envJwkVar} has malformed key material (${className}${codeSuffix}). Verify the JWK is well-formed and matches the declared kty/crv. Underlying details suppressed to avoid leaking key bytes.`
+      );
+    }
+    const publicJWK = publicNodeKey.export({ format: "jwk" });
+    publicJWK.kid = jwkDict.kid || kidDefault;
+    publicJWK.alg = detectedAlg;
+    publicJWK.use = "sig";
+    return { privateKey, publicJWK };
+  }
+  return generateUCPSigningKey({ kid: kidDefault, alg: algFallback });
+}
+async function loadUCPSigningKeyFromEnv({
+  envJwkVar,
+  envKidVar,
+  envAlgVar,
+  defaultKid,
+  defaultAlg
+} = {}) {
+  const resolved = {
+    ...DEFAULT_LOAD_OPTS,
+    ...envJwkVar !== void 0 && { envJwkVar },
+    ...envKidVar !== void 0 && { envKidVar },
+    ...envAlgVar !== void 0 && { envAlgVar },
+    ...defaultKid !== void 0 && { defaultKid },
+    ...defaultAlg !== void 0 && { defaultAlg }
+  };
+  const key = cacheKey(resolved);
+  let cached = envLoaderCache.get(key);
+  if (cached) return cached;
+  cached = buildEnvSigningKey(resolved).catch((err) => {
+    envLoaderCache.delete(key);
+    throw err;
+  });
+  envLoaderCache.set(key, cached);
+  return cached;
+}
+
+// src/discovery/well_known.ts
+var UCP_CACHE_SECONDS = 60;
+var JWKS_CACHE_SECONDS = 300;
+var UCP_SHOPPING_SPEC_2026_04_08 = "https://ucp.dev/2026-04-08/specification/overview";
+function requestId(headers) {
+  if (headers === void 0) return void 0;
+  if (headers instanceof Headers) return headers.get("x-request-id") ?? void 0;
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.toLowerCase() === "x-request-id") return v;
+  }
+  return void 0;
+}
+function attachRequestId(headers, requestHeaders) {
+  const rid = requestId(requestHeaders);
+  if (rid !== void 0) headers["X-Request-ID"] = rid;
+}
+function isTempoSession(s) {
+  return "escrowContract" in s && "store" in s;
+}
+function isStripe(s) {
+  return !("recipient" in s);
+}
+function railHasRecipientField(spec) {
+  return Object.hasOwn(spec, "recipient");
+}
+function composeHandlers(checkout) {
+  const handlers = {};
+  const mpp = [];
+  const x402 = [];
+  const stripe = [];
+  for (const spec of Object.values(checkout.rails)) {
+    if (isStripe(spec)) {
+      stripe.push(spec);
+      continue;
+    }
+    if (isTempoSession(spec)) {
+      if (railHasRecipientField(spec)) mpp.push(spec);
+      continue;
+    }
+    const network = spec.network ?? "";
+    if (network.startsWith("eip155:") || "mode" in spec) {
+      if (railHasRecipientField(spec)) x402.push(spec);
+    } else if (network.startsWith("solana:") || "rpcUrl" in spec) {
+      if (railHasRecipientField(spec)) mpp.push(spec);
+    } else {
+      if (railHasRecipientField(spec)) mpp.push(spec);
+    }
+  }
+  if (mpp.length > 0) Object.assign(handlers, mppPaymentHandler({ networks: mpp }));
+  if (x402.length > 0) Object.assign(handlers, x402PaymentHandler({ networks: x402 }));
+  for (const spec of stripe) Object.assign(handlers, stripeSptPaymentHandler({ spec }));
+  return handlers;
+}
+function misconfiguredResponse(requestHeaders) {
+  const body = {
+    error: {
+      code: "ucp_misconfigured",
+      message: "Merchant has no configured payment handlers."
+    },
+    next_steps: {
+      action: "contact_merchant",
+      user_message: "This merchant is temporarily unable to accept agent payments."
+    },
+    agent_instructions: {
+      action: "contact_merchant",
+      steps: [
+        "Surface a transient error to the user.",
+        "Retry later; the merchant operator will repair the configuration."
+      ],
+      user_message: "Merchant temporarily offline for agent payments."
+    }
+  };
+  const headers = {
+    "Access-Control-Allow-Origin": "*",
+    "Cache-Control": `public, max-age=${UCP_CACHE_SECONDS}`
+  };
+  attachRequestId(headers, requestHeaders);
+  return {
+    body: JSON.stringify(body),
+    mediaType: "application/json",
+    headers,
+    status: 503
+  };
+}
+async function buildSignedUcpResponse(opts) {
+  const {
+    checkout,
+    name,
+    wellKnownUcpUrl,
+    services,
+    requestHeaders,
+    signingKid = "merchant-default",
+    agentscoreGate
+  } = opts;
+  const handlers = composeHandlers(checkout);
+  if (Object.keys(handlers).length === 0) {
+    return misconfiguredResponse(requestHeaders);
+  }
+  const key = await loadUCPSigningKeyFromEnv({ defaultKid: signingKid });
+  const signingKeyEntry = UCPSigningKey.fromJWK(key.publicJWK);
+  const profile = buildUCPProfile({
+    name,
+    supported_versions: { "2026-04-08": wellKnownUcpUrl },
+    agentscore_gate: agentscoreGate,
+    services,
+    payment_handlers: handlers,
+    signing_keys: [signingKeyEntry]
+  });
+  const signed = await signUCPProfile(profile, {
+    signingKey: key.privateKey,
+    kid: key.publicJWK.kid,
+    alg: key.publicJWK.alg ?? "EdDSA"
+  });
+  const headers = {
+    "Cache-Control": `public, max-age=${UCP_CACHE_SECONDS}`,
+    "Access-Control-Allow-Origin": "*"
+  };
+  attachRequestId(headers, requestHeaders);
+  return {
+    body: JSON.stringify(signed),
+    mediaType: "application/json",
+    headers,
+    status: 200
+  };
+}
+async function buildSignedJwksResponse(opts) {
+  const { requestHeaders, signingKid = "merchant-default" } = opts ?? {};
+  const key = await loadUCPSigningKeyFromEnv({ defaultKid: signingKid });
+  const jwks = buildJWKSResponse([UCPSigningKey.fromJWK(key.publicJWK)]);
+  const headers = {
+    "Cache-Control": `public, max-age=${JWKS_CACHE_SECONDS}`,
+    "Access-Control-Allow-Origin": "*"
+  };
+  attachRequestId(headers, requestHeaders);
+  return {
+    body: JSON.stringify(jwks),
+    mediaType: "application/jwk-set+json",
+    headers,
+    status: 200
+  };
+}
+function wellKnownCorsPreflightHeaders(requestHeaders) {
+  const headers = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, OPTIONS",
+    "Access-Control-Max-Age": "86400",
+    Vary: "Access-Control-Request-Headers"
+  };
+  if (requestHeaders === void 0) return headers;
+  const acrh = requestHeaders instanceof Headers ? requestHeaders.get("access-control-request-headers") : Object.entries(requestHeaders).find(([k]) => k.toLowerCase() === "access-control-request-headers")?.[1];
+  if (acrh) headers["Access-Control-Allow-Headers"] = acrh;
+  return headers;
+}
+function wellKnownPreflightResponse(requestHeaders) {
+  return new Response(null, {
+    status: 204,
+    headers: wellKnownCorsPreflightHeaders(requestHeaders)
+  });
+}
+function defaultA2aServices(opts) {
+  return {
+    "dev.ucp.shopping": [
+      {
+        version: "2026-04-08",
+        spec: UCP_SHOPPING_SPEC_2026_04_08,
+        transport: "a2a",
+        endpoint: opts.agentCardUrl
+      }
+    ]
+  };
+}
+async function bootstrapUcpSigningKey(opts) {
+  const defaultKid = opts?.defaultKid ?? "merchant-default";
+  await loadUCPSigningKeyFromEnv({ defaultKid });
+}
+function signedResponseHono(resp) {
+  return new Response(resp.body, {
+    status: resp.status,
+    headers: { ...resp.headers, "Content-Type": resp.mediaType }
+  });
+}
+function signedResponseNextjs(resp) {
+  return signedResponseHono(resp);
+}
+function signedResponseWeb(resp) {
+  return signedResponseHono(resp);
+}
+function signedResponseExpress(res, resp) {
+  res.status(resp.status);
+  res.set(resp.headers);
+  res.type(resp.mediaType);
+  res.send(resp.body);
+}
+function signedResponseFastify(reply, resp) {
+  reply.code(resp.status);
+  for (const [k, v] of Object.entries(resp.headers)) reply.header(k, v);
+  reply.type(resp.mediaType);
+  return reply.send(resp.body);
+}
+
+// src/discovery/request_id.ts
+function echoRequestIdHeaderHono() {
+  return async (c, next) => {
+    await next();
+    const id = c.get("requestId");
+    if (id) c.header("X-Request-ID", id);
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  PURCHASE_MODE_NOTES,
   agentscoreDenialSchemas,
   agentscoreOpenApiSnippets,
   agentscorePaymentRequiredSchema,
   agentscoreSecuritySchemes,
   applyNoindexHeader,
+  bootstrapUcpSigningKey,
+  buildAgentscoreOnboardingSteps,
   buildDiscoveryProbeResponse,
   buildLlmsTxt,
+  buildMerchantIndexJson,
+  buildRedemptionSkillMd,
+  buildSignedJwksResponse,
+  buildSignedUcpResponse,
   buildSkillMd,
+  buildSuccessNextSteps,
   buildWellKnownMpp,
   buildWellKnownX402,
   compatibleClientsByRails,
   createBazaarDiscovery,
+  defaultA2aServices,
   defaultDiscoveryPaths,
+  echoRequestIdHeaderHono,
   isDiscoveryPath,
   isDiscoveryProbeRequest,
   llmsTxtIdentitySection,
@@ -891,10 +1914,21 @@ function buildSkillMd(input) {
   noindexNonDiscoveryPaths,
   noindexNonDiscoveryPathsExpress,
   noindexNonDiscoveryPathsFastify,
+  purchaseModeNote,
   sampleX402AcceptForNetwork,
+  signedResponseExpress,
+  signedResponseFastify,
+  signedResponseHono,
+  signedResponseNextjs,
+  signedResponseWeb,
   siwxSecurityScheme,
+  standardEndpointDescriptions,
+  wellKnownCorsPreflightHeaders,
+  wellKnownPreflightResponse,
   wrapNoindexResponse,
   xGuidanceExtension,
-  xPaymentInfoExtension
+  xPaymentInfoExtension,
+  xPaymentInfoFromCheckout,
+  xServiceInfoExtension
 });
 //# sourceMappingURL=index.js.map