twzrd-x402-gate 0.8.19 → 0.9.1

package/QUICKSTART.md

@@ -1,17 +1,15 @@
 # twzrd-x402-gate — Quickstart (15 minutes, 0 USDC)
 
-Refuses payment to a wash-flagged merchant **before your wallet signs**. Free intel, no
-API key, no signup, no config — every `TWZRD_*` env var is an optional override. If intel
-is unreachable the gate never *invents* a wash flag (the wash check fails open); a failed
-preflight blocks the payment by default (`TWZRD_FAIL_OPEN=true` to allow).
+**Product:** replace naked `createX402Client({ wallet })` with a client that
+**refuses wash before sign**. Free `merchant_card`, no API key. Intel down →
+**fail-open** (never invents wash). No Path A in the default path.
 
-**Pin:** `twzrd-x402-gate@0.8.19` + stock PayAI client `x402-solana@2.1.0` (official
-`beforePayment` seat). `@x402/core` Path E remains supported; refuse script is fallback.
+**Pin:** `twzrd-x402-gate@0.9.0` + `x402-solana@3.0.0`.
 
 ## 1. Stock PayAI client (default seat — copy-paste)
 
 ```bash
-npm install twzrd-x402-gate@0.8.19 x402-solana@2.1.0
+npm install twzrd-x402-gate@0.9.0 x402-solana@3.0.0
 ```
 
 > **ESM-only.** The package ships `import` conditions only — a CommonJS
@@ -19,6 +17,16 @@ npm install twzrd-x402-gate@0.8.19 x402-solana@2.1.0
 > fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`. Set `"type": "module"` in your
 > package.json, use `.mjs`, or bundle ESM.
 
+```typescript
+import { createX402Client } from "x402-solana";
+import { createTwzrdPayingClient } from "twzrd-x402-gate";
+
+// was: createX402Client({ wallet })
+const client = createX402Client(createTwzrdPayingClient({ wallet }));
+```
+
+Or hook-only:
+
 ```typescript
 import { createX402Client } from "x402-solana";
 import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
@@ -26,17 +34,18 @@ import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
 const client = createX402Client({
   wallet,
   network: "solana",
-  beforePayment: createTwzrdBeforePaymentHook({ refuseWashFlagged: true }),
+  beforePayment: createTwzrdBeforePaymentHook(),
 });
 ```
 
-Equivalent: `beforePayment: installTwzrdAutoGate("x402-solana", { refuseWashFlagged: true })`.
+Default engine = wash only. Full 0.8 preflight/Path A: `{ engine: "full" }`.
+
 Then: `await client.fetch("https://merchant.example/paid");`
 
 ## 1b. Official `@x402/core` client (Path E)
 
 ```bash
-npm install twzrd-x402-gate@0.8.19 @x402/core @x402/fetch @x402/svm
+npm install twzrd-x402-gate@0.9.0 @x402/core @x402/fetch @x402/svm
 ```
 
 ```typescript
