twzrd-x402-gate 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -0,0 +1,146 @@
+# Changelog
+
+All notable changes to `twzrd-x402-gate`. Dates are npm publish dates (UTC).
+
+## Versioning policy (from 0.11.0)
+
+- **A change to what the gate allows or refuses ships in a minor release** (0.x.0 while
+  the package is below 1.0), with an entry here. Below 1.0, npm's caret range stays
+  within one minor (`^0.11.0` never resolves to 0.12.0), so nobody gets a new refusal
+  policy without choosing it.
+- **Patch releases** (0.x.y) carry fixes that do not change any allow/refuse outcome
+  for a well-formed card, plus docs, types and tests.
+- The package is published from this repository only, by the `publish` workflow with an
+  `expected_version` input, with npm provenance.
+
+## failOpen, stated once
+
+- **Buyer side** (`createTwzrdBeforePaymentHook`, `createGuardedX402Fetch`,
+  `withTwzrdGuard`, `evaluate_x402_resource`): fail-closed by default. A preflight that
+  returns any non-2xx status or a non-JSON body, or throws, refuses with
+  `twzrd_fail_closed`.
+  A free merchant-card lookup that returns 5xx/429, a non-JSON body, or throws refuses
+  with `twzrd_card_unreachable_fail_closed`. With `failOpen: true` (or
+  `TWZRD_FAIL_OPEN=1`) both allow instead. A merchant-card 4xx is intel answering,
+  not an outage, and never refuses on its own.
+- **Seller side** (`createTwzrdSettleGuard`): fail-open by default. A screen that throws
+  returns without aborting settlement unless `failOpen: false`.
+
+## 0.11.0 — unreleased
+
+**Behaviour change: unevaluated sellers follow the card's cap.**
+
+- A seller intel has never evaluated (`null_reason` set, or `score: null`) is no longer
+  refused outright. Live intel answers such a seller with `decision: "warn"` and a
+  `recommended_cap_usdc` of min($0.10, requested price) on 2026-09-28; the gate now allows the
+  payment at or under that cap (`twzrd_unevaluated_within_cap_<price>_le_<cap>`) and
+  refuses it above the cap, when the card has no cap, or when the price is unknown.
+  An approval carries `unevaluated: true` and `score: null`. The free wash check still
+  runs after it.
+- New option `refuseUnevaluated` (env `TWZRD_REFUSE_UNEVALUATED`), default `false`.
+  `true` restores the 0.9.9–0.9.16 behaviour: every unevaluated seller is refused with
+  `twzrd_unevaluated_subject_<null_reason>`. The bounty preflight CLI sets it, so bounty
+  payees are still refused when unevaluated.
+- Direct callers of the exported `evaluateReadinessCard` must pass `priceUsdc` to get
+  an approval for an unevaluated card. Without it the reason is now
+  `twzrd_unevaluated_unknown_price_<null_reason>` (was
+  `twzrd_unevaluated_subject_<null_reason>`); `approved` is still `false`.
+- The $0.001 `/quick` escalation (`escalateOnWarn`) no longer runs for an unevaluated
+  seller: intel has no paid score for it either, so the hop spent money without being
+  able to change the decision.
+- Why a minor: 0.9.9 made "never evaluated" a refusal in a patch release, which meant
+  every new seller was refused before signing even when intel itself said "warn,
+  within cap". This reverses that default, so it ships as a minor.
+- **Why 0.11.0 and not 0.10.0:** see the 0.10.x entry below. Those version numbers are
+  taken on npm.
+
+Unchanged in 0.11.0: attribution headers. Every preflight still sends
+`X-TWZRD-Client` and `X-Twzrd-Caller` (the gate version); `X-TWZRD-Integration` and
+`X-TWZRD-Run-Id` are sent only when `attribution` is configured.
+
+## 0.9.16 — 2026-09-28
+
+- `createGuardedX402Fetch` recognises devnet USDC (Circle and faucet mints) on Solana
+  devnet instead of treating it as an unknown asset.
+- An `@x402/core` spend-control refusal is rethrown with a hint explaining that core's
+  default controls ran before the TWZRD hook.
+- A missing optional `@x402/fetch` peer throws an install hint instead of a bare import
+  error.
+
+## 0.9.15 — 2026-09-27
+
+- Docs: the package README explains `@x402/core` ≥2.23 default spend controls
+  (recognised assets, $1 per payment), which run before any `beforePaymentCreation` hook.
+
+## 0.9.14 — 2026-09-27
+
+- Tests run against `@x402/core` ^2.26 with its default spend controls on. No `src`
+  change.
+
+## 0.9.13 — 2026-09-26
+
+- `safeFetch` counts a `pay()` that throws after the signer ran against the budget,
+  instead of releasing it.
+
+Entries below were reconstructed on 2026-09-28 by diffing the published tarballs, so
+each change is listed under the first version that actually contains it. Several of
+them changed allow/refuse or paid behaviour in a patch release; 0.11.0's policy exists
+because of that.
+
+## 0.9.12 — 2026-09-26 (paid behaviour change in a patch release)
+
+- Buyer Path A defaults changed. With `x402Fetch` wired and the flags unset, a `warn`
+  now takes the $0.001 `/quick` hop at any price; before, a `warn` at $2.50 or more
+  bought the $0.05 receipt. `requireReceipt` default `onWarn` went from `true` to
+  `false`.
+
+## 0.9.11 — 2026-09-26 (behaviour change in a patch release)
+
+- An `accepts[]` entry whose v1 and v2 price fields (`maxAmountRequired` / `amount`)
+  or recipient fields (`payTo` / `pay_to`) disagree is refused on every path
+  (`amount_field_conflict` / `payto_field_conflict`). New export
+  `resolveRequirementFields`.
+
+## 0.9.10 — 2026-09-20 (behaviour change in a patch release)
+
+- The wash engine no longer hardcodes allow on an intel outage (timeout, 5xx, 429,
+  throw, bad JSON). New modules: `attempt-echo`, `cloudflare-x402`, `foreign-key`,
+  `paying-fetch`, `policy-fetch`, `wash-default`. See `COMPATIBILITY.md`.
+
+## 0.9.9 — 2026-09-15 (behaviour change in a patch release)
+
+- Base mainnet (`eip155:8453`) is scored instead of abstaining.
+- **A seller intel never evaluated is refused** (`twzrd_unevaluated_subject_*`). Every
+  new seller was refused before signing. 0.11.0 reverses the default.
+
+## 0.9.8 — 2026-09-13 (behaviour change in a patch release)
+
+- A merchant-card outage obeys `failOpen` instead of silently allowing. Before this, a
+  card lookup that failed was treated as "no wash signal" and allowed the payment even
+  with `failOpen: false`.
+
+## 0.9.7 — 2026-09-12
+
+- `evaluateIntent` re-checks the mandate ceiling and new-counterparty cap in the same
+  step that records the spend, so two concurrent intents can no longer both clear one
+  ceiling.
+- `safeFetch` hands the payer only the offer the gate approved (`accepts: [selected]`),
+  not the whole `accepts[]`.
+
+## 0.9.4 – 0.9.6 — 2026-09-07 to 2026-09-12
+
+- 0.9.4: `./unsafe` removed from the exports map and from the release contract. The
+  version line was moved from 0.10.1 back to 0.9.4 (see below).
+- 0.9.5: portable payment decisions (`twzrd.payment_decision.v1`) with an offline
+  verifier.
+- 0.9.6: reproducible build.
+
+## 0.10.0, 0.10.1 — 2026-09-02, 2026-09-07 (deprecated)
+
+- Both exported `./unsafe`, a documented signature-bypass export, because the release
+  contract at the time required it for a "complete" release. Both also carried the
+  merchant-card fail-open defect fixed in 0.9.8, and neither build is reproducible from
+  source in git.
+- Both are deprecated on npm. The line continued at 0.9.4. Semver ranks 0.10.1 above
+  every 0.9.x, so an install pinned to `^0.10` stays on the deprecated line: move to
+  `^0.11.0`.

