@agent-score/commerce 1.7.0 → 1.8.0

package/dist/core.d.mts

@@ -1,3 +1,5 @@
+import { P as PaymentSigner } from './signer-CFVQsWjL.mjs';
+
 interface AgentIdentity {
     address?: string;
     operatorToken?: string;
@@ -225,14 +227,28 @@ interface CaptureWalletOptions {
      *  prevents agent retries from inflating transaction_count. */
     idempotencyKey?: string;
 }
-interface VerifyWalletSignerMatchOptions {
-    /** The wallet claimed via `X-Wallet-Address`. */
-    claimedWallet: string;
-    /** The signer wallet recovered from the payment credential. `null` means the rail carries
-     *  no wallet signer (SPT, card) — the helper returns `wallet_auth_requires_wallet_signing`. */
-    signer: string | null;
-    /** Network of the signer. EVM covers every EVM chain; `solana` lives in its own namespace. */
-    network?: 'evm' | 'solana';
+/** Combined wallet-signer verdict surfaced by `getSignerVerdict(c)` — both verdicts come
+ *  through the gate's primary `/v1/assess` call (single round trip). `signer_match` describes
+ *  the wallet-binding (claimed wallet's operator ≡ signer wallet's operator); `signer_sanctions`
+ *  describes the OFAC SDN wallet-address check.
+ *
+ *  `signer_match` is projected to the gate's camelCase `VerifyWalletSignerResult` shape so
+ *  existing `buildSignerMismatchBody(...)` helpers consume it unchanged. `signer_sanctions`
+ *  passes through in the API's wire shape (already short and stable). Returned `undefined`
+ *  from `getSignerVerdict` when the gate didn't run with a signer (operator-token-only
+ *  paths, discovery legs with no payment header). */
+interface SignerVerdict {
+    signer_match: VerifyWalletSignerResult | null;
+    signer_sanctions: {
+        status: 'clear';
+    } | {
+        sanctioned: true;
+        ofac_label: string;
+        sdn_uid: string;
+        listed_at: string | null;
+    } | {
+        status: 'unavailable';
+    } | null;
 }
 type VerifyWalletSignerResult = {
     kind: 'pass';
@@ -252,9 +268,6 @@ type VerifyWalletSignerResult = {
     kind: 'wallet_auth_requires_wallet_signing';
     claimedWallet: string;
     agentInstructions: string;
-} | {
-    kind: 'api_error';
-    claimedWallet: string;
 };
 interface AgentScoreCore {
     /**
@@ -263,26 +276,22 @@ interface AgentScoreCore {
      * @param ctx - optional framework-specific context (Hono c, Express req, etc.) passed
      *   through to `createSessionOnMissing` hooks. Opaque to core.
      */
-    evaluate(identity: AgentIdentity | undefined, ctx?: unknown): Promise<EvaluateOutcome>;
+    evaluate(identity: AgentIdentity | undefined, ctx?: unknown, 
+    /** Pre-extracted payment signer from the inbound request (the adapter middleware
+     *  extracts it via `extractPaymentSigner`). When provided, the assess call carries
+     *  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>;
-    /**
-     * Verify the payment signer resolves to the same operator as the claimed `X-Wallet-Address`.
-     *
-     * Returns `pass` when the signer is linked to the same operator as the claimed wallet
-     * (byte-equal wallets pass trivially; other wallets linked to the same operator also pass —
-     * multi-wallet agents work without ergonomic pain). Returns `wallet_signer_mismatch` when
-     * the signer resolves to a different (or no) operator. Returns `wallet_auth_requires_wallet_signing`
-     * when the signer is `null` (SPT, card — rails that carry no wallet signature).
-     *
-     * Call this AFTER the gate evaluates (so the claimed wallet's operator is cached) and
-     * AFTER the payment credential is parsed (so the signer is known). Merchants should call
-     * it before settling payment.
-     */
-    verifyWalletSignerMatch(options: VerifyWalletSignerMatchOptions): Promise<VerifyWalletSignerResult>;
 }
 declare function buildAgentMemoryHint(): AgentMemoryHint;
 declare function createAgentScoreCore(options: AgentScoreCoreOptions): AgentScoreCore;
 
-export { type AccountVerification, type AgentIdentity, type AgentMemoryHint, type AgentScoreCore, type AgentScoreCoreOptions, type AssessResult, type CaptureWalletOptions, type CreateSessionOnMissing, type DenialCode, type DenialReason, type EvaluateOutcome, type FailOpenInfraReason, type GateQuotaInfo, type OperatorVerification, type PolicyCheck, type PolicyResult, type SessionMetadata, type VerifyWalletSignerMatchOptions, type VerifyWalletSignerResult, buildAgentMemoryHint, createAgentScoreCore };
+export { type AccountVerification, type AgentIdentity, type AgentMemoryHint, type AgentScoreCore, type AgentScoreCoreOptions, type AssessResult, type CaptureWalletOptions, 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.d.ts

@@ -1,3 +1,5 @@
+import { P as PaymentSigner } from './signer-CFVQsWjL.js';
+
 interface AgentIdentity {
     address?: string;
     operatorToken?: string;
@@ -225,14 +227,28 @@ interface CaptureWalletOptions {
      *  prevents agent retries from inflating transaction_count. */
     idempotencyKey?: string;
 }
-interface VerifyWalletSignerMatchOptions {
-    /** The wallet claimed via `X-Wallet-Address`. */
-    claimedWallet: string;
-    /** The signer wallet recovered from the payment credential. `null` means the rail carries
-     *  no wallet signer (SPT, card) — the helper returns `wallet_auth_requires_wallet_signing`. */
-    signer: string | null;
-    /** Network of the signer. EVM covers every EVM chain; `solana` lives in its own namespace. */
-    network?: 'evm' | 'solana';
+/** Combined wallet-signer verdict surfaced by `getSignerVerdict(c)` — both verdicts come
+ *  through the gate's primary `/v1/assess` call (single round trip). `signer_match` describes
+ *  the wallet-binding (claimed wallet's operator ≡ signer wallet's operator); `signer_sanctions`
+ *  describes the OFAC SDN wallet-address check.
+ *
+ *  `signer_match` is projected to the gate's camelCase `VerifyWalletSignerResult` shape so
+ *  existing `buildSignerMismatchBody(...)` helpers consume it unchanged. `signer_sanctions`
+ *  passes through in the API's wire shape (already short and stable). Returned `undefined`
+ *  from `getSignerVerdict` when the gate didn't run with a signer (operator-token-only
+ *  paths, discovery legs with no payment header). */
+interface SignerVerdict {
+    signer_match: VerifyWalletSignerResult | null;
+    signer_sanctions: {
+        status: 'clear';
+    } | {
+        sanctioned: true;
+        ofac_label: string;
+        sdn_uid: string;
+        listed_at: string | null;
+    } | {
+        status: 'unavailable';
+    } | null;
 }
 type VerifyWalletSignerResult = {
     kind: 'pass';
@@ -252,9 +268,6 @@ type VerifyWalletSignerResult = {
     kind: 'wallet_auth_requires_wallet_signing';
     claimedWallet: string;
     agentInstructions: string;
-} | {
-    kind: 'api_error';
-    claimedWallet: string;
 };
 interface AgentScoreCore {
     /**
@@ -263,26 +276,22 @@ interface AgentScoreCore {
      * @param ctx - optional framework-specific context (Hono c, Express req, etc.) passed
      *   through to `createSessionOnMissing` hooks. Opaque to core.
      */
-    evaluate(identity: AgentIdentity | undefined, ctx?: unknown): Promise<EvaluateOutcome>;
+    evaluate(identity: AgentIdentity | undefined, ctx?: unknown, 
+    /** Pre-extracted payment signer from the inbound request (the adapter middleware
+     *  extracts it via `extractPaymentSigner`). When provided, the assess call carries
+     *  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>;
-    /**
-     * Verify the payment signer resolves to the same operator as the claimed `X-Wallet-Address`.
-     *
-     * Returns `pass` when the signer is linked to the same operator as the claimed wallet
-     * (byte-equal wallets pass trivially; other wallets linked to the same operator also pass —
-     * multi-wallet agents work without ergonomic pain). Returns `wallet_signer_mismatch` when
-     * the signer resolves to a different (or no) operator. Returns `wallet_auth_requires_wallet_signing`
-     * when the signer is `null` (SPT, card — rails that carry no wallet signature).
-     *
-     * Call this AFTER the gate evaluates (so the claimed wallet's operator is cached) and
-     * AFTER the payment credential is parsed (so the signer is known). Merchants should call
-     * it before settling payment.
-     */
-    verifyWalletSignerMatch(options: VerifyWalletSignerMatchOptions): Promise<VerifyWalletSignerResult>;
 }
 declare function buildAgentMemoryHint(): AgentMemoryHint;
 declare function createAgentScoreCore(options: AgentScoreCoreOptions): AgentScoreCore;
 
-export { type AccountVerification, type AgentIdentity, type AgentMemoryHint, type AgentScoreCore, type AgentScoreCoreOptions, type AssessResult, type CaptureWalletOptions, type CreateSessionOnMissing, type DenialCode, type DenialReason, type EvaluateOutcome, type FailOpenInfraReason, type GateQuotaInfo, type OperatorVerification, type PolicyCheck, type PolicyResult, type SessionMetadata, type VerifyWalletSignerMatchOptions, type VerifyWalletSignerResult, buildAgentMemoryHint, createAgentScoreCore };
+export { type AccountVerification, type AgentIdentity, type AgentMemoryHint, type AgentScoreCore, type AgentScoreCoreOptions, type AssessResult, type CaptureWalletOptions, 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

@@ -220,7 +220,7 @@ function createAgentScoreCore(options) {
   } = options;
   const baseUrl = stripTrailingSlashes(rawBaseUrl);
   const agentMemoryHint = buildAgentMemoryHint();
-  const defaultUa = `@agent-score/commerce@${"1.7.0"}`;
+  const defaultUa = `@agent-score/commerce@${"1.8.0"}`;
   const userAgentHeader = userAgent ? `${userAgent} (${defaultUa})` : defaultUa;
   const sdk = new import_sdk.AgentScore({ apiKey, baseUrl, userAgent: userAgentHeader });
   const sessionSdkCache = /* @__PURE__ */ new Map();
@@ -294,7 +294,7 @@ function createAgentScoreCore(options) {
       return void 0;
     }
   }
-  async function evaluate(identity, ctx) {
+  async function evaluate(identity, ctx, signer) {
     if (!identity || !identity.address && !identity.operatorToken) {
       if (failOpen) return { kind: "allow" };
       const sessionReason = await tryMintSessionDenial(ctx);
@@ -354,7 +354,12 @@ function createAgentScoreCore(options) {
     try {
       const opts = {
         chain: gateChain,
-        ...Object.keys(policy).length > 0 ? { policy } : {}
+        ...Object.keys(policy).length > 0 ? { policy } : {},
+        // Pre-extracted payment signer (by the adapter middleware). When present, the API
+        // composes BOTH signer_match (wallet-binding) and signer_sanctions (OFAC SDN wallet
+        // check) verdicts on the response in one round trip. Under
+        // policy.require_sanctions_clear, a signer_sanctions hit flips decision -> deny inline.
+        ...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 });
       data = result;
@@ -462,36 +467,6 @@ function createAgentScoreCore(options) {
       console.warn("[agentscore-commerce] captureWallet failed:", err instanceof Error ? err.message : err);
     }
   }
-  async function resolveWalletToOperator(walletAddress) {
-    const wallet = normalizeAddress(walletAddress);
-    const extractFromCached = (raw) => {
-      const op = raw.resolved_operator;
-      const links = raw.linked_wallets;
-      return {
-        operator: typeof op === "string" ? op : null,
-        linkedWallets: Array.isArray(links) ? links.filter((w) => typeof w === "string") : []
-      };
-    };
-    const plainCached = cache.get(wallet);
-    if (plainCached?.raw) {
-      return { ok: true, ...extractFromCached(plainCached.raw) };
-    }
-    const resolveCached = cache.get(`resolve:${wallet}`);
-    if (resolveCached?.raw) {
-      return { ok: true, ...extractFromCached(resolveCached.raw) };
-    }
-    try {
-      const data = await sdk.assess(walletAddress);
-      cache.set(`resolve:${wallet}`, { allow: true, raw: data });
-      return { ok: true, ...extractFromCached(data) };
-    } catch (err) {
-      console.warn("[gate] resolveWalletToOperator failed \u2014 returning { ok:false }:", err instanceof Error ? err.message : err);
-      return { ok: false };
-    }
-  }
-  function reportSignerEvent(kind) {
-    void sdk.telemetrySignerMatch({ kind });
-  }
   function projectSignerMatch(sm, claimedNorm, signerNorm) {
     const kind = sm.kind;
     if (kind === "pass") {
@@ -519,77 +494,22 @@ function createAgentScoreCore(options) {
       agentInstructions: sm.agent_instructions ?? WALLET_SIGNER_MISMATCH_INSTRUCTIONS
     };
   }
-  async function verifyWalletSignerMatch(options2) {
-    const { claimedWallet, signer, network } = options2;
-    if (!signer) {
-      reportSignerEvent("wallet_auth_requires_wallet_signing");
-      return {
-        kind: "wallet_auth_requires_wallet_signing",
-        claimedWallet,
-        agentInstructions: WALLET_AUTH_REQUIRES_WALLET_SIGNING_INSTRUCTIONS
-      };
-    }
-    const claimedNorm = normalizeAddress(claimedWallet);
-    const signerNorm = normalizeAddress(signer);
-    if (claimedNorm === signerNorm) {
-      reportSignerEvent("pass");
-      return { kind: "pass", claimedOperator: null, signerOperator: null };
-    }
-    const cachedEntry = cache.get(claimedNorm);
-    const cachedMatch = cachedEntry?.signerMatchBySigner?.get(signerNorm);
-    if (cachedMatch) {
-      return projectSignerMatch(cachedMatch, claimedNorm, signerNorm);
-    }
-    const inferredNetwork = network ?? (signerNorm.startsWith("0x") ? "evm" : "solana");
-    let assessResponse;
-    try {
-      assessResponse = await sdk.assess(claimedNorm, {
-        resolveSigner: { address: signerNorm, network: inferredNetwork }
-      });
-    } catch (err) {
-      console.warn("[gate] verifyWalletSignerMatch assess failed:", err instanceof Error ? err.message : err);
-      reportSignerEvent("api_error");
-      return { kind: "api_error", claimedWallet: claimedNorm };
-    }
-    const signerMatch = assessResponse.signer_match;
-    if (signerMatch && typeof signerMatch === "object") {
-      if (cachedEntry) {
-        const map = cachedEntry.signerMatchBySigner ?? /* @__PURE__ */ new Map();
-        map.set(signerNorm, signerMatch);
-        cachedEntry.signerMatchBySigner = map;
-      } else {
-        const entry = { allow: true, raw: assessResponse };
-        entry.signerMatchBySigner = /* @__PURE__ */ new Map([[signerNorm, signerMatch]]);
-        cache.set(claimedNorm, entry);
-      }
-      return projectSignerMatch(signerMatch, claimedNorm, signerNorm);
-    }
-    const [claimedResolve, signerResolve] = await Promise.all([
-      resolveWalletToOperator(claimedNorm),
-      resolveWalletToOperator(signerNorm)
-    ]);
-    if (!claimedResolve.ok || !signerResolve.ok) {
-      reportSignerEvent("api_error");
-      return { kind: "api_error", claimedWallet: claimedNorm };
-    }
-    const claimedOperator = claimedResolve.operator;
-    const signerOperator = signerResolve.operator;
-    if (claimedOperator && signerOperator && claimedOperator === signerOperator) {
-      reportSignerEvent("pass");
-      return { kind: "pass", claimedOperator, signerOperator };
-    }
-    reportSignerEvent("wallet_signer_mismatch");
+  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;
+    const rawMatch = raw.signer_match;
+    const rawSanctions = raw.signer_sanctions;
+    if (!rawMatch && !rawSanctions) return void 0;
+    const signerNorm = rawMatch?.actual_signer ?? claimedNorm;
     return {
-      kind: "wallet_signer_mismatch",
-      claimedOperator,
-      actualSignerOperator: signerOperator,
-      expectedSigner: claimedNorm,
-      actualSigner: signerNorm,
-      linkedWallets: claimedResolve.linkedWallets,
-      agentInstructions: WALLET_SIGNER_MISMATCH_INSTRUCTIONS
+      signer_match: rawMatch ? projectSignerMatch(rawMatch, claimedNorm, signerNorm) : null,
+      signer_sanctions: rawSanctions ?? null
     };
   }
-  return { evaluate, captureWallet, verifyWalletSignerMatch };
+  return { evaluate, captureWallet, getSignerVerdict };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {