@agent-score/commerce 1.0.0

package/dist/identity/policy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/identity/policy.ts"],"sourcesContent":["/**\n * Per-product / per-tier compliance policy helpers.\n *\n * A *policy* is a small bag of fields describing what identity the merchant wants\n * verified for a given resource:\n *\n * - `enforcement`: `\"hard\"` (today's wine path — 403 on miss) or `\"soft\"` (gate\n *   denial is swallowed; the order completes with a degraded `identity_status`).\n *   `null` / absent = no gate at all.\n * - `requireKyc` / `requireSanctionsClear` / `minAge`: passed through to the\n *   per-framework `agentscoreGate(...)` factory.\n * - `allowedJurisdictions`: buyer-verified country list (`[\"US\", \"CA\", ...]`).\n * - `allowedShippingCountries` / `allowedShippingStates`: optional shipping\n *   allowlists. State list is only enforced for US shipments.\n *\n * This module ships three primitives:\n *\n * 1. {@link PolicyBlock} — the typed shape.\n * 2. {@link policyToGateOptions} — translate a block into the options object the\n *    per-framework `agentscoreGate(...)` accepts. Returns `null` when the policy\n *    has no enforcement (treat as \"no gate; anonymous OK\").\n * 3. {@link runGateWithEnforcement} — wrap a per-framework middleware in the\n *    hard/soft enforcement runner. The middleware is given an `onDenied` shim\n *    that captures the denial body and status; the runner returns a structured\n *    {@link GateResult} so the vendor decides how to surface it.\n *\n * All three are additive — vendors using `agentscoreGate(...)` directly are\n * unaffected. The pattern was extracted from `agentscore/store`; see its\n * `store/routes/purchase.py` (Python sibling) for the full per-request flow.\n */\n\nimport type { AgentScoreCoreOptions, DenialReason } from '../core.js';\n\n/** Hard = 403 propagates; soft = swallowed + identity_status=\"unverified\". */\nexport type EnforcementMode = 'hard' | 'soft';\n\n/** Per-order trust level captured at settle time. */\nexport type IdentityStatus = 'verified' | 'unverified' | 'anonymous' | 'denied';\n\n/** Compliance fields a merchant attaches per product / per tier. All optional. */\nexport interface PolicyBlock {\n  enforcement?: EnforcementMode;\n  requireKyc?: boolean;\n  requireSanctionsClear?: boolean;\n  minAge?: number;\n  allowedJurisdictions?: readonly string[];\n  allowedShippingCountries?: readonly string[];\n  allowedShippingStates?: readonly string[];\n}\n\n/**\n * Outcome of running a gate under an enforcement mode.\n *\n * - `verified`: gate accepted; identity is fully verified for the policy.\n * - `unverified`: soft mode swallowed a gate denial; the agent had *some*\n *   identity but didn't meet the policy. Stamp this on the order so\n *   ops/analytics can tell apart soft passes from hard passes.\n * - `anonymous`: no gate ran (policy was null / no enforcement).\n * - `denied`: hard mode rejected; the caller must propagate the 403. The\n *   `denialBody` and `denialStatus` carry the original gate response so the\n *   caller can return it as-is.\n */\nexport interface GateResult {\n  status: IdentityStatus;\n  denialStatus?: number;\n  denialBody?: Record<string, unknown>;\n  denialReason?: DenialReason;\n}\n\n/**\n * Translate a {@link PolicyBlock} into the options the per-framework\n * `agentscoreGate(...)` expects. Returns `null` when the block has no\n * `enforcement` set — the caller should treat that as \"no gate; anonymous OK\".\n *\n * Use a fresh gate per request rather than constructing once at module scope\n * when the policy varies per resource (e.g. per product). Each adapter's gate\n * is cheap to instantiate.\n */\nexport function policyToGateOptions(\n  policy: PolicyBlock | null | undefined,\n  base: { apiKey: string; baseUrl?: string },\n): AgentScoreCoreOptions | null {\n  if (!policy || !policy.enforcement) return null;\n  return {\n    apiKey: base.apiKey,\n    ...(base.baseUrl !== undefined && { baseUrl: base.baseUrl }),\n    ...(policy.requireKyc !== undefined && { requireKyc: policy.requireKyc }),\n    ...(policy.requireSanctionsClear !== undefined && {\n      requireSanctionsClear: policy.requireSanctionsClear,\n    }),\n    ...(policy.minAge !== undefined && { minAge: policy.minAge }),\n    ...(policy.allowedJurisdictions !== undefined && {\n      allowedJurisdictions: [...policy.allowedJurisdictions],\n    }),\n  };\n}\n\n/**\n * Run a per-framework gate middleware respecting the enforcement mode.\n *\n * The vendor passes:\n * - `gate`: their framework's middleware (Hono `MiddlewareHandler`, Express\n *   `(req, res, next) => void`, etc.) — anything that resolves on accept and\n *   throws or returns a `Response` on deny.\n * - `runGate`: a thin adapter that calls the middleware with the framework\n *   context and returns either `{ ok: true }` (gate accepted) or\n *   `{ ok: false, status, body, reason? }` (gate denied with details).\n *\n * `runGateWithEnforcement` wraps that in the hard/soft split:\n *\n * - `gate=null` or `enforcement=null`: no gate fires; status=\"anonymous\".\n * - `enforcement=\"hard\"` + denied: status=\"denied\"; caller propagates denialStatus + denialBody.\n * - `enforcement=\"soft\"` + denied: swallow; status=\"unverified\".\n * - accepted: status=\"verified\".\n */\nexport async function runGateWithEnforcement(\n  enforcement: EnforcementMode | undefined,\n  runGate: (() => Promise<{ ok: true } | { ok: false; status: number; body: Record<string, unknown>; reason?: DenialReason }>) | null,\n): Promise<GateResult> {\n  if (!runGate || !enforcement) return { status: 'anonymous' };\n\n  const outcome = await runGate();\n  if (outcome.ok) return { status: 'verified' };\n\n  if (enforcement === 'hard') {\n    return {\n      status: 'denied',\n      denialStatus: outcome.status,\n      denialBody: outcome.body,\n      ...(outcome.reason !== undefined && { denialReason: outcome.reason }),\n    };\n  }\n  return {\n    status: 'unverified',\n    denialStatus: outcome.status,\n    denialBody: outcome.body,\n    ...(outcome.reason !== undefined && { denialReason: outcome.reason }),\n  };\n}\n\n/** NULL policy / NULL allowlist → ship anywhere. Otherwise country must be in the list. */\nexport function shippingCountryAllowed(country: string, policy: PolicyBlock | null | undefined): boolean {\n  if (!policy?.allowedShippingCountries || policy.allowedShippingCountries.length === 0) return true;\n  const allowed = new Set(policy.allowedShippingCountries.map((c) => c.toUpperCase()));\n  return allowed.has(country.toUpperCase());\n}\n\n/**\n * US-state allowlist (e.g. wine).\n *\n * Only enforced for US shipments — non-US shipments are governed by\n * {@link shippingCountryAllowed} independently.\n */\nexport function shippingStateAllowed(\n  state: string,\n  country: string,\n  policy: PolicyBlock | null | undefined,\n): boolean {\n  if (!policy?.allowedShippingStates || policy.allowedShippingStates.length === 0) return true;\n  if (country.toUpperCase() !== 'US') return true;\n  const allowed = new Set(policy.allowedShippingStates.map((s) => s.toUpperCase()));\n  return allowed.has(state.toUpperCase());\n}\n"],"mappings":";AA8EO,SAAS,oBACd,QACA,MAC8B;AAC9B,MAAI,CAAC,UAAU,CAAC,OAAO,YAAa,QAAO;AAC3C,SAAO;AAAA,IACL,QAAQ,KAAK;AAAA,IACb,GAAI,KAAK,YAAY,UAAa,EAAE,SAAS,KAAK,QAAQ;AAAA,IAC1D,GAAI,OAAO,eAAe,UAAa,EAAE,YAAY,OAAO,WAAW;AAAA,IACvE,GAAI,OAAO,0BAA0B,UAAa;AAAA,MAChD,uBAAuB,OAAO;AAAA,IAChC;AAAA,IACA,GAAI,OAAO,WAAW,UAAa,EAAE,QAAQ,OAAO,OAAO;AAAA,IAC3D,GAAI,OAAO,yBAAyB,UAAa;AAAA,MAC/C,sBAAsB,CAAC,GAAG,OAAO,oBAAoB;AAAA,IACvD;AAAA,EACF;AACF;AAoBA,eAAsB,uBACpB,aACA,SACqB;AACrB,MAAI,CAAC,WAAW,CAAC,YAAa,QAAO,EAAE,QAAQ,YAAY;AAE3D,QAAM,UAAU,MAAM,QAAQ;AAC9B,MAAI,QAAQ,GAAI,QAAO,EAAE,QAAQ,WAAW;AAE5C,MAAI,gBAAgB,QAAQ;AAC1B,WAAO;AAAA,MACL,QAAQ;AAAA,MACR,cAAc,QAAQ;AAAA,MACtB,YAAY,QAAQ;AAAA,MACpB,GAAI,QAAQ,WAAW,UAAa,EAAE,cAAc,QAAQ,OAAO;AAAA,IACrE;AAAA,EACF;AACA,SAAO;AAAA,IACL,QAAQ;AAAA,IACR,cAAc,QAAQ;AAAA,IACtB,YAAY,QAAQ;AAAA,IACpB,GAAI,QAAQ,WAAW,UAAa,EAAE,cAAc,QAAQ,OAAO;AAAA,EACrE;AACF;AAGO,SAAS,uBAAuB,SAAiB,QAAiD;AACvG,MAAI,CAAC,QAAQ,4BAA4B,OAAO,yBAAyB,WAAW,EAAG,QAAO;AAC9F,QAAM,UAAU,IAAI,IAAI,OAAO,yBAAyB,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AACnF,SAAO,QAAQ,IAAI,QAAQ,YAAY,CAAC;AAC1C;AAQO,SAAS,qBACd,OACA,SACA,QACS;AACT,MAAI,CAAC,QAAQ,yBAAyB,OAAO,sBAAsB,WAAW,EAAG,QAAO;AACxF,MAAI,QAAQ,YAAY,MAAM,KAAM,QAAO;AAC3C,QAAM,UAAU,IAAI,IAAI,OAAO,sBAAsB,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAChF,SAAO,QAAQ,IAAI,MAAM,YAAY,CAAC;AACxC;","names":[]}