@@ -53,7 +62,7 @@ installTwzrdAutoGate(client, { refuseWashFlagged: true });
 
 ```bash
 # Stock-client seat proof (beforePayment, signer_invocation_count=0)
-# needs x402-solana@2.1.0 installed - the harness fallback runs but does not
+# needs x402-solana@3.0.0 installed - the harness fallback runs but does not
 # clear closure (its negative arm counts a would-be sign)
 npm run x402-solana-before-payment-proof
 # writes block-proof-<run_id>.json — hook: beforePayment

package/README.md

@@ -1,18 +1,72 @@
 # twzrd-x402-gate
 
-**TWZRD is the default `onBeforePaymentCreation` policy engine for official x402 clients.**
+**Product: the paying client that already has the brake.**
 
-**Core product (buyer gate):** after the client selects the exact payment requirement and
-**before** payment payload creation / wallet signing — free preflight + merchant_card wash
-refuse. Protects the **payer** from a risky **merchant** (`payTo`). Chain-neutral envelope;
-**Solana-deep** reputation only (Base/EVM = explicit `unknown`).
+Agents pay other machines unsupervised. Most 402s are junk or wash. Something has
+to say **no** before the signature. TWZRD is that no — inside `beforePayment` /
+fetch+sign, not inside PayAI’s SDK defaults, not as a shop at intel.twzrd.xyz.
 
-### Default-on AutoGate (5 lines)
+The other reason the no must live at the signature: **attaching a funded wallet
+to an agent that reads untrusted web content is a drain vector** — indirect
+prompt injection can spend anything the agent can sign. The gate closes it by
+attaching the wallet to a policy runtime the injected content cannot
+renegotiate: per-request cap, rolling daily ceiling, wash brake, endpoint
+mandates, and a tamper-evident spend ledger that survives restarts. A fully
+compromised agent spends at most what policy allows, to whom it allows, with
+every decision signed.
+
+### Replace naked `createX402Client({ wallet })` (5 lines)
+
+```bash
+npm install twzrd-x402-gate@0.9.0 x402-solana@3.0.0
+```
+
+```typescript
+import { createX402Client } from "x402-solana";
+import { createTwzrdPayingClient } from "twzrd-x402-gate";
+
+// was: createX402Client({ wallet })
+const client = createX402Client(createTwzrdPayingClient({ wallet }));
+```
+
+Equivalent one-hook form:
+
+```typescript
+import { createX402Client } from "x402-solana";
+import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
+
+const client = createX402Client({
+  wallet,
+  network: "solana",
+  beforePayment: createTwzrdBeforePaymentHook(), // wash default
+});
+```
+
+**Default path (engine `"wash"`):**  
+`GET /v1/intel/merchant_card/{payTo}` → abort **iff** `wash_flagged === true` →  
+**fail-open** on timeout / non-2xx / throw (never invent wash).  
+No Path A, no requireReceipt, no second 402, no payment-control tokens.
+
+**Full 0.8.x engine (named opt-in):** preflight + optional Path A / escalate /
+paymentControl:
+
+```typescript
+createTwzrdBeforePaymentHook({ engine: "full", /* … */ })
+// or createTwzrdFullBeforePaymentHook({ … })
+```
+
+Customer = whoever ships `createX402Client({ wallet })` with no hook (Eliza, MCP
+hosts, agent wallets). Crawlers will never `npm install`.
+
+> **ESM-only:** CommonJS `require()` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`
+> — set `"type": "module"` (or use `.mjs` / an ESM bundler).
+
+### Default-on AutoGate (alternate seats)
 
 ```bash
-npm install twzrd-x402-gate@0.8.19 x402-solana@2.1.0
+npm install twzrd-x402-gate@0.9.0 x402-solana@3.0.0
 # official @x402/* path (alternate seat):
-# npm install twzrd-x402-gate@0.8.19 @x402/core @x402/fetch @x402/svm
+# npm install twzrd-x402-gate@0.9.0 @x402/core @x402/fetch @x402/svm
 ```
 
 ```typescript
@@ -20,7 +74,7 @@ import { x402Client } from "@x402/core/client";
 import { installTwzrdAutoGate } from "twzrd-x402-gate";
 
 const client = new x402Client();
-// refuseWashFlagged defaults true; gateOnCanSpend stays false unless you opt in
+// stock solana seat still defaults to wash via createTwzrdBeforePaymentHook()
 installTwzrdAutoGate(client, { refuseWashFlagged: true });
 // then register schemes + wrapFetchWithPayment as usual
 ```
@@ -35,16 +89,13 @@ cd packages/twzrd-x402-gate && npm run autogate-block-proof
 # fixture resolves live: wash_flagged seller if available, else decision=block
 ```
 
-> **ESM-only:** CommonJS `require()` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`
-> — set `"type": "module"` (or use `.mjs` / an ESM bundler).
+`gateOnCanSpend` remains **opt-in** (`false` by default; set `true` or `TWZRD_GATE_ON_CAN_SPEND=1` only when you want hard cap enforcement). Full-engine preflight outage default stays fail-closed unless `failOpen: true` / `TWZRD_FAIL_OPEN=1`. The **product wash path always fail-opens** on intel outage.
 
-`gateOnCanSpend` remains **opt-in** (`false` by default; set `true` or `TWZRD_GATE_ON_CAN_SPEND=1` only when you want hard cap enforcement).
-
-**Optional (0.8.1):** a resource-server settle hook so merchants can apply **customer policy**
+**Optional:** a resource-server settle hook so merchants can apply **customer policy**
 before they settle and serve (abuse, sanctions, bots, “don’t serve this payer”). Not an equal
 mirror of the buyer problem — settled USDC is final; wash resistance is mainly TWZRD scoring.
 
