@astrasyncai/verification-gateway 5.19.0 → 5.20.0

package/dist/index.mjs

@@ -30,7 +30,7 @@ function getTrustLevel(score) {
 }
 
 // src/version.ts
-var SDK_VERSION = "5.19.0";
+var SDK_VERSION = "5.20.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -312,6 +312,7 @@ function cacheResult(request, result, configuredTtl, counterpartyId) {
 }
 function clearCache() {
   verificationCache.clear();
+  inflightVerifies.clear();
 }
 function extractCredentials(headers, query) {
   const credentials = {};
@@ -485,6 +486,9 @@ async function callVerifyAccessAPI(config, request) {
   if (requestData.enableRuntimeChallenge)
     body.enableRuntimeChallenge = requestData.enableRuntimeChallenge;
   if (requestData.routePolicy) body.routePolicy = requestData.routePolicy;
+  if (config.actingProof?.connectorToken) {
+    body.actingProof = { connectorToken: config.actingProof.connectorToken };
+  }
   if (requestData.approvalHeldByRoute) body.approvalHeldByRoute = true;
   if (requestData.createSession) body.createSession = requestData.createSession;
   if (requestData.durationRequired) body.durationRequired = requestData.durationRequired;
@@ -652,22 +656,46 @@ async function verify(config, request, options) {
       "[VerificationGateway] minTrustScore / minTrustScoreForFull are deprecated in v2.3.0 and have no effect. Server is now the single source of truth for access decisions (verified ID + runtime challenge + PDLSS + trust score). To gate access to an endpoint, configure the endpoint's trust_score_requirement server-side."
     );
   }
-  const uncacheable = Boolean(request.commerceArtifacts);
+  const uncacheable = Boolean(request.commerceArtifacts) || Boolean(mergedConfig.actingProof);
   if (mergedConfig.cacheTtl !== 0 && !options?.bypassCache && !uncacheable) {
     const cached = getCachedResult(request, mergedConfig.counterpartyId);
     if (cached) {
       if (mergedConfig.debug) {
         console.log("[VerificationGateway] Returning cached result");
       }
-      const hit = { ...cached };
-      if (request.attemptId) {
-        hit.attemptId = request.attemptId;
-      } else {
-        delete hit.attemptId;
-      }
-      return hit;
+      return sharedVerdict(cached, request);
+    }
+  }
+  if (mergedConfig.cacheTtl !== 0 && !options?.bypassCache && !uncacheable) {
+    const key = getCacheKey(request, mergedConfig.counterpartyId);
+    const pending = inflightVerifies.get(key);
+    if (pending) return sharedVerdict(await pending, request);
+    const flight = verifyViaApi(mergedConfig, request, urls, uncacheable);
+    inflightVerifies.set(key, flight);
+    try {
+      return await flight;
+    } finally {
+      inflightVerifies.delete(key);
     }
   }
+  return verifyViaApi(mergedConfig, request, urls, uncacheable);
+}
+var inflightVerifies = /* @__PURE__ */ new Map();
+var sharedVerdicts = /* @__PURE__ */ new WeakSet();
+function isSharedVerdict(result) {
+  return sharedVerdicts.has(result);
+}
+function sharedVerdict(source, request) {
+  const hit = { ...source };
+  if (request.attemptId) {
+    hit.attemptId = request.attemptId;
+  } else {
+    delete hit.attemptId;
+  }
+  sharedVerdicts.add(hit);
+  return hit;
+}
+async function verifyViaApi(mergedConfig, request, urls, uncacheable) {
   const enrichedRequest = { ...request };
   if (!enrichedRequest.counterpartyUrl && mergedConfig.counterpartyUrl) {
     enrichedRequest.counterpartyUrl = mergedConfig.counterpartyUrl;
@@ -746,7 +774,9 @@ async function verify(config, request, options) {
       fulfilment: apiResponse.fulfilment,
       mandates: apiResponse.mandates,
       kyaToken: apiResponse.kyaToken,
-      aep: apiResponse.aep
+      aep: apiResponse.aep,
+      // 5.20.0 (round 29.1): non-fatal integration warnings (e.g. events_url_missing).
+      warnings: apiResponse.warnings
     };
     return result2;
   }
@@ -814,7 +844,9 @@ async function verify(config, request, options) {
     // 5.15.0: merchant-lane AP2 mandates + KYAPay identity token.
     mandates: apiResponse.mandates,
     kyaToken: apiResponse.kyaToken,
-    aep: apiResponse.aep
+    aep: apiResponse.aep,
+    // 5.20.0 (round 29.1): non-fatal integration warnings (e.g. events_url_missing).
+    warnings: apiResponse.warnings
   };
   if (result.recommendation === "deny") {
     result.policyAllowed = false;
@@ -840,8 +872,24 @@ async function verify(config, request, options) {
       cacheResult(request, result, mergedConfig.cacheTtl, mergedConfig.counterpartyId);
     }
   }
+  notifyVerificationListeners(request, result);
   return result;
 }
