twzrd-x402-gate 0.1.1 → 0.5.0

package/README.md

@@ -1,17 +1,43 @@
 # 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 + free merchant_card wash refuse 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 { installTwzrdAutoGate } from "twzrd-x402-gate";
+import { wrapFetchWithPayment } from "@x402/svm";
 
-**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 payingFetch = installTwzrdAutoGate((guarded) => wrapFetchWithPayment(guarded, buyerWallet));
+// Every 402 gated BEFORE your client signs → free preflight + free merchant_card wash check → throws on block.
+const response = await payingFetch("https://api.exa.ai/search");
+```
+
+## Buyer flow (trustless, fail-open) — locked sequence
+
+Canonical path for every agent that spends USDC on Solana x402:
+
+| Step | Call | Cost | What gates pay |
+|------|------|------|----------------|
+| 1 | `POST /v1/intel/preflight` | free | `decision=block` → refuse (`twzrd_decision_block`). Score floor / optional `can_spend` also deny. |
+| 2 | `GET /v1/intel/merchant_card/{payTo}` | free | `wash_flagged: true` → refuse by default (`twzrd_wash_flagged`). **Only tightens** step 1. |
+| 3 | Optional paid trust | $0.05 / $0.001 | On `warn` or high-value: `GET /v1/intel/trust/{payTo}` or `quickCheck`. Never required for the free refuse path. |
+| 4 | Pay (or refuse) | resource price | Only if steps 1–2 approved (and any opt-in paid escalate did not block). |
+
+**Fail-open (no invent):**
+- Preflight HTTP/network error → default fail-closed in gate 0.2+ (`TWZRD_FAIL_OPEN=true` restores legacy allow-on-outage).
+- Merchant card unreachable / non-2xx / missing `wash_flagged` → `washFlagged=null` → **do not refuse on wash** (preflight decision stands).
+- Only a successful card with `wash_flagged: true` triggers wash refuse or soft cap.
+
+**Wash policy (exact):**
+- Prior preflight deny → unchanged (wash never loosens a block).
+- `refuseWashFlagged=false` or wash not true → keep preflight approval.
+- `wash_flagged=true` + no cap → `approved=false`, `reason=twzrd_wash_flagged`, `verdict=block`.
+- `wash_flagged=true` + `washMaxUsdc` set + `priceUsdc <= cap` → allow, `washCapped=true`, reason `twzrd_wash_capped_{price}_le_{cap}`.
+- `wash_flagged=true` + price above cap (or price unknown) → refuse with `twzrd_wash_flagged_above_cap_*`.
+
+**Order note:** `onWarnUpsell` (points at paid `/trust`) fires on preflight `warn` **before** the merchant_card wash check. A wash-flagged seller that preflighted as `warn` may still get the upsell hook, then be refused on step 2.
+
+Dogfood (live, free only): `npm run wash-dogfood` → [`examples/wash-refuse-dogfood.ts`](./examples/wash-refuse-dogfood.ts).
 
 ## Install
 
@@ -19,34 +45,206 @@ AgentCash's `fetch` (it handles 402 internally) — verify before assuming a wra
 npm install twzrd-x402-gate
 ```
 
-## Usage
+## Quickstart: `installTwzrdAutoGate` (default-on)
 
-### Wrap any fetch that may receive a 402
+`installTwzrdAutoGate` is the one-liner form of "guard the raw fetch, then hand it to your
+x402 client." It takes a `payWrap` function — whatever composes your paying client on top of
+a fetch — and returns a fetch that's already gated: a blocked seller throws before your client
+ever gets a chance to sign.
 
-```ts
-import { wrapFetchWithTwzrdGate, resolveConfig } from "twzrd-x402-gate";
+```typescript
+import { installTwzrdAutoGate } from "twzrd-x402-gate";
+import { wrapFetchWithPayment } from "@x402/svm";
 
-const gatedFetch = wrapFetchWithTwzrdGate(fetch, resolveConfig());
+const payingFetch = installTwzrdAutoGate((guarded) => wrapFetchWithPayment(guarded, buyerWallet));
 
-// 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 payingFetch everywhere you'd call a paid resource:
+const response = await payingFetch("https://api.exa.ai/search");
 ```
 
-### As the @x402/mcp payment hook
+`payWrap` receives the **guarded** fetch (the guard has already run by the time your client
+sees a 402) — this is the only correct composition order. Building it the other way round
+(guarding an already-paying fetch) is a no-op; see [Compatibility note](#compatibility-note).
+Any x402 client that composes over an underlying `fetch` works the same way — swap in
+whatever `payWrap` your client's API expects (agentcash, ClawRouter, PayAI, a custom
+`@x402/svm` scheme, etc.).
 
-```ts
-import { defaultGate } from "twzrd-x402-gate";
+Default **ON**. Disable with `TWZRD_AUTO_GATE=0` (env, deploy-time kill switch) or
+`{ disabled: true }` (per-call, e.g. in tests) — the raw fetch is handed straight to
+`payWrap`, unguarded.
 