package/dist/identity/web.d.mts

@@ -0,0 +1,82 @@
+export { F as FIXABLE_DENIAL_REASONS, b as buildContactSupportNextSteps, a as buildSignerMismatchBody, d as denialReasonStatus, c as denialReasonToBody, i as isFixableDenial, v as verificationAgentInstructions } from '../_response-DmziuJz6.mjs';
+export { e as extractPaymentSignerAddress, r as readX402PaymentHeader } from '../signer-Cvdwn6Cs.mjs';
+import { AgentScoreCoreOptions, AgentIdentity, DenialReason, CreateSessionOnMissing, AgentScoreData, VerifyWalletSignerResult } from '../core.mjs';
+
+interface AgentScoreGateOptions extends Omit<AgentScoreCoreOptions, 'createSessionOnMissing'> {
+    /** Custom function to extract agent identity from a Request. */
+    extractIdentity?: (req: Request) => AgentIdentity | undefined;
+    /** Custom handler invoked when a request is denied. Must return a Response. */
+    onDenied?: (req: Request, reason: DenialReason) => Response | Promise<Response>;
+    /** Auto-create a verification session on missing identity. Hooks receive the `Request`. */
+    createSessionOnMissing?: CreateSessionOnMissing<Request>;
+}
+/**
+ * Result of a gate check. `allowed: true` means the request passed; forward it to your
+ * handler. `allowed: false` means it was denied; return `response` directly to the client.
+ *
+ * When the request was authenticated via `operator_token`, `captureWallet` is bound to the
+ * identity and can be called after payment to report the signer wallet back to AgentScore.
+ * When the request was wallet-authenticated (nothing to associate), `captureWallet` is
+ * undefined. Always fire-and-forget.
+ */
+type GuardResult = {
+    allowed: true;
+    data?: AgentScoreData;
+    captureWallet?: (opts: {
+        walletAddress: string;
+        network: 'evm' | 'solana';
+        idempotencyKey?: string;
+    }) => Promise<void>;
+    /** Verify the payment signer matches the claimed X-Wallet-Address. Bound only when
+     *  the request was wallet-authenticated. Pass `opts.signer` explicitly or omit to
+     *  auto-extract from the original `Request`. */
+    verifyWalletSignerMatch?: (opts?: {
+        signer?: string | null;
+        network?: 'evm' | 'solana';
+    }) => Promise<VerifyWalletSignerResult>;
+} | {
+    allowed: false;
+    response: Response;
+};
+/**
+ * Create a Web Fetch-compatible gate. Works with any runtime that speaks the standard
+ * Request/Response API: Cloudflare Workers, Deno Deploy, Bun, Next.js App Router, etc.
+ *
+ * ```ts
+ * const guard = createAgentScoreGate({ apiKey: 'as_live_...', requireKyc: true });
+ *
+ * export default {
+ *   async fetch(req: Request) {
+ *     const result = await guard(req);
+ *     if (!result.allowed) return result.response;
+ *     return handle(req, result.data);
+ *   },
+ * };
+ * ```
+ */
+declare function createAgentScoreGate(options: AgentScoreGateOptions): (req: Request) => Promise<GuardResult>;
+/**
+ * Wrap a Web Fetch request handler with the gate. Denied requests are returned directly;
+ * allowed requests are passed to `handler` along with the assess data.
+ *
+ * ```ts
+ * export const POST = withAgentScoreGate(
+ *   { apiKey: 'as_live_...', requireKyc: true },
+ *   async (req, { data }) => Response.json({ ok: true }),
+ * );
+ * ```
+ */
+declare function withAgentScoreGate<TCtx = unknown>(options: AgentScoreGateOptions, handler: (req: Request, gate: {
+    data?: AgentScoreData;
+    captureWallet?: (opts: {
+        walletAddress: string;
+        network: 'evm' | 'solana';
+        idempotencyKey?: string;
+    }) => Promise<void>;
+    verifyWalletSignerMatch?: (opts?: {
+        signer?: string | null;
+        network?: 'evm' | 'solana';
+    }) => Promise<VerifyWalletSignerResult>;
+}, ctx?: TCtx) => Response | Promise<Response>): (req: Request, ctx?: TCtx) => Promise<Response>;
+
+export { type AgentScoreGateOptions, type GuardResult, createAgentScoreGate, withAgentScoreGate };

package/dist/identity/web.d.ts

@@ -0,0 +1,82 @@
+export { F as FIXABLE_DENIAL_REASONS, b as buildContactSupportNextSteps, a as buildSignerMismatchBody, d as denialReasonStatus, c as denialReasonToBody, i as isFixableDenial, v as verificationAgentInstructions } from '../_response-rbK0zM7y.js';
+export { e as extractPaymentSignerAddress, r as readX402PaymentHeader } from '../signer-Cvdwn6Cs.js';
+import { AgentScoreCoreOptions, AgentIdentity, DenialReason, CreateSessionOnMissing, AgentScoreData, VerifyWalletSignerResult } from '../core.js';
+
+interface AgentScoreGateOptions extends Omit<AgentScoreCoreOptions, 'createSessionOnMissing'> {
+    /** Custom function to extract agent identity from a Request. */
+    extractIdentity?: (req: Request) => AgentIdentity | undefined;
+    /** Custom handler invoked when a request is denied. Must return a Response. */
+    onDenied?: (req: Request, reason: DenialReason) => Response | Promise<Response>;
+    /** Auto-create a verification session on missing identity. Hooks receive the `Request`. */
+    createSessionOnMissing?: CreateSessionOnMissing<Request>;
+}
+/**
+ * Result of a gate check. `allowed: true` means the request passed; forward it to your
+ * handler. `allowed: false` means it was denied; return `response` directly to the client.
+ *
+ * When the request was authenticated via `operator_token`, `captureWallet` is bound to the
+ * identity and can be called after payment to report the signer wallet back to AgentScore.
+ * When the request was wallet-authenticated (nothing to associate), `captureWallet` is
+ * undefined. Always fire-and-forget.
+ */
+type GuardResult = {
+    allowed: true;
+    data?: AgentScoreData;
+    captureWallet?: (opts: {
+        walletAddress: string;
+        network: 'evm' | 'solana';
+        idempotencyKey?: string;
+    }) => Promise<void>;
+    /** Verify the payment signer matches the claimed X-Wallet-Address. Bound only when
+     *  the request was wallet-authenticated. Pass `opts.signer` explicitly or omit to
+     *  auto-extract from the original `Request`. */
+    verifyWalletSignerMatch?: (opts?: {
+        signer?: string | null;
+        network?: 'evm' | 'solana';
+    }) => Promise<VerifyWalletSignerResult>;
+} | {
+    allowed: false;
+    response: Response;
+};
+/**
+ * Create a Web Fetch-compatible gate. Works with any runtime that speaks the standard
+ * Request/Response API: Cloudflare Workers, Deno Deploy, Bun, Next.js App Router, etc.
+ *
+ * ```ts
+ * const guard = createAgentScoreGate({ apiKey: 'as_live_...', requireKyc: true });
+ *
+ * export default {
+ *   async fetch(req: Request) {
+ *     const result = await guard(req);
+ *     if (!result.allowed) return result.response;
+ *     return handle(req, result.data);
+ *   },
+ * };
+ * ```
+ */
+declare function createAgentScoreGate(options: AgentScoreGateOptions): (req: Request) => Promise<GuardResult>;
+/**
+ * Wrap a Web Fetch request handler with the gate. Denied requests are returned directly;
+ * allowed requests are passed to `handler` along with the assess data.
+ *
+ * ```ts
+ * export const POST = withAgentScoreGate(
+ *   { apiKey: 'as_live_...', requireKyc: true },
+ *   async (req, { data }) => Response.json({ ok: true }),
+ * );
+ * ```
+ */
+declare function withAgentScoreGate<TCtx = unknown>(options: AgentScoreGateOptions, handler: (req: Request, gate: {
+    data?: AgentScoreData;
+    captureWallet?: (opts: {
+        walletAddress: string;
+        network: 'evm' | 'solana';
+        idempotencyKey?: string;
+    }) => Promise<void>;
+    verifyWalletSignerMatch?: (opts?: {
+        signer?: string | null;
+        network?: 'evm' | 'solana';
+    }) => Promise<VerifyWalletSignerResult>;
+}, ctx?: TCtx) => Response | Promise<Response>): (req: Request, ctx?: TCtx) => Promise<Response>;
+
+export { type AgentScoreGateOptions, type GuardResult, createAgentScoreGate, withAgentScoreGate };