+var verificationListeners = /* @__PURE__ */ new Set();
+function onVerificationResult(listener) {
+  verificationListeners.add(listener);
+  return () => {
+    verificationListeners.delete(listener);
+  };
+}
+function notifyVerificationListeners(request, result) {
+  for (const listener of verificationListeners) {
+    try {
+      listener(result, request);
+    } catch {
+    }
+  }
+}
 async function recordDecision(config, sessionId, decision, reason) {
   const headers = { "Content-Type": "application/json" };
   if (config.apiKey) {
@@ -906,6 +954,7 @@ async function fetchRoutes(config, counterpartyId, options = {}) {
     headers["X-API-Key"] = config.apiKey;
   }
   try {
+    headers["X-AstraSync-SDK-Version"] = SDK_VERSION;
     const response = await sdkFetch(
       `${config.apiBaseUrl}/endpoints/${encodeURIComponent(counterpartyId)}/routes` + (options.codeGates?.length ? `?codeGates=${options.codeGates.map(encodeURIComponent).join(",")}` : ""),
       { method: "GET", headers }
@@ -920,6 +969,13 @@ async function fetchRoutes(config, counterpartyId, options = {}) {
       return null;
     }
     const body = await response.json();
+    const type2 = body.data?.counterpartyType;
+    if (typeof type2 === "string" && options.onEndpointType) {
+      try {
+        options.onEndpointType(type2);
+      } catch {
+      }
+    }
     return body.data?.routes ?? [];
   } catch {
     return null;
@@ -2843,14 +2899,14 @@ function createMiddleware(options) {
           res.setHeader("X-Astra-Gateway-Mode", "enforced");
           res.setHeader("X-Astra-Gateway-Reason", "evaluated-not-enforced");
         }
-        if (shouldRecordDecisions && sessionId) {
+        if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
           recordDecision(config, sessionId, "granted").catch(() => {
           });
         }
         return next();
       }
       if (!result.policyAllowed) {
-        if (shouldRecordDecisions && sessionId) {
+        if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
           });
         }
@@ -2863,7 +2919,7 @@ function createMiddleware(options) {
       }
       if (requiresHumanApproval(result)) {
         annotateApprovalRequired(result);
-        if (shouldRecordDecisions && sessionId) {
+        if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
           });
         }
@@ -2888,7 +2944,7 @@ function createMiddleware(options) {
               documentationUrl: wellKnownUrls.documentationUrl
             };
           }
-          if (shouldRecordDecisions && sessionId) {
+          if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
             recordDecision(config, sessionId, "denied", trustFailure.message).catch(() => {
             });
           }
@@ -2897,7 +2953,7 @@ function createMiddleware(options) {
           return;
         }
       }
-      if (shouldRecordDecisions && sessionId) {
+      if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
         recordDecision(config, sessionId, "granted").catch(() => {
         });
       }
@@ -3745,6 +3801,80 @@ var VerificationGatewayClient = class {
     }
     return json4.data;
   }