-const client = createX402MCPClient({
-  onPaymentRequested: defaultGate.onPaymentRequested, // returns false to deny
+What happens on every HTTP 402 the raw fetch returns:
+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. `decision=block` (or score floor) throws — `payWrap`'s client never signs.
+3. Calls `GET /v1/intel/merchant_card/{payTo}` — free, no auth. `wash_flagged: true` refuses by default (only tightens step 2; fail-open if the card is unreachable — no invent).
+4. Otherwise returns the 402 to `payWrap`'s client, which pays normally.
+
+Non-402 responses pass through unchanged.
+
+### Lower-level: `withTwzrdGuard`
+
+`installTwzrdAutoGate` is built on `withTwzrdGuard` — the fetch wrapper itself, if you want to
+manage the raw/paying composition yourself:
+
+```typescript
+import { withTwzrdGuard } from "twzrd-x402-gate";
+import { wrapFetchWithPayment } from "@x402/svm";
+
+const raw = globalThis.fetch;               // MUST still surface HTTP 402
+const guarded = withTwzrdGuard(raw);        // guard sits upstream
+const safeFetch = wrapFetchWithPayment(guarded, buyerWallet);
+
+const response = await safeFetch("https://api.exa.ai/search");
+```
+
+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. Free `POST /v1/intel/preflight` — `decision=block` / score floor deny.
+3. Free `GET /v1/intel/merchant_card/{payTo}` — `wash_flagged:true` **refuses by default**
+   (`reason: twzrd_wash_flagged`). Fail-open if the card is unreachable (no invent).
+4. If approved: returns the original 402 for the x402 client to pay.
+
+Opt out of wash refuse: `withTwzrdGuard(fetch, { refuseWashFlagged: false })` or
+`TWZRD_REFUSE_WASH_FLAGGED=0`. Soft cap instead of hard refuse: `washMaxUsdc` /
+`TWZRD_WASH_MAX_USDC`.
+
+Non-402 responses pass through unchanged.
+
+### 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 +256,72 @@ 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 |
+| `disabled` (`installTwzrdAutoGate` only) | `TWZRD_AUTO_GATE=0`/`false` | `false` | Bypass the guard entirely — `payWrap` gets the raw, unguarded fetch |
 
-## 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 if it wraps the client's *output* —
+it must wrap the client's *input*. `installTwzrdAutoGate` enforces this composition order by
+construction: it guards the raw fetch first, then hands the guarded fetch to your `payWrap`.
+If you're composing `withTwzrdGuard` manually instead, pass the raw (non-paying) fetch to
+`withTwzrdGuard`, then wrap its output in your x402 client — never the reverse. 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/auto-gate.d.ts

@@ -0,0 +1,48 @@
+import { type TwzrdGuardOptions } from "./with-guard.js";
+/**
+ * Takes a guarded (pre-pay-checked) fetch and returns the fetch your agent actually
+ * calls — i.e. your x402 client composed on top of the guard (agentcash, ClawRouter,
+ * @x402/svm, PayAI, etc.).
+ */
+export type PayWrap = (guardedFetch: typeof fetch) => typeof fetch;
+export type InstallAutoGateOptions = TwzrdGuardOptions & {
+    /**
+     * The RAW (non-paying) fetch to guard. This MUST be a fetch that still surfaces
+     * HTTP 402 — do not pass an already-paying client here (see compatibility note
+     * in README: proxied clients like AgentCash/.fetch resolve 402 internally and
+     * return 200, so the guard would never see the block condition).
+     * Default: globalThis.fetch.
+     */
+    rawFetch?: typeof fetch;
+    /**
+     * Force-disable the gate (payWrap gets the raw fetch, unguarded). Mirrors
+     * TWZRD_AUTO_GATE=0 / "false". Prefer the env var for a deploy-time kill switch;
+     * use this for tests.
+     */
+    disabled?: boolean;
+};
+/**
+ * Default-on composition helper: guards the RAW fetch with the free TWZRD preflight,
+ * THEN hands the guarded fetch to your payment wrapper. This is the one-liner form of
+ * the two-step pattern documented in the README:
+ *
+ *   const raw = globalThis.fetch;
+ *   const gated = withTwzrdGuard(raw);
+ *   const paying = payWrap(gated);
+ *
+ * Composing it this way by construction rules out the common mis-wiring of guarding
+ * an already-paying fetch (which returns 200 and never gives the guard a 402 to act on).
+ *
+ * Default ON — a blocked seller throws before payWrap's client ever signs. Opt out with
+ * TWZRD_AUTO_GATE=0 (env) or { disabled: true } (per-call), e.g. for a local dev harness
+ * that intentionally wants the unguarded fetch.
+ *
+ * @example
+ *   import { installTwzrdAutoGate } from "twzrd-x402-gate";
+ *   import { wrapFetchWithPayment } from "@x402/svm";
+ *
+ *   const payingFetch = installTwzrdAutoGate((guarded) => wrapFetchWithPayment(guarded, buyerWallet));
+ *   await payingFetch("https://api.exa.ai/search"); // blocked sellers throw before signing
+ */
+export declare function installTwzrdAutoGate(payWrap: PayWrap, options?: InstallAutoGateOptions): typeof fetch;
+//# sourceMappingURL=auto-gate.d.ts.map

package/dist/auto-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-gate.d.ts","sourceRoot":"","sources":["../src/auto-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,YAAY,EAAE,OAAO,KAAK,KAAK,OAAO,KAAK,CAAC;AAEnE,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,GAAG;IACvD;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,KAAK,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,KAAK,CAQd"}

package/dist/auto-gate.js

@@ -0,0 +1,34 @@
+import { withTwzrdGuard } from "./with-guard.js";
+/**
+ * Default-on composition helper: guards the RAW fetch with the free TWZRD preflight,
+ * THEN hands the guarded fetch to your payment wrapper. This is the one-liner form of
+ * the two-step pattern documented in the README:
+ *
+ *   const raw = globalThis.fetch;
+ *   const gated = withTwzrdGuard(raw);
+ *   const paying = payWrap(gated);
+ *
+ * Composing it this way by construction rules out the common mis-wiring of guarding
+ * an already-paying fetch (which returns 200 and never gives the guard a 402 to act on).
+ *
+ * Default ON — a blocked seller throws before payWrap's client ever signs. Opt out with
+ * TWZRD_AUTO_GATE=0 (env) or { disabled: true } (per-call), e.g. for a local dev harness
+ * that intentionally wants the unguarded fetch.
+ *
+ * @example
+ *   import { installTwzrdAutoGate } from "twzrd-x402-gate";
+ *   import { wrapFetchWithPayment } from "@x402/svm";
+ *
+ *   const payingFetch = installTwzrdAutoGate((guarded) => wrapFetchWithPayment(guarded, buyerWallet));
+ *   await payingFetch("https://api.exa.ai/search"); // blocked sellers throw before signing
+ */
+export function installTwzrdAutoGate(payWrap, options) {
+    const raw = options?.rawFetch ?? globalThis.fetch;
+    const envDisabled = process.env.TWZRD_AUTO_GATE === "0" || process.env.TWZRD_AUTO_GATE === "false";
+    const disabled = options?.disabled ?? envDisabled;
+    if (disabled)
+        return payWrap(raw);
+    const guarded = withTwzrdGuard(raw, options);
+    return payWrap(guarded);
+}
+//# sourceMappingURL=auto-gate.js.map

package/dist/auto-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-gate.js","sourceRoot":"","sources":["../src/auto-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAA0B,MAAM,iBAAiB,CAAC;AA0BzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAgB,EAChB,OAAgC;IAEhC,MAAM,GAAG,GAAG,OAAO,EAAE,QAAQ,IAAI,UAAU,CAAC,KAAK,CAAC;IAClD,MAAM,WAAW,GACf,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,OAAO,CAAC;IACjF,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,WAAW,CAAC;IAClD,IAAI,QAAQ;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC7C,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC"}

package/dist/config.d.ts

@@ -1,11 +1,16 @@
-import type { TwzrdGateConfig } from "./types.js";
+import type { TwzrdGateConfig, TwzrdUpsellContext } from "./types.js";
 export type ResolvedTwzrdGateConfig = {
     intelBase: string;
     preflightMinScore: number;
     blockDecisions: Set<string>;
     failOpen: boolean;
     gateOnCanSpend: boolean;
+    /** Default true: refuse when free merchant_card.wash_flagged */
+    refuseWashFlagged: boolean;
+    /** Soft cap USDC when wash_flagged; null = hard refuse */
+    washMaxUsdc: number | null;
     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,gEAAgE;IAChE,iBAAiB,EAAE,OAAO,CAAC;IAC3B,0DAA0D;IAC1D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,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,CAkElF"}

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,40 @@ 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");
+    // Default true: free merchant_card.wash_flagged → refuse pay (trustless step 3).
+    // Opt out: refuseWashFlagged:false or TWZRD_REFUSE_WASH_FLAGGED=0|false.
+    const refuseWashEnv = process.env.TWZRD_REFUSE_WASH_FLAGGED;
+    const refuseWashFlagged = overrides?.refuseWashFlagged ??
+        !(refuseWashEnv === "0" || refuseWashEnv === "false");
+    let washMaxUsdc = null;
+    if (overrides?.washMaxUsdc != null && Number.isFinite(overrides.washMaxUsdc)) {
+        washMaxUsdc = overrides.washMaxUsdc;
+    }
+    else if (process.env.TWZRD_WASH_MAX_USDC != null && process.env.TWZRD_WASH_MAX_USDC !== "") {
+        const n = Number(process.env.TWZRD_WASH_MAX_USDC);
+        if (Number.isFinite(n) && n >= 0)
+            washMaxUsdc = n;
+    }
     const fetchFn = overrides?.fetch ?? globalThis.fetch;
     if (typeof fetchFn !== "function") {
         throw new Error("[twzrd-x402-gate] fetch is not available; pass config.fetch");
@@ -30,7 +53,10 @@ export function resolveConfig(overrides) {
         blockDecisions,
         failOpen,
         gateOnCanSpend,
+        refuseWashFlagged,
+        washMaxUsdc,
         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":"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"}

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