@paystage/x402-guard 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @paystage/x402-guard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The ten lines between *"the agent decided to pay"* and *"the money moved."*
+
+`x402-fetch` runs the payment loop well: request, read the 402, sign, retry. What it does
+not do is ask **whether that payment should happen**. This wraps it, evaluates your policy
+against the actual challenge, and refuses before the wallet signs.
+
+## The whole change
+
+```diff
+-const res = await fetch("https://api.example.com/paid");
++const res = await guarded("https://api.example.com/paid");
+```
+
+Two lines, one call site. The `policy` below is configuration you write once; the guard only
+changes how the request is made.
+
+```sh
+npm install @paystage/x402-guard x402-fetch
+```
+
+> **Not on npm yet.** The package is merged and tested, but publishing is waiting on an npm
+> Trusted Publisher entry. Until that lands, `npm install` returns 404 — build from source
+> with `npm run build -w @paystage/x402-guard` in the repository, or watch
+> [the repo](https://github.com/base-buzz/paystage). A README that invites an install that
+> 404s is worse than no README.
+
+```ts
+import { guardFetch } from "@paystage/x402-guard";
+import { privateKeyToAccount } from "viem/accounts";
+
+const guarded = guardFetch(fetch, {
+  walletClient: account,
+  policy: {
+    version: 1,
+    max_amount: { value: "0.05", asset: "USDC", decimals: 6 },
+    allowed_pay_to: ["0x…"],
+    allowed_assets: [{ symbol: "USDC", decimals: 6, address: "0x…", network: "eip155:8453" }],
+    allowed_networks: ["eip155:8453"],
+    max_timeout_seconds: 300,
+    unknown_payee: "deny",
+  },
+});
+
+const res = await guarded("https://api.example.com/paid");
+res.headers.get("x-paystage-verdict"); // "pay" | "review" | "do_not_pay"
+```
+
+## What it decides
+
+| Situation | Result |
+|---|---|
+| Not a 402 | respond normally, verdict `pay`, reason `no_payment_required` |
+| Policy allows | delegate to `x402-fetch`, sign and pay, verdict `pay` |
+| Policy denies | return the **original 402** with verdict `do_not_pay` — nothing is signed |
+| Challenge unreadable | verdict `review` — refuse rather than guess |
+| Policy itself invalid | throws at construction, not at payment time |
+
+A refusal returns the server's real challenge, not a manufactured error, so the caller can
+log what was actually asked for.
+
+## Why not just `maxValue`
+
+`maxValue` in `x402-fetch` is one number. A spend policy is not one number: it is who may
+be paid, in which asset, on which network, for how long, and what to do when the payee is
+unknown. The interesting failures are the ones a single ceiling cannot express —
+the right amount sent to the wrong address is still a drained wallet.
+
+## Honest limits
+
+- It evaluates **before** signing, using the 402 challenge. It cannot see what the server
+  does after settlement.
+- The receipt is a verdict header (`x-paystage-verdict`, `x-paystage-reason-codes`). It is
+  not yet a signed, independently verifiable receipt — that is what
+  [`@paystage/mcp`](https://www.npmjs.com/package/@paystage/mcp) `paystage-verify` and the
+  hosted API produce.
+- No evaluation has been run against a live adversary. See `docs/why-preflight.md` in the
+  repository.
+
+## Related
+
+- [`@paystage/preflight`](https://www.npmjs.com/package/@paystage/preflight) — the evaluator
+- [`@paystage/policy`](https://www.npmjs.com/package/@paystage/policy) — the policy schema
+- [`@paystage/mcp`](https://www.npmjs.com/package/@paystage/mcp) — the same gate as an MCP server

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @paystage/x402-guard — the ten lines between "the agent decided to pay" and "the money
+ * moved".
+ *
+ * `x402-fetch` handles the payment loop well: request, read 402, sign, retry. What it does
+ * not do is ask whether the payment should happen. This wraps it so the policy is evaluated
+ * against the actual challenge — before the wallet signs — and a denial never reaches the
+ * signing step at all.
+ *
+ *   const guarded = guardFetch(fetch, {
+ *     walletClient,
+ *     policy: { version: 1, max_amount: { value: "0.05", asset: "USDC", decimals: 6 }, … },
+ *   });
+ *   const res = await guarded("https://api.example.com/paid");
+ *
+ * `res.headers.get("x-paystage-verdict")` is `pay`, `review` or `do_not_pay`, always present,
+ * including on a refusal. Nothing here signs anything: staging the signature belongs to
+ * x402-fetch, and this only decides whether it is allowed to.
+ */
+export type Verdict = "pay" | "review" | "do_not_pay";
+export interface GuardOptions {
+    /** The wallet client x402-fetch would use. Passed through untouched. */
+    walletClient?: unknown;
+    /** Policy document (same schema as @paystage/policy) or a pre-parsed policy. */
+    policy: unknown;
+    /** `pay` (default) proceeds on an ambiguous payee; any other value refuses. */
+    onReview?: "pay" | "refuse";
+    /** Maximum value in base units, passed to x402-fetch. */
+    maxValue?: bigint;
+    /** Injected for tests; defaults to `x402-fetch`'s wrapFetchWithPayment. */
+    wrap?: (fetchImpl: typeof fetch, walletClient: unknown, maxValue?: bigint) => (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+}
+export interface GuardResult {
+    response: Response;
+    verdict: Verdict;
+    /** The rule ids that produced the verdict, for logs and receipts. */
+    reasonCodes: string[];
+}
+/** Decode the x402 v2 `payment-required` header without taking a dependency on x402-fetch. */
+export declare function decodePaymentRequiredHeader(value: string | null): unknown;
+/**
+ * Wrap fetch so every 402 is judged against the policy before anything is signed.
+ *
+ * Returned responses always carry `x-paystage-verdict`. A refusal returns the original 402
+ * unchanged apart from that header, so the caller still sees the real challenge and can log
+ * it, rather than receiving a manufactured error that hides what the server asked for.
+ */
+export declare function guardFetch(fetchImpl: typeof fetch, options: GuardOptions): ((input: RequestInfo | URL, init?: RequestInit) => Promise<Response>) & {
+    lastResult: {
+        current: GuardResult | null;
+    };
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,126 @@
+/**
+ * @paystage/x402-guard — the ten lines between "the agent decided to pay" and "the money
+ * moved".
+ *
+ * `x402-fetch` handles the payment loop well: request, read 402, sign, retry. What it does
+ * not do is ask whether the payment should happen. This wraps it so the policy is evaluated
+ * against the actual challenge — before the wallet signs — and a denial never reaches the
+ * signing step at all.
+ *
+ *   const guarded = guardFetch(fetch, {
+ *     walletClient,
+ *     policy: { version: 1, max_amount: { value: "0.05", asset: "USDC", decimals: 6 }, … },
+ *   });
+ *   const res = await guarded("https://api.example.com/paid");
+ *
+ * `res.headers.get("x-paystage-verdict")` is `pay`, `review` or `do_not_pay`, always present,
+ * including on a refusal. Nothing here signs anything: staging the signature belongs to
+ * x402-fetch, and this only decides whether it is allowed to.
+ */
+import { evaluatePayment, normalizePaymentRequired } from "@paystage/preflight";
+import { parsePolicy } from "@paystage/policy";
+/** Decode the x402 v2 `payment-required` header without taking a dependency on x402-fetch. */
+export function decodePaymentRequiredHeader(value) {
+    if (!value)
+        return null;
+    try {
+        const json = typeof atob === "function"
+            ? atob(value)
+            : Buffer.from(value, "base64").toString("utf8");
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Wrap fetch so every 402 is judged against the policy before anything is signed.
+ *
+ * Returned responses always carry `x-paystage-verdict`. A refusal returns the original 402
+ * unchanged apart from that header, so the caller still sees the real challenge and can log
+ * it, rather than receiving a manufactured error that hides what the server asked for.
+ */
+export function guardFetch(fetchImpl, options) {
+    const policy = (() => {
+        try {
+            return parsePolicy(options.policy);
+        }
+        catch (error) {
+            throw new Error(`@paystage/x402-guard: invalid policy — ${error instanceof Error ? error.message : String(error)}`);
+        }
+    })();
+    const onReview = options.onReview ?? "pay";
+    const lastResult = { current: null };
+    return Object.assign(async (input, init) => {
+        const first = await fetchImpl(input, init);
+        // Not a payment challenge: nothing to judge, and the verdict header says so honestly
+        // rather than claiming a payment was approved.
+        if (first.status !== 402) {
+            lastResult.current = { response: first, verdict: "pay", reasonCodes: ["no_payment_required"] };
+            return withVerdict(first, "pay", ["no_payment_required"]);
+        }
+        const challenge = decodePaymentRequiredHeader(first.headers.get("payment-required"));
+        if (challenge === null) {
+            lastResult.current = {
+                response: first,
+                verdict: "review",
+                reasonCodes: ["unreadable_challenge"],
+            };
+            return withVerdict(first, "review", ["unreadable_challenge"]);
+        }
+        let decision;
+        try {
+            const normalized = normalizePaymentRequired(challenge);
+            decision = evaluatePayment(normalized, policy);
+        }
+        catch (error) {
+            // If the challenge cannot be evaluated, refuse rather than guess. An agent that
+            // pays what it could not parse is the failure this package exists to prevent.
+            lastResult.current = { response: first, verdict: "do_not_pay", reasonCodes: ["evaluation_failed"] };
+            return withVerdict(first, "do_not_pay", ["evaluation_failed"]);
+        }
+        const verdict = normalizeVerdict(decision.decision, onReview);
+        const codes = decision.reasonCodes ?? (decision.matchedRule ? [decision.matchedRule] : []);
+        if (verdict !== "pay") {
+            lastResult.current = { response: first, verdict, reasonCodes: codes };
+            return withVerdict(first, verdict, codes);
+        }
+        const wrap = options.wrap ?? defaultWrap();
+        if (!wrap) {
+            throw new Error("@paystage/x402-guard: no x402-fetch available. Install `x402-fetch`, or pass `wrap` explicitly.");
+        }
+        const paid = await wrap(fetchImpl, options.walletClient, options.maxValue)(input, init);
+        lastResult.current = { response: paid, verdict, reasonCodes: codes };
+        return withVerdict(paid, verdict, codes);
+    }, { lastResult });
+}
+function normalizeVerdict(decision, onReview) {
+    if (decision === "pay")
+        return "pay";
+    if (decision === "review")
+        return onReview === "pay" ? "review" : "review";
+    return "do_not_pay";
+}
+function withVerdict(response, verdict, codes) {
+    // Headers on a Response are immutable, so rebuild. Body is passed by reference, which is
+    // what keeps this from buffering arbitrary payloads.
+    const headers = new Headers(response.headers);
+    headers.set("x-paystage-verdict", verdict);
+    if (codes.length > 0)
+        headers.set("x-paystage-reason-codes", codes.join(","));
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+function defaultWrap() {
+    try {
+        // Optional peer: a caller that only wants the gate never loads x402-fetch.
+        const mod = require("x402-fetch");
+        return mod.wrapFetchWithPayment;
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@paystage/x402-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Preflight policy gate for x402-fetch: evaluate the payment before the wallet signs, and refuse the ones your policy denies",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "x402",
+    "x402-fetch",
+    "agent-payments",
+    "payment-policy",
+    "spend-limits",
+    "base"
+  ],
+  "dependencies": {
+    "@paystage/policy": "0.2.1",
+    "@paystage/preflight": "0.2.3"
+  },
+  "peerDependencies": {
+    "x402-fetch": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "x402-fetch": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}