+  /**
+   * 5.20.0 (round 29.1): change an endpoint's OPERATIONAL URLs with this
+   * client's API key — `PATCH /api/endpoints/:id`. Accepts the key of the
+   * endpoint's owner, or a personal key of an individual with an active seat
+   * in the owning organisation. Policy (rules, trust floor, challenge, edge
+   * config) stays dashboard-only. `null` clears a field. The owner is alerted
+   * when `eventsUrl` changes.
+   *
+   * @param endpointId the ASTRAE id (defaults to the client's `counterpartyId`)
+   * @returns the endpoint as stored, plus `changed` (the fields that changed)
+   * @throws AstraSyncError — 400 `UNKNOWN_FIELDS` / validation, 401/403, 404
+   */
+  async updateEndpoint(endpointId, patch) {
+    return this.endpointCall("PATCH", endpointId, "", patch);
+  }
+  /**
+   * 5.20.0 (round 29.1): ask AstraSync to send ONE signed step-up event to the
+   * endpoint's Events URL now — `POST /api/endpoints/:id/events/test`.
+   * Delivered synchronously, outside the event outbox (random `eventId`, no
+   * retries), signed with the endpoint's webhook secret like a real event.
+   * Without `approvalId` the payload is synthetic (a kit acknowledges and
+   * ignores it). With the id of a held kit approval at this endpoint the
+   * payload is the real one, so your resume path runs: `approved` makes the
+   * kit re-confirm (held again — nothing is charged); `denied` / `expired` /
+   * `lapsed` release the session.
+   *
+   * Resolves even when your endpoint refused the event (`delivered: false`,
+   * with `responseCode` / `error`).
+   */
+  async sendTestEvent(endpointId, options) {
+    return this.endpointCall("POST", endpointId, "/events/test", options);
+  }
+  async endpointCall(method, endpointId, suffix, body) {
+    const id = endpointId ?? this.config.counterpartyId;
+    if (!id) {
+      throw new AstraSyncError(
+        "An endpoint id (ASTRAE-\u2026) is required: pass it, or set counterpartyId on the client",
+        400,
+        "VALIDATION"
+      );
+    }
+    if (!this.config.apiKey) {
+      throw new AstraSyncError("This call needs the client apiKey", 401, "AUTH_REQUIRED");
+    }
+    const base = this.config.apiBaseUrl.replace(/\/+$/, "");
+    const url = `${base}/endpoints/${encodeURIComponent(id)}${suffix}`;
+    let res;
+    try {
+      res = await sdkFetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.config.apiKey}`,
+          "X-API-Key": this.config.apiKey
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(Math.max(this.timeout, 15e3))
+      });
+    } catch (err) {
+      throw new AstraSyncError(
+        `${method} ${suffix || "/endpoints/:id"} failed: ${err instanceof Error ? err.message : String(err)}`,
+        0,
+        "network_error"
+      );
+    }
+    const json4 = await res.json().catch(() => ({}));
+    if (!res.ok || json4.success === false || json4.data === void 0) {
+      const errObj = typeof json4.error === "object" ? json4.error : void 0;
+      const code = json4.code ?? errObj?.code ?? (typeof json4.error === "string" ? json4.error : "unknown_error");
+      const message = json4.message ?? errObj?.message ?? `HTTP ${res.status}`;
+      throw new AstraSyncError(`${message} (${code})`, res.status, code);
+    }
+    return json4.data;
+  }
   /**
    * Quick verification — checks credentials and policy in one call.
    *
@@ -6709,16 +6839,30 @@ function createMcpMiddleware(options) {
     failOnError = "closed",
     toolGatePrecedence = "code",
     routesRefreshMs,
+    skipEvaluation,
     ...config
   } = options;
+  const skipTools = new Set(skipEvaluation?.tools ?? []);
+  const skipMethods = new Set(skipEvaluation?.methods ?? []);
   if (config.apiBaseUrl) {
     prefetchWellKnown(config.apiBaseUrl).catch(() => {
     });
   }
   const codeGatedTools = Object.entries(toolGates ?? {}).filter(([, g]) => g !== "observe").map(([name]) => name);
+  let warnedEndpointType = false;
+  const onEndpointType = (counterpartyType) => {
+    if (counterpartyType === "mcp_server" || warnedEndpointType) return;
+    warnedEndpointType = true;
+    console.warn(
+      `[VerificationGateway/MCP] counterpartyId ${config.counterpartyId} is a '${counterpartyType}' endpoint, not an 'mcp_server' endpoint. Dashboard tool rules are read from an mcp_server endpoint only: register a separate MCP endpoint for this server (same owner) and use its id here. See https://astrasync.ai/docs/mcp-integration#tool-rules.`
+    );
+  };
   const rulesCache = config.apiKey && config.counterpartyId ? createRoutesCache(config, {
     ...routesRefreshMs !== void 0 && { refreshMs: routesRefreshMs },
-    ...codeGatedTools.length && { fetchOptions: { codeGates: codeGatedTools } }
+    fetchOptions: {
+      ...codeGatedTools.length && { codeGates: codeGatedTools },
+      onEndpointType
+    }
   }) : void 0;
   return async (req, res, next) => {
     try {
@@ -6768,6 +6912,9 @@ function createMcpMiddleware(options) {
           return next();
         }
       }
+      if (!parsed.toolName && skipMethods.has(parsed.method) && methodGates?.[parsed.method] === void 0) {
+        return next();
+      }
       const dashboardRules = rulesCache ? dashboardToolRules(await rulesCache.current()) : void 0;
       const gateDecision = resolveGate(parsed, {
         toolGates,
@@ -6775,6 +6922,9 @@ function createMcpMiddleware(options) {
         dashboardRules,
         toolGatePrecedence
       });
+      if (!gateDecision.enforce && (parsed.toolName && skipTools.has(parsed.toolName) || !parsed.toolName && skipMethods.has(parsed.method))) {
+        return next();
+      }
       const credentials = extractCredentials(
         req.headers,
         req.query
@@ -6831,8 +6981,14 @@ function createMcpMiddleware(options) {
       const forwardedFor = req.headers["x-forwarded-for"];
       const forwardedForStr = Array.isArray(forwardedFor) ? forwardedFor.join(", ") : forwardedFor;
       const sourceIp = req.ip ?? (forwardedForStr ? forwardedForStr.split(",")[0].trim() : void 0);
+      const attemptRaw = readSingleHeader(req.headers["x-astra-attempt-id"]);
+      const metaAttempt = req.body?.params?._meta?.astrasync?.attemptId;
+      const attemptId = [attemptRaw, metaAttempt].find(
+        (v) => typeof v === "string" && /^att_[0-9a-f]{32}$/.test(v)
+      );
       const verificationRequest = {
         credentials,
+        ...attemptId && { attemptId },
         purpose: pdlss.purpose,
         action: pdlss.action,
         resource: pdlss.resource,
@@ -6894,14 +7050,14 @@ function createMcpMiddleware(options) {
           res.setHeader("X-Astra-Gateway-Mode", "enforced");
           res.setHeader("X-Astra-Gateway-Reason", "evaluated-not-enforced");
         }
-        if (shouldRecordDecisions && sessionId) {
+        if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
           recordDecision(config, sessionId, "granted").catch(() => {
           });
         }
         return next();
       }
       if (!result.policyAllowed) {
-        if (shouldRecordDecisions && sessionId) {
+        if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
           });
         }
@@ -6911,7 +7067,7 @@ function createMcpMiddleware(options) {
       }
       if (requiresHumanApproval(result)) {
         annotateApprovalRequired(result);
-        if (shouldRecordDecisions && sessionId) {
+        if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
           });
         }
@@ -6929,7 +7085,7 @@ function createMcpMiddleware(options) {
           })
         );
       }
