@agent-score/commerce 2.4.0 → 2.6.0

package/dist/core.d.ts

@@ -1,8 +1,18 @@
+import { AipSignatureMaterial } from '@agent-score/sdk';
 import { P as PaymentSigner } from './signer-3FAit11j.js';
 
 interface AgentIdentity {
     address?: string;
     operatorToken?: string;
+    /** Raw AIP Agent Identity Token (a JWT). When set, the gate has verified the token's RFC 9421
+     *  proof-of-possession at the edge as a fail-fast filter; `evaluate` forwards it to `/v1/assess`
+     *  as `aip_token` (with {@link aipSignature}) for AUTHORITATIVE server-side re-verification of the
+     *  IdP signature + proof-of-possession + policy. */
+    aipToken?: string;
+    /** RFC 9421 signature material accompanying {@link aipToken}, forwarded to `/v1/assess` as
+     *  `aip_signature` so the API re-verifies proof-of-possession itself (the edge is not trusted as
+     *  the authority). Always set together with `aipToken`. */
+    aipSignature?: AipSignatureMaterial;
 }
 /**
  * Session metadata returned from `POST /v1/sessions`. Surfaced to the `onBeforeSession`
@@ -66,7 +76,7 @@ interface AgentScoreCoreOptions {
     failOpen?: boolean;
     /** How long to cache results, in seconds. Defaults to 300. */
     cacheSeconds?: number;
-    /** AgentScore API base URL. Defaults to "https://api.agentscore.sh". */
+    /** AgentScore API base URL. Defaults to "https://api.agentscore.com". */
     baseUrl?: string;
     /** Optional chain to filter scoring to. */
     chain?: string;
@@ -74,6 +84,11 @@ interface AgentScoreCoreOptions {
     userAgent?: string;
     /** When set and no identity is found, create a verification session instead of denying immediately. */
     createSessionOnMissing?: CreateSessionOnMissing;
+    /** Issuers whose AIP Agent Identity Tokens this gate accepts. When set, the missing-identity
+     *  recovery instructions and the `agent_memory` hint advertise the AIT path so agents holding
+     *  one can present it. Set by Checkout from `gate.aip.trustedIssuers`; the actual AIT
+     *  verification happens at the edge (Checkout) before `evaluate`. */
+    aipTrustedIssuers?: string[];
 }
 type DenialCode = 'wallet_not_trusted' | 'missing_identity' | 'api_error' | 'payment_required' | 'identity_verification_required' | 'wallet_signer_mismatch' | 'wallet_auth_requires_wallet_signing' | 'token_expired' | 'invalid_credential';
 /**
@@ -90,7 +105,12 @@ interface AgentMemoryHint {
     identity_paths: {
         wallet: string;
         operator_token: string;
+        agent_identity?: string;
     };
+    /** Issuers whose AIP Agent Identity Tokens this merchant accepts. Present only when the
+     *  merchant opted into AIP; an agent holding an AIT from one of these can present it via an
+     *  `Agent-Identity` header + RFC 9421 signature instead of bootstrapping a fresh credential. */
+    aip_trusted_issuers?: string[];
     bootstrap: string;
     do_not_persist_in_memory: string[];
     persist_in_credential_store: string[];
@@ -169,6 +189,16 @@ interface AssessResult {
     linked_wallets?: string[];
     verify_url?: string;
     policy_result?: PolicyResult | null;
+    /** IdP provenance, present only when `identity_method === 'aip_token'` — which issuer attested
+     *  the identity and the trust level it asserted. Mirrors the SDK's `AssessResponse.aip`. */
+    aip?: {
+        issuer: string;
+        subject: string;
+        trust_level?: 'autonomous' | 'human_present' | 'human_confirmed';
+        agent_provider?: string;
+        /** True when /v1/assess re-verified the RFC 9421 proof-of-possession (always true on success). */
+        pop_verified?: boolean;
+    };
 }
 /**
  * Reason a failOpen allow short-circuited an evaluate call due to AgentScore-side
@@ -200,6 +230,12 @@ interface GateQuotaInfo {
  *   merchants can alert/log without parsing console output.
  * - `quota` propagates the SDK's per-request quota observability when the API emits the
  *   `X-Quota-*` headers. Optional; absent on Enterprise / unlimited tiers.
+ * - `signerVerdict` carries the per-request wallet-signer verdicts (signer_match + signer_sanctions)
+ *   composed by this evaluate's assess call. It rides on the RETURN VALUE (not a shared slot on the
+ *   core) so concurrent same-wallet/different-signer requests can't read each other's verdict —
+ *   the adapter stashes it on its per-request state for `getSignerVerdict(ctx)` to read back.
+ *   Present only on wallet-only identity when the response carried either signer block; `undefined`
+ *   otherwise (operator-token / AIT paths, discovery legs with no signer).
  * - `{ kind: 'deny', reason }` — the request was denied. Adapters should render a 403 with the
  *   reason, or invoke the caller's custom denial handler.
  */