-## Seller settle guard (`onBeforeSettle`) — optional 0.8.1
+## Seller settle guard (`onBeforeSettle`) — optional
 
 Resource servers can screen the **payer** before *they* settle an inbound payment and serve
 the resource. Use for merchant policy (abuse / sanctions / bots / customer selection). TWZRD is
@@ -56,7 +107,7 @@ transfer on-chain. Wash/sybil edges are primarily discounted in TWZRD scoring, n
 revenue refusal.
 
 ```bash
-npm install twzrd-x402-gate@0.8.19
+npm install twzrd-x402-gate@0.9.0
 ```
 
 ```typescript
@@ -89,24 +140,22 @@ Fixture-backed SVM extract tests live in `test/seller-hook.test.ts` +
 `test/fixtures/exact-svm-transfer-checked.ts`.
 
 **PayAI x402-solana@2.1.0+** (stock client - primary Solana seat via `beforePayment`).
-`x402-solana@3.0.0` passes `declaredResource` as `{ url }`; the hook flattens `.url`
-so the same buyer copy-paste runs without a PayAI merge:
+Both 2.1.0 and 3.0.0 are supported and produce an identical refuse transcript; 3.0.0
+is the current release and what the install lines pin. The hook absorbs the one
+breaking change between them (`declaredResource` is a string on 2.1.0, `{ url }` on
+3.0.0) - see `src/x402-client-hook.ts` and `test/x402-solana-before-payment.test.ts`.
 
 ```typescript
 import { createX402Client } from "x402-solana";
-import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
+import { createTwzrdPayingClient } from "twzrd-x402-gate";
 
-const client = createX402Client({
-  wallet,
-  network: "solana",
-  beforePayment: createTwzrdBeforePaymentHook({ refuseWashFlagged: true }),
-});
+const client = createX402Client(createTwzrdPayingClient({ wallet }));
 ```
 
-Also: `installTwzrdAutoGate("x402-solana", opts)` returns the same hook.
+Also: `installTwzrdAutoGate("x402-solana", opts)` returns the same wash-default hook.
 Prove refuse-before-sign: `npm run x402-solana-before-payment-proof`.
 
-**PayAI agentic-payments** (alternate PayAI surface; prefer x402-solana@2.1.0 when available):
+**PayAI agentic-payments** (alternate PayAI surface; prefer x402-solana@3.0.0 when available):
 `npx tsx examples/payai-agentic-onPaymentVerified.ts` — wire `onPaymentVerified`
 → `toPayaiVerifyResult` to screen payers before serving. Fail-open by default.
 
@@ -118,7 +167,7 @@ Prove refuse-before-sign: `npm run x402-solana-before-payment-proof`.
 Install the published gate and run against wash fixtures:
 
 ```bash
