@astrasyncai/verification-gateway 5.18.1 → 5.20.0

package/dist/adapters/sdk.mjs

@@ -1,5 +1,5 @@
 // src/version.ts
-var SDK_VERSION = "5.18.1";
+var SDK_VERSION = "5.20.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -177,7 +177,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) {
@@ -202,6 +207,7 @@ function cacheResult(request, result, configuredTtl, counterpartyId) {
 }
 function clearCache() {
   verificationCache.clear();
+  inflightVerifies.clear();
 }
 function mcpGuidance(urls) {
   if (!urls?.mcpEndpoint) return void 0;
@@ -338,6 +344,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;
@@ -354,6 +363,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) {
@@ -500,22 +514,43 @@ 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 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;
@@ -543,9 +578,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.
@@ -585,7 +629,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;
   }
@@ -653,7 +699,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;
@@ -679,8 +727,18 @@ async function verify(config, request, options) {
       cacheResult(request, result, mergedConfig.cacheTtl, mergedConfig.counterpartyId);
     }
   }
+  notifyVerificationListeners(request, result);
   return result;
 }
+var verificationListeners = /* @__PURE__ */ new Set();
+function notifyVerificationListeners(request, result) {
+  for (const listener of verificationListeners) {
+    try {
+      listener(result, request);
+    } catch {
+    }
+  }
+}
 async function quickVerify(config, credentials) {
   const result = await verify(config, {
     credentials,
@@ -716,6 +774,7 @@ var SettlementReportError = class extends AstraSyncError {
 };
 
 // src/adapters/sdk.ts
+var warnedPhaselessValue = false;
 var VerificationGatewayClient = class {
   constructor(options) {
     this.config = {
@@ -747,9 +806,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,
@@ -765,6 +831,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
@@ -803,6 +906,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 = {
@@ -825,6 +936,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
         },
@@ -885,6 +998,80 @@ var VerificationGatewayClient = class {
     }
     return json.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 json = await res.json().catch(() => ({}));
+    if (!res.ok || json.success === false || json.data === void 0) {
+      const errObj = typeof json.error === "object" ? json.error : void 0;
+      const code = json.code ?? errObj?.code ?? (typeof json.error === "string" ? json.error : "unknown_error");
+      const message = json.message ?? errObj?.message ?? `HTTP ${res.status}`;
+      throw new AstraSyncError(`${message} (${code})`, res.status, code);
+    }
+    return json.data;
+  }
   /**
    * Quick verification — checks credentials and policy in one call.
    *