twzrd-x402-gate 0.9.4 → 0.9.6

package/QUICKSTART.md

@@ -1,15 +1,17 @@
 # twzrd-x402-gate — Quickstart (15 minutes, 0 USDC)
 
-**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.
+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).
 
-**Pin:** `twzrd-x402-gate@0.9.3` + `x402-solana@3.0.0`.
+**Pin:** `twzrd-x402-gate@0.9.6` + stock PayAI client `x402-solana@3.0.0` (official
+`beforePayment` seat). `@x402/core` Path E remains supported; refuse script is fallback.
 
 ## 1. Stock PayAI client (default seat — copy-paste)
 
 ```bash
-npm install twzrd-x402-gate@0.9.3 x402-solana@3.0.0
+npm install twzrd-x402-gate@0.9.6 x402-solana@3.0.0
 ```
 
 > **ESM-only.** The package ships `import` conditions only — a CommonJS
@@ -17,16 +19,6 @@ npm install twzrd-x402-gate@0.9.3 x402-solana@3.0.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";
@@ -34,18 +26,17 @@ import { createTwzrdBeforePaymentHook } from "twzrd-x402-gate";
 const client = createX402Client({
   wallet,
   network: "solana",
-  beforePayment: createTwzrdBeforePaymentHook(),
+  beforePayment: createTwzrdBeforePaymentHook({ refuseWashFlagged: true }),
 });
 ```
 
-Default engine = wash only. Full 0.8 preflight/Path A: `{ engine: "full" }`.
-
+Equivalent: `beforePayment: installTwzrdAutoGate("x402-solana", { refuseWashFlagged: true })`.
 Then: `await client.fetch("https://merchant.example/paid");`
 
 ## 1b. Official `@x402/core` client (Path E)
 
 ```bash
-npm install twzrd-x402-gate@0.9.3 @x402/core @x402/fetch @x402/svm
+npm install twzrd-x402-gate@0.9.6 @x402/core @x402/fetch @x402/svm
 ```
 
 ```typescript
@@ -58,6 +49,33 @@ installTwzrdAutoGate(client, { refuseWashFlagged: true });
 // then register schemes + wrapFetchWithPayment as usual
 ```
 
+## 1c. PayKit (`createPayKitClient`) — Foundation #303
+
+PayKit callers pass TWZRD as `onBeforeX402PaymentCreation`. No TWZRD branding
+inside pay-kit itself. The option is on `solana-foundation/pay-kit#303` (and the
+`twzrd-sol` fork); until Foundation merges, use the fork or wait.
+
+```typescript
+import { createPayKitClient } from "@solana/pay-kit";
+import { createTwzrdPayKitBeforePaymentHook } from "twzrd-x402-gate";
+
+const client = await createPayKitClient({
+  accept: ["x402"],
+  onBeforeX402PaymentCreation: createTwzrdPayKitBeforePaymentHook({
+    refuseWashFlagged: true,
+  }),
+  rpcUrl,
+  signer,
+});
+```
+
+Equivalent: `onBeforeX402PaymentCreation: installTwzrdAutoGate("pay-kit", { refuseWashFlagged: true })`.
+The hook is the official `@x402/core` context shape (same evaluator as Path E).
+`@solana/pay-kit` is optional — this package does not hard-depend on it.
+The factory itself does not read `TWZRD_AUTO_GATE`; use the AutoGate seat if you
+want the env kill switch re-read per call. You cannot `installTwzrdAutoGate(client)`
+after `createPayKitClient` — PayKit only accepts the hook at construction.
+
 ## 2. Prove it blocked something (spends nothing)
 
 ```bash
@@ -69,6 +87,9 @@ npm run x402-solana-before-payment-proof
 
 # @x402/core Path E proof (onBeforePaymentCreation)
 npm run autogate-block-proof
+
+# PayKit seat (fake createPayKitClient — no unpublished @solana/pay-kit)
+npm run pay-kit-before-payment
 ```
 
 That JSON is your receipt: a bad merchant intercepted with 0 USDC at risk.
@@ -121,7 +142,7 @@ payWrap as `x402Fetch`.
 
 | Knob | Effect |
 |------|--------|
-| `TWZRD_AUTO_GATE=0` | Kill switch — gate fully off, payments proceed unguarded |
+| `TWZRD_AUTO_GATE=0` | Kill switch — gate fully off, payments proceed unguarded. Read per call on the x402-client / x402-solana / pay-kit / MPP seats; the fetch (payWrap) seat resolves it once when the fetch is composed, in both directions — rebuild the fetch to change it. |
 | `refuseWashFlagged: false` | Stop refusing wash-flagged merchants (default `true`) |
 | `gateOnCanSpend: true` | Opt-in hard cap: also block when `can_spend=false` (default `false`) |
 
@@ -129,42 +150,9 @@ Everything else (thresholds, wash caps, fail posture, settle guard): [README](./
 
 ## What this will NOT do
 
-- **No Base/EVM reputation.** Non-Solana networks get an explicit `unknown` (payment
-  allowed, observed) unless you set `TWZRD_UNSUPPORTED_NETWORK_MODE=strict`.
+- **No Base/EVM reputation.** Non-Solana networks get an explicit `unknown`
+  (observed; no Solana preflight) unless you set
+  `TWZRD_UNSUPPORTED_NETWORK_MODE=strict`. Observe is not a wash bypass —
+  `wash_flagged` still refuses before sign.
 - **No delivery guarantee.** It screens the merchant before you pay, nothing after.
 - **Not a wallet.** It never holds keys or signs — it only decides if your signer runs.
-
-
-## Pay Kit before-payment hook (upstream PR pending)
-
-`solana-foundation/pay-kit#303` is open as of 2026-09-07. This adapter targets
-that PR's `onBeforeX402PaymentCreation` option; a released Pay Kit client must
-expose that option before this integration can enforce policy.
-
-```ts
-import { createPayKitClient } from "@solana/pay-kit";
-import { installTwzrdAutoGate } from "twzrd-x402-gate";
-
-const client = await createPayKitClient({
-  accept: ["x402"],
-  rpcUrl,
-  signer,
-  onBeforeX402PaymentCreation: installTwzrdAutoGate("pay-kit", {
-    refuseWashFlagged: true,
-  }),
-});
-```
-
-The adapter returns the official x402 context hook and reuses the shared
-before-payment evaluator. It adds no Pay Kit dependency. Supply it at client
-construction; passing the constructed Pay Kit client to AutoGate is unsupported.
-This hook covers x402 payment creation, not Pay Kit's MPP path.
-
-`createTwzrdPayKitBeforePaymentHook(options)` exposes the same evaluator directly.
-The AutoGate form reads environment kill switches on every call; the direct
-factory does not. Calling AutoGate installs protection by default, whereas
-ClawRouter's integration loads AutoGate only after explicit opt-in.
-
-Source-checkout verification: `npx tsx test/pay-kit-before-payment.test.ts`.
-The test covers a fake Pay Kit host and the real x402 client with a fake scheme;
-it does not establish released Pay Kit compatibility or external use.