-npm install twzrd-x402-gate@0.8.19
+npm install twzrd-x402-gate@0.9.0
 # from package root after install, or from a checkout:
 npm run wash-dogfood
 ```
@@ -138,7 +187,7 @@ Gate dogfood: `approved=false` `reason=twzrd_decision_block`, **USDC spent = 0**
 
 **Accurate paste line:**
 
-> Preflight returned decision=block on wash seller 7G73PL… / HuSiSpc… (preflight_id 378468 / 378469, wash_flagged=true). Gate approved=false reason=twzrd_decision_block. No USDC spent. No tx broadcast. Repro: `npm i twzrd-x402-gate@0.8.5 && npm run wash-dogfood` or gist above.
+> Preflight returned decision=block on wash seller 7G73PL… / HuSiSpc… (preflight_id 378468 / 378469, wash_flagged=true). Gate approved=false reason=twzrd_decision_block. No USDC spent. No tx broadcast. Repro: `npm i twzrd-x402-gate@0.9.0 && npm run wash-dogfood` or gist above.
 
 This is a **reproducible demonstration** that the free gate blocks known wash sellers with stamped `preflight_id`s and zero spend. It is **not** proof that external agents already default to this path at scale.
 
@@ -216,6 +265,56 @@ No AgentCash. No marketplace. No second probe. No TWZRD custody.
 Wire `twzrdOnPaymentRequested` / prefer `onPaymentRequired` + `onBeforePayment` per
 [lifecycle hooks](https://docs.x402.org/advanced-concepts/lifecycle-hooks). Same policy core.
 
+### Cloudflare Agents x402 (Base)
+
+Cloudflare's `withX402Client` takes an `onPaymentRequired` callback before its
+automatic payment retry. Use the adapter below at that boundary:
+
+```ts
+import { createTwzrdCloudflareX402Approval } from "twzrd-x402-gate";
+
+const approvePayment = createTwzrdCloudflareX402Approval({
+  // Base/EVM has no TWZRD behavioral reputation yet. Refuse it rather than
+  // presenting a policy allow as a trust verdict.
+  unsupportedNetworkMode: "strict",
+});
+
+await this.x402Client.callTool(approvePayment, {
+  name: "paid_tool",
+  arguments: {},
+});
+```
+
+`observe` is available for an agent that intentionally permits unscored Base
+payments, but it returns policy allow with `decision=unknown`; it is never a
+TWZRD reputation approval. This adapter protects the Cloudflare x402 path only.
+MPP is a separate protocol and belongs on its own `onChallenge` /
+`onPaymentRequired` control path.
+
+### Cloudflare Worker / Base x402 (edge-safe preflight)
+
+For a Worker, import the dedicated subpath rather than the package root. It has
+no Node-native imports and sends the exact Base `payTo` plus `chain_id: 8453` to
+`/v1/intel/preflight` before a Viem account signs:
+
+```ts
+import { withTwzrdBasePreflight } from "twzrd-x402-gate/cloudflare-base";
+
+const signature = await withTwzrdBasePreflight(
+  paymentRequirements, // accepts: [{ network: "eip155:8453", payTo: "0x..." }]
+  { intelBase: "https://intel.twzrd.xyz" },
+  () => account.signTypedData(eip3009Authorization),
+);
+```
+
+`block` throws `TwzrdBasePaymentBlockedError` and never invokes the signing
+callback. `allow` and `warn` both proceed; enforce any additional amount or
+mandate policy in the caller. Base is not presented as reputation-scored.
+Checksummed and lowercase EVM addresses are accepted unchanged. The fixture in
+[`test/cloudflare-base-edge.test.ts`](./test/cloudflare-base-edge.test.ts) proves
+`block → zero signTypedData calls` and the compiled subpath is checked for Node
+runtime leaks.
+
 ### Raw-fetch composition (injectible pay client only)
 
 ```typescript
