@agent-score/commerce 1.0.0 → 1.0.1

package/dist/identity/fastify.mjs

@@ -2,11 +2,10 @@
 var FIXABLE_DENIAL_REASONS = /* @__PURE__ */ new Set([
   "kyc_required",
   "kyc_pending",
-  "kyc_failed",
-  "jurisdiction_restricted"
+  "kyc_failed"
 ]);
 function isFixableDenial(reasons) {
-  if (!reasons || reasons.length === 0) return true;
+  if (!reasons || reasons.length === 0) return false;
   return reasons.every((r) => FIXABLE_DENIAL_REASONS.has(r));
 }
 function denialReasonStatus(reason) {
@@ -79,6 +78,47 @@ function verificationAgentInstructions(input = {}) {
 }
 
 // src/_response.ts
+var WALLET_NOT_TRUSTED_INSTRUCTIONS = JSON.stringify({
+  action: "contact_support",
+  steps: [
+    "The wallet's operator failed an UNFIXABLE compliance check (sanctions, age, or jurisdiction). `reasons` lists which: `sanctions_flagged` / `age_insufficient` / `jurisdiction_restricted`. KYC re-verification won't change the outcome \u2014 the policy denial is structural.",
+    "Surface the denial to the user with the merchant's support contact. Do not retry the same merchant request; do not hand the user a verify_url (verification won't fix this code path).",
+    "Fixable compliance reasons (`kyc_required`, `kyc_pending`, `kyc_failed`) do NOT land on this code \u2014 the gate auto-mints a verification session for those and returns `identity_verification_required` with poll endpoints, same shape as `missing_identity`. `jurisdiction_restricted` IS in the unfixable bucket because the API only emits it after KYC is verified (the user's KYC'd country is in the blocked list \u2014 re-doing KYC won't change the country)."
+  ],
+  user_message: "This purchase is denied by the merchant's compliance policy and cannot be resolved by re-verifying. Contact the merchant's support if you believe this is in error."
+});
+var PAYMENT_REQUIRED_INSTRUCTIONS = JSON.stringify({
+  action: "contact_merchant",
+  steps: [
+    "The merchant's AgentScore tier does not include the assess feature, so agent identity cannot be evaluated. This is a merchant-side configuration gap \u2014 there is no agent-side recovery.",
+    "Contact the merchant (their support channel \u2014 typically listed in /llms.txt or the OpenAPI servers metadata) and request they upgrade their AgentScore plan."
+  ],
+  user_message: "This merchant's identity gate is misconfigured (AgentScore tier doesn't support assess). Contact the merchant \u2014 there's nothing to fix on the agent side."
+});
+var IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({
+  action: "deliver_verify_url_and_poll",
+  steps: [
+    "Share verify_url with the user \u2014 they complete identity verification on AgentScore.",
+    "If session_id + poll_secret are present in the body, poll poll_url every 5 seconds with header `X-Poll-Secret: <poll_secret>` until status=verified. The poll returns a one-time operator_token.",
+    "Retry the original request with header `X-Operator-Token: <opc_...>`."
+  ],
+  user_message: "Identity verification is required. Visit verify_url, then poll poll_url for the operator token and retry."
+});
+var TOKEN_EXPIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({
+  action: "deliver_verify_url_and_poll",
+  steps: [
+    "The operator token is expired or revoked. AgentScore auto-mints a fresh verification session \u2014 complete it to receive a new opc_...",
+    "Share verify_url with the user, then poll poll_url every 5 seconds with header `X-Poll-Secret: <poll_secret>` until status=verified. The poll returns a fresh one-time operator_token.",
+    "Retry the original request with header `X-Operator-Token: <new_opc_...>`."
+  ],
+  user_message: "Operator token is expired or revoked. A new verification session has been minted \u2014 visit verify_url to refresh."
+});
+var DEFAULT_AGENT_INSTRUCTIONS = {
+  wallet_not_trusted: WALLET_NOT_TRUSTED_INSTRUCTIONS,
+  payment_required: PAYMENT_REQUIRED_INSTRUCTIONS,
+  identity_verification_required: IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS,
+  token_expired: TOKEN_EXPIRED_FALLBACK_INSTRUCTIONS
+};
 var DEFAULT_MESSAGES = {
   missing_identity: "No identity provided. Send X-Wallet-Address (wallet) or X-Operator-Token (credential).",
   identity_verification_required: "Identity verification is required to access this resource. Visit verify_url to complete KYC.",
@@ -115,7 +155,8 @@ function denialReasonToBody(reason) {
   if (reason.session_id) body.session_id = reason.session_id;
   if (reason.poll_secret) body.poll_secret = reason.poll_secret;
   if (reason.poll_url) body.poll_url = reason.poll_url;
-  if (reason.agent_instructions) body.agent_instructions = reason.agent_instructions;
+  const instructions = reason.agent_instructions ?? DEFAULT_AGENT_INSTRUCTIONS[reason.code];
+  if (instructions) body.agent_instructions = instructions;
   if (reason.agent_memory) body.agent_memory = reason.agent_memory;
   if (reason.claimed_operator) body.claimed_operator = reason.claimed_operator;
   if (reason.code === "wallet_signer_mismatch") body.actual_signer_operator = reason.actual_signer_operator ?? null;
@@ -265,80 +306,80 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint();
-  const defaultUa = `@agent-score/commerce@${"1.0.0"}`;
+  const defaultUa = `@agent-score/commerce@${"1.0.1"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const API_TIMEOUT_MS = 1e4;
   const cache = new TTLCache(cacheSeconds * 1e3);
-  async function evaluate(identity, ctx) {
-    if (!identity || !identity.address && !identity.operatorToken) {
-      if (failOpen) return { kind: "allow" };
-      if (createSessionOnMissing) {
+  async function tryMintSessionDenial(ctx) {
+    if (!createSessionOnMissing) return void 0;
+    try {
+      const sessionBody = {};
+      if (createSessionOnMissing.context != null) sessionBody.context = createSessionOnMissing.context;
+      if (createSessionOnMissing.productName != null) sessionBody.product_name = createSessionOnMissing.productName;
+      if (createSessionOnMissing.getSessionOptions && ctx !== void 0) {
         try {
-          const sessionBody = {};
-          if (createSessionOnMissing.context != null) sessionBody.context = createSessionOnMissing.context;
-          if (createSessionOnMissing.productName != null) sessionBody.product_name = createSessionOnMissing.productName;
-          if (createSessionOnMissing.getSessionOptions && ctx !== void 0) {
-            try {
-              const dynamic = await createSessionOnMissing.getSessionOptions(ctx);
-              if (dynamic?.context != null) sessionBody.context = dynamic.context;
-              if (dynamic?.productName != null) sessionBody.product_name = dynamic.productName;
-            } catch (err) {
-              console.warn("[gate] createSessionOnMissing.getSessionOptions hook failed:", err instanceof Error ? err.message : err);
-            }
-          }
-          const sessionBaseUrl = stripTrailingSlashes(createSessionOnMissing.baseUrl ?? "https://api.agentscore.sh");
-          const sessionRes = await fetch(`${sessionBaseUrl}/v1/sessions`, {
-            method: "POST",
-            headers: {
-              "X-API-Key": createSessionOnMissing.apiKey,
-              "Content-Type": "application/json",
-              Accept: "application/json",
-              "User-Agent": userAgentHeader
-            },
-            body: JSON.stringify(sessionBody),
-            signal: AbortSignal.timeout(API_TIMEOUT_MS)
-          });
-          if (sessionRes.ok) {
-            const data = await sessionRes.json();
-            if (typeof data.session_id !== "string" || typeof data.poll_secret !== "string" || typeof data.verify_url !== "string") {
-              console.warn("[gate] /v1/sessions returned 200 without required fields \u2014 falling back to bare missing_identity");
-            } else {
-              let extra;
-              if (createSessionOnMissing.onBeforeSession && ctx !== void 0) {
-                try {
-                  const sessionMeta = {
-                    session_id: data.session_id,
-                    verify_url: data.verify_url,
-                    poll_secret: data.poll_secret,
-                    poll_url: data.poll_url,
-                    expires_at: data.expires_at
-                  };
-                  const result = await createSessionOnMissing.onBeforeSession(ctx, sessionMeta);
-                  if (result && typeof result === "object") extra = result;
-                } catch (err) {
-                  console.warn("[gate] createSessionOnMissing.onBeforeSession hook failed:", err instanceof Error ? err.message : err);
-                }
-              }
-              const apiNextSteps = data.next_steps;
-              return {
-                kind: "deny",
-                reason: {
-                  code: "identity_verification_required",
-                  verify_url: data.verify_url,
-                  session_id: data.session_id,
-                  poll_secret: data.poll_secret,
-                  poll_url: data.poll_url,
-                  agent_instructions: apiNextSteps ? JSON.stringify(apiNextSteps) : void 0,
-                  agent_memory: agentMemoryHint,
-                  ...extra && { extra }
-                }
-              };
-            }
-          }
+          const dynamic = await createSessionOnMissing.getSessionOptions(ctx);
+          if (dynamic?.context != null) sessionBody.context = dynamic.context;
+          if (dynamic?.productName != null) sessionBody.product_name = dynamic.productName;
+        } catch (err) {
+          console.warn("[gate] createSessionOnMissing.getSessionOptions hook failed:", err instanceof Error ? err.message : err);
+        }
+      }
+      const sessionBaseUrl = stripTrailingSlashes(createSessionOnMissing.baseUrl ?? "https://api.agentscore.sh");
+      const sessionRes = await fetch(`${sessionBaseUrl}/v1/sessions`, {
+        method: "POST",
+        headers: {
+          "X-API-Key": createSessionOnMissing.apiKey,
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          "User-Agent": userAgentHeader
+        },
+        body: JSON.stringify(sessionBody),
+        signal: AbortSignal.timeout(API_TIMEOUT_MS)
+      });
+      if (!sessionRes.ok) return void 0;
+      const data = await sessionRes.json();
+      if (typeof data.session_id !== "string" || typeof data.poll_secret !== "string" || typeof data.verify_url !== "string") {
+        console.warn("[gate] /v1/sessions returned 200 without required fields \u2014 falling back to bare denial");
+        return void 0;
+      }
+      let extra;
+      if (createSessionOnMissing.onBeforeSession && ctx !== void 0) {
+        try {
+          const sessionMeta = {
+            session_id: data.session_id,
+            verify_url: data.verify_url,
+            poll_secret: data.poll_secret,
+            poll_url: data.poll_url,
+            expires_at: data.expires_at
+          };
+          const result = await createSessionOnMissing.onBeforeSession(ctx, sessionMeta);
+          if (result && typeof result === "object") extra = result;
         } catch (err) {
-          console.warn("[gate] createSessionOnMissing path failed \u2014 falling back to bare missing_identity:", err instanceof Error ? err.message : err);
+          console.warn("[gate] createSessionOnMissing.onBeforeSession hook failed:", err instanceof Error ? err.message : err);
         }
       }
+      const apiNextSteps = data.next_steps;
+      return {
+        code: "identity_verification_required",
+        verify_url: data.verify_url,
+        session_id: data.session_id,
+        poll_secret: data.poll_secret,
+        poll_url: data.poll_url,
+        agent_instructions: apiNextSteps ? JSON.stringify(apiNextSteps) : void 0,
+        agent_memory: agentMemoryHint,
+        ...extra && { extra }
+      };
+    } catch (err) {
+      console.warn("[gate] createSessionOnMissing path failed \u2014 falling back to bare denial:", err instanceof Error ? err.message : err);
+      return void 0;
+    }
+  }
+  async function evaluate(identity, ctx) {
+    if (!identity || !identity.address && !identity.operatorToken) {
+      if (failOpen) return { kind: "allow" };
+      const sessionReason = await tryMintSessionDenial(ctx);
+      if (sessionReason) return { kind: "deny", reason: sessionReason };
       const missingIdentityInstructions = JSON.stringify({
         action: "probe_identity_then_session",
         steps: [
@@ -363,6 +404,10 @@ function createAgentScoreCore(options) {
       if (cached.allow) {
         return { kind: "allow", data: cached.raw };
       }
+      if (isFixableDenial(cached.reasons)) {
+        const sessionReason = await tryMintSessionDenial(ctx);
+        if (sessionReason) return { kind: "deny", reason: sessionReason };
+      }
       return {
         kind: "deny",
         reason: {
@@ -460,6 +505,10 @@ function createAgentScoreCore(options) {
       if (allow) {
         return { kind: "allow", data };
       }
+      if (isFixableDenial(decisionReasons)) {
+        const sessionReason = await tryMintSessionDenial(ctx);
+        if (sessionReason) return { kind: "deny", reason: sessionReason };
+      }
       return {
         kind: "deny",
         reason: {