@@ -209,9 +245,11 @@ type EvaluateOutcome = {
     degraded?: boolean;
     infraReason?: FailOpenInfraReason;
     quota?: GateQuotaInfo;
+    signerVerdict?: SignerVerdict;
 } | {
     kind: 'deny';
     reason: DenialReason;
+    signerVerdict?: SignerVerdict;
 };
 interface CaptureWalletOptions {
     /** Operator credential (`opc_...`) that the agent authenticated with. */
@@ -280,16 +318,11 @@ interface AgentScoreCore {
      *  it and the response includes `signer_match` + `signer_sanctions` verdicts in one
      *  round trip. */
     signer?: PaymentSigner | null): Promise<EvaluateOutcome>;
-    /** Synchronous read of the cached signer verdicts (signer_match + signer_sanctions)
-     *  populated when the gate's evaluate call was made with a pre-extracted signer. Returns
-     *  `undefined` when the gate didn't run, the request was operator-token-authenticated,
-     *  or no signer was extractable (discovery legs). */
-    getSignerVerdict(claimedAddress: string): SignerVerdict | undefined;
     /** Report a wallet seen paying under an operator credential. Fire-and-forget; silently
      *  swallows non-fatal errors because capture is informational, not on the critical path. */
     captureWallet(options: CaptureWalletOptions): Promise<void>;
 }
-declare function buildAgentMemoryHint(): AgentMemoryHint;
+declare function buildAgentMemoryHint(aipTrustedIssuers?: string[]): AgentMemoryHint;
 declare function createAgentScoreCore(options: AgentScoreCoreOptions): AgentScoreCore;
 
 export { type AccountVerification, type AgentIdentity, type AgentMemoryHint, type AgentScoreCore, type AgentScoreCoreOptions, type AssessResult, type CreateSessionOnMissing, type DenialCode, type DenialReason, type EvaluateOutcome, type FailOpenInfraReason, type GateQuotaInfo, type OperatorVerification, type PolicyCheck, type PolicyResult, type SessionMetadata, type SignerVerdict, type VerifyWalletSignerResult, buildAgentMemoryHint, createAgentScoreCore };

package/dist/core.js

@@ -24,6 +24,7 @@ __export(core_exports, {
   createAgentScoreCore: () => createAgentScoreCore
 });
 module.exports = __toCommonJS(core_exports);
+var import_node_crypto = require("crypto");
 var import_sdk = require("@agent-score/sdk");
 
 // src/_denial.ts