@@ -263,7 +362,7 @@ Dogfood (one public live proof path):
 ## Install
 
 ```bash
-npm install twzrd-x402-gate@0.8.19 x402-solana@2.1.0
+npm install twzrd-x402-gate@0.9.0 x402-solana@3.0.0
 ```
 
 Install pin is the published version (`GATE_PACKAGE_PIN` in
@@ -363,15 +462,16 @@ installTwzrdX402ClientHook(client, {
 - Hook binding test:
   [`test/intent-binding.test.ts`](./test/intent-binding.test.ts).
 
-### On MPP (Machine Payments Protocol) — Solana charge only
+### On MPP (Machine Payments Protocol) — Solana and narrow Base EVM charge
 
-`createTwzrdMppOnChallenge` guards `Mppx.create({ onChallenge })`. The mppx
-Solana method signs AND broadcasts the transaction inside `createCredential()`,
-so `onChallenge` is the last deterministic checkpoint before money moves - and
-mppx re-throws `onChallenge` errors, so a TWZRD block is an exception that means
-**`createCredential()` never runs and nothing signs**. On allow, the guard
-creates the credential for the exact challenge it evaluated; non-`solana/charge`
-challenges fail closed (`allowUnevaluated: true` to opt out).
+`createTwzrdMppOnChallenge` guards `Mppx.create({ onChallenge })`. It supports
+`solana/charge` and the published native MPP `evm/charge` shape only for
+Base-mainnet native USDC (EIP-3009 authorization). `onChallenge` is the last
+deterministic checkpoint before `createCredential()` makes the credential, so a
+TWZRD block is an exception that means **`createCredential()` never runs and
+nothing signs**. On allow, the guard creates the credential for the exact
+challenge it evaluated; other methods/intents fail closed
+(`allowUnevaluated: true` is an explicit ungated opt-out).
 
 ```typescript
 import { Mppx } from "mppx/client";
@@ -387,6 +487,30 @@ const mppx = Mppx.create({
 });
 ```
 
+For Base, use mppx's EVM client with explicit local spend policy:
+
+```typescript
+import { Mppx } from "mppx/client";
+import { evm } from "mppx/evm/client";
+import { createTwzrdMppOnChallenge, createLocalDecisionSigner } from "twzrd-x402-gate";
+
+const mppx = Mppx.create({
+  methods: [evm({ account: wallet })],
+  onChallenge: createTwzrdMppOnChallenge({
+    signer: createLocalDecisionSigner(),
+    policy: {
+      allowedNetworks: ["eip155:8453"],
+      allowedAssets: ["0x833589fCD6EDb6E08f4c7C32D4f71b54bdA02913"],
+      maxAmountUsd: "1.00",
+    },
+  }),
+});
+```
+
+Base is **not reputation-scored**. The EVM path provides an actual pre-credential
+local control point for Base USDC; it does not call a Solana-derived score or
+present a local policy allow as a TWZRD trust verdict.
+
 **Scope limit (honest):** the guard is authoritative only when no
 `onChallengeReceived` event handler supplies a credential. mppx resolves
 `eventCredential ?? onChallenge(...)`, so an event handler returning a credential
@@ -402,6 +526,8 @@ fails closed rather than approve a payment it cannot bind:
 | Non-USD-pegged asset | `UNPRICED_ASSET` | Policy ceilings are USD; the wire amount is base-unit tokens. Pricing SOL would store `asset: solana:native` beside a **dollar** `amount` and lose the token quantity actually transferred. (A 1.5 SOL charge of `1500000000` at 9 decimals would otherwise evaluate as "$1.50" and sail under a $5 ceiling while moving ~$270.) USDC/USDT only until an intent version carries token amount + quote. |
 | Unknown cluster | `UNKNOWN_CLUSTER` | mppx-solana's `resolveEndpoint` returns an unrecognized `cluster` **verbatim as the RPC endpoint URL**, and a network string containing "solana" is otherwise scored as mainnet - so `solana:https://seller-rpc.example` would inherit mainnet reputation for a chain never observed. Known cluster names only. |
 | Misdeclared decimals | `MALFORMED_CHALLENGE` | A known stablecoin declaring the wrong decimals is a discount attempt, not a rounding error. |
+| Non-Base EVM chain | `UNSUPPORTED_EVM_NETWORK` | EVM MPP is narrow: Base mainnet only. A testnet or another EVM network cannot inherit a Base USDC valuation. |
+| EVM split recipients | `MULTI_LEG_CHARGE` | mppx EVM permits `splits`; each is an additional recipient. PaymentIntent v1 binds one amount to one payTo, so the guard refuses rather than approve transfers it cannot represent. |
 
 The intent binds a **digest of the entire normalized challenge**, not just
 `realm:id` - swapping `recipient` or `amount` under the same challenge id changes
@@ -790,17 +916,31 @@ const gatedFetch = wrapFetchWithTwzrdGate(fetch, resolveConfig());
 
 A payment is **blocked** when:
 1. `decision ∈ blockDecisions` (default: `["block"]`)
-2. `trust_score < preflightMinScore` (default: `40`)
+2. `trust_score < preflightMinScore` (default: `40`) — note a card with **no**
+   `trust_score` is scored `0` (`policy.ts`: `card.trust_score ?? 0`), so a
+   missing score blocks under the default floor
 3. `can_spend === false` — **only** when `gateOnCanSpend: true` (default `false`, opt-in)
+4. `merchant_card.wash_flagged === true` — **on by default**
+   (`refuseWashFlagged`, `TWZRD_REFUSE_WASH_FLAGGED`); forces `verdict: "block"`
+   with `reason: twzrd_wash_flagged`. Only tightens, and fails **open** when the
+   card is unreachable or `wash_flagged` is `null` (never evaluated ≠ clean).
+   Soft-cap instead of hard refuse with `washMaxUsdc` / `TWZRD_WASH_MAX_USDC`.
 
 `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.
 
 A 402 whose payment requirements yield **no identifiable seller wallet** (missing/empty `payTo`, or an unparseable `accepts[]`) is a different case from "unknown seller" — it always **blocks** with `reason: twzrd_unidentifiable_payment_recipient`, without ever calling the preflight network. This is unconditional (not affected by `failOpen`): `failOpen` governs what happens when the TWZRD *service* is unreachable, not what happens when the caller can't say who they're paying.
 
 > **`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.
+> not yet in the TWZRD corpus, including legitimate ones. That **`can_spend` leg
+> alone** is opt-in — it is ignored unless you set `gateOnCanSpend: true` — so an
+> unknown seller on a platform like Agentic.Market is not blocked *on that basis*.
+>
+> This is **not** a blanket "unknown sellers are allowed by default". Conditions 1,
+> 2 and 4 above are all active by default, and condition 2 is the one that catches
+> unknown sellers: a card carrying no `trust_score` evaluates as `0` and blocks
+> under the default `preflightMinScore: 40` with `twzrd_score_0_below_40`. To
+> actually let unscored sellers through, lower or disable `preflightMinScore` —
+> setting `gateOnCanSpend` does not govern it.
 
 ## Config
 
@@ -811,11 +951,24 @@ A 402 whose payment requirements yield **no identifiable seller wallet** (missin
 | `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` |
+| `refuseWashFlagged` | `TWZRD_REFUSE_WASH_FLAGGED` | **`true`** | Refuse when `merchant_card.wash_flagged === true` (Policy 4). Set `false` / `0` to opt out |
+| `washMaxUsdc` | `TWZRD_WASH_MAX_USDC` | — | Soft cap instead of hard refuse on wash: allow up to this USDC amount |
+| `unsupportedNetworkMode` | `TWZRD_UNSUPPORTED_NETWORK_MODE` | `observe` | Behavior on a non-Solana / unrecognized network |
+| `fetch` | — | global `fetch` | Injected fetch used for preflight + merchant card (testing / custom agents) |
+| `onWarnUpsell` | — | — | Callback fired on a `warn` verdict (Path A upsell hook) |
+| `attribution` | `TWZRD_ATTRIBUTION_INTEGRATION` + `TWZRD_ATTRIBUTION_RUN_ID` | — | Opt-in run attribution (see below) |
+
+The four options below are **not** `TwzrdGateConfig` fields — they belong to
+`TwzrdGuardOptions` / `InstallAutoGateOptions` (`withTwzrdGuard` /
+`installTwzrdAutoGate`). Passing them to `createTwzrdGate({...})` is a type error
+and is silently dropped at runtime:
+
+| Option | Env | Default | Description |
+|---|---|---|---|
 | `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 |
-| `attribution` | `TWZRD_ATTRIBUTION_INTEGRATION` + `TWZRD_ATTRIBUTION_RUN_ID` | — | Opt-in run attribution (see below) |
 
 ## Gate adoption proof (no-spend harness)
 

package/dist/cloudflare-base.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Edge-safe Base x402 preflight gate.
+ *
+ * This module is intentionally standalone: it imports no package code and uses
+ * only Fetch/Web-standard APIs, so Workers can import `twzrd-x402-gate/cloudflare-base`
+ * without bringing Node modules or Solana adapters into their bundle.
+ */
+export declare const BASE_CHAIN_ID = 8453;
+export declare const BASE_NETWORK = "eip155:8453";
+export type CloudflareBaseRequirements = {
+    resource?: string;
+    accepts?: Array<Record<string, unknown>>;
+};
+export type BasePreflightVerdict = {
+    decision: "allow" | "warn" | "block";
+    /** TWZRD's current preflight calls this trust_score; normalized here for callers. */
+    riskScore: number | null;
+    reasons: string[];
+};
+export type CloudflareBaseGateOptions = {
+    intelBase?: string;
+    fetch?: typeof fetch;
+    /** Explicit price context only; x402 atomic amounts are never treated as USD. */
+    priceUsdc?: number;
+    resourceName?: string;
+    agentIntent?: string;
+    /** Default false: an unavailable or malformed preflight does not permit signing. */
+    failOpen?: boolean;
+};
+export declare class TwzrdBasePaymentBlockedError extends Error {
+    readonly verdict: BasePreflightVerdict;
+    constructor(verdict: BasePreflightVerdict);
+}
+/**
+ * Calls the live TWZRD preflight with an exact Base mainnet payTo.
+ *
+ * Both lowercase and checksummed EVM addresses are valid inputs. The address is
+ * preserved as received; the endpoint evaluates the exact recipient the client
+ * is about to authorize.
+ */
+export declare function twzrdBasePreflight(requirements: CloudflareBaseRequirements, options?: CloudflareBaseGateOptions): Promise<BasePreflightVerdict>;
+/** Cloudflare `withX402Client` callback: true permits the retry; false aborts it. */
+export declare function createTwzrdCloudflareBaseApproval(options?: CloudflareBaseGateOptions): (requirements: CloudflareBaseRequirements) => Promise<boolean>;
+/**
+ * Minimal signing interceptor for a Worker or Viem account. The callback is
+ * invoked only after the exact Base payTo received a non-block verdict.
+ */
+export declare function withTwzrdBasePreflight<T>(requirements: CloudflareBaseRequirements, options: CloudflareBaseGateOptions, signOrSend: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=cloudflare-base.d.ts.map

package/dist/cloudflare-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-base.d.ts","sourceRoot":"","sources":["../src/cloudflare-base.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,aAAa,OAAO,CAAC;AAClC,eAAO,MAAM,YAAY,gBAA4B,CAAC;AAEtD,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,qFAAqF;IACrF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;gBAE3B,OAAO,EAAE,oBAAoB;CAK1C;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,0BAA0B,EACxC,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,oBAAoB,CAAC,CAqB/B;AAED,qFAAqF;AACrF,wBAAgB,iCAAiC,CAC/C,OAAO,GAAE,yBAA8B,GACtC,CAAC,YAAY,EAAE,0BAA0B,KAAK,OAAO,CAAC,OAAO,CAAC,CAQhE;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,YAAY,EAAE,0BAA0B,EACxC,OAAO,EAAE,yBAAyB,EAClC,UAAU,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC,CAUZ"}

package/dist/cloudflare-base.js

@@ -0,0 +1,113 @@
+/**
+ * Edge-safe Base x402 preflight gate.
+ *
+ * This module is intentionally standalone: it imports no package code and uses
+ * only Fetch/Web-standard APIs, so Workers can import `twzrd-x402-gate/cloudflare-base`
+ * without bringing Node modules or Solana adapters into their bundle.
+ */
+export const BASE_CHAIN_ID = 8453;
+export const BASE_NETWORK = `eip155:${BASE_CHAIN_ID}`;
+export class TwzrdBasePaymentBlockedError extends Error {
+    verdict;
+    constructor(verdict) {
+        super(`[twzrd] Base payment blocked: ${verdict.reasons.join(",") || "PREFLIGHT_BLOCK"}`);
+        this.name = "TwzrdBasePaymentBlockedError";
+        this.verdict = verdict;
+    }
+}
+/**
+ * Calls the live TWZRD preflight with an exact Base mainnet payTo.
+ *
+ * Both lowercase and checksummed EVM addresses are valid inputs. The address is
+ * preserved as received; the endpoint evaluates the exact recipient the client
+ * is about to authorize.
+ */
+export async function twzrdBasePreflight(requirements, options = {}) {
+    const payTo = basePayTo(requirements);
+    const fetchFn = options.fetch ?? globalThis.fetch;
+    if (typeof fetchFn !== "function")
+        throw new Error("[twzrd] Worker fetch is unavailable");
+    const intelBase = (options.intelBase ?? "https://intel.twzrd.xyz").replace(/\/+$/, "");
+    const response = await fetchFn(`${intelBase}/v1/intel/preflight`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            resource_name: options.resourceName ?? requirements.resource ?? "cloudflare_base_x402",
+            resource_url: requirements.resource,
+            seller_wallet: payTo,
+            price_usdc: options.priceUsdc,
+            agent_intent: options.agentIntent ?? "cloudflare_base_x402_preflight",
+            chain: "base",
+            chain_id: BASE_CHAIN_ID,
+        }),
+    });
+    if (!response.ok)
+        throw new Error(`[twzrd] Base preflight HTTP ${response.status}`);
+    return normalizePreflight(await response.json());
+}
+/** Cloudflare `withX402Client` callback: true permits the retry; false aborts it. */
+export function createTwzrdCloudflareBaseApproval(options = {}) {
+    return async (requirements) => {
+        try {
+            return (await twzrdBasePreflight(requirements, options)).decision !== "block";
+        }
+        catch {
+            return options.failOpen === true;
+        }
+    };
+}
+/**
+ * Minimal signing interceptor for a Worker or Viem account. The callback is
+ * invoked only after the exact Base payTo received a non-block verdict.
+ */
+export async function withTwzrdBasePreflight(requirements, options, signOrSend) {
+    let verdict;
+    try {
+        verdict = await twzrdBasePreflight(requirements, options);
+    }
+    catch (error) {
+        if (options.failOpen === true)
+            return signOrSend();
+        throw error;
+    }
+    if (verdict.decision === "block")
+        throw new TwzrdBasePaymentBlockedError(verdict);
+    return signOrSend();
+}
+function basePayTo(requirements) {
+    const accept = requirements.accepts?.find((candidate) => {
+        const network = candidate.network;
+        const chainId = candidate.chainId ?? candidate.chain_id;
+        return network === BASE_NETWORK || chainId === BASE_CHAIN_ID || chainId === String(BASE_CHAIN_ID);
+    });
+    const payTo = accept?.payTo ?? accept?.pay_to;
+    if (typeof payTo !== "string" || !/^0x[a-fA-F0-9]{40}$/.test(payTo)) {
+        throw new Error("[twzrd] Base x402 requirements lack a valid eip155:8453 payTo");
+    }
+    return payTo;
+}
+function normalizePreflight(value) {
+    const response = asRecord(value);
+    if (!response)
+        throw new Error("[twzrd] Base preflight returned a non-object response");
+    const card = asRecord(response.readiness_card) ?? response;
+    const decision = card.decision;
+    if (decision !== "allow" && decision !== "warn" && decision !== "block") {
+        throw new Error("[twzrd] Base preflight returned no valid decision");
+    }
+    const riskScore = numberOrNull(card.risk_score) ?? numberOrNull(card.trust_score);
+    const reasons = strings(card.reasons ?? card.reason_codes ?? asRecord(card.decision_envelope)?.reason_codes);
+    return { decision, riskScore, reasons };
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function numberOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function strings(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+//# sourceMappingURL=cloudflare-base.js.map

package/dist/cloudflare-base.js.map

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

package/dist/cloudflare-x402.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Cloudflare Agents x402 approval adapter.
+ *
+ * Cloudflare's `withX402Client(...).callTool(onPaymentRequired, ...)` asks the
+ * caller to approve a payment before it constructs and submits the payment
+ * payload. This adapter turns that callback into the same TWZRD decision used
+ * by the generic MCP hook.
+ *
+ * This is an approval boundary, not a claim that Base has TWZRD behavioral
+ * reputation. Base/EVM stays `decision=unknown`: observe permits it and strict
+ * refuses it before the Cloudflare client pays.
+ */
+import type { TwzrdGateConfig, X402PaymentRequiredBody } from "./types.js";
+/** Dependency-free structural shape passed to Cloudflare's callback. */
+export type CloudflareX402PaymentRequirements = X402PaymentRequiredBody & {
+    resource?: string;
+    description?: string;
+};
+/**
+ * Build a Cloudflare `onPaymentRequired` callback.
+ *
+ * @example
+ * const approvePayment = createTwzrdCloudflareX402Approval({
+ *   unsupportedNetworkMode: "strict",
+ * });
+ * await client.callTool(approvePayment, { name: "paid_tool", arguments: {} });
+ */
+export declare function createTwzrdCloudflareX402Approval(options?: TwzrdGateConfig): (paymentRequirements: CloudflareX402PaymentRequirements) => Promise<boolean>;
+//# sourceMappingURL=cloudflare-x402.d.ts.map

package/dist/cloudflare-x402.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare-x402.d.ts","sourceRoot":"","sources":["../src/cloudflare-x402.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE3E,wEAAwE;AACxE,MAAM,MAAM,iCAAiC,GAAG,uBAAuB,GAAG;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,CAAC,EAAE,eAAe,GACxB,CAAC,mBAAmB,EAAE,iCAAiC,KAAK,OAAO,CAAC,OAAO,CAAC,CAU9E"}