package/QUICKSTART.md

@@ -2,16 +2,17 @@
 
 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).
+is unreachable the gate never *invents* a wash flag. A failed preflight, or a merchant_card
+outage on a scored path, blocks by default (`TWZRD_FAIL_OPEN=true` to allow). A reachable
+card with no wash signal still proceeds.
 
-**Pin:** `twzrd-x402-gate@0.9.3` + stock PayAI client `x402-solana@3.0.0` (official
+**Pin:** `twzrd-x402-gate@0.11.0` + 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.11.0 x402-solana@3.0.0
 ```
 
 > **ESM-only.** The package ships `import` conditions only — a CommonJS
@@ -36,7 +37,7 @@ 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.11.0 @x402/core @x402/fetch @x402/svm
 ```
 
 ```typescript
@@ -49,17 +50,75 @@ 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.
+`createTwzrdPayKitBeforePaymentHook` does not read `TWZRD_AUTO_GATE` or
+`TWZRD_GATE_ENABLED`. `installTwzrdAutoGate("pay-kit", opts)` is the seat that
+reads that kill switch per call and then calls the factory. You cannot
+`installTwzrdAutoGate(client)` after `createPayKitClient` — PayKit only accepts
+the hook at construction.
+
+## 1d. Cold-start a foreign diet (0 USDC)
+
+```bash
+npx twzrd-cold-start
+# policy.json: default-deny allowlist of foreign 402 hosts
+# signer_invocation_count: 0, usdc_spent: 0
+```
+
+Probes a pinned foreign GET 402 diet (not `*.twzrd`), scores each `payTo` with
+`evaluate_x402_resource` (wash refuse), writes `policy.json`, hops once from
+the resource join. Does not spend. `--spend` is refused. Seat AutoGate on the
+payer with
+`beforePayment: installTwzrdAutoGate("x402-solana", { refuseWashFlagged: true })`
+using that policy as the host allowlist. Live proof (needs egress):
+`npm run cold-start-live`.
+
 ## 2. Prove it blocked something (spends nothing)
 
+Hello-world that closes from this package (needs a prior **repo-root** `npm ci`
+and `npm run build`; do not `npm ci` in this directory):
+
 ```bash
-# Stock-client seat proof (beforePayment, signer_invocation_count=0)
-# 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 gate-eval-refuse
+# signer_invocation_count: 0, usdc_spent: 0
+```
+
+Optional seat proofs (live intel; the clean-fixture leg can exit 2 when
+`CLEAN_PAYTO` is wash-flagged — that is not the first demo):
+
+```bash
+# Stock-client seat proof (beforePayment). Needs x402-solana@3.0.0.
+# Harness fallback runs without it but does not clear closure.
 npm run x402-solana-before-payment-proof
 # writes block-proof-<run_id>.json — hook: beforePayment
 
 # @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.
@@ -90,9 +149,10 @@ createTwzrdBeforePaymentHook({
 
 ## 3b. Turn on Path A (buyer cash, not the rail)
 
-Refuse stays free until you wire a paying fetch. Then warn + material amount
-buys the $0.05 V6 (or $0.001 quick below $2.50). Facilitator settle hooks stay
-free.
+Refuse stays free until you wire a paying fetch. Then a proceeding `warn`
+settles the first paid hop: `GET /v1/intel/quick/{payTo}` at $0.001. Optional
+V7 `$0.05` `/trust` stays on material allow or explicit `autoReceipt`.
+Facilitator settle hooks stay free.
 
 ```typescript
 import { wrapFetchWithPayment } from "@x402/svm";
@@ -112,7 +172,7 @@ payWrap as `x402Fetch`.
 
 | Knob | Effect |
 |------|--------|
-| `TWZRD_AUTO_GATE=0` | Kill switch — gate fully off, payments proceed unguarded |
+| `TWZRD_AUTO_GATE=0` | Kill switch for `installTwzrdAutoGate` only — that seat proceeds unguarded. `createTwzrdBeforePaymentHook` does not read `TWZRD_AUTO_GATE` or `TWZRD_GATE_ENABLED`, so a direct call still aborts a bad payment. `installTwzrdAutoGate` reads the switch per call on the x402-client / x402-solana / pay-kit / MPP seats before it calls the factory. The fetch (payWrap) seat resolves it once when the fetch is composed — 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`) |
 
@@ -120,7 +180,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`.
+- **Base mainnet is scored.** Solana mainnet and Base mainnet (`eip155:8453`)
+  run the scored preflight. Other EVM networks do not: they get an explicit
+  `unknown` 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.