@astrasyncai/verification-gateway 5.18.1 → 5.19.0

package/dist/index.js

@@ -53,6 +53,7 @@ __export(src_exports, {
   MemoryCheckoutStore: () => MemoryCheckoutStore,
   MemoryIdempotencyStore: () => MemoryIdempotencyStore,
   MemoryMppChallengeStore: () => MemoryMppChallengeStore,
+  MemorySeenEvents: () => MemorySeenEvents,
   PLATFORM_AGENT_SIGNATURES: () => PLATFORM_AGENT_SIGNATURES,
   RUNTIME_SIGNATURES: () => RUNTIME_SIGNATURES,
   RedisIdempotencyStore: () => RedisIdempotencyStore,
@@ -67,6 +68,7 @@ __export(src_exports, {
   VERIFICATION_STATUS_HEADER: () => VERIFICATION_STATUS_HEADER,
   VERSION: () => SDK_VERSION,
   _resetEdgeConfigCache: () => _resetEdgeConfigCache,
+  abandonIdempotent: () => abandonIdempotent,
   acpPaymentHandlers: () => acpPaymentHandlers,
   aepCanonicalJson: () => aepCanonicalJson,
   aepHash: () => aepHash,
@@ -78,6 +80,7 @@ __export(src_exports, {
   aepTimestamp: () => aepTimestamp,
   aepVerifySignature: () => aepVerifySignature,
   agent: () => agent_exports,
+  approvalEventsHandler: () => approvalEventsHandler,
   astrasyncPaymentHandlers: () => astrasyncPaymentHandlers,
   authorizeSettlement: () => authorizeSettlement,
   awaitStepUpApproval: () => awaitStepUpApproval,
@@ -124,6 +127,7 @@ __export(src_exports, {
   getEdgeConfig: () => getEdgeConfig,
   getTrustLevel: () => getTrustLevel,
   getWellKnownUrls: () => getWellKnownUrls,
+  handleApprovalEvents: () => handleApprovalEvents,
   hasCredentials: () => hasCredentials,
   idempotencyMiddleware: () => idempotencyMiddleware,
   isEdgeConfig: () => isEdgeConfig,
@@ -214,7 +218,7 @@ function getTrustLevel(score) {
 }
 
 // src/version.ts
-var SDK_VERSION = "5.18.1";
+var SDK_VERSION = "5.19.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -466,7 +470,12 @@ function getCacheKey(request, counterpartyId) {
     // its start_checkout quote was served the cached quote-leg grant (no
     // settlementOutcome) and never reached the backend. Same F-A1-07 bug class.
     request.commercePhase || "",
-    request.checkoutSessionId || ""
+    request.checkoutSessionId || "",
+    // 5.19.0: a route_config purpose claim is checked server-side against
+    // the stored rule for this method + path, so it changes the verdict.
+    request.purposeSource || "",
+    request.requestMethod || "",
+    request.requestPath || ""
   ].join("|");
 }
 function getCachedResult(request, counterpartyId) {
@@ -680,6 +689,11 @@ async function callVerifyAccessAPI(config, request) {
   if (requestData.buyerEmail) body.buyerEmail = requestData.buyerEmail;
   if (requestData.commerceArtifacts) body.commerceArtifacts = requestData.commerceArtifacts;
   if (requestData.attemptId) body.attemptId = requestData.attemptId;
+  if (requestData.purposeSource) body.purposeSource = requestData.purposeSource;
+  if (requestData.agentArtifacts) body.agentArtifacts = requestData.agentArtifacts;
+  if (requestData.metadata) body.metadata = requestData.metadata;
+  if (requestData.requestMethod) body.requestMethod = requestData.requestMethod;
+  if (requestData.requestPath) body.requestPath = requestData.requestPath;
   if (requestData.considerationSet) body.considerationSet = requestData.considerationSet;
   body.sdkVersion = SDK_VERSION;
   if (requestData.callerMetadata || requestData.clientIp || requestData.userAgent) {
@@ -869,9 +883,18 @@ async function verify(config, request, options) {
   if (!apiResponse.access?.allowed) {
     const aggregatedFailures = apiResponse.access?.failures;
     const idVerifiedFromBackend = apiResponse.verificationContext?.idVerified === true && !aggregatedFailures?.some((f) => REJECTED_IDENTITY_DIMENSIONS.has(f.dimension));
+    const denyAgent = idVerifiedFromBackend && apiResponse.agent ? {
+      astraId: apiResponse.agent.astraId,
+      name: apiResponse.agent.name,
+      trustScore: apiResponse.agent.trustScore,
+      trustLevel: getTrustLevel(apiResponse.agent.trustScore),
+      blockchainAnchored: apiResponse.agent.blockchainStatus === "anchored",
+      status: apiResponse.agent.agentStatus
+    } : void 0;
     const result2 = {
       identityVerified: idVerifiedFromBackend,
       policyAllowed: false,
+      ...denyAgent && { agent: denyAgent },
       // 3.6.0: the server now emits top-level denialReasons on every deny
       // path — prefer it verbatim; the failure-message reconstruction remains
       // as the fallback for older backends.
@@ -1063,7 +1086,7 @@ async function reportAttempt(config, report, options = {}) {
 }
 var ATTEMPT_REPORT_MAX_RETRY_DELAY_MS = 2e3;
 var refusedPolicyReads = /* @__PURE__ */ new Set();
-async function fetchRoutes(config, counterpartyId) {
+async function fetchRoutes(config, counterpartyId, options = {}) {
   if (!counterpartyId) return null;
   const headers = { "Content-Type": "application/json" };
   if (config.apiKey) {
@@ -1072,7 +1095,7 @@ async function fetchRoutes(config, counterpartyId) {
   }
   try {
     const response = await sdkFetch(
-      `${config.apiBaseUrl}/endpoints/${encodeURIComponent(counterpartyId)}/routes`,
+      `${config.apiBaseUrl}/endpoints/${encodeURIComponent(counterpartyId)}/routes` + (options.codeGates?.length ? `?codeGates=${options.codeGates.map(encodeURIComponent).join(",")}` : ""),
       { method: "GET", headers }
     );
     if (!response.ok) {
@@ -1755,6 +1778,42 @@ async function detectFetchCommerce(request) {
   );
 }
 
+// src/adapters/routes-cache.ts
+var DEFAULT_ROUTES_REFRESH_MS = 5 * 60 * 1e3;
+function createRoutesCache(config, opts = {}) {
+  const refreshMs = opts.refreshMs ?? DEFAULT_ROUTES_REFRESH_MS;
+  let cached = [];
+  let lastFetchAt = 0;
+  let refreshing = null;
+  async function refresh() {
+    if (!config.counterpartyId) {
+      opts.onNoCounterparty?.();
+      return;
+    }
+    const fetched = await fetchRoutes(config, config.counterpartyId, opts.fetchOptions);
+    if (fetched) {
+      cached = fetched;
+      lastFetchAt = Date.now();
+      opts.onFetched?.(fetched);
+    }
+  }
+  function start() {
+    refreshing = refresh().catch(() => void 0).finally(() => {
+      refreshing = null;
+    });
+  }
+  start();
+  return {
+    async current() {
+      if (refreshing) await refreshing.catch(() => {
+      });
+      if (config.counterpartyId && Date.now() - lastFetchAt > refreshMs) start();
+      return cached;
+    },
+    peek: () => cached
+  };
+}
+
 // src/transport/http.ts
 var HEADER_PREFIX = "X-Astra-";
 function setHttpHeaders(headers, credentials) {
@@ -1931,6 +1990,20 @@ function resolveHttpPdlss(input) {
   }
   return { purpose, action, purposeSource, actionSource };
 }
+function wirePurposeSource(source) {
+  switch (source) {
+    case "route_config":
+      return "route_config";
+    case "header":
+    case "legacy_header":
+    case "query":
+      return "header";
+    case "custom_extractor":
+      return "body";
+    default:
+      return "default";
+  }
+}
 
 // src/pdlss-pre-check.ts
 function performCounterpartyPreCheck(routeConfig, astraCreds, purpose) {
@@ -2430,12 +2503,12 @@ var BeaconBuffer = class {
   }
   /** Oldest eligible item + up to maxBatch-1 more for the same destination. */
   takeBatch(now) {
-    const first = this.queue.find((q) => q.eligibleAt <= now);
-    if (!first) return [];
+    const first2 = this.queue.find((q) => q.eligibleAt <= now);
+    if (!first2) return [];
     const batch = [];
     const rest = [];
     for (const q of this.queue) {
-      if (batch.length < this.opts.maxBatch && q.destKey === first.destKey && q.eligibleAt <= now) {
+      if (batch.length < this.opts.maxBatch && q.destKey === first2.destKey && q.eligibleAt <= now) {
         q.inFlight = true;
         batch.push(q);
       } else {
@@ -2712,7 +2785,6 @@ function defaultOnDenied(result, _req, res) {
     }
   });
 }
-var DEFAULT_ROUTES_REFRESH_MS = 5 * 60 * 1e3;
 function createMiddleware(options) {
   if ("routes" in options) {
     console.warn(
@@ -2728,7 +2800,7 @@ function createMiddleware(options) {
     recordDecisions,
     enableRuntimeChallenge = true,
     routesRefreshMs = DEFAULT_ROUTES_REFRESH_MS,
-    failOnError = "open",
+    failOnError = "closed",
     caseInsensitiveRouteMatch = false,
     anonymousBeacon = true,
     trustVerifiedHop = false,
@@ -2752,26 +2824,19 @@ function createMiddleware(options) {
       rawHeaders: req.headers
     });
   } : void 0;
-  let cachedRoutes = [];
-  let lastFetchAt = 0;
-  let refreshing = null;
   let warnedNoCounterparty = false;
   let warnedEmptyRoutes = false;
-  async function refreshRoutes() {
-    if (!config.counterpartyId) {
-      if (!warnedNoCounterparty) {
-        console.warn(
-          "[VerificationGateway] No counterpartyId configured \u2014 falling through (allow all). Per-route policy lives in the AstraSync dashboard now; register the endpoint and set counterpartyId in your middleware config to enforce policy."
-        );
-        warnedNoCounterparty = true;
-      }
-      return;
-    }
-    const fetched = await fetchRoutes(config, config.counterpartyId);
-    if (fetched) {
-      cachedRoutes = fetched;
-      lastFetchAt = Date.now();
-      if (cachedRoutes.length === 0 && !warnedEmptyRoutes) {
+  const routesCache = createRoutesCache(config, {
+    refreshMs: routesRefreshMs,
+    onNoCounterparty: () => {
+      if (warnedNoCounterparty) return;
+      console.warn(
+        "[VerificationGateway] No counterpartyId configured \u2014 falling through (allow all). Per-route policy lives in the AstraSync dashboard now; register the endpoint and set counterpartyId in your middleware config to enforce policy."
+      );
+      warnedNoCounterparty = true;
+    },
+    onFetched: (routes) => {
+      if (routes.length === 0 && !warnedEmptyRoutes) {
         const dashboard = config.dashboardUrl ?? "https://astrasync.ai/dashboard";
         console.warn(
           `[VerificationGateway] No route policy configured for ${config.counterpartyId}. Gateway is in pass-through mode for ALL traffic until you add at least one route. Configure at ${dashboard}/dashboard/endpoints/${config.counterpartyId}/routes`
@@ -2779,9 +2844,6 @@ function createMiddleware(options) {
         warnedEmptyRoutes = true;
       }
     }
-  }
-  refreshing = refreshRoutes().finally(() => {
-    refreshing = null;
   });
   return async (req, res, next) => {
     try {
@@ -2789,15 +2851,9 @@ function createMiddleware(options) {
       if (shouldSkip) {
         return next();
       }
-      if (refreshing) {
-        await refreshing.catch(() => {
-        });
-      }
-      if (config.counterpartyId && Date.now() - lastFetchAt > routesRefreshMs) {
-        refreshing = refreshRoutes().finally(() => {
-          refreshing = null;
-        });
-      }
+      const cachedRoutes = (await routesCache.current()).filter(
+        (r) => typeof r.pattern === "string" && !r.tool
+      );
       const correlationId = req.headers["x-request-id"] || req.headers["x-correlation-id"];
       const matchedRoute = findRouteConfig(cachedRoutes, req.path, req.method, {
         caseInsensitive: caseInsensitiveRouteMatch,
@@ -2921,6 +2977,12 @@ function createMiddleware(options) {
         ...commerceArtifacts && { commerceArtifacts },
         purpose,
         action: pdlssPair.action,
+        // 5.19.0: the source + the request line let verify-access check a
+        // route purpose against the stored rule (item 20: an MPP paid leg
+        // keeps `shopping.purchase` instead of `commerce.payment.execute`).
+        purposeSource: wirePurposeSource(pdlssPair.purposeSource),
+        requestMethod: req.method,
+        requestPath: req.path,
         resource: req.path,
         createSession: shouldRecordDecisions,
         counterpartyUrl,
@@ -2998,7 +3060,8 @@ function createMiddleware(options) {
         return;
       }
       if (routeConfig.minTrustScore && result.agent) {
-        if (result.agent.trustScore < routeConfig.minTrustScore) {
+        const score = result.agent.trustScore;
+        if (typeof score !== "number" || score < routeConfig.minTrustScore) {
           const trustFailure = {
             dimension: "endpoint.trust",
             message: "Trust below the route requirement for this endpoint.",
@@ -3442,6 +3505,10 @@ function createMiddleware2(options) {
       ...commerceArtifacts && { commerceArtifacts },
       purpose,
       action: pdlssPair.action,
+      // 5.19.0: route purpose claim + request line (checked server-side).
+      purposeSource: wirePurposeSource(pdlssPair.purposeSource),
+      requestMethod: request.method,
+      requestPath: pathname,
       resource: pathname,
       counterpartyUrl,
       counterpartyType: config.counterpartyType || "website",
@@ -3642,6 +3709,7 @@ function isRetryableSettlementError(err) {
 }
 
 // src/adapters/sdk.ts
+var warnedPhaselessValue = false;
 var VerificationGatewayClient = class {
   constructor(options) {
     this.config = {
@@ -3673,9 +3741,16 @@ var VerificationGatewayClient = class {
       apiKey: options.apiKey,
       jwt: options.jwt
     };
+    if (options.transactionValue && !options.commercePhase && !warnedPhaselessValue) {
+      warnedPhaselessValue = true;
+      console.warn(
+        "[astrasync] verify() with a transactionValue and no commercePhase is a purchase leg: it records a pending order and redeems a matching owner approval. Use quoteCheckout() for a price / limit check (commercePhase 'quote') and confirmCheckout() for the purchase. The default becomes 'quote' in 6.0."
+      );
+    }
     return this.executeWithRetry(
       () => verify(this.config, {
         credentials,
+        ...options.commercePhase && { commercePhase: options.commercePhase },
         purpose: options.purpose,
         action: options.action,
         resourceType: options.resourceType,
@@ -3691,6 +3766,43 @@ var VerificationGatewayClient = class {
       })
     );
   }
+  /**
+   * 5.19.0: the QUOTE leg of a checkout — a price / limit check before the
+   * purchase. Sends `commercePhase: 'quote'`: verify-access evaluates the
+   * agent's policy at this value and tells you whether a purchase would be
+   * granted, held for the owner's approval, or denied, but records no order,
+   * moves no money and never redeems an approval. Always reaches the backend
+   * (no verdict cache).
+   *
+   * Quotes count toward limit-probing detection: a run of rising quotes is
+   * how an agent (or a merchant) maps a spending limit. Quote what the buyer
+   * asked for, not a ladder of values.
+   */
+  async quoteCheckout(options) {
+    const credentials = {
+      astraId: options.astraId,
+      apiKey: options.apiKey,
+      jwt: options.jwt
+    };
+    return this.executeWithRetry(
+      () => verify(
+        this.config,
+        {
+          credentials,
+          purpose: options.purpose ?? "shopping",
+          action: options.action ?? "shopping.purchase",
+          transactionValue: options.transactionValue,
+          currency: options.currency,
+          commercePhase: "quote",
+          ...options.checkoutSessionId && { checkoutSessionId: options.checkoutSessionId },
+          ...options.attemptId && { attemptId: options.attemptId },
+          counterpartyUrl: options.counterpartyUrl,
+          counterpartyType: options.counterpartyType
+        },
+        { bypassCache: true }
+      )
+    );
+  }
   /**
    * 5.4.0 (astra-pay): confirm-leg of a checkout — the ONLY call that may fire
    * first-party charge-at-redeem (server-side settlement on the owner's saved
@@ -3729,6 +3841,14 @@ var VerificationGatewayClient = class {
    * is matched to — and only to — this confirm. A held cart's approval is
    * bound to its checkout session and exact value; a confirm for any other
    * cart is held for its own approval.
+   *
+   * 5.19.0 checkout kits: pass the kit's `agentArtifacts` (the inbound agent
+   * request — signed RFC 9421 headers with the public URL and raw-body
+   * digest, or `{ unsigned: true }`) and `metadata` (`{ kitSessionId,
+   * protocol }`) from the `verifyPurchase` context. The platform attributes
+   * the confirm to the agent from the artifacts, and stores the metadata on
+   * any approval this confirm creates so the approval event
+   * (`handleApprovalEvents`) can find the kit session.
    */
   async confirmCheckout(options) {
     const credentials = {
@@ -3751,6 +3871,8 @@ var VerificationGatewayClient = class {
           ...options.checkoutJwt && { checkoutJwt: options.checkoutJwt },
           ...options.attemptId && { attemptId: options.attemptId },
           buyerEmail: options.buyerEmail,
+          ...options.agentArtifacts && { agentArtifacts: options.agentArtifacts },
+          ...options.metadata && { metadata: options.metadata },
           counterpartyUrl: options.counterpartyUrl,
           counterpartyType: options.counterpartyType
         },
@@ -4678,9 +4800,9 @@ function extractFulfillmentOption(body) {
   if (direct) return direct;
   const options = body.fulfillment_options;
   if (Array.isArray(options) && options.length > 0) {
-    const first = options[0];
-    if (first && typeof first === "object") {
-      const id = coerceString3(first.id);
+    const first2 = options[0];
+    if (first2 && typeof first2 === "object") {
+      const id = coerceString3(first2.id);
       if (id) return id;
     }
   }
@@ -5687,7 +5809,8 @@ function verifyMPP(input) {
   }
   let replayOk = true;
   if (challenge?.digest && expiryOk) {
-    const replayKey = `mpp:${challenge.digest}:${challenge.nonce ?? ""}`;
+    const c = challenge;
+    const replayKey = `mpp:${challenge.digest}:${c.id ?? ""}:${c.nonce ?? ""}`;
     const expiresAt = (nowSec + tolerance) * 1e3;
     if (nonceStore.seen(replayKey, expiresAt)) {
       replayOk = false;
@@ -6244,11 +6367,11 @@ function resolveTransactionValue(input) {
     if (v) return v;
   }
   if (input.x402?.paymentRequired) {
-    const first = input.x402.paymentRequired.accepts[0];
-    if (first) {
+    const first2 = input.x402.paymentRequired.accepts[0];
+    if (first2) {
       const v = extractX402TransactionValue({
-        maxAmountRequired: Number(first.amount),
-        asset: first.asset
+        maxAmountRequired: Number(first2.amount),
+        asset: first2.asset
       });
       if (v) return v;
     }
@@ -6706,6 +6829,21 @@ function defaultMcpDenied(result, req, res) {
     }
   });
 }
+function dashboardToolRules(routes) {
+  const out = /* @__PURE__ */ new Map();
+  for (const r of routes) {
+    if (typeof r.tool !== "string" || !r.tool || r.legacy === true) continue;
+    if (out.has(r.tool)) continue;
+    out.set(r.tool, {
+      tool: r.tool,
+      ...r.purpose && { purpose: r.purpose },
+      ...r.action && { action: r.action },
+      ...r.resource && { resource: r.resource },
+      ...r.observe === true && { observe: true }
+    });
+  }
+  return out;
+}
 function resolveGate(parsed, opts) {
   if (!parsed.toolName) {
     const methodGate = opts.methodGates?.[parsed.method];
@@ -6715,8 +6853,30 @@ function resolveGate(parsed, opts) {
     return { enforce: false, source: "discovery_default" };
   }
   const toolGate = opts.toolGates?.[parsed.toolName];
+  const rule = opts.dashboardRules?.get(parsed.toolName);
+  const fromRule = (r) => r.observe ? { enforce: false, source: "dashboard" } : {
+    enforce: true,
+    config: {
+      ...r.purpose && { purpose: r.purpose },
+      ...r.action && { action: r.action },
+      ...r.resource && { resource: r.resource }
+    },
+    source: "dashboard"
+  };
+  const codeGated = toolGate !== void 0 && toolGate !== "observe";
+  if (rule && (opts.toolGatePrecedence === "dashboard" || !codeGated)) return fromRule(rule);
   if (toolGate !== void 0) {
-    return toolGate === "observe" ? { enforce: false, source: "toolGate" } : { enforce: true, config: toolGate, source: "toolGate" };
+    if (toolGate === "observe") return { enforce: false, source: "toolGate" };
+    if (rule && !rule.observe && rule.purpose && (rule.purpose !== toolGate.purpose || rule.action && rule.action !== toolGate.action)) {
+      const extra = fromRule(rule).config;
+      return {
+        enforce: true,
+        config: toolGate,
+        additional: { ...extra, ...!extra.resource && toolGate.resource && { resource: toolGate.resource } },
+        source: "toolGate"
+      };
+    }
+    return { enforce: true, config: toolGate, source: "toolGate" };
   }
   return { enforce: mcpDefaultEnforced(parsed), source: "tier" };
 }
@@ -6731,13 +6891,20 @@ function createMcpMiddleware(options) {
     verifiedHopMaxAgeMs,
     recordDecisions,
     enableRuntimeChallenge = true,
-    failOnError = "open",
+    failOnError = "closed",
+    toolGatePrecedence = "code",
+    routesRefreshMs,
     ...config
   } = options;
   if (config.apiBaseUrl) {
     prefetchWellKnown(config.apiBaseUrl).catch(() => {
     });
   }
+  const codeGatedTools = Object.entries(toolGates ?? {}).filter(([, g]) => g !== "observe").map(([name]) => name);
+  const rulesCache = config.apiKey && config.counterpartyId ? createRoutesCache(config, {
+    ...routesRefreshMs !== void 0 && { refreshMs: routesRefreshMs },
+    ...codeGatedTools.length && { fetchOptions: { codeGates: codeGatedTools } }
+  }) : void 0;
   return async (req, res, next) => {
     try {
       if (skip) return next();
@@ -6786,9 +6953,12 @@ function createMcpMiddleware(options) {
           return next();
         }
       }
+      const dashboardRules = rulesCache ? dashboardToolRules(await rulesCache.current()) : void 0;
       const gateDecision = resolveGate(parsed, {
         toolGates,
-        methodGates
+        methodGates,
+        dashboardRules,
+        toolGatePrecedence
       });
       const credentials = extractCredentials(
         req.headers,
@@ -6886,6 +7056,20 @@ function createMcpMiddleware(options) {
           result.stepUpOutcome = outcome;
         }
       }
+      if (shouldEnforce && gateDecision.additional?.purpose && result.policyAllowed && !requiresHumanApproval(result)) {
+        const extra = mcpToPdlss(parsed, req.path, void 0, void 0, gateDecision.additional);
+        const extraResult = await verify(config, {
+          ...verificationRequest,
+          purpose: extra.purpose,
+          action: extra.action,
+          resource: extra.resource
+        });
+        if (!extraResult.policyAllowed || requiresHumanApproval(extraResult)) {
+          result = extraResult;
+          req.agentVerification = result;
+          sessionId = result.sessionId;
+        }
+      }
       if (!result.policyAllowed && isVerificationUnavailable(result) && (!shouldEnforce || isReadOnlyMcpMethod(parsed) && !credentials.astraId && !credentials.jwt)) {
         res.setHeader(VERIFICATION_STATUS_HEADER, "unavailable");
         return next();
@@ -10192,15 +10376,15 @@ function requireDumper() {
     return !isWhitespace(c) && c !== CHAR_COLON;
   }
   function codePointAt(string, pos) {
-    const first = string.charCodeAt(pos);
+    const first2 = string.charCodeAt(pos);
     let second;
-    if (first >= 55296 && first <= 56319 && pos + 1 < string.length) {
+    if (first2 >= 55296 && first2 <= 56319 && pos + 1 < string.length) {
       second = string.charCodeAt(pos + 1);
       if (second >= 56320 && second <= 57343) {
-        return (first - 55296) * 1024 + second - 56320 + 65536;
+        return (first2 - 55296) * 1024 + second - 56320 + 65536;
       }
     }
-    return first;
+    return first2;
   }
   function needIndentIndicator(string) {
     const leadingSpaceRe = /^\n* /;
@@ -11854,6 +12038,12 @@ async function finishIdempotent(opts, decision, response) {
   } catch {
   }
 }
+async function abandonIdempotent(opts, decision) {
+  try {
+    await opts.store.delete(decision.storeKey);
+  } catch {
+  }
+}
 var KEPT_HEADERS = ["content-type", "location"];
 function withHeader(res, name, value) {
   const headers = new Headers(res.headers);
@@ -12009,6 +12199,87 @@ function warnInMemoryStores(kit, missing) {
     `[astrasync] ${kit} checkout kit is using the in-memory ${missing.join(" and ")} (sessions are lost on restart and not shared across instances). Pass ${missing.map((m) => m.startsWith("idempotency") ? "idempotencyStore" : "store").join(" and ")} in production.`
   );
 }
+var SECRET_KEY = /token|secret|credential|cvc|cvv|number|pan|password|key|cryptogram|signature/i;
+function scrubPaymentInput(input) {
+  if (!input || typeof input !== "object") return void 0;
+  const out = {};
+  for (const [k, v] of Object.entries(input)) {
+    if (SECRET_KEY.test(k)) continue;
+    if (v === null || ["string", "number", "boolean"].includes(typeof v)) out[k] = v;
+  }
+  return out;
+}
+var NEVER_FORWARD = /* @__PURE__ */ new Set(["authorization", "cookie", "x-api-key", "proxy-authorization"]);
+function coveredHeaders(signatureInput) {
+  const names = /* @__PURE__ */ new Set();
+  for (const m of signatureInput.matchAll(/\(([^)]*)\)/g)) {
+    for (const q of m[1].matchAll(/"([^"]+)"/g)) {
+      const name = q[1].toLowerCase();
+      if (!name.startsWith("@")) names.add(name);
+    }
+  }
+  return [...names];
+}
+function buildAgentArtifacts(req, rawBody, opts) {
+  const signature = req.headers.get("signature");
+  const signatureInput = req.headers.get("signature-input");
+  if (opts.protocol === "acp" || !signature || !signatureInput) {
+    return { unsigned: true, protocol: opts.protocol };
+  }
+  const headers = {};
+  const names = [
+    "signature",
+    "signature-input",
+    "signature-agent",
+    "ucp-agent",
+    "content-digest",
+    ...coveredHeaders(signatureInput)
+  ];
+  for (const name of names) {
+    if (NEVER_FORWARD.has(name)) continue;
+    const v = req.headers.get(name);
+    if (v !== null) headers[name] = v;
+  }
+  const u = new URL(req.url);
+  const origin = opts.publicOrigin ? opts.publicOrigin.replace(/\/+$/, "") : u.origin;
+  return {
+    protocol: opts.protocol,
+    method: req.method,
+    url: `${origin}${u.pathname}${u.search}`,
+    headers,
+    ...rawBody && { contentDigest: contentDigest(rawBody) }
+  };
+}
+async function withReportRetries(fn, opts = {}, isRetryable) {
+  const attempts = Math.max(1, opts.attempts ?? 3);
+  const backoff = opts.backoffMs ?? 250;
+  let last;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      last = err;
+      if (i === attempts - 1 || !isRetryable(err)) break;
+      await new Promise((r) => setTimeout(r, backoff * 2 ** i));
+    }
+  }
+  throw last;
+}
+function defaultOnReportError(err, ctx) {
+  console.error(
+    `[astrasync] checkout kit: ${ctx.kind === "order_webhook" ? "order webhook" : "settlement report"} failed for session ${ctx.sessionId}${ctx.orderId ? ` (order ${ctx.orderId})` : ""}:`,
+    err
+  );
+}
+var NON_TERMINAL = /* @__PURE__ */ new Set(["busy", "still_held"]);
+function isTerminalOutcome(outcome) {
+  return !NON_TERMINAL.has(outcome);
+}
+var resumeResult = (outcome, session) => ({
+  outcome,
+  terminal: isTerminalOutcome(outcome),
+  session
+});
 
 // src/ucp/checkout-kit.ts
 var MemoryCheckoutStore = class {
@@ -12033,6 +12304,15 @@ var MemoryCheckoutStore = class {
     const id = this.orders.get(orderId);
     return id ? this.m.get(id) ?? null : null;
   }
+  async findByCheckoutSessionId(checkoutSessionId) {
+    for (const s of this.m.values()) {
+      if ((s._astraCheckoutSessionId ?? s.id) === checkoutSessionId) return s;
+    }
+    return this.m.get(checkoutSessionId) ?? null;
+  }
+  async listHeld() {
+    return [...this.m.values()].filter((s) => s.status === "requires_escalation");
+  }
 };
 function buildUcpOrder(session, opts = {}) {
   if (!session.order) return null;
@@ -12055,11 +12335,20 @@ function buildUcpOrder(session, opts = {}) {
     totals: session.totals
   };
 }
+function heldBody(text) {
+  try {
+    return JSON.parse(text).status === "requires_escalation";
+  } catch {
+    return false;
+  }
+}
 var json2 = (status, body, headers = {}) => new Response(JSON.stringify(body), {
   status,
   headers: { "content-type": "application/json", ...headers }
 });
 var total = (s) => s.totals.find((t) => t.type === "total")?.amount ?? 0;
+var clone = (v) => JSON.parse(JSON.stringify(v));
+var inFlight = (st) => st === "complete_in_progress" || st === "finishing";
 function createUcpCheckoutKit(opts) {
   const profile = buildUcpProfile(opts.profile);
   const store = opts.store ?? new MemoryCheckoutStore();
@@ -12085,6 +12374,11 @@ function createUcpCheckoutKit(opts) {
       ...entries.map((e) => e.id)
     ])
   );
+  const publicOrigin = (opts.publicOrigin ?? new URL(opts.profile.endpoint).origin).replace(
+    /\/+$/,
+    ""
+  );
+  const onReportError = opts.onReportError ?? defaultOnReportError;
   const fetchProfile = opts.fetchProfile ?? (async (url, fresh) => {
     const r = await fetchUcpProfile(url, { fresh });
     return r.ok ? r.profile : r;
@@ -12106,7 +12400,7 @@ function createUcpCheckoutKit(opts) {
         payment_handlers: profile.ucp.payment_handlers
       },
       id: s.id,
-      status: s.status,
+      status: s.status === "finishing" ? "complete_in_progress" : s.status,
       currency: s.currency,
       line_items: s.line_items,
       totals: s.totals,
@@ -12152,6 +12446,23 @@ function createUcpCheckoutKit(opts) {
       "ephemeral"
     );
   }
+  function heldNoEdit(s) {
+    return render(
+      {
+        ...s,
+        messages: [
+          ...s.messages ?? [],
+          ucpError(
+            "checkout_awaiting_approval",
+            "This checkout is waiting for the buyer\u2019s approval and can\u2019t be changed. Cancel it to start over.",
+            "requires_buyer_review"
+          )
+        ]
+      },
+      409,
+      "ephemeral"
+    );
+  }
   async function save(s) {
     if (s.order) orderIndex.set(s.order.id, s.id);
     await store.put(s);
@@ -12182,31 +12493,44 @@ function createUcpCheckoutKit(opts) {
     return r;
   }
   function emitOrder(s) {
-    void deliverOrder(s).catch(() => void 0);
-  }
-  async function reportOutcome(p, settled) {
-    if (!opts.reportSettlement || !p.orderId) return;
-    await opts.reportSettlement({
-      orderId: p.orderId,
-      status: settled.status,
-      ...p.report,
-      ...settled.status === "settled" && settled.processorRef && { processorRef: settled.processorRef },
-      ...settled.status === "settled" && settled.txHash && { txHash: settled.txHash, chainId: settled.chainId },
-      ...settled.status === "failed" && settled.failureCode && { failureCode: settled.failureCode }
-    }).catch(() => void 0);
+    const ctx = { sessionId: s.id, orderId: s.order?.id, kind: "order_webhook" };
+    void deliverOrder(s).then((r) => {
+      if (r && !r.ok) onReportError(new Error(`order webhook failed (HTTP ${r.status})`), ctx);
+    }).catch((err) => onReportError(err, ctx));
+  }
+  async function reportOutcome(s, p, settled) {
+    const report = opts.reportSettlement;
+    const ref = p.orderId ? { orderId: p.orderId } : p.sessionId ? { sessionId: p.sessionId } : null;
+    if (!report || !ref) return;
+    await withReportRetries(
+      () => report({
+        ...ref,
+        status: settled.status,
+        ...p.report,
+        ...settled.status === "settled" && settled.processorRef && { processorRef: settled.processorRef },
+        ...settled.status === "settled" && settled.txHash && { txHash: settled.txHash, chainId: settled.chainId },
+        ...settled.status === "failed" && settled.failureCode && { failureCode: settled.failureCode }
+      }),
+      opts.reportRetry,
+      isRetryableSettlementError
+    ).catch(
+      (err) => onReportError(err, { sessionId: s.id, orderId: p.orderId, kind: "settlement_report" })
+    );
   }
   async function finish(s, result, p, settled) {
-    await reportOutcome(p, settled);
+    await reportOutcome(s, p, settled);
     delete s._pending;
+    delete s._held;
+    delete s._approvalId;
     if (settled.status === "failed") {
       s.status = "ready_for_complete";
       s.messages = [
-        ucpError("payment_failed", "The payment did not go through.", "requires_buyer_input")
+        ucpError("payment_failed", "The payment did not go through.", "recoverable")
       ];
       await save(s);
       return;
     }
-    const order = await opts.fulfil({ session: s, result });
+    const order = await opts.fulfil({ session: s, result, settled });
     s.order = {
       ...order,
       ...!order.permalink_url && opts.permalinkBase && {
@@ -12240,7 +12564,8 @@ function createUcpCheckoutKit(opts) {
     const out = [];
     const messages = [];
     for (const [i, l] of lines.entries()) {
-      const item = l.item?.id ? await opts.catalog(l.item.id) : null;
+      const q = Math.max(1, Math.floor(l.quantity ?? 1));
+      const item = l.item?.id ? await opts.catalog(l.item.id, q) : null;
       if (!item) {
         messages.push(
           ucpError(
@@ -12252,7 +12577,6 @@ function createUcpCheckoutKit(opts) {
         );
         continue;
       }
-      const q = Math.max(1, Math.floor(l.quantity ?? 1));
       const amount = item.price * q;
       out.push({
         id: `li_${i + 1}`,
@@ -12274,6 +12598,19 @@ function createUcpCheckoutKit(opts) {
       ]
     };
   }
+  async function validate(s) {
+    if (!opts.validateCart) return { messages: [], blocked: false };
+    const found = await opts.validateCart(s);
+    const messages = found.map(
+      (m) => (m.type ?? "error") === "error" ? ucpError(m.code, m.content, "recoverable", m.path) : {
+        type: m.type,
+        code: m.code,
+        content: m.content,
+        ...m.path && { path: m.path }
+      }
+    );
+    return { messages, blocked: found.some((m) => (m.type ?? "error") === "error") };
+  }
   async function platform(req, body) {
     const profileUrl = parseUcpAgentHeader(req.headers.get("ucp-agent"));
     if (!profileUrl) {
@@ -12345,17 +12682,20 @@ function createUcpCheckoutKit(opts) {
       });
     const res = await run();
     if (d.kind === "proceed") {
-      await finishIdempotent(idem, d, {
-        status: res.status,
-        headers: { "content-type": "application/json" },
-        body: await res.clone().text()
-      });
+      const text = await res.clone().text();
+      if (heldBody(text)) await abandonIdempotent(idem, d);
+      else
+        await finishIdempotent(idem, d, {
+          status: res.status,
+          headers: { "content-type": "application/json" },
+          body: text
+        });
     }
     return res;
   }
-  async function complete(req, s, body) {
+  async function complete(req, s, body, agentArtifacts) {
     if (s.status === "completed" || s.status === "canceled") return render(s);
-    if (s.status === "complete_in_progress") return busy(s);
+    if (inFlight(s.status)) return busy(s);
     const ap2 = body.ap2;
     const checkoutJwt = s._ap2 ? s._checkoutJwt : void 0;
     if (s._ap2) {
@@ -12371,13 +12711,13 @@ function createUcpCheckoutKit(opts) {
         return render(s);
       }
       const kidResolver = async (kid) => opts.mandateKey ? opts.mandateKey(kid, s) : (s._platformKeys ?? []).find((k) => k.kid === kid) ?? null;
-      const v = await verifyAp2Mandate(ap2.checkout_mandate, {
+      const v2 = await verifyAp2Mandate(ap2.checkout_mandate, {
         resolveRootKey: kidResolver,
         expectedVct: AP2_VCT.checkout,
         ...checkoutJwt && { checkoutJwt }
       });
-      if (!v.ok) {
-        s.messages = [ucpError(v.code, v.error, "unrecoverable")];
+      if (!v2.ok) {
+        s.messages = [ucpError(v2.code, v2.error, "unrecoverable")];
         await store.put(s);
         return render(s);
       }
@@ -12396,19 +12736,32 @@ function createUcpCheckoutKit(opts) {
       await store.put(s);
       return render(s);
     }
+    const v = await validate(s);
+    if (v.blocked) {
+      s.status = "incomplete";
+      s.messages = v.messages;
+      delete s._held;
+      delete s._approvalId;
+      await store.put(s);
+      return render(s);
+    }
     const from = s.status;
     if (!await claim2(s, from)) {
       const current = await store.get(s.id);
       return busy(current ?? s);
     }
+    const astraId = req.headers.get("x-astra-id") ?? void 0;
+    const attemptId = req.headers.get("x-astra-attempt-id") ?? s._attemptId;
     try {
       const result = await opts.verifyPurchase({
         session: s,
         checkoutSessionId: s._astraCheckoutSessionId ?? s.id,
-        astraId: req.headers.get("x-astra-id") ?? void 0,
-        attemptId: req.headers.get("x-astra-attempt-id") ?? void 0,
+        astraId,
+        attemptId,
         ...checkoutJwt && { checkoutJwt },
-        valueMajor: total(s) / 100
+        valueMajor: total(s) / 100,
+        agentArtifacts,
+        metadata: { kitSessionId: s.id, protocol: "ucp" }
       });
       const binding2 = await bindAgent(req, result);
       if (binding2) {
@@ -12420,6 +12773,16 @@ function createUcpCheckoutKit(opts) {
       if (isHeld(result)) {
         s.status = "requires_escalation";
         s.continue_url = result.stepUpApproval?.approvalUrl ?? opts.fallbackContinueUrl;
+        s._approvalId = result.stepUpApproval?.approvalId;
+        s._astraId = astraId ?? result.agent?.astraId;
+        s._attemptId = attemptId ?? result.attemptId;
+        s._held = {
+          line_items: clone(s.line_items),
+          totals: clone(s.totals),
+          ...scrubPaymentInput(instrument) && { instrument: scrubPaymentInput(instrument) },
+          ...result.stepUpApproval?.pollUrl && { pollUrl: result.stepUpApproval.pollUrl },
+          ...result.stepUpApproval?.expiresAt && { expiresAt: result.stepUpApproval.expiresAt }
+        };
         s.messages = [
           ucpError(
             "buyer_approval_required",
@@ -12442,21 +12805,7 @@ function createUcpCheckoutKit(opts) {
         await store.put(s);
         return render(s);
       }
-      const settled = await opts.settle({ session: s, result, instrument });
-      const pending = {
-        ...result.settlementOutcome?.orderId && {
-          orderId: result.settlementOutcome.orderId
-        },
-        report: orderReportAmount(result, { amountMinor: total(s), currency: s.currency }),
-        result: pendingResult(result)
-      };
-      if (settled.status === "pending") {
-        s._pending = pending;
-        s.messages = [];
-        await store.put(s);
-        return render(s);
-      }
-      await finish(s, result, pending, settled);
+      await settleAndFinish(s, result, instrument);
       return render(s);
     } catch (e) {
       if (s.status === "complete_in_progress" && !s._pending) {
@@ -12466,13 +12815,184 @@ function createUcpCheckoutKit(opts) {
       throw e;
     }
   }
+  async function settleAndFinish(s, result, instrument) {
+    const settled = await opts.settle({ session: s, result, instrument });
+    const enhanced = result;
+    const pending = {
+      ...result.settlementOutcome?.orderId && {
+        orderId: result.settlementOutcome.orderId
+      },
+      ...enhanced.sessionId && { sessionId: enhanced.sessionId },
+      report: orderReportAmount(result, { amountMinor: total(s), currency: s.currency }),
+      result: pendingResult(result)
+    };
+    if (settled.status === "pending") {
+      s._pending = pending;
+      s.messages = [];
+      delete s._held;
+      delete s._approvalId;
+      await store.put(s);
+      return "pending";
+    }
+    await finish(s, result, pending, settled);
+    return settled.status === "failed" ? "payment_failed" : "completed";
+  }
   async function resolvePending(sessionId, outcome) {
     const s = await store.get(sessionId);
     if (!s) return null;
     if (s.status !== "complete_in_progress" || !s._pending) return s;
-    await finish(s, s._pending.result, s._pending, outcome);
+    if (store.claim) {
+      if (!await store.claim(s.id, "complete_in_progress", "finishing")) {
+        return await store.get(sessionId) ?? s;
+      }
+      s.status = "finishing";
+    } else {
+      s.status = "finishing";
+      await store.put(s);
+    }
+    const pending = s._pending;
+    try {
+      await finish(s, pending.result, pending, outcome);
+    } catch (e) {
+      s.status = "complete_in_progress";
+      s._pending = pending;
+      await store.put(s).catch(() => void 0);
+      throw e;
+    }
     return s;
   }
+  async function resumeApproved(sessionId, event) {
+    const s = await store.get(sessionId);
+    if (!s) return resumeResult("not_found", null);
+    if (s.status === "completed") return resumeResult("already_completed", s);
+    if (s.status === "canceled") return resumeResult("canceled", s);
+    if (inFlight(s.status)) return resumeResult("busy", s);
+    if (s.status !== "requires_escalation" || !s._held) return resumeResult("not_held", s);
+    if (event?.approvalId && s._approvalId && event.approvalId !== s._approvalId)
+      return resumeResult("stale", s);
+    if (!await claim2(s, "requires_escalation")) {
+      return resumeResult("busy", await store.get(sessionId) ?? s);
+    }
+    const held = s._held;
+    const backToHeld = async () => {
+      s.status = "requires_escalation";
+      s._held = held;
+      await store.put(s).catch(() => void 0);
+    };
+    try {
+      s.line_items = clone(held.line_items);
+      s.totals = clone(held.totals);
+      const v = await validate(s);
+      if (v.blocked) {
+        s.status = "incomplete";
+        s.messages = v.messages;
+        delete s._held;
+        delete s._approvalId;
+        delete s.continue_url;
+        await store.put(s);
+        return resumeResult("cart_invalid", s);
+      }
+      const checkoutJwt = s._ap2 ? s._checkoutJwt : void 0;
+      const result = await opts.verifyPurchase({
+        session: s,
+        checkoutSessionId: s._astraCheckoutSessionId ?? s.id,
+        astraId: s._astraId,
+        attemptId: s._attemptId,
+        ...checkoutJwt && { checkoutJwt },
+        valueMajor: total(s) / 100,
+        metadata: { kitSessionId: s.id, protocol: "ucp" },
+        resumed: { ...s._approvalId && { approvalId: s._approvalId } }
+      });
+      if (isHeld(result)) {
+        await backToHeld();
+        return resumeResult("still_held", s);
+      }
+      if (!result.identityVerified || !result.policyAllowed) {
+        s.status = "ready_for_complete";
+        s.messages = [
+          ucpError(
+            "agent_not_authorized",
+            "The agent is not authorized for this purchase.",
+            "unrecoverable"
+          )
+        ];
+        delete s._held;
+        delete s._approvalId;
+        delete s.continue_url;
+        await store.put(s);
+        return resumeResult("not_authorized", s);
+      }
+      delete s.continue_url;
+      const outcome = await settleAndFinish(s, result, held.instrument);
+      return resumeResult(outcome, s);
+    } catch (e) {
+      if (!s._pending && inFlight(s.status)) await backToHeld();
+      throw e;
+    }
+  }
+  async function resumeDeclined(sessionId, reason = "denied", event) {
+    const s = await store.get(sessionId);
+    if (!s) return resumeResult("not_found", null);
+    if (s.status === "completed") return resumeResult("already_completed", s);
+    if (s.status === "canceled") return resumeResult("canceled", s);
+    if (inFlight(s.status)) return resumeResult("busy", s);
+    if (s.status !== "requires_escalation") return resumeResult("not_held", s);
+    if (event?.approvalId && s._approvalId && event.approvalId !== s._approvalId)
+      return resumeResult("stale", s);
+    if (store.claim && !await store.claim(s.id, "requires_escalation", "ready_for_complete")) {
+      return resumeResult("busy", await store.get(sessionId) ?? s);
+    }
+    s.status = "ready_for_complete";
+    delete s._held;
+    delete s._approvalId;
+    delete s.continue_url;
+    s.messages = [
+      ucpError(
+        `approval_${reason}`,
+        reason === "denied" ? "The buyer declined this purchase." : "The approval for this purchase is no longer valid. Complete the checkout again to request a new one.",
+        "requires_buyer_review"
+      )
+    ];
+    await store.put(s);
+    return resumeResult("declined", s);
+  }
+  async function findForEvent(event) {
+    if (event.kitSessionId) {
+      const s = await store.get(event.kitSessionId);
+      if (s) return s;
+    }
+    if (store.findByCheckoutSessionId)
+      return store.findByCheckoutSessionId(event.checkoutSessionId);
+    return store.get(event.checkoutSessionId);
+  }
+  async function applyApprovalEvent(event) {
+    const s = await findForEvent(event);
+    if (!s) return resumeResult("not_found", null);
+    if (event.type === "step_up.approved") return resumeApproved(s.id, event);
+    return resumeDeclined(s.id, event.type.slice("step_up.".length), event);
+  }
+  async function pollHeldSessions(o = {}) {
+    const sessions = o.sessionIds ? (await Promise.all(o.sessionIds.map((id) => store.get(id)))).filter(
+      (x) => Boolean(x)
+    ) : store.listHeld ? await store.listHeld() : [];
+    const out = [];
+    for (const s of sessions) {
+      if (s.status !== "requires_escalation" || !s._held?.pollUrl || !s._approvalId) continue;
+      const status = await pollStepUpStatus({ apiBaseUrl: o.apiBaseUrl ?? "" }, {
+        approvalId: s._approvalId,
+        pollUrl: s._held.pollUrl,
+        expiresAt: s._held.expiresAt ?? ""
+      });
+      if (status === "approved" || status === "consumed") {
+        out.push({ sessionId: s.id, outcome: (await resumeApproved(s.id)).outcome });
+      } else if (status === "denied" || status === "expired") {
+        out.push({ sessionId: s.id, outcome: (await resumeDeclined(s.id, status)).outcome });
+      } else {
+        out.push({ sessionId: s.id, outcome: "pending" });
+      }
+    }
+    return out;
+  }
   async function sendOrderWebhook(sessionId) {
     const s = await store.get(sessionId);
     return s ? deliverOrder(s) : null;
@@ -12491,6 +13011,7 @@ function createUcpCheckoutKit(opts) {
     const p = await platform(req, body);
     if ("error" in p && p.error) return p.error;
     const ctx = p;
+    const agentArtifacts = buildAgentArtifacts(req, body, { protocol: "ucp", publicOrigin });
     const caller = await resolveCallerScope(req, reqCtx, opts.resolveCallerId) ?? fallbackScope("ucp-profile", ctx.profileUrl);
     if (req.method === "POST" && path === "/checkout-sessions") {
       return withIdempotency2(req, body, path, caller, async () => {
@@ -12523,6 +13044,11 @@ function createUcpCheckoutKit(opts) {
             )
           );
         }
+        if (priced.lines.length && !priced.messages.length) {
+          const v = await validate(s2);
+          s2.messages = [...s2.messages ?? [], ...v.messages];
+          if (v.blocked) s2.status = "incomplete";
+        }
         await store.put(s2);
         return render(s2, 201);
       });
@@ -12548,13 +13074,19 @@ function createUcpCheckoutKit(opts) {
     if (req.method === "PUT" && !m[2]) {
       return withIdempotency2(req, body, path, caller, async () => {
         if (s.status === "completed" || s.status === "canceled") return render(s);
-        if (s.status === "complete_in_progress") return busy(s);
+        if (inFlight(s.status)) return busy(s);
+        if (s.status === "requires_escalation") return heldNoEdit(s);
         if (parsed.line_items) {
           const priced = await priceLines(parsed.line_items);
           s.line_items = priced.lines;
           s.totals = priced.totals;
           s.messages = priced.messages;
           s.status = priced.lines.length && !priced.messages.length ? "ready_for_complete" : "incomplete";
+          if (s.status === "ready_for_complete") {
+            const v = await validate(s);
+            s.messages = [...s.messages, ...v.messages];
+            if (v.blocked) s.status = "incomplete";
+          }
         }
         if (parsed.buyer) s.buyer = parsed.buyer;
         await store.put(s);
@@ -12562,7 +13094,13 @@ function createUcpCheckoutKit(opts) {
       });
     }
     if (req.method === "POST" && m[2] === "/complete") {
-      return withIdempotency2(req, body, path, caller, () => complete(req, s, parsed));
+      return withIdempotency2(
+        req,
+        body,
+        path,
+        caller,
+        () => complete(req, s, parsed, agentArtifacts)
+      );
     }
     if (req.method === "POST" && m[2] === "/cancel") {
       return withIdempotency2(req, body, path, caller, async () => {
@@ -12571,7 +13109,7 @@ function createUcpCheckoutKit(opts) {
             code: "method_not_allowed",
             content: `A ${s.status} checkout can't be canceled.`
           });
-        if (s.status === "complete_in_progress") return busy(s);
+        if (inFlight(s.status)) return busy(s);
         s.status = "canceled";
         await store.put(s);
         return render(s);
@@ -12584,10 +13122,156 @@ function createUcpCheckoutKit(opts) {
     profile,
     profileHandler: () => json2(200, profile, { "cache-control": "public, max-age=300" }),
     resolvePending,
-    sendOrderWebhook
+    sendOrderWebhook,
+    /** 5.19.0 */
+    protocol: "ucp",
+    publicOrigin,
+    resumeApproved,
+    resumeDeclined,
+    applyApprovalEvent,
+    pollHeldSessions
   };
 }
 
+// src/webhooks.ts
+var import_crypto9 = require("crypto");
+var DEFAULT_TOLERANCE_SECONDS = 300;
+function parseSignatureHeader(header) {
+  let t;
+  const signatures = [];
+  for (const segment of header.split(",")) {
+    const eq = segment.indexOf("=");
+    if (eq < 0) continue;
+    const k = segment.slice(0, eq).trim();
+    const v = segment.slice(eq + 1).trim();
+    if (k === "t") t = v;
+    else if ((k === "v1" || k === "v1old") && v) signatures.push(v);
+  }
+  return { t, signatures };
+}
+function computeHmac(secret, signedPayload) {
+  return (0, import_crypto9.createHmac)("sha256", secret).update(signedPayload, "utf8").digest("hex");
+}
+function constantTimeEquals(a, b) {
+  const aBuf = Buffer.from(a, "utf8");
+  const bBuf = Buffer.from(b, "utf8");
+  if (aBuf.length !== bBuf.length) return false;
+  return (0, import_crypto9.timingSafeEqual)(aBuf, bBuf);
+}
+function verifyAstraSyncWebhook(rawBody, headers, secret, options = {}) {
+  const secrets = (Array.isArray(secret) ? secret : [secret]).filter(
+    (x) => typeof x === "string" && x.length > 0
+  );
+  if (!secrets.length) return { ok: false, reason: "no_secret_provided" };
+  const rawHeader = headers["x-astrasync-signature"] ?? headers["X-Astrasync-Signature"] ?? headers["X-AstraSync-Signature"] ?? headers["X-ASTRASYNC-SIGNATURE"];
+  if (!rawHeader) return { ok: false, reason: "missing_signature_header" };
+  const headerValue3 = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+  const { t: timestamp2, signatures } = parseSignatureHeader(headerValue3);
+  if (!timestamp2 || !signatures.length) {
+    return { ok: false, reason: "malformed_signature_header" };
+  }
+  const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  const now = options.nowMs ?? Date.now();
+  const tsSeconds = Number(timestamp2);
+  if (!Number.isFinite(tsSeconds)) {
+    return { ok: false, reason: "invalid_timestamp" };
+  }
+  const ageSeconds = Math.abs(now / 1e3 - tsSeconds);
+  if (ageSeconds > tolerance) {
+    return { ok: false, reason: "timestamp_outside_tolerance" };
+  }
+  for (const key of secrets) {
+    const expectedSignature = computeHmac(key, `${timestamp2}.${rawBody}`);
+    if (signatures.some((received) => constantTimeEquals(expectedSignature, received))) {
+      return { ok: true };
+    }
+  }
+  return { ok: false, reason: "signature_mismatch" };
+}
+
+// src/ucp/approval-events.ts
+var MemorySeenEvents = class {
+  constructor(max = 1e4) {
+    this.max = max;
+    this.ids = /* @__PURE__ */ new Set();
+  }
+  async has(eventId) {
+    return this.ids.has(eventId);
+  }
+  async add(eventId) {
+    if (this.ids.size >= this.max) {
+      const first2 = this.ids.values().next().value;
+      if (first2 !== void 0) this.ids.delete(first2);
+    }
+    this.ids.add(eventId);
+  }
+};
+var defaultSeen = new MemorySeenEvents();
+var TYPES = /* @__PURE__ */ new Set(["step_up.approved", "step_up.denied", "step_up.expired", "step_up.lapsed"]);
+function toHeaderRecord(headers) {
+  if (typeof Headers !== "undefined" && headers instanceof Headers) {
+    const out2 = {};
+    headers.forEach((v, k) => out2[k.toLowerCase()] = v);
+    return out2;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) out[k.toLowerCase()] = v;
+  return out;
+}
+async function handleApprovalEvents(rawBody, headers, secret, opts) {
+  const raw = typeof rawBody === "string" ? rawBody : Buffer.from(rawBody).toString("utf8");
+  const sig = verifyAstraSyncWebhook(raw, toHeaderRecord(headers), secret, {
+    ...opts.toleranceSeconds !== void 0 && { toleranceSeconds: opts.toleranceSeconds },
+    ...opts.nowMs !== void 0 && { nowMs: opts.nowMs }
+  });
+  if (!sig.ok) return { status: 401, body: { ok: false, error: sig.reason } };
+  let event;
+  try {
+    event = JSON.parse(raw);
+  } catch {
+    return { status: 400, body: { ok: false, error: "invalid_json" } };
+  }
+  if (!event || typeof event.eventId !== "string" || typeof event.type !== "string") {
+    return { status: 400, body: { ok: false, error: "invalid_event" } };
+  }
+  if (!TYPES.has(event.type)) {
+    opts.onEvent?.(event, "ignored");
+    return { status: 200, body: { ok: true, eventId: event.eventId, outcome: "ignored" } };
+  }
+  const seen = opts.seen ?? defaultSeen;
+  const has = typeof seen === "function" ? seen : (id) => seen.has(id);
+  try {
+    if (await has(event.eventId)) {
+      opts.onEvent?.(event, "duplicate");
+      return { status: 200, body: { ok: true, eventId: event.eventId, outcome: "duplicate" } };
+    }
+    const candidates = event.protocol ? opts.kits.filter((k) => k.protocol === event.protocol) : opts.kits;
+    let last = "not_found";
+    let terminal = true;
+    for (const kit of candidates) {
+      const r = await kit.applyApprovalEvent(event);
+      last = r.outcome;
+      terminal = r.terminal;
+      if (r.outcome !== "not_found") break;
+    }
+    opts.onEvent?.(event, last);
+    if (!terminal) {
+      return { status: 503, body: { ok: false, eventId: event.eventId, outcome: last } };
+    }
+    if (typeof seen !== "function") await seen.add(event.eventId);
+    return { status: 200, body: { ok: true, eventId: event.eventId, outcome: last } };
+  } catch (err) {
+    return {
+      status: 503,
+      body: {
+        ok: false,
+        eventId: event.eventId,
+        error: err instanceof Error ? err.message : "transient_error"
+      }
+    };
+  }
+}
+
 // src/payments/x402.ts
 var CAIP2 = /^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32}$/;
 var b64 = (v) => Buffer.from(JSON.stringify(v), "utf8").toString("base64");
@@ -12637,7 +13321,7 @@ function x402PaymentMatchesOffer(payment, offered) {
 }
 
 // src/payments/mpp.ts
-var import_crypto9 = require("crypto");
+var import_crypto10 = require("crypto");
 var b64url = (s) => Buffer.from(s, "utf8").toString("base64url");
 function canonical(value) {
   if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
@@ -12658,7 +13342,7 @@ function binding(c, secret) {
   ];
   if (c.header && c.header.toLowerCase() !== "authorization") slots.push(c.header);
   slots.push(c.opaque ?? "");
-  return (0, import_crypto9.createHmac)("sha256", secret).update(slots.join("|")).digest("base64url");
+  return (0, import_crypto10.createHmac)("sha256", secret).update(slots.join("|")).digest("base64url");
 }
 var quote = (v) => `"${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 function buildMppChallenge(input, hmacSecret) {
@@ -12700,13 +13384,13 @@ var MemoryMppChallengeStore = class {
   }
 };
 function mppBodyDigest(body) {
-  return `sha-256=${(0, import_crypto9.createHash)("sha256").update(body).digest("base64")}`;
+  return `sha-256=${(0, import_crypto10.createHash)("sha256").update(body).digest("base64")}`;
 }
 function checkChallenge(challenge, hmacSecret, now) {
   const { id, ...rest } = challenge;
   const expected = Buffer.from(binding(rest, hmacSecret));
   const got = Buffer.from(String(id ?? ""));
-  if (expected.length !== got.length || !(0, import_crypto9.timingSafeEqual)(expected, got))
+  if (expected.length !== got.length || !(0, import_crypto10.timingSafeEqual)(expected, got))
     return { ok: false, reason: "invalid_id" };
   if (challenge.expires && Date.parse(challenge.expires) < now.getTime())
     return { ok: false, reason: "expired" };
@@ -12722,7 +13406,7 @@ function verifyMppChallenge(challenge, hmacSecret, nowOrOptions = /* @__PURE__ *
       if (opts.body === void 0) return { ok: false, reason: "body_required" };
       const want = Buffer.from(challenge.digest);
       const got = Buffer.from(mppBodyDigest(opts.body));
-      if (want.length !== got.length || !(0, import_crypto9.timingSafeEqual)(want, got))
+      if (want.length !== got.length || !(0, import_crypto10.timingSafeEqual)(want, got))
         return { ok: false, reason: "digest_mismatch" };
     }
     if (opts.store) {
@@ -12826,7 +13510,7 @@ async function verifyKyaPayTokens(header, opts) {
 }
 
 // src/aep/core.ts
-var import_crypto10 = require("crypto");
+var import_crypto11 = require("crypto");
 var AEP_SPEC_VERSION = "aep-1.0.3-rc.2";
 function aepCanonicalJson(value) {
   if (value === null) return "null";
@@ -12847,7 +13531,7 @@ function aepCanonicalJson(value) {
   throw new Error(`AEP canonical JSON: unsupported value of type ${typeof value}`);
 }
 function digest(input) {
-  return (0, import_crypto10.createHash)("sha256").update(aepCanonicalJson(input), "utf8").digest();
+  return (0, import_crypto11.createHash)("sha256").update(aepCanonicalJson(input), "utf8").digest();
 }
 function aepHash(input) {
   return `sha256:${digest(input).toString("hex")}`;
@@ -12860,7 +13544,7 @@ var ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
 function aepPrivateKeyFromSeed(seedBase64) {
   const seed = Buffer.from(seedBase64, "base64");
   if (seed.length !== 32) throw new Error("Ed25519 seed must be 32 bytes");
-  return (0, import_crypto10.createPrivateKey)({
+  return (0, import_crypto11.createPrivateKey)({
     key: Buffer.concat([ED25519_PKCS8_PREFIX, seed]),
     format: "der",
     type: "pkcs8"
@@ -12869,14 +13553,14 @@ function aepPrivateKeyFromSeed(seedBase64) {
 function aepPublicKeyFromBase64(raw) {
   const bytes2 = Buffer.from(raw, "base64");
   if (bytes2.length !== 32) throw new Error("Ed25519 public key must be 32 bytes");
-  return (0, import_crypto10.createPublicKey)({
+  return (0, import_crypto11.createPublicKey)({
     key: Buffer.concat([ED25519_SPKI_PREFIX, bytes2]),
     format: "der",
     type: "spki"
   });
 }
 function aepRawPublicKey(key) {
-  const pub = key.type === "private" ? (0, import_crypto10.createPublicKey)(key) : key;
+  const pub = key.type === "private" ? (0, import_crypto11.createPublicKey)(key) : key;
   return pub.export({ format: "der", type: "spki" }).subarray(12).toString("base64");
 }
 function hashBytes(currentHash) {
@@ -12885,11 +13569,11 @@ function hashBytes(currentHash) {
   return Buffer.from(m[1], "hex");
 }
 function aepSign(currentHash, privateKey) {
-  return (0, import_crypto10.sign)(null, hashBytes(currentHash), privateKey).toString("base64");
+  return (0, import_crypto11.sign)(null, hashBytes(currentHash), privateKey).toString("base64");
 }
 function aepVerifySignature(currentHash, signature, publicKey) {
   try {
-    return (0, import_crypto10.verify)(null, hashBytes(currentHash), publicKey, Buffer.from(signature, "base64"));
+    return (0, import_crypto11.verify)(null, hashBytes(currentHash), publicKey, Buffer.from(signature, "base64"));
   } catch {
     return false;
   }
@@ -12987,7 +13671,7 @@ function aepPublicKeyDocument(keys, revocations = []) {
 }
 
 // src/acp/checkout-kit.ts
-var import_crypto11 = require("crypto");
+var import_crypto12 = require("crypto");
 var ACP_API_VERSION = "2026-04-17";
 var ACP_SUPPORTED_API_VERSIONS = [ACP_API_VERSION];
 function acpPaymentHandlers(names) {
@@ -13017,6 +13701,23 @@ function buildAcpWellKnown(opts) {
 var json3 = (status, body) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
 var apiError = (status, code, message, param) => json3(status, { type: "invalid_request", code, message, ...param && { param } });
 var total2 = (s) => s.totals.find((t) => t.type === "total")?.amount ?? 0;
+var clone2 = (v) => JSON.parse(JSON.stringify(v));
+var inFlight2 = (st) => st === "complete_in_progress" || st === "finishing";
+var ACP_CODES = /* @__PURE__ */ new Set([
+  "missing",
+  "invalid",
+  "out_of_stock",
+  "payment_declined",
+  "requires_sign_in",
+  "requires_3ds"
+]);
+function heldBody2(text) {
+  try {
+    return JSON.parse(text).status === "pending_approval";
+  } catch {
+    return false;
+  }
+}
 function createAcpCheckoutKit(opts) {
   const mem = /* @__PURE__ */ new Map();
   const store = opts.store ?? {
@@ -13027,7 +13728,14 @@ function createAcpCheckoutKit(opts) {
       if (!s || s.status !== from) return false;
       s.status = to;
       return true;
-    }
+    },
+    findByCheckoutSessionId: async (checkoutSessionId) => {
+      for (const s of mem.values()) {
+        if ((s._astraCheckoutSessionId ?? s.id) === checkoutSessionId) return s;
+      }
+      return mem.get(checkoutSessionId) ?? null;
+    },
+    listHeld: async () => [...mem.values()].filter((s) => s.status === "pending_approval")
   };
   const idem = {
     store: opts.idempotencyStore ?? new MemoryIdempotencyStore(),
@@ -13045,16 +13753,19 @@ function createAcpCheckoutKit(opts) {
     );
   }
   const handlers = acpPaymentHandlers(opts.paymentHandlers);
+  const handlerIds = new Set(handlers.flatMap((h) => [h.id, h.name]));
+  const publicOrigin = opts.publicOrigin?.replace(/\/+$/, "");
+  const onReportError = opts.onReportError ?? defaultOnReportError;
   function view(s) {
     return {
       id: s.id,
-      status: s.status,
+      status: s.status === "finishing" ? "complete_in_progress" : s.status,
       currency: s.currency.toLowerCase(),
       line_items: s.line_items,
       totals: s.totals,
       fulfillment_options: [],
       messages: s.messages,
-      links: [],
+      links: opts.links ?? [],
       capabilities: { payment: { handlers } },
       ...s.continue_url && s.status === "pending_approval" && { continue_url: s.continue_url },
       ...s.order && { order: s.order }
@@ -13064,7 +13775,8 @@ function createAcpCheckoutKit(opts) {
     const lines = [];
     const messages = [];
     for (const [i, it] of items.entries()) {
-      const c = it.id ? await opts.catalog(it.id) : null;
+      const q = Math.max(1, Math.floor(it.quantity ?? 1));
+      const c = it.id ? await opts.catalog(it.id, q) : null;
       if (!c) {
         messages.push({
           type: "error",
@@ -13075,7 +13787,6 @@ function createAcpCheckoutKit(opts) {
         });
         continue;
       }
-      const q = Math.max(1, Math.floor(it.quantity ?? 1));
       const amount = c.price * q;
       lines.push({
         id: `li_${i + 1}`,
@@ -13099,6 +13810,21 @@ function createAcpCheckoutKit(opts) {
       ]
     };
   }
+  async function validate(s) {
+    if (!opts.validateCart) return { messages: [], blocked: false };
+    const found = await opts.validateCart(s);
+    const messages = found.map((m) => {
+      const error = (m.type ?? "error") === "error";
+      return {
+        type: m.type ?? "error",
+        code: error ? ACP_CODES.has(m.code) ? m.code : "invalid" : m.code,
+        content: m.content,
+        ...error && { resolution: "recoverable" },
+        ...m.path && { param: m.path }
+      };
+    });
+    return { messages, blocked: found.some((m) => (m.type ?? "error") === "error") };
+  }
   async function idempotent(req, body, path, caller, run) {
     const d = await beginIdempotent(idem, {
       method: req.method,
@@ -13114,29 +13840,43 @@ function createAcpCheckoutKit(opts) {
         headers: { ...d.headers, "idempotent-replayed": "true" }
       });
     const res = await run();
-    if (d.kind === "proceed")
-      await finishIdempotent(idem, d, {
-        status: res.status,
-        headers: { "content-type": "application/json" },
-        body: await res.clone().text()
-      });
+    if (d.kind === "proceed") {
+      const text = await res.clone().text();
+      if (heldBody2(text)) await abandonIdempotent(idem, d);
+      else
+        await finishIdempotent(idem, d, {
+          status: res.status,
+          headers: { "content-type": "application/json" },
+          body: text
+        });
+    }
     return res;
   }
   const inProgress = () => apiError(409, "checkout_in_progress", "This checkout session is already being completed.");
-  async function reportOutcome(p, settled) {
-    if (!opts.reportSettlement || !p.orderId) return;
-    await opts.reportSettlement({
-      orderId: p.orderId,
-      status: settled.status,
-      ...p.report,
-      ...settled.status === "settled" && settled.processorRef && { processorRef: settled.processorRef },
-      ...settled.status === "settled" && settled.txHash && { txHash: settled.txHash, chainId: settled.chainId },
-      ...settled.status === "failed" && settled.failureCode && { failureCode: settled.failureCode }
-    }).catch(() => void 0);
+  async function reportOutcome(s, p, settled) {
+    const report = opts.reportSettlement;
+    const ref = p.orderId ? { orderId: p.orderId } : p.sessionId ? { sessionId: p.sessionId } : null;
+    if (!report || !ref) return;
+    await withReportRetries(
+      () => report({
+        ...ref,
+        status: settled.status,
+        ...p.report,
+        ...settled.status === "settled" && settled.processorRef && { processorRef: settled.processorRef },
+        ...settled.status === "settled" && settled.txHash && { txHash: settled.txHash, chainId: settled.chainId },
+        ...settled.status === "failed" && settled.failureCode && { failureCode: settled.failureCode }
+      }),
+      opts.reportRetry,
+      isRetryableSettlementError
+    ).catch(
+      (err) => onReportError(err, { sessionId: s.id, orderId: p.orderId, kind: "settlement_report" })
+    );
   }
   async function finish(s, result, p, settled) {
-    await reportOutcome(p, settled);
+    await reportOutcome(s, p, settled);
     delete s._pending;
+    delete s._held;
+    delete s._approvalId;
     if (settled.status === "failed") {
       s.status = "ready_for_payment";
       s.messages = [
@@ -13145,13 +13885,13 @@ function createAcpCheckoutKit(opts) {
           code: "payment_declined",
           content: "The payment was declined.",
           severity: "high",
-          resolution: "requires_buyer_input"
+          resolution: "recoverable"
         }
       ];
       await store.put(s);
       return;
     }
-    const order = await opts.fulfil({ session: s, result });
+    const order = await opts.fulfil({ session: s, result, settled });
     const permalink = order.permalink_url ?? (opts.permalinkBase && `${opts.permalinkBase.replace(/\/+$/, "")}/${encodeURIComponent(order.id)}`);
     s.order = {
       id: order.id,
@@ -13174,11 +13914,29 @@ function createAcpCheckoutKit(opts) {
     s.messages = [];
     await store.put(s);
   }
-  async function complete(req, s, body) {
+  async function complete(req, s, body, agentArtifacts) {
     if (s.status === "completed" || s.status === "canceled") return json3(200, view(s));
-    if (s.status === "complete_in_progress") return inProgress();
+    if (inFlight2(s.status)) return inProgress();
     if (!body.payment_data)
       return apiError(400, "missing", "payment_data is required.", "$.payment_data");
+    const paymentData = body.payment_data;
+    if (Array.isArray(paymentData) || typeof paymentData !== "object" || typeof paymentData.handler_id !== "string" || !handlerIds.has(paymentData.handler_id)) {
+      return apiError(
+        400,
+        "invalid",
+        "payment_data must be one object whose handler_id is the id or name of a payment handler this merchant declares.",
+        "$.payment_data.handler_id"
+      );
+    }
+    const v = await validate(s);
+    if (v.blocked) {
+      s.status = "not_ready_for_payment";
+      s.messages = v.messages;
+      delete s._held;
+      delete s._approvalId;
+      await store.put(s);
+      return json3(200, view(s));
+    }
     const from = s.status;
     if (store.claim) {
       if (!await store.claim(s.id, from, "complete_in_progress")) return inProgress();
@@ -13187,17 +13945,31 @@ function createAcpCheckoutKit(opts) {
       s.status = "complete_in_progress";
       await store.put(s);
     }
+    const astraId = req.headers.get("x-astra-id") ?? void 0;
+    const attemptId = req.headers.get("x-astra-attempt-id") ?? s._attemptId;
     try {
       const result = await opts.verifyPurchase({
         session: s,
         checkoutSessionId: s._astraCheckoutSessionId ?? s.id,
-        astraId: req.headers.get("x-astra-id") ?? void 0,
-        attemptId: req.headers.get("x-astra-attempt-id") ?? void 0,
-        valueMajor: total2(s) / 100
+        astraId,
+        attemptId,
+        valueMajor: total2(s) / 100,
+        agentArtifacts,
+        metadata: { kitSessionId: s.id, protocol: "acp" }
       });
       if (isHeld(result)) {
         s.status = "pending_approval";
         s.continue_url = result.stepUpApproval?.approvalUrl ?? opts.fallbackContinueUrl;
+        s._approvalId = result.stepUpApproval?.approvalId;
+        s._astraId = astraId ?? result.agent?.astraId;
+        s._attemptId = attemptId ?? result.attemptId;
+        s._held = {
+          line_items: clone2(s.line_items),
+          totals: clone2(s.totals),
+          ...scrubPaymentInput(paymentData) && { paymentData: scrubPaymentInput(paymentData) },
+          ...result.stepUpApproval?.pollUrl && { pollUrl: result.stepUpApproval.pollUrl },
+          ...result.stepUpApproval?.expiresAt && { expiresAt: result.stepUpApproval.expiresAt }
+        };
         s.messages = [
           {
             type: "error",
@@ -13212,36 +13984,11 @@ function createAcpCheckoutKit(opts) {
       }
       if (!result.identityVerified || !result.policyAllowed) {
         s.status = from;
-        s.messages = [
-          {
-            type: "error",
-            code: "intervention_required",
-            content: "The agent is not authorized for this purchase.",
-            severity: "high",
-            resolution: "requires_buyer_review"
-          }
-        ];
-        await store.put(s);
-        return json3(200, view(s));
-      }
-      const settled = await opts.settle({
-        session: s,
-        result,
-        paymentData: body.payment_data
-      });
-      const orderId = result.settlementOutcome?.orderId;
-      const pending = {
-        ...orderId && { orderId },
-        report: orderReportAmount(result, { amountMinor: total2(s), currency: s.currency }),
-        result: pendingResult(result)
-      };
-      if (settled.status === "pending") {
-        s._pending = pending;
-        s.messages = [];
+        s.messages = [notAuthorized()];
         await store.put(s);
         return json3(200, view(s));
       }
-      await finish(s, result, pending, settled);
+      await settleAndFinish(s, result, paymentData);
       return json3(200, view(s));
     } catch (e) {
       if (s.status === "complete_in_progress" && !s._pending) {
@@ -13251,13 +13998,188 @@ function createAcpCheckoutKit(opts) {
       throw e;
     }
   }
+  const notAuthorized = () => ({
+    type: "error",
+    code: "intervention_required",
+    content: "The agent is not authorized for this purchase.",
+    severity: "high",
+    resolution: "requires_buyer_review"
+  });
+  async function settleAndFinish(s, result, paymentData) {
+    const settled = await opts.settle({ session: s, result, paymentData });
+    const orderId = result.settlementOutcome?.orderId;
+    const sessionId = result.sessionId;
+    const pending = {
+      ...orderId && { orderId },
+      ...sessionId && { sessionId },
+      report: orderReportAmount(result, { amountMinor: total2(s), currency: s.currency }),
+      result: pendingResult(result)
+    };
+    if (settled.status === "pending") {
+      s._pending = pending;
+      s.messages = [];
+      delete s._held;
+      delete s._approvalId;
+      await store.put(s);
+      return "pending";
+    }
+    await finish(s, result, pending, settled);
+    return settled.status === "failed" ? "payment_failed" : "completed";
+  }
   async function resolvePending(sessionId, outcome) {
     const s = await store.get(sessionId);
     if (!s) return null;
     if (s.status !== "complete_in_progress" || !s._pending) return s;
-    await finish(s, s._pending.result, s._pending, outcome);
+    if (store.claim) {
+      if (!await store.claim(s.id, "complete_in_progress", "finishing")) {
+        return await store.get(sessionId) ?? s;
+      }
+      s.status = "finishing";
+    } else {
+      s.status = "finishing";
+      await store.put(s);
+    }
+    const pending = s._pending;
+    try {
+      await finish(s, pending.result, pending, outcome);
+    } catch (e) {
+      s.status = "complete_in_progress";
+      s._pending = pending;
+      await store.put(s).catch(() => void 0);
+      throw e;
+    }
     return s;
   }
+  async function resumeApproved(sessionId, event) {
+    const s = await store.get(sessionId);
+    if (!s) return resumeResult("not_found", null);
+    if (s.status === "completed") return resumeResult("already_completed", s);
+    if (s.status === "canceled") return resumeResult("canceled", s);
+    if (inFlight2(s.status)) return resumeResult("busy", s);
+    if (s.status !== "pending_approval" || !s._held) return resumeResult("not_held", s);
+    if (event?.approvalId && s._approvalId && event.approvalId !== s._approvalId)
+      return resumeResult("stale", s);
+    if (store.claim) {
+      if (!await store.claim(s.id, "pending_approval", "complete_in_progress"))
+        return resumeResult("busy", await store.get(sessionId) ?? s);
+      s.status = "complete_in_progress";
+    } else {
+      s.status = "complete_in_progress";
+      await store.put(s);
+    }
+    const held = s._held;
+    const backToHeld = async () => {
+      s.status = "pending_approval";
+      s._held = held;
+      await store.put(s).catch(() => void 0);
+    };
+    try {
+      s.line_items = clone2(held.line_items);
+      s.totals = clone2(held.totals);
+      const v = await validate(s);
+      if (v.blocked) {
+        s.status = "not_ready_for_payment";
+        s.messages = v.messages;
+        delete s._held;
+        delete s._approvalId;
+        delete s.continue_url;
+        await store.put(s);
+        return resumeResult("cart_invalid", s);
+      }
+      const result = await opts.verifyPurchase({
+        session: s,
+        checkoutSessionId: s._astraCheckoutSessionId ?? s.id,
+        astraId: s._astraId,
+        attemptId: s._attemptId,
+        valueMajor: total2(s) / 100,
+        metadata: { kitSessionId: s.id, protocol: "acp" },
+        resumed: { ...s._approvalId && { approvalId: s._approvalId } }
+      });
+      if (isHeld(result)) {
+        await backToHeld();
+        return resumeResult("still_held", s);
+      }
+      if (!result.identityVerified || !result.policyAllowed) {
+        s.status = "ready_for_payment";
+        s.messages = [notAuthorized()];
+        delete s._held;
+        delete s._approvalId;
+        delete s.continue_url;
+        await store.put(s);
+        return resumeResult("not_authorized", s);
+      }
+      delete s.continue_url;
+      return resumeResult(await settleAndFinish(s, result, held.paymentData), s);
+    } catch (e) {
+      if (!s._pending && inFlight2(s.status)) await backToHeld();
+      throw e;
+    }
+  }
+  async function resumeDeclined(sessionId, reason = "denied", event) {
+    const s = await store.get(sessionId);
+    if (!s) return resumeResult("not_found", null);
+    if (s.status === "completed") return resumeResult("already_completed", s);
+    if (s.status === "canceled") return resumeResult("canceled", s);
+    if (inFlight2(s.status)) return resumeResult("busy", s);
+    if (s.status !== "pending_approval") return resumeResult("not_held", s);
+    if (event?.approvalId && s._approvalId && event.approvalId !== s._approvalId)
+      return resumeResult("stale", s);
+    if (store.claim && !await store.claim(s.id, "pending_approval", "ready_for_payment")) {
+      return resumeResult("busy", await store.get(sessionId) ?? s);
+    }
+    s.status = "ready_for_payment";
+    delete s._held;
+    delete s._approvalId;
+    delete s.continue_url;
+    s.messages = [
+      {
+        type: "error",
+        code: `approval_${reason}`,
+        content: reason === "denied" ? "The buyer declined this purchase." : "The approval for this purchase is no longer valid. Complete the session again to request a new one.",
+        severity: "medium",
+        resolution: "requires_buyer_review"
+      }
+    ];
+    await store.put(s);
+    return resumeResult("declined", s);
+  }
+  async function findForEvent(event) {
+    if (event.kitSessionId) {
+      const s = await store.get(event.kitSessionId);
+      if (s) return s;
+    }
+    if (store.findByCheckoutSessionId)
+      return store.findByCheckoutSessionId(event.checkoutSessionId);
+    return store.get(event.checkoutSessionId);
+  }
+  async function applyApprovalEvent(event) {
+    const s = await findForEvent(event);
+    if (!s) return resumeResult("not_found", null);
+    if (event.type === "step_up.approved") return resumeApproved(s.id, event);
+    return resumeDeclined(s.id, event.type.slice("step_up.".length), event);
+  }
+  async function pollHeldSessions(o = {}) {
+    const sessions = o.sessionIds ? (await Promise.all(o.sessionIds.map((id) => store.get(id)))).filter(
+      (x) => Boolean(x)
+    ) : store.listHeld ? await store.listHeld() : [];
+    const out = [];
+    for (const s of sessions) {
+      if (s.status !== "pending_approval" || !s._held?.pollUrl || !s._approvalId) continue;
+      const status = await pollStepUpStatus({ apiBaseUrl: o.apiBaseUrl ?? "" }, {
+        approvalId: s._approvalId,
+        pollUrl: s._held.pollUrl,
+        expiresAt: s._held.expiresAt ?? ""
+      });
+      if (status === "approved" || status === "consumed") {
+        out.push({ sessionId: s.id, outcome: (await resumeApproved(s.id)).outcome });
+      } else if (status === "denied" || status === "expired") {
+        out.push({ sessionId: s.id, outcome: (await resumeDeclined(s.id, status)).outcome });
+      } else {
+        out.push({ sessionId: s.id, outcome: "pending" });
+      }
+    }
+    return out;
+  }
   async function route(req, reqCtx) {
     const version = req.headers.get("api-version");
     if (!version) return apiError(400, "missing", "The API-Version header is required.");
@@ -13282,6 +14204,7 @@ function createAcpCheckoutKit(opts) {
     const caller = await resolveCallerScope(req, reqCtx, opts.resolveCallerId);
     if (!caller)
       return apiError(401, "unauthorized", "Send an Authorization header (or X-Astra-Id).");
+    const agentArtifacts = buildAgentArtifacts(req, body, { protocol: "acp", publicOrigin });
     if (req.method === "POST" && path === "/checkout_sessions") {
       return idempotent(req, body, path, caller, async () => {
         const items = parsed.line_items ?? parsed.items;
@@ -13289,7 +14212,7 @@ function createAcpCheckoutKit(opts) {
           return apiError(400, "missing", "line_items is required.", "$.line_items");
         const p = await price(items);
         const s2 = {
-          id: `cs_${(0, import_crypto11.randomUUID)().replace(/-/g, "")}`,
+          id: `cs_${(0, import_crypto12.randomUUID)().replace(/-/g, "")}`,
           status: p.lines.length && !p.messages.length ? "ready_for_payment" : "not_ready_for_payment",
           currency: opts.currency,
           line_items: p.lines,
@@ -13300,6 +14223,11 @@ function createAcpCheckoutKit(opts) {
             _astraCheckoutSessionId: req.headers.get("x-astra-checkout-session").slice(0, 64)
           }
         };
+        if (s2.status === "ready_for_payment") {
+          const v = await validate(s2);
+          s2.messages = [...s2.messages, ...v.messages];
+          if (v.blocked) s2.status = "not_ready_for_payment";
+        }
         await store.put(s2);
         return json3(201, view(s2));
       });
@@ -13313,7 +14241,13 @@ function createAcpCheckoutKit(opts) {
     if (!m[2]) {
       return idempotent(req, body, path, caller, async () => {
         if (s.status === "completed" || s.status === "canceled") return json3(200, view(s));
-        if (s.status === "complete_in_progress") return inProgress();
+        if (inFlight2(s.status)) return inProgress();
+        if (s.status === "pending_approval")
+          return apiError(
+            409,
+            "checkout_awaiting_approval",
+            "This session is waiting for the buyer\u2019s approval and can\u2019t be changed. Cancel it to start over."
+          );
         const items = parsed.line_items ?? parsed.items;
         if (items) {
           const p = await price(items);
@@ -13323,17 +14257,22 @@ function createAcpCheckoutKit(opts) {
             messages: p.messages,
             status: p.lines.length && !p.messages.length ? "ready_for_payment" : "not_ready_for_payment"
           });
+          if (s.status === "ready_for_payment") {
+            const v = await validate(s);
+            s.messages = [...s.messages, ...v.messages];
+            if (v.blocked) s.status = "not_ready_for_payment";
+          }
         }
         await store.put(s);
         return json3(200, view(s));
       });
     }
     if (m[2] === "/complete")
-      return idempotent(req, body, path, caller, () => complete(req, s, parsed));
+      return idempotent(req, body, path, caller, () => complete(req, s, parsed, agentArtifacts));
     return idempotent(req, body, path, caller, async () => {
       if (s.status === "completed" || s.status === "canceled")
         return apiError(405, "method_not_allowed", `A ${s.status} session can't be canceled.`);
-      if (s.status === "complete_in_progress") return inProgress();
+      if (inFlight2(s.status)) return inProgress();
       s.status = "canceled";
       await store.put(s);
       return json3(200, view(s));
@@ -13349,7 +14288,17 @@ function createAcpCheckoutKit(opts) {
     if (requestId) headers.set("request-id", requestId);
     return new Response(res.body, { status: res.status, headers });
   }
-  return { handle, resolvePending };
+  return {
+    handle,
+    resolvePending,
+    /** 5.19.0 */
+    protocol: "acp",
+    publicOrigin,
+    resumeApproved,
+    resumeDeclined,
+    applyApprovalEvent,
+    pollHeldSessions
+  };
 }
 
 // src/adapters/kit-express.ts
@@ -13371,11 +14320,46 @@ function rawBodyOf(req) {
   }
   return void 0;
 }
+var first = (v) => (Array.isArray(v) ? v[0] : v)?.split(",")[0]?.trim() || void 0;
+function originOf(req, publicOrigin) {
+  if (publicOrigin) return publicOrigin.replace(/\/+$/, "");
+  const trustProxy = Boolean(req.app?.get("trust proxy"));
+  const host = trustProxy && first(req.headers["x-forwarded-host"]) || req.get?.("host") || req.headers.host || "localhost";
+  const proto = trustProxy && first(req.headers["x-forwarded-proto"]) || req.protocol || "http";
+  return `${proto}://${host}`;
+}
+var isKit = (k) => typeof k.applyApprovalEvent === "function" && (k.protocol === "ucp" || k.protocol === "acp");
+async function writeEvents(req, res, secret, kits, seen) {
+  const raw = rawBodyOf(req);
+  const text = raw === void 0 ? "" : typeof raw === "string" ? raw : Buffer.from(raw).toString("utf8");
+  const out = secret ? await handleApprovalEvents(text, req.headers, secret, { kits, ...seen && { seen } }) : { status: 500, body: { ok: false, error: "webhook_secret_not_configured" } };
+  res.status(out.status);
+  res.setHeader("content-type", "application/json");
+  res.end(JSON.stringify(out.body));
+}
+function approvalEventsHandler(options) {
+  return async (req, res, next) => {
+    try {
+      await writeEvents(req, res, options.secret, options.kits, options.seen);
+    } catch (err) {
+      next(err);
+    }
+  };
+}
 function expressHandler(kit, options = {}) {
   return async (req, res, next) => {
     try {
-      const host = req.get?.("host") ?? req.headers.host ?? "localhost";
-      const url = `${req.protocol ?? "http"}://${host}${req.originalUrl ?? req.url}`;
+      if (options.approvalEventsPath && req.method === "POST") {
+        const p = options.approvalEventsPath.replace(/\/+$/, "");
+        const full = (req.originalUrl ?? req.url).split("?")[0].replace(/\/+$/, "");
+        const local = req.url.split("?")[0].replace(/\/+$/, "");
+        if (full === p || local === p) {
+          const kits = options.approvalEventKits ?? (isKit(kit) ? [kit] : []);
+          await writeEvents(req, res, options.webhookSecret, kits, options.seenEvents);
+          return;
+        }
+      }
+      const url = `${originOf(req, kit.publicOrigin)}${req.originalUrl ?? req.url}`;
       const headers = new Headers();
       for (const [k, v] of Object.entries(req.headers)) {
         if (v === void 0) continue;
@@ -13426,6 +14410,7 @@ function expressHandler(kit, options = {}) {
   MemoryCheckoutStore,
   MemoryIdempotencyStore,
   MemoryMppChallengeStore,
+  MemorySeenEvents,
   PLATFORM_AGENT_SIGNATURES,
   RUNTIME_SIGNATURES,
   RedisIdempotencyStore,
@@ -13440,6 +14425,7 @@ function expressHandler(kit, options = {}) {
   VERIFICATION_STATUS_HEADER,
   VERSION,
   _resetEdgeConfigCache,
+  abandonIdempotent,
   acpPaymentHandlers,
   aepCanonicalJson,
   aepHash,
@@ -13451,6 +14437,7 @@ function expressHandler(kit, options = {}) {
   aepTimestamp,
   aepVerifySignature,
   agent,
+  approvalEventsHandler,
   astrasyncPaymentHandlers,
   authorizeSettlement,
   awaitStepUpApproval,
@@ -13497,6 +14484,7 @@ function expressHandler(kit, options = {}) {
   getEdgeConfig,
   getTrustLevel,
   getWellKnownUrls,
+  handleApprovalEvents,
   hasCredentials,
   idempotencyMiddleware,
   isEdgeConfig,