@@ -67,7 +68,7 @@ var IDENTITY_VERIFICATION_REQUIRED_FALLBACK_INSTRUCTIONS = JSON.stringify({
 var API_ERROR_INSTRUCTIONS = JSON.stringify({
   action: "retry_with_backoff",
   steps: [
-    "Verification is temporarily unavailable. Retry the request after 5\u201330 seconds with exponential backoff.",
+    "Verification is temporarily unavailable. Retry the request after 5-30 seconds with exponential backoff.",
     "This is NOT a compliance denial \u2014 the user does not need to re-verify their identity. Send the same identity headers (X-Wallet-Address or X-Operator-Token) on retry.",
     "If the request continues to fail after 3+ retries (~60 seconds total), surface the error to the user with the merchant's support contact."
   ],
@@ -158,7 +159,7 @@ function stripTrailingSlashes(s) {
   while (end > 0 && s.charCodeAt(end - 1) === 47) end--;
   return end === s.length ? s : s.slice(0, end);
 }
-var CANONICAL_AGENTSCORE_API = "https://api.agentscore.sh";
+var CANONICAL_AGENTSCORE_API = "https://api.agentscore.com";
 var WALLET_SIGNER_MISMATCH_INSTRUCTIONS = JSON.stringify({
   action: "resign_or_switch_to_operator_token",
   steps: [
@@ -184,17 +185,22 @@ var INVALID_CREDENTIAL_INSTRUCTIONS = JSON.stringify({
   ],
   user_message: "The operator_token is not recognized. Use a different stored token, or restart the verification session flow to mint a new one."
 });
-function buildAgentMemoryHint() {
+function buildAgentMemoryHint(aipTrustedIssuers) {
   const api = CANONICAL_AGENTSCORE_API;
+  const acceptsAip = aipTrustedIssuers !== void 0 && aipTrustedIssuers.length > 0;
   return {
     save_for_future_agentscore_gates: true,
     pattern_summary: "AgentScore is a cross-merchant identity substrate for agent commerce. Any endpoint that returns 403 missing_identity / identity_verification_required or 402 challenges referencing AgentScore uses the same identity system. One KYC works across all AgentScore merchants \u2014 no re-verification per site. Save this pattern (and the endpoints below) to persistent memory so future AgentScore encounters skip the cold-start session flow.",
-    quickstart: "https://docs.agentscore.sh/guides/agent-identity",
+    quickstart: "https://docs.agentscore.com/guides/agent-identity",
     identity_check_endpoint: `${api}/v1/credentials`,
     identity_paths: {
       wallet: "If paying from a crypto wallet you have used before on any AgentScore merchant, send `X-Wallet-Address: 0x...`. Shortest path; no token lifecycle to manage.",
-      operator_token: "For any rail (Stripe SPT, card, or a wallet you have not linked yet), send `X-Operator-Token: opc_...`. Reusable across merchants until the token expires."
+      operator_token: "For any rail (Stripe SPT, card, or a wallet you have not linked yet), send `X-Operator-Token: opc_...`. Reusable across merchants until the token expires.",
+      ...acceptsAip && {
+        agent_identity: 'If you hold an AIP Agent Identity Token from a trusted issuer (see aip_trusted_issuers), present it: send the JWT in an `Agent-Identity` header plus an RFC 9421 HTTP Message Signature (Signature-Input + Signature over @method @authority @path agent-identity, tag="agent-identity") signed with the token-bound cnf key. The merchant verifies it and applies its policy \u2014 no separate AgentScore credential needed.'
+      }
     },
+    ...acceptsAip && { aip_trusted_issuers: aipTrustedIssuers },
     bootstrap: "If you have neither a linked wallet nor a valid operator_token, follow the session/verify flow in the per-request `agent_instructions` block. This happens at most once per agent identity \u2014 after first verification, the operator_token and any subsequently used wallet are reusable everywhere.",
     do_not_persist_in_memory: ["operator_token", "poll_secret"],
     persist_in_credential_store: ["operator_token"]
@@ -202,7 +208,7 @@ function buildAgentMemoryHint() {
 }
 function createAgentScoreCore(options) {
   if (!options.apiKey) {
-    throw new Error("AgentScore API key is required. Get one at https://agentscore.sh/sign-up");
+    throw new Error("AgentScore API key is required. Get one at https://www.agentscore.com/sign-up");
   }
   const {
     apiKey,
@@ -213,14 +219,15 @@ function createAgentScoreCore(options) {
     allowedJurisdictions,
     failOpen = false,
     cacheSeconds = 300,
-    baseUrl: rawBaseUrl = "https://api.agentscore.sh",
+    baseUrl: rawBaseUrl = "https://api.agentscore.com",
     chain: gateChain,
     userAgent,
-    createSessionOnMissing
+    createSessionOnMissing,
+    aipTrustedIssuers
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
-  const agentMemoryHint = buildAgentMemoryHint();
-  const defaultUa = `@agent-score/commerce@${"2.4.0"}`;
+  const agentMemoryHint = buildAgentMemoryHint(aipTrustedIssuers);
+  const defaultUa = `@agent-score/commerce@${"2.6.0"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new import_sdk.AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();
@@ -295,16 +302,21 @@ function createAgentScoreCore(options) {
     }
   }
   async function evaluate(identity, ctx, signer) {
-    if (!identity || !identity.address && !identity.operatorToken) {
+    if (!identity || !identity.address?.trim() && !identity.operatorToken?.trim() && !identity.aipToken?.trim()) {
       if (failOpen) return { kind: "allow" };
       const sessionReason = await tryMintSessionDenial(ctx);
       if (sessionReason) return { kind: "deny", reason: sessionReason };
+      const acceptsAip = aipTrustedIssuers !== void 0 && aipTrustedIssuers.length > 0;
+      const aipStep = acceptsAip ? [
+        `If you hold an AIP Agent Identity Token from a trusted issuer (${aipTrustedIssuers.join(", ")}): present it \u2014 send the JWT in an Agent-Identity header plus an RFC 9421 HTTP Message Signature (Signature-Input + Signature over @method @authority @path agent-identity, tag="agent-identity") signed with the token-bound cnf key. This satisfies identity in one round trip without an AgentScore credential.`
+      ] : [];
       const missingIdentityInstructions = JSON.stringify({
         action: "probe_identity_then_session",
         steps: [
+          ...aipStep,
           "If you have a wallet AND this merchant accepts a wallet-signing rail (Tempo MPP or x402 \u2014 see openapi.json x-payment-info): send X-Wallet-Address and retry. If the wallet is already linked to an AgentScore operator (via prior SIWE claim or prior captureWallet), this passes in one round trip. If the wallet is unlinked or the account has no KYC, the 403 will include a verify_url \u2014 share it with the user to claim the wallet + complete KYC, then retry.",
           "If step 1 is denied or you already have a stored operator_token (valid + not expired): send X-Operator-Token: opc_... and retry.",
-          "If neither applies: retry with NO identity header. Merchants that auto-create verification sessions (most AgentScore merchants do) return verify_url + session_id + poll_secret in the 403 body \u2014 share verify_url with the user, then poll poll_url every 5s with the X-Poll-Secret header until status=verified (the poll returns a one-time operator_token). If the retry returns the same bare 403, this merchant does not support self-service session bootstrapping \u2014 direct the user to https://agentscore.sh/sign-up to create an AgentScore identity and mint an operator_token from their dashboard (https://agentscore.sh/dashboard/verify). The user hands the opc_... to you, and you retry with X-Operator-Token."
+          "If neither applies: retry with NO identity header. Merchants that auto-create verification sessions (most AgentScore merchants do) return verify_url + session_id + poll_secret in the 403 body \u2014 share verify_url with the user, then poll poll_url every 5s with the X-Poll-Secret header until status=verified (the poll returns a one-time operator_token). If the retry returns the same bare 403, this merchant does not support self-service session bootstrapping \u2014 direct the user to https://www.agentscore.com/sign-up to create an AgentScore identity and mint an operator_token from their dashboard (https://www.agentscore.com/dashboard/verify). The user hands the opc_... to you, and you retry with X-Operator-Token."
         ],
         user_message: "Try X-Wallet-Address first if you have a wallet and the merchant accepts Tempo/x402; fall back to a stored X-Operator-Token, then to the session/verify flow described in agent_memory.bootstrap."
       });
@@ -317,21 +329,26 @@ function createAgentScoreCore(options) {
         }
       };
     }
-    const cacheKey = identity.operatorToken?.toLowerCase() ?? (identity.address ? normalizeAddress(identity.address) : "");
+    const identityKey = identity.aipToken ? `aip:${(0, import_node_crypto.createHash)("sha256").update(identity.aipToken).digest("hex")}` : identity.operatorToken?.toLowerCase() ?? (identity.address ? normalizeAddress(identity.address) : "");
+    const cacheKey = signer ? JSON.stringify([identityKey, signer.network, normalizeAddress(signer.address)]) : JSON.stringify([identityKey]);
     const cached = cache.get(cacheKey);
     if (cached) {
+      const cachedVerdict = cached.raw ? buildSignerVerdict(identity, cached.raw) : void 0;
       if (cached.allow) {
         const cachedRaw = cached.raw;
         const cachedQuota = cachedRaw?.quota;
         return {
           kind: "allow",
           data: cachedRaw,
-          ...cachedQuota !== void 0 && { quota: cachedQuota }
+          ...cachedQuota !== void 0 && { quota: cachedQuota },
+          ...cachedVerdict !== void 0 && { signerVerdict: cachedVerdict }
         };
       }
       if (isFixableDenial(cached.reasons)) {
         const sessionReason = await tryMintSessionDenial(ctx);
-        if (sessionReason) return { kind: "deny", reason: sessionReason };
+        if (sessionReason) {
+          return { kind: "deny", reason: sessionReason, ...cachedVerdict !== void 0 && { signerVerdict: cachedVerdict } };
+        }
       }
       return {
         kind: "deny",
@@ -341,7 +358,8 @@ function createAgentScoreCore(options) {
           reasons: cached.reasons,
           verify_url: cached.raw?.verify_url,
           data: cached.raw
-        }
+        },
+        ...cachedVerdict !== void 0 && { signerVerdict: cachedVerdict }
       };
     }
     const policy = {};
@@ -362,7 +380,10 @@ function createAgentScoreCore(options) {
         // regardless of policy.require_sanctions_clear (which gates the separate NAME screen).
         ...signer && { signer: { address: signer.address, network: signer.network } }
       };
-      const result = identity.address ? await sdk.assess(identity.address, { ...opts, operatorToken: identity.operatorToken }) : await sdk.assess(null, { ...opts, operatorToken: identity.operatorToken });
+      if (identity.aipToken !== void 0 && identity.aipSignature === void 0) {
+        throw new Error("AgentScoreCore.evaluate: aipToken requires aipSignature (RFC 9421 proof-of-possession material).");
+      }
+      const result = identity.aipToken !== void 0 && identity.aipSignature !== void 0 ? await sdk.assess(null, { ...opts, aipToken: identity.aipToken, aipSignature: identity.aipSignature }) : identity.address ? await sdk.assess(identity.address, { ...opts, operatorToken: identity.operatorToken }) : await sdk.assess(null, { ...opts, operatorToken: identity.operatorToken });
       data = result;
     } catch (err) {
       if (err instanceof import_sdk.PaymentRequiredError) {
@@ -433,17 +454,21 @@ function createAgentScoreCore(options) {
     const decisionReasons = data.decision_reasons ?? [];
     const allow = decision === "allow" || decision == null;
     cache.set(cacheKey, { allow, decision: decision ?? void 0, reasons: decisionReasons, raw: data });
+    const signerVerdict = buildSignerVerdict(identity, data);
     if (allow) {
       const quota = data.quota;
       return {
         kind: "allow",
         data,
-        ...quota !== void 0 && { quota }
+        ...quota !== void 0 && { quota },
+        ...signerVerdict !== void 0 && { signerVerdict }
       };
     }
     if (isFixableDenial(decisionReasons)) {
       const sessionReason = await tryMintSessionDenial(ctx);
-      if (sessionReason) return { kind: "deny", reason: sessionReason };
+      if (sessionReason) {
+        return { kind: "deny", reason: sessionReason, ...signerVerdict !== void 0 && { signerVerdict } };
+      }
     }
     return {
       kind: "deny",
@@ -453,7 +478,8 @@ function createAgentScoreCore(options) {
         reasons: decisionReasons,
         verify_url: data.verify_url,
         data
-      }
+      },
+      ...signerVerdict !== void 0 && { signerVerdict }
     };
   }
   async function captureWallet(options2) {
@@ -495,22 +521,21 @@ function createAgentScoreCore(options) {
       agentInstructions: sm.agent_instructions ?? WALLET_SIGNER_MISMATCH_INSTRUCTIONS
     };
   }
-  function getSignerVerdict(claimedAddress) {
-    const claimedNorm = normalizeAddress(claimedAddress);
-    const cached = cache.get(claimedNorm);
-    if (!cached) return void 0;
-    const raw = cached.raw;
-    if (!raw) return void 0;
+  function buildSignerVerdict(identity, raw) {
+    if (identity.address === void 0 || identity.operatorToken !== void 0 || identity.aipToken !== void 0) {
+      return void 0;
+    }
     const rawMatch = raw.signer_match;
     const rawSanctions = raw.signer_sanctions;
     if (!rawMatch && !rawSanctions) return void 0;
+    const claimedNorm = normalizeAddress(identity.address);
     const signerNorm = rawMatch?.actual_signer ?? claimedNorm;
     return {
       signer_match: rawMatch ? projectSignerMatch(rawMatch, claimedNorm, signerNorm) : null,
       signer_sanctions: rawSanctions ?? null
     };
   }
-  return { evaluate, captureWallet, getSignerVerdict };
+  return { evaluate, captureWallet };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {