twzrd-x402-gate 0.1.0 → 0.3.0

package/README.md

@@ -1,17 +1,14 @@
 # twzrd-x402-gate
 
-Buyer-side x402 **trust gate**. Run a free [TWZRD preflight](https://intel.twzrd.xyz) (`ReadinessCard`)
-**before** signing USDC to any x402 merchant. Wraps `fetch` (HTTP 402) and the `@x402/mcp`
-`onPaymentRequested` hook. Fail-open by default so an unreachable preflight never hard-blocks a payment.
+Agent-side x402 **firewall**. TWZRD sits in the path before any 402 payment leaves your
+agent's wallet — free preflight decides `allow / warn / block` before USDC moves.
 
-This is the independent **pre-spend** layer — it does not settle, route, or hold funds. It works where
-your code receives an exposed 402 (e.g. direct `@x402/fetch` or raw merchant calls). 
+```typescript
+import { withTwzrdGuard } from "twzrd-x402-gate";
 
-**ClawRouter / `@blockrun/clawrouter` note:** The local :8402 proxy signs internally and returns 200 (no
-outer 402 is visible). Use the pre-proxy hook from the `twzrd-clawrouter` skill (explicit call before the
-proxy) or an upstream `onBeforePayment` if ClawRouter exposes one. Same internalization applies to
-AgentCash's `fetch` (it handles 402 internally) — verify before assuming a wrapper sees it. The MCP
-`onPaymentRequested` hook covers clients that expose a payment callback.
+const safeFetch = withTwzrdGuard(myX402Fetch);
+// Every 402 intercepted → free TWZRD preflight → throws on block, proceeds on warn/allow.
+```
 
 ## Install
 
@@ -19,34 +16,167 @@ AgentCash's `fetch` (it handles 402 internally) — verify before assuming a wra
 npm install twzrd-x402-gate
 ```
 
-## Usage
+## Quickstart: `withTwzrdGuard`
 
-### Wrap any fetch that may receive a 402
+Wrap any fetch that will receive x402 responses. The guard intercepts every HTTP 402, runs a
+free TWZRD preflight on the seller wallet, and throws `[twzrd] blocked: ...` before your
+wallet signs anything.
 
-```ts
-import { wrapFetchWithTwzrdGate, resolveConfig } from "twzrd-x402-gate";
+```typescript
+import { withTwzrdGuard } from "twzrd-x402-gate";
+import { createAgentcashFetch } from "agentcash";
 
-const gatedFetch = wrapFetchWithTwzrdGate(fetch, resolveConfig());
+// Pass the x402-capable fetch IN — the guard sits upstream of it.
+const x402Fetch = createAgentcashFetch({ apiKey: process.env.AGENTCASH_API_KEY });
+const safeFetch = withTwzrdGuard(x402Fetch);
 
-// On HTTP 402, the gate reads payTo from the x402 `accepts[0]`, runs preflight,
-// and THROWS if policy denies. On allow it returns the original 402 so your
-// x402 client attaches payment and retries as usual.
-const res = await gatedFetch("https://merchant.example/paid");
+// Use safeFetch everywhere you'd call a paid resource:
+const response = await safeFetch("https://api.exa.ai/search");
 ```
 
-### As the @x402/mcp payment hook
+What the guard does on HTTP 402:
+1. Reads the Solana-network entry from `accepts[]` (falls back to first entry) to get the seller wallet.
+2. Calls `POST /v1/intel/preflight` — free, no auth.
+3. `decision=block` - throws `[twzrd] blocked: ...`.
+4. `decision=warn` or `allow` - returns the original 402 for the x402 client to pay.
 
-```ts
-import { defaultGate } from "twzrd-x402-gate";
+Non-402 responses pass through unchanged.
 
-const client = createX402MCPClient({
-  onPaymentRequested: defaultGate.onPaymentRequested, // returns false to deny
+### Auto-receipt on warn (revenue path)
+
+```typescript
+const safeFetch = withTwzrdGuard(x402Fetch, {
+  autoReceipt: true,   // on warn or allow, auto-buy the $0.05 TWZRD trust receipt
+  x402Fetch,           // the paying fetch — TWZRD earns the fee on-chain
+  onReceipt: (receipt, tx) => {
+    // receipt is a twzrd_receipt (V6 + ERC-8004 reputation_credential)
+    console.log("Trust receipt captured:", tx);
+  },
 });
 ```
 
-### Direct decision (no network wiring)
+`autoReceipt` is **off by default** — it spends the **buyer's** USDC, so you opt in. When on,
+every warn/allow verdict settles $0.05 USDC to TWZRD and returns a signed V6 trust credential
+for the counterparty before you pay the resource.
+
+**`x402Fetch` is yours to supply** (this package is dependency-free). Wire the proven
+`@x402/svm` sponsored-feePayer client — the same one `twzrd-mcp-server` uses:
+
+```typescript
+import { wrapFetchWithPayment } from "@x402/svm";
+const x402Fetch = wrapFetchWithPayment(fetch, buyerWallet); // settles 402 challenges
+```
+
+Gate it behind your own ROI policy (e.g. only auto-buy the receipt for payments above a
+threshold). Runnable, no-spend demo: [`examples/auto-receipt.ts`](./examples/auto-receipt.ts)
+(`npm run autoreceipt-demo`). A bundled/sponsored `x402Fetch` (so integrators need no wallet)
+is the next step.
+
+### Quick tier ($0.001) — cheap paid qualify
+
+The reputation ladder has three rungs: **free** preflight (`allow/warn/block`), **$0.001**
+`quickCheck` (tier + score, no receipt), **$0.05** `autoReceipt` (full intel + signed V6
+receipt). When the free preflight is inconclusive (`warn` / unknown seller) and you want a
+cheap *paid* confirmation before committing — without paying 50× for the portable receipt —
+use `quickCheck`:
+
+```typescript
+import { quickCheck } from "twzrd-x402-gate";
+
+const q = await quickCheck(sellerWallet, { x402Fetch }); // settles $0.001 to /v1/intel/quick
+if (q.available && (q.tier === "Gold" || q.tier === "Platinum")) {
+  // tier is high enough — proceed with the larger payment
+}
+```
+
+`quickCheck` is **fail-soft** — it never throws; any gap (no `x402Fetch`, unreachable, settle
+failure) returns `available: false`, so a quick-tier hiccup can't break your flow. The hard
+allow/warn/block decision stays the free preflight's job.
+
+### Autonomous risk-escalation — `escalateOnWarn` (pay-to-confirm on warn)
+
+The free preflight leaves an unknown/uncertain seller at `warn`, which **proceeds** by
+default. `escalateOnWarn` closes the loop autonomously: on a proceeding `warn`, the guard
+settles the cheap **$0.001** quick tier and **re-decides on the paid score** — below the
+floor the payment is **blocked**, at/above it proceeds. The paid call fires from your
+agent's own risk policy (no human), and the paid signal actually gates the spend (unlike
+`autoReceipt`, which is upsell-only and never changes the decision).
 
 ```ts
+const safeFetch = withTwzrdGuard(x402Fetch, {
+  escalateOnWarn: {
+    minSpendUsdc: 0.01,   // don't pay $0.001 to vet a sub-cent buy
+    blockBelowScore: 40,  // block when the paid quick score is below this (default: preflightMinScore)
+  },
+  x402Fetch,              // settles the $0.001 quick charge
+});
+// warn + paid score < 40  -> throws "[twzrd-guard] payment blocked: twzrd_escalated_warn_block ..."
+// warn + paid score >= 40 -> proceeds (result.escalated=true, result.escalatedScore set)
+```
+
+Opt-in, **fail-soft** (if the quick tier can't answer, the base `warn` is preserved), and it
+**only tightens** — a `warn` may become a block, but an `allow` or `block` is never changed.
+This is the autonomous demand loop: an uncertain counterparty is vetted with real paid intel,
+automatically, before your agent commits.
+
+### Sponsored payer — use the paid rungs with no wallet (prototype)
+
+`createSponsoredX402Fetch` lets a **sponsor** settle the paid rungs on the agent's behalf, so
+an integrator can call `quickCheck` / `autoReceipt` with **no wallet of their own**:
+
+```typescript
+import { createSponsoredX402Fetch, quickCheck } from "twzrd-x402-gate";
+
+// `settle` = the funded backend (your @x402/svm fetch, or a TWZRD treasury sponsor endpoint).
+const x402Fetch = createSponsoredX402Fetch({ settle });
+const q = await quickCheck(seller, { x402Fetch }); // sponsor pays — caller holds no wallet
+```
+
+Two backends plug into `settle`: **gas-sponsored** (live via `@x402/svm` — agent pays USDC, the
+resource server's `feePayer` covers SOL gas, the model `twzrd-mcp-server` uses) and
+**full-sponsor** (a TWZRD treasury endpoint pays on the agent's behalf — the true no-wallet
+path). The full-sponsor endpoint + treasury is **founder-gated** (who funds it + per-agent
+budget caps); this ships the client seam + a dry-run so the wiring is ready.
+No-spend demo: [`examples/sponsored-payer.ts`](./examples/sponsored-payer.ts) (`npm run sponsored-demo`).
+
+## `evaluate_x402_resource` — standalone preflight
+
+Use when you already have the `paymentRequirements` object from a parsed 402 body:
+
+```typescript
+import { evaluate_x402_resource } from "twzrd-x402-gate";
+
+const result = await evaluate_x402_resource(
+  "https://api.exa.ai/search",
+  paymentRequirements, // X402PaymentRequirements from the 402 body
+);
+
+console.log(result.decision);    // "allow" | "warn" | "block"
+console.log(result.trustScore);  // number | null
+console.log(result.approved);    // boolean
+console.log(result.receiptUrl);  // "https://intel.twzrd.xyz/v1/intel/trust/<payTo>"
+
+if (!result.approved) throw new Error(`Blocked: ${result.reason}`);
+```
+
+With `autoReceipt`:
+
+```typescript
+const result = await evaluate_x402_resource(url, requirements, {
+  autoReceipt: true,
+  x402Fetch: myPayingFetch,
+  onReceipt: (receipt, tx) => storeCredential(receipt),
+});
+// result.receipt — twzrd_receipt (V6 + ERC-8004 reputation_credential)
+// result.receiptTx — on-chain settlement tx
+// result.receiptFeeCaptured — true when fee landed
+```
+
+## Lower-level APIs
+
+### Direct approval call
+
+```typescript
 import { createTwzrdGate } from "twzrd-x402-gate";
 
 const gate = createTwzrdGate();
@@ -58,38 +188,68 @@ const { approved, reason, card } = await gate.approvePayment({
 if (!approved) abort(reason);
 ```
 
+### `@x402/mcp` payment hook
+
+```typescript
+import { defaultGate } from "twzrd-x402-gate";
+
+const client = createX402MCPClient({
+  onPaymentRequested: defaultGate.onPaymentRequested, // returns false to deny
+});
+```
+
+### `wrapFetchWithTwzrdGate`
+
+```typescript
+import { wrapFetchWithTwzrdGate, resolveConfig } from "twzrd-x402-gate";
+
+// Alternative fetch wrapper — same interception logic, no autoReceipt.
+const gatedFetch = wrapFetchWithTwzrdGate(fetch, resolveConfig());
+```
+
+`withTwzrdGuard` is preferred — it composes with `autoReceipt` and `onReceipt`.
+`wrapFetchWithTwzrdGate` remains for codebases that can't migrate.
+
 ## Policy
 
-A payment is **denied** when any of these hold (mirrors `scripts/twzrd_gate_agentcash_fetch.sh`):
+A payment is **blocked** when:
+1. `decision ∈ blockDecisions` (default: `["block"]`)
+2. `trust_score < preflightMinScore` (default: `40`)
+3. `can_spend === false` — **only** when `gateOnCanSpend: true` (default `false`, opt-in)
+
+`warn` is allowed unless overridden. Preflight network failure **fails closed** by default (a preflight outage blocks the payment, so an intel hiccup never silently approves a spend); set `failOpen: true` / `TWZRD_FAIL_OPEN=true` to opt into legacy allow-on-outage.
 
-1. `decision ∈ blockDecisions` (default: `block`)
-2. `can_spend === false` — **only when `gateOnCanSpend` is true (default)**
-3. `trust_score < preflightMinScore` (default: `40`)
+> **`can_spend` note:** the free preflight returns `can_spend=false` for most sellers
+> not yet in the TWZRD corpus, including legitimate ones. The default is decision-only
+> gating so unknown sellers on platforms like Agentic.Market are not blocked by default.
+> Set `gateOnCanSpend: true` for strict mode.
 
-Otherwise approved (`warn` is allowed with reason `twzrd_warn_allowed`). On preflight HTTP/network
-failure the gate **fails open** (approves) unless `failOpen` is disabled.
+## Config
 
-> **ClawRouter / free-tier note:** the free preflight returns `can_spend=false` for most sellers
-> (including well-known ones), so the default policy will deny most unknown ClawRouter/BlockRun
-> sellers. To follow the "gate only on `decision=block`" policy documented in the `twzrd-clawrouter`
-> skill, set `gateOnCanSpend: false` (or `TWZRD_GATE_ON_CAN_SPEND=false`).
+| Option | Env | Default | Description |
+|---|---|---|---|
+| `intelBase` | `TWZRD_INTEL_BASE` | `https://intel.twzrd.xyz` | Preflight API base |
+| `preflightMinScore` | `TWZRD_PREFLIGHT_MIN_SCORE` | `40` | Block below this score |
+| `blockDecisions` | `TWZRD_BLOCK_DECISIONS` | `block` | Decisions that throw |
+| `failOpen` | `TWZRD_FAIL_OPEN` | `false` | `true` opts into legacy allow-on-outage; default blocks (fail-closed) |
+| `gateOnCanSpend` | `TWZRD_GATE_ON_CAN_SPEND` | `false` | Also block when `can_spend=false` |
+| `autoReceipt` | — | `false` | Auto-buy $0.05 TWZRD receipt on warn/allow |
+| `x402Fetch` | — | — | x402-capable fetch for `autoReceipt` |
+| `onReceipt` | — | — | Callback after receipt is captured |
 
-## Config (overrides or env)
+## Compatibility note
 
-| Option | Env | Default |
-|---|---|---|
-| `intelBase` | `TWZRD_INTEL_BASE` | `https://intel.twzrd.xyz` |
-| `preflightMinScore` | `TWZRD_PREFLIGHT_MIN_SCORE` | `40` |
-| `blockDecisions` | `TWZRD_BLOCK_DECISIONS` | `block` |
-| `failOpen` | `TWZRD_FAIL_OPEN` | `true` (`false`/`0` to disable) |
-| `gateOnCanSpend` | `TWZRD_GATE_ON_CAN_SPEND` | `true` (`false`/`0` = gate only on `decision`) |
-| `fetch` | — | global `fetch` |
+**Proxied x402 clients** (AgentCash's `.fetch`, ClawRouter `:8402`): these clients handle
+402 internally and return 200. The guard never sees a 402. Pass the raw (non-paying) fetch
+to `withTwzrdGuard`, then wrap its output in your x402 client. Or call
+`evaluate_x402_resource` explicitly before routing through the proxy.
 
 ## Why pre-spend, not post-pay
 
-`GET /v1/intel/trust/{wallet}` is the **paid** (0.05 USDC) deep-intel surface — it is *not* a gate.
-`POST /v1/intel/preflight` is the **free** `ReadinessCard` for the pre-spend decision. This package
-only ever calls the free preflight; you decide whether to proceed before any USDC leaves your wallet.
+`GET /v1/intel/trust/{wallet}` is the **paid** ($0.05 USDC) deep-intel surface — not a gate.
+`POST /v1/intel/preflight` is the **free** `ReadinessCard` for the pre-spend decision.
+This package only ever calls the free preflight; you decide whether to proceed before any
+USDC leaves your wallet.
 
 ## License
 

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import type { TwzrdGateConfig } from "./types.js";
+import type { TwzrdGateConfig, TwzrdUpsellContext } from "./types.js";
 export type ResolvedTwzrdGateConfig = {
     intelBase: string;
     preflightMinScore: number;
@@ -6,6 +6,7 @@ export type ResolvedTwzrdGateConfig = {
     failOpen: boolean;
     gateOnCanSpend: boolean;
     fetch: typeof fetch;
+    onWarnUpsell?: (ctx: TwzrdUpsellContext) => void | Promise<void>;
 };
 export declare function resolveConfig(overrides?: TwzrdGateConfig): ResolvedTwzrdGateConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,KAAK,EAAE,OAAO,KAAK,CAAC;CACrB,CAAC;AAYF,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,eAAe,GAAG,uBAAuB,CAuClF"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEtE,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,KAAK,EAAE,OAAO,KAAK,CAAC;IACpB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE,CAAC;AAYF,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,eAAe,GAAG,uBAAuB,CAiDlF"}

package/dist/config.js

@@ -1,5 +1,5 @@
 function parseBlockDecisions(raw) {
-    const source = raw ?? "block";
+    const source = raw?.trim() || "block";
     return new Set(source
         .split(",")
         .map((s) => s.trim())
@@ -9,17 +9,26 @@ export function resolveConfig(overrides) {
     const intelBase = (overrides?.intelBase ??
         process.env.TWZRD_INTEL_BASE ??
         "https://intel.twzrd.xyz").replace(/\/+$/, "");
-    const preflightMinScore = overrides?.preflightMinScore ??
+    const rawMin = overrides?.preflightMinScore ??
         Number(process.env.TWZRD_PREFLIGHT_MIN_SCORE ?? "40");
+    const preflightMinScore = (Number.isFinite(rawMin) && rawMin >= 0) ? rawMin : 40;
     const blockDecisions = overrides?.blockDecisions != null
         ? new Set([...overrides.blockDecisions].map((s) => s.trim()).filter(Boolean))
         : parseBlockDecisions(process.env.TWZRD_BLOCK_DECISIONS);
+    // Default false (fail-closed): block and log loudly on preflight outage.
+    // Opt in to legacy fail-open with TWZRD_FAIL_OPEN=true or TWZRD_FAIL_OPEN=1.
     const failOpen = overrides?.failOpen ??
-        (process.env.TWZRD_FAIL_OPEN !== "false" &&
-            process.env.TWZRD_FAIL_OPEN !== "0");
+        (process.env.TWZRD_FAIL_OPEN === "true" ||
+            process.env.TWZRD_FAIL_OPEN === "1");
+    // Default false (decision-only): an unknown seller (warn / can_spend=false,
+    // which is EVERY not-yet-seen merchant at score 45) is NOT blocked by default —
+    // only an explicit decision=block (a real wash/sybil flag) blocks. This matches
+    // the sister package @wzrd_sol/plugin-trustgate and the preflight's own
+    // warn-not-block intent, and keeps the gate usable for discovery. Opt in to
+    // strict can_spend gating with TWZRD_GATE_ON_CAN_SPEND=true or =1.
     const gateOnCanSpend = overrides?.gateOnCanSpend ??
-        (process.env.TWZRD_GATE_ON_CAN_SPEND !== "false" &&
-            process.env.TWZRD_GATE_ON_CAN_SPEND !== "0");
+        (process.env.TWZRD_GATE_ON_CAN_SPEND === "true" ||
+            process.env.TWZRD_GATE_ON_CAN_SPEND === "1");
     const fetchFn = overrides?.fetch ?? globalThis.fetch;
     if (typeof fetchFn !== "function") {
         throw new Error("[twzrd-x402-gate] fetch is not available; pass config.fetch");
@@ -31,6 +40,7 @@ export function resolveConfig(overrides) {
         failOpen,
         gateOnCanSpend,
         fetch: fetchFn,
+        onWarnUpsell: overrides?.onWarnUpsell,
     };
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAWA,SAAS,mBAAmB,CAAC,GAAuB;IAClD,MAAM,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC;IAC9B,OAAO,IAAI,GAAG,CACZ,MAAM;SACH,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CACnB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,SAA2B;IACvD,MAAM,SAAS,GAAG,CAChB,SAAS,EAAE,SAAS;QACpB,OAAO,CAAC,GAAG,CAAC,gBAAgB;QAC5B,yBAAyB,CAC1B,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAEtB,MAAM,iBAAiB,GACrB,SAAS,EAAE,iBAAiB;QAC5B,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,IAAI,CAAC,CAAC;IAExD,MAAM,cAAc,GAClB,SAAS,EAAE,cAAc,IAAI,IAAI;QAC/B,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC7E,CAAC,CAAC,mBAAmB,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IAE7D,MAAM,QAAQ,GACZ,SAAS,EAAE,QAAQ;QACnB,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,OAAO;YACtC,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,GAAG,CAAC,CAAC;IAEzC,MAAM,cAAc,GAClB,SAAS,EAAE,cAAc;QACzB,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,OAAO;YAC9C,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,GAAG,CAAC,CAAC;IAEjD,MAAM,OAAO,GAAG,SAAS,EAAE,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IACrD,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACjF,CAAC;IAED,OAAO;QACL,SAAS;QACT,iBAAiB;QACjB,cAAc;QACd,QAAQ;QACR,cAAc;QACd,KAAK,EAAE,OAAO;KACf,CAAC;AACJ,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAYA,SAAS,mBAAmB,CAAC,GAAuB;IAClD,MAAM,MAAM,GAAG,GAAG,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC;IACtC,OAAO,IAAI,GAAG,CACZ,MAAM;SACH,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CACnB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,SAA2B;IACvD,MAAM,SAAS,GAAG,CAChB,SAAS,EAAE,SAAS;QACpB,OAAO,CAAC,GAAG,CAAC,gBAAgB;QAC5B,yBAAyB,CAC1B,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAEtB,MAAM,MAAM,GACV,SAAS,EAAE,iBAAiB;QAC5B,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,yBAAyB,IAAI,IAAI,CAAC,CAAC;IACxD,MAAM,iBAAiB,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAEjF,MAAM,cAAc,GAClB,SAAS,EAAE,cAAc,IAAI,IAAI;QAC/B,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC7E,CAAC,CAAC,mBAAmB,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;IAE7D,yEAAyE;IACzE,6EAA6E;IAC7E,MAAM,QAAQ,GACZ,SAAS,EAAE,QAAQ;QACnB,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,MAAM;YACrC,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,GAAG,CAAC,CAAC;IAEzC,4EAA4E;IAC5E,gFAAgF;IAChF,gFAAgF;IAChF,wEAAwE;IACxE,4EAA4E;IAC5E,mEAAmE;IACnE,MAAM,cAAc,GAClB,SAAS,EAAE,cAAc;QACzB,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,MAAM;YAC7C,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,GAAG,CAAC,CAAC;IAEjD,MAAM,OAAO,GAAG,SAAS,EAAE,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IACrD,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACjF,CAAC;IAED,OAAO;QACL,SAAS;QACT,iBAAiB;QACjB,cAAc;QACd,QAAQ;QACR,cAAc;QACd,KAAK,EAAE,OAAO;QACd,YAAY,EAAE,SAAS,EAAE,YAAY;KACtC,CAAC;AACJ,CAAC"}

package/dist/evaluate.d.ts

@@ -0,0 +1,77 @@
+import { type TwzrdTier } from "./quick.js";
+import type { TwzrdDecision, TwzrdGateConfig, TwzrdReadinessCard, X402PaymentRequirements } from "./types.js";
+export type EvaluateX402Options = TwzrdGateConfig & {
+    /**
+     * When true, automatically fetches the paid TWZRD trust receipt (via x402)
+     * after a warn/allow decision. Requires x402Fetch to be provided.
+     * Default: false.
+     */
+    autoReceipt?: boolean;
+    /**
+     * x402-capable fetch that can settle USDC payments. Used by autoReceipt (the
+     * $0.05 receipt) and by escalateOnWarn (the $0.001 quick tier). The caller wires
+     * in a Solana wallet + x402 payer.
+     */
+    x402Fetch?: typeof fetch;
+    /**
+     * Called immediately after a receipt is captured on-chain.
+     * Provides the raw twzrd_receipt object and the settlement tx hash (if present).
+     */
+    onReceipt?: (receipt: unknown, tx: string | undefined) => void;
+    /**
+     * Autonomous risk-escalation. When the free preflight is inconclusive
+     * (decision="warn" and otherwise proceeding), the gate autonomously settles the
+     * cheap $0.001 quick tier and RE-DECIDES on the paid score: below `blockBelowScore`
+     * (default: preflightMinScore) the payment is denied (approved=false); at/above it
+     * proceeds. The paid call fires from the agent's own risk policy - no human - and
+     * the paid signal actually gates the spend (unlike autoReceipt, which is upsell-only
+     * and never changes the decision). Opt-in; requires x402Fetch. Fail-soft: if the
+     * quick tier cannot answer, the base warn decision is preserved. Only tightens
+     * (warn -> maybe block); never loosens a block or allow. Short-circuits the
+     * autoReceipt path for the warn case (no double settle).
+     */
+    escalateOnWarn?: {
+        /** Skip escalation when the resource price is below this - don't pay $0.001 to vet a sub-cent buy. Default 0. */
+        minSpendUsdc?: number;
+        /** Deny when the paid quick score is below this. Default: preflightMinScore (40). */
+        blockBelowScore?: number;
+    };
+};
+export type EvaluateX402Result = {
+    decision: TwzrdDecision | "unknown";
+    trustScore: number | null;
+    approved: boolean;
+    reason: string;
+    card: TwzrdReadinessCard;
+    /** true when the preflight was unreachable and fail-open allowed the resource */
+    failOpen?: boolean;
+    /** URL of the paid TWZRD trust endpoint for this seller (for manual upsell) */
+    receiptUrl?: string;
+    /** Present when autoReceipt=true and the x402 trust call succeeded */
+    receipt?: unknown;
+    /** On-chain settlement tx from the receipt payment */
+    receiptTx?: string;
+    /** true when a fee was captured on-chain */
+    receiptFeeCaptured?: boolean;
+    /** true when a `warn` triggered an autonomous paid quick-tier re-decision (escalateOnWarn) */
+    escalated?: boolean;
+    /** the paid quick-tier score that drove the escalated decision; null when the quick tier could not answer */
+    escalatedScore?: number | null;
+    /** the paid quick-tier label (Bronze/Silver/Gold/Platinum) from the escalation */
+    escalatedTier?: TwzrdTier | null;
+};
+/**
+ * Evaluate an x402 resource before the buyer pays:
+ *   1. Run free TWZRD preflight on the seller (no auth, no cost).
+ *   2. Return decision + trust score.
+ *   3. If escalateOnWarn is set and decision=warn: autonomously settle the cheap
+ *      $0.001 quick tier and re-decide on the paid score (the autonomous risk loop).
+ *   4. Else if autoReceipt=true and decision !== block: auto-fetch the paid TWZRD
+ *      trust receipt via x402Fetch (TWZRD earns the receipt fee on-chain).
+ *
+ * Defaults to gateOnCanSpend=false (decision-only) — the free-tier preflight
+ * returns can_spend=false for most unknown sellers, which would block too eagerly
+ * on platforms like Agentic.Market where sellers are not yet in the corpus.
+ */
+export declare function evaluate_x402_resource(resourceUrl: string, paymentRequirements: X402PaymentRequirements, opts?: EvaluateX402Options): Promise<EvaluateX402Result>;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../src/evaluate.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG;IAClD;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAC/D;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,EAAE;QACf,iHAAiH;QACjH,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,qFAAqF;QACrF,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,aAAa,GAAG,SAAS,CAAC;IACpC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,kBAAkB,CAAC;IACzB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,8FAA8F;IAC9F,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,6GAA6G;IAC7G,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,kFAAkF;IAClF,aAAa,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CAClC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,mBAAmB,EAAE,uBAAuB,EAC5C,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAmH7B"}

package/dist/evaluate.js

@@ -0,0 +1,114 @@
+import { resolveConfig } from "./config.js";
+import { twzrdApprovePayment } from "./policy.js";
+import { payToFromRequirements, priceUsdcFromAmountMicro } from "./payto.js";
+import { quickCheck } from "./quick.js";
+/**
+ * Evaluate an x402 resource before the buyer pays:
+ *   1. Run free TWZRD preflight on the seller (no auth, no cost).
+ *   2. Return decision + trust score.
+ *   3. If escalateOnWarn is set and decision=warn: autonomously settle the cheap
+ *      $0.001 quick tier and re-decide on the paid score (the autonomous risk loop).
+ *   4. Else if autoReceipt=true and decision !== block: auto-fetch the paid TWZRD
+ *      trust receipt via x402Fetch (TWZRD earns the receipt fee on-chain).
+ *
+ * Defaults to gateOnCanSpend=false (decision-only) — the free-tier preflight
+ * returns can_spend=false for most unknown sellers, which would block too eagerly
+ * on platforms like Agentic.Market where sellers are not yet in the corpus.
+ */
+export async function evaluate_x402_resource(resourceUrl, paymentRequirements, opts = {}) {
+    const config = resolveConfig({
+        intelBase: opts.intelBase,
+        preflightMinScore: opts.preflightMinScore,
+        blockDecisions: opts.blockDecisions,
+        failOpen: opts.failOpen,
+        // Decision-only gate: unknown sellers score warn (~45), not block.
+        // Gating on can_spend would block every Agentic.Market seller not in corpus.
+        gateOnCanSpend: opts.gateOnCanSpend,
+        fetch: opts.fetch,
+    });
+    const { payTo, amountMicro, resource } = payToFromRequirements(paymentRequirements);
+    const priceUsdc = priceUsdcFromAmountMicro(amountMicro);
+    const approval = await twzrdApprovePayment({
+        resourceUrl: resource ?? resourceUrl,
+        payTo,
+        priceUsdc,
+        agentIntent: "evaluate_x402_resource",
+    }, config);
+    const decision = (approval.card.decision ?? "unknown");
+    const receiptUrl = payTo
+        ? `${config.intelBase}/v1/intel/trust/${encodeURIComponent(payTo)}`
+        : undefined;
+    const base = {
+        decision,
+        trustScore: approval.card.trust_score ?? null,
+        approved: approval.approved,
+        reason: approval.reason,
+        card: approval.card,
+        failOpen: approval.failOpen,
+        receiptUrl,
+    };
+    // Autonomous risk-escalation: a *proceeding* `warn` (uncertain / unknown seller)
+    // is vetted by settling the cheap $0.001 quick tier and re-deciding on the paid
+    // score. This is the autonomous demand loop - the paid call fires from the agent's
+    // own risk policy, and the paid signal gates the spend (only tightens). Fail-soft:
+    // if the quick tier cannot answer, the base warn decision is preserved.
+    if (opts.escalateOnWarn &&
+        typeof opts.x402Fetch === "function" &&
+        payTo &&
+        decision === "warn" &&
+        base.approved &&
+        (priceUsdc ?? 0) >= (opts.escalateOnWarn.minSpendUsdc ?? 0)) {
+        const floor = opts.escalateOnWarn.blockBelowScore ?? config.preflightMinScore;
+        const quick = await quickCheck(payTo, {
+            intelBase: config.intelBase,
+            fetch: config.fetch,
+            x402Fetch: opts.x402Fetch,
+        });
+        if (quick.available && quick.score !== null) {
+            const escApproved = quick.score >= floor;
+            return {
+                ...base,
+                approved: escApproved,
+                trustScore: quick.score,
+                escalated: true,
+                escalatedScore: quick.score,
+                escalatedTier: quick.tier,
+                reason: escApproved
+                    ? `twzrd_escalated_warn_allow (paid quick score ${quick.score} >= ${floor})`
+                    : `twzrd_escalated_warn_block (paid quick score ${quick.score} < ${floor})`,
+            };
+        }
+        // Quick tier could not answer (fail-soft) - preserve the base warn decision.
+        return { ...base, escalated: true, escalatedScore: null };
+    }
+    // Auto-upsell: on warn or allow, fetch the paid TWZRD trust receipt.
+    // This is the revenue capture path: x402Fetch settles $0.05 USDC to TWZRD.
+    if (opts.autoReceipt &&
+        typeof opts.x402Fetch === "function" &&
+        payTo &&
+        decision !== "block") {
+        try {
+            // Echo the verify->act funnel link so this paid call is attributed to its preflight.
+            const headers = { accept: "application/json" };
+            if (typeof approval.preflightId === "number") {
+                headers["x-twzrd-preflight-id"] = String(approval.preflightId);
+            }
+            const resp = await opts.x402Fetch(`${config.intelBase}/v1/intel/trust/${encodeURIComponent(payTo)}`, { method: "GET", headers });
+            if (resp.ok) {
+                const body = (await resp.json());
+                const receipt = body.twzrd_receipt;
+                const preimage = receipt?.preimage;
+                const tx = body.tx ?? body.tx_pending ?? (typeof preimage?.settlement_tx === "string" ? preimage.settlement_tx : undefined);
+                const feeCaptured = !!tx || body.charged === true;
+                if (opts.onReceipt)
+                    opts.onReceipt(receipt, tx);
+                return { ...base, receipt, receiptTx: tx, receiptFeeCaptured: feeCaptured };
+            }
+        }
+        catch {
+            // Fail-open: receipt upsell failure does not block access to the resource.
+        }
+    }
+    return base;
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/evaluate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.js","sourceRoot":"","sources":["../src/evaluate.ts"],"names":[],"mappings":"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"}

package/dist/gate.d.ts

@@ -16,4 +16,17 @@ export type TwzrdGate = {
 export declare function createTwzrdGate(overrides?: TwzrdGateConfig): TwzrdGate;
 /** Default gate using process.env / global fetch */
 export declare const defaultGate: TwzrdGate;
+/**
+ * Decorator-style guard for agent payment flows.
+ * Runs TWZRD preflight on the seller before invoking `fn`.
+ * Throws if policy denies; passes through on allow/warn.
+ *
+ * @example
+ * const safePay = withTwzrdGuard(
+ *   (seller) => agentcashFetch(`https://api.seller.xyz/paid`),
+ *   { preflightMinScore: 50 }
+ * );
+ * const result = await safePay("SELLER_WALLET_BASE58");
+ */
+export declare function withTwzrdGuard<TArgs extends unknown[], TReturn>(fn: (sellerWallet: string, ...args: TArgs) => Promise<TReturn>, config?: TwzrdGateConfig): (sellerWallet: string, ...args: TArgs) => Promise<TReturn>;
 //# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE1E,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,SAAS,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;IAC7E,cAAc,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;IACrF,kBAAkB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,SAAS,EAAE,CAAC,UAAU,EAAE,OAAO,KAAK,KAAK,OAAO,KAAK,CAAC;IACtD,qBAAqB,EAAE,OAAO,qBAAqB,CAAC;IACpD,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,qBAAqB,EAAE,OAAO,qBAAqB,CAAC;IACpD,wBAAwB,EAAE,OAAO,wBAAwB,CAAC;CAC3D,CAAC;AAEF,wBAAgB,eAAe,CAAC,SAAS,CAAC,EAAE,eAAe,GAAG,SAAS,CAatE;AAED,oDAAoD;AACpD,eAAO,MAAM,WAAW,EAAE,SAA6B,CAAC"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE1E,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,SAAS,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;IAC7E,cAAc,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;IACrF,kBAAkB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,SAAS,EAAE,CAAC,UAAU,EAAE,OAAO,KAAK,KAAK,OAAO,KAAK,CAAC;IACtD,qBAAqB,EAAE,OAAO,qBAAqB,CAAC;IACpD,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,qBAAqB,EAAE,OAAO,qBAAqB,CAAC;IACpD,wBAAwB,EAAE,OAAO,wBAAwB,CAAC;CAC3D,CAAC;AAEF,wBAAgB,eAAe,CAAC,SAAS,CAAC,EAAE,eAAe,GAAG,SAAS,CAatE;AAED,oDAAoD;AACpD,eAAO,MAAM,WAAW,EAAE,SAA6B,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EAC7D,EAAE,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EAC9D,MAAM,CAAC,EAAE,eAAe,GACvB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAc5D"}

package/dist/gate.js

@@ -19,4 +19,26 @@ export function createTwzrdGate(overrides) {
 }
 /** Default gate using process.env / global fetch */
 export const defaultGate = createTwzrdGate();
+/**
+ * Decorator-style guard for agent payment flows.
+ * Runs TWZRD preflight on the seller before invoking `fn`.
+ * Throws if policy denies; passes through on allow/warn.
+ *
+ * @example
+ * const safePay = withTwzrdGuard(
+ *   (seller) => agentcashFetch(`https://api.seller.xyz/paid`),
+ *   { preflightMinScore: 50 }
+ * );
+ * const result = await safePay("SELLER_WALLET_BASE58");
+ */
+export function withTwzrdGuard(fn, config) {
+    const cfg = resolveConfig(config);
+    return async (sellerWallet, ...args) => {
+        const { approved, verdict, score, reason } = await twzrdApprovePayment({ sellerWallet, agentIntent: "withTwzrdGuard" }, cfg);
+        if (!approved) {
+            throw new Error(`[twzrd] withTwzrdGuard blocked: ${reason} (verdict=${verdict}, score=${score})`);
+        }
+        return fn(sellerWallet, ...args);
+    };
+}
 //# sourceMappingURL=gate.js.map