-      if (shouldRecordDecisions && sessionId) {
+      if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
         recordDecision(config, sessionId, "granted").catch(() => {
         });
       }
@@ -10938,6 +11094,16 @@ function checkUcpAgentBinding(header, identities) {
 
 // src/ucp/profile.ts
 var UCP_VERSION = "2026-08-25";
+function ucpProfileKeys(profile) {
+  const out = [];
+  for (const list of [profile?.keys, profile?.signing_keys]) {
+    if (!Array.isArray(list)) continue;
+    for (const k of list) {
+      if (k && typeof k === "object" && k.use !== "enc") out.push(k);
+    }
+  }
+  return out;
+}
 var SPEC = `https://ucp.dev/${UCP_VERSION}/specification`;
 var SCHEMAS = `https://ucp.dev/${UCP_VERSION}/schemas`;
 function astrasyncPaymentHandlers(handlers, specBase = "https://astrasync.ai/ucp/handlers") {
@@ -12102,6 +12268,19 @@ var resumeResult = (outcome, session) => ({
 });
 
 // src/ucp/checkout-kit.ts
+function withValidImageUrl(item) {
+  if (item.image_url === void 0) return item;
+  let ok = false;
+  try {
+    const u = new URL(item.image_url);
+    ok = u.protocol === "https:" || u.protocol === "http:";
+  } catch {
+    ok = false;
+  }
+  if (ok) return item;
+  const { image_url: _drop, ...rest } = item;
+  return rest;
+}
 var MemoryCheckoutStore = class {
   constructor() {
     this.m = /* @__PURE__ */ new Map();
@@ -12385,7 +12564,8 @@ function createUcpCheckoutKit(opts) {
     const messages = [];
     for (const [i, l] of lines.entries()) {
       const q = Math.max(1, Math.floor(l.quantity ?? 1));
-      const item = l.item?.id ? await opts.catalog(l.item.id, q) : null;
+      const found = l.item?.id ? await opts.catalog(l.item.id, q) : null;
+      const item = found && withValidImageUrl(found);
       if (!item) {
         messages.push(
           ucpError(
@@ -12474,7 +12654,7 @@ function createUcpCheckoutKit(opts) {
         { method: req.method, url: req.url, headers, body: body || void 0 },
         async (fresh) => {
           const pp = fresh ? await fetchProfile(profileUrl, true) : plat;
-          return "keys" in pp && pp.keys ? pp.keys : [];
+          return "ucp" in pp ? ucpProfileKeys(pp) : [];
         }
       );
       if (!sig.ok) return { error: json2(sig.status, { code: sig.code, content: sig.content }) };
@@ -12770,7 +12950,7 @@ function createUcpCheckoutKit(opts) {
       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"
+        "recoverable"
       )
     ];
     await store.put(s);
@@ -12805,7 +12985,7 @@ function createUcpCheckoutKit(opts) {
       });
       if (status === "approved" || status === "consumed") {
         out.push({ sessionId: s.id, outcome: (await resumeApproved(s.id)).outcome });
-      } else if (status === "denied" || status === "expired") {
+      } else if (status === "denied" || status === "expired" || status === "lapsed") {
         out.push({ sessionId: s.id, outcome: (await resumeDeclined(s.id, status)).outcome });
       } else {
         out.push({ sessionId: s.id, outcome: "pending" });
@@ -12848,7 +13028,7 @@ function createUcpCheckoutKit(opts) {
           _caller: caller,
           _platformProfile: ctx.profileUrl,
           _ap2: ctx.ap2,
-          _platformKeys: ctx.plat.keys ?? [],
+          _platformKeys: ucpProfileKeys(ctx.plat),
           ...typeof webhookUrl === "string" && /^https:\/\//.test(webhookUrl) && { _webhookUrl: webhookUrl },
           ...req.headers.get("x-astra-checkout-session") && {
             _astraCheckoutSessionId: req.headers.get("x-astra-checkout-session").slice(0, 64)
@@ -13540,7 +13720,12 @@ var ACP_CODES = /* @__PURE__ */ new Set([
   "out_of_stock",
   "payment_declined",
   "requires_sign_in",
-  "requires_3ds"
+  "requires_3ds",
+  // 5.20.0: the owner-approval codes the kit itself emits.
+  "approval_required",
+  "approval_denied",
+  "approval_expired",
+  "approval_lapsed"
 ]);
 function heldBody2(text) {
   try {
@@ -13607,7 +13792,8 @@ function createAcpCheckoutKit(opts) {
     const messages = [];
     for (const [i, it] of items.entries()) {
       const q = Math.max(1, Math.floor(it.quantity ?? 1));
-      const c = it.id ? await opts.catalog(it.id, q) : null;
+      const found = it.id ? await opts.catalog(it.id, q) : null;
+      const c = found && withValidImageUrl(found);
       if (!c) {
         messages.push({
           type: "error",
@@ -13621,7 +13807,13 @@ function createAcpCheckoutKit(opts) {
       const amount = c.price * q;
       lines.push({
         id: `li_${i + 1}`,
-        item: { id: c.id, name: c.title, unit_amount: c.price },
+        item: {
+          id: c.id,
+          name: c.title,
+          unit_amount: c.price,
+          ...c.image_url && { image_url: c.image_url },
+          ...typeof c.description === "string" && { description: c.description }
+        },
         quantity: q,
         name: c.title,
         unit_amount: c.price,
@@ -13968,7 +14160,7 @@ function createAcpCheckoutKit(opts) {
         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"
+        resolution: "recoverable"
       }
     ];
     await store.put(s);
@@ -14003,7 +14195,7 @@ function createAcpCheckoutKit(opts) {
       });
       if (status === "approved" || status === "consumed") {
         out.push({ sessionId: s.id, outcome: (await resumeApproved(s.id)).outcome });
-      } else if (status === "denied" || status === "expired") {
+      } else if (status === "denied" || status === "expired" || status === "lapsed") {
         out.push({ sessionId: s.id, outcome: (await resumeDeclined(s.id, status)).outcome });
       } else {
         out.push({ sessionId: s.id, outcome: "pending" });
@@ -14320,6 +14512,7 @@ export {
   isEdgeConfig,
   isRejectedIdentityClaim,
   isRetryableSettlementError,
+  isSharedVerdict,
   isSpecialUseIp,
   isVerificationUnavailable,
   isVerifiedHopValidFor,
@@ -14331,6 +14524,7 @@ export {
   negotiateUcp,
   nextjs_exports as nextjs,
   normalizeDeclaredSource,
+  onVerificationResult,
   openCheckoutMandate,
   openPaymentMandate,
   parseYaml as parseLocalPolicyYaml,
@@ -14364,6 +14558,7 @@ export {
   ucpEscalation,
   ucpFailure,
   ucpProfileHandler,
+  ucpProfileKeys,
   ucpRequiredComponents,
   unavailableRetryAfterSeconds,
   validatePolicy as validateLocalPolicy,