uvd-x402-sdk 2.101.0 → 2.103.0

package/README.md

@@ -888,11 +888,74 @@ app.post('/api/premium', async (req, res) => {
 });
 ```
 
-`createPaymentMiddleware()` and `createHonoMiddleware()` verify and settle automatically by default (`before-handler`). Use `settlementStrategy: 'manual'` if you need to control when settlement happens (e.g., settle only after confirming you can fulfill the request).
+`createPaymentMiddleware()`, `createHonoMiddleware()` and `createFetchPaywall()` verify and settle automatically by default (`before-handler`). Use `settlementStrategy: 'manual'` if you need to control when settlement happens (e.g., settle only after confirming you can fulfill the request).
+
+A buyer in a browser on another origin reads the terms of a v2 402, in the `PAYMENT-REQUIRED` header, only if the app's CORS exposes that header: list it in `Access-Control-Expose-Headers` (with `hono/cors`, `exposeHeaders: ['PAYMENT-REQUIRED']`) and send `Access-Control-Allow-Origin`. The 402 of `createHonoMiddleware` and `createFetchPaywall` sets no CORS header of its own; `create402Response` lists the header in its `headers` but sets no `Access-Control-Allow-Origin` (spread `getCorsHeaders(origin)` too).
+
+### Astro, Next.js, Vercel and Cloudflare (`createFetchPaywall`)
+
+A route that takes a `Request` and returns a `Response` gets the same paywall as `createHonoMiddleware`: same options, same answers, same code underneath. `createFetchPaywall(options)` returns a wrapper; the route it wraps runs only for a verified payment (settled first, unless `settlementStrategy: 'manual'`) and receives it as its second argument. Without a payment the route answers `402` with the accepts, and it never runs for a refused, unverifiable or already used one.
+
+**Astro** (`src/pages/api/premium/[id].ts`, on-demand rendering with any adapter, e.g. `@astrojs/vercel`):
+
+```typescript
+import type { APIRoute } from 'astro';
+import { createFetchPaywall } from 'uvd-x402-sdk/backend';
+
+// Run on every request: a prerendered endpoint is called once, at build time, without a payment.
+export const prerender = false;
+
+const paywall = createFetchPaywall({
+  accepts: [{
+    network: 'base',
+    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
+    amount: '10000', // $0.01 (6 decimals)
+    payTo: process.env.RECEIVING_ADDRESS as string,
+  }],
+});
+
+export const GET: APIRoute = paywall(async (context, x402) => {
+  return Response.json({ id: context.params.id, payer: x402.verifyResult.payer });
+});
+```
+
+**Next.js** (App Router, `app/api/articles/[slug]/route.ts`):
+
+```typescript
+import { createFetchPaywall } from 'uvd-x402-sdk/backend';
+
+const paywall = createFetchPaywall({ accepts: [/* as above */] });
+
+export const GET = paywall(async (request: Request, x402, { params }: { params: Promise<{ slug: string }> }) => {
+  const { slug } = await params;
+  const settled = await x402.settle(); // the settle already made before the handler ran
+  return Response.json({ slug, transaction: settled.transactionHash });
+});
+```
+
+**Vercel Functions and Cloudflare Workers** take the `Request` itself; whatever else the platform passes (`env`, `ctx`) comes after the payment:
+
+```typescript
+import { createFetchPaywall } from 'uvd-x402-sdk/backend';
+
+const paywall = createFetchPaywall({
+  accepts: [{ network: 'base', asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', amount: '10000', payTo: '0xYourWallet' }],
+});
+
+export default {
+  fetch: paywall(async (request: Request, x402, env: Env, ctx: ExecutionContext) => new Response('paid content')),
+};
+```
+
+- The route's first argument is the `Request`, or an object that carries it as `request` (Astro, SvelteKit, React Router). The handler gets that same first argument back, then the payment, then the rest.
+- The advertised `resource` is `request.url`. Behind a proxy that rewrites the host, set `resource` in the accept.
+- A facilitator receipt goes out as `PAYMENT-RESPONSE` on the response the handler returns, added to its own `Access-Control-Expose-Headers` and `Cache-Control` rather than replacing them; a `Response.redirect()` works too. In `'manual'` mode, a `settle()` that ends after the handler returned changes nothing in the response.
+- Once a receipt exists, a handler that throws an `Error` gets a `500` that keeps the receipt headers, as Hono's default error handler answers one, and the error goes to `console.error`: the buyer may have paid, and the receipt is their proof. Such an error does not reach the framework's error reporting (Next.js `onRequestError`, a Sentry wrapper); catch it inside the handler if it must. The framework's own control flow passes through untouched: a thrown `Response` (React Router, Remix) is rethrown with the receipt headers, and SvelteKit's `redirect()` / `error()` and Next.js' `redirect()` / `notFound()` are rethrown as they are, so the receipt does not ride on them; to send it with a redirect, return `Response.redirect()` instead. Without a receipt every error reaches the framework as usual.
+- The paywall answers every request that reaches it, `OPTIONS` included. If browsers on another origin pay, answer the preflight before the paywall (an `OPTIONS` export in Astro or Next.js, a method check in a Worker) and add `Access-Control-Allow-Origin` to what the route returns (`getCorsHeaders(origin)`).
 
 ### Stack key (services run by Ultravioleta DAO)
 
-Services run by Ultravioleta DAO carry a per-service credential, the stack key, so that the facilitator's rate-limit policy does not answer them `429`. Everything in this SDK that calls the facilitator sends it as `X-UVD-Stack-Key`: the clients `FacilitatorClient` (and the two middlewares), `Erc8004Client`, `BazaarClient`, `EscrowClient` and `AdvancedEscrowClient`, and the functions `anchorEvidence`, `availableBackends`, `streamTrafficEvents` and `getFacilitatorReceipt`, which take the same `stackKey` / `stackKeyHosts` options. It changes nothing else about a payment, and a facilitator that does not know the header ignores it.
+Services run by Ultravioleta DAO carry a per-service credential, the stack key, so that the facilitator's rate-limit policy does not answer them `429`. Everything in this SDK that calls the facilitator sends it as `X-UVD-Stack-Key`: the clients `FacilitatorClient` (and the two middlewares and `createFetchPaywall`), `Erc8004Client`, `BazaarClient`, `EscrowClient` and `AdvancedEscrowClient`, and the functions `anchorEvidence`, `availableBackends`, `streamTrafficEvents` and `getFacilitatorReceipt`, which take the same `stackKey` / `stackKeyHosts` options. It changes nothing else about a payment, and a facilitator that does not know the header ignores it.
 
 - **Where it comes from:** the facilitator's operator issues one per service: `uvdsk_` followed by 43-128 base64url characters. The process receives it as `UVD_STACK_KEY` (read by default) or as the `stackKey` option, from a secret store, never from code.
 - **Not for third parties:** if you integrate this SDK in your own product you have no key and need none. Leave both unset and no header is sent.
@@ -1248,7 +1311,7 @@ anti-double-settle guard, adopted here.
 
 ### Middleware
 
-`createPaymentMiddleware` and `createHonoMiddleware` answer **503 with a
+`createPaymentMiddleware`, `createHonoMiddleware` and `createFetchPaywall` answer **503 with a
 `Retry-After` header** — not `402`, not `500` — whenever the facilitator reached
 no verdict, and keep answering `402` for genuine rejections.
 
@@ -1260,7 +1323,7 @@ the buyer's client can reconcile instead of paying again.
 An X-PAYMENT the facilitator already admitted for another request is answered
 **`409`** (`authorization_already_settled`, `receipt_request_conflict`: it was
 used, the handler does not run) or **`503` + `Retry-After`** while it is
-`authorization_in_flight` — never `402` and never `500`. Both middlewares add
+`authorization_in_flight` — never `402` and never `500`. All three add
 `PAYMENT-RESPONSE` to an existing `Access-Control-Expose-Headers` and `no-store`
 to an existing `Cache-Control` instead of replacing them, and in `'manual'` mode
 a `settle()` after the handler already answered no longer touches the sent
@@ -1771,7 +1834,7 @@ bazaarExtension({
 });
 ```
 
-The result is `{ bazaar: { info, schema } }`: `info.input` (`type: "http"`, `method`, then `bodyType` and `body` for a body method, or `queryParams` for a query method, plus optional `headers`), `info.output` (`type`, default `json`, and `example`), and `schema`, the JSON Schema (draft 2020-12) that `info` validates against. `bodyType` is `json` (default), `form-data` or `text` (then `body` is a string). A body method without `body`, a query method with one, or a method the spec does not name (`CONNECT`, `OPTIONS`, ...) throws. `extensions` is a v2 field: `create402Response` throws if the response would be v1 rather than dropping it, and without `extensions` it returns exactly what it returned before.
+The result is `{ bazaar: { info, schema } }`: `info.input` (`type: "http"`, `method`, then `bodyType` and `body` for a body method, or `queryParams` for a query method, plus optional `headers`), `info.output` (`type`, default `json`, and `example`), and `schema`, the JSON Schema (draft 2020-12) that `info` validates against. `bodyType` is `json` (default), `form-data` or `text` (then `body` is a string). A body method without `body`, a query method with one, or a method the spec does not name (`CONNECT`, `OPTIONS`, ...) throws. `extensions` is a v2 field: `create402Response` throws if the response would be v1 rather than dropping it, and without `extensions` the body has no `extensions` key.
 
 ## x402 v2 requests (`buildVerifyRequestV2` / `buildSettleRequestV2`)
 
@@ -2103,8 +2166,8 @@ the authorization and reuse it after uncertainty. Payment confirmation does not
 prove merchant delivery. See [the receipt guide](docs/facilitator-receipts.md).
 
 Every `/verify` and `/settle` carries an `Idempotency-Key`, the same one for both
-calls of a payment and for their retries: `verifyAndSettle` and both middlewares
-create one per payment, and `verify`/`settle` accept `{ idempotencyKey }`
+calls of a payment and for their retries: `verifyAndSettle`, both middlewares and
+`createFetchPaywall` create one per payment, and `verify`/`settle` accept `{ idempotencyKey }`
 (`createIdempotencyKey()`). The facilitator returns an admitted payment's original
 answer (`SettleResponse.replayed`, from `Idempotent-Replayed: true`) only to that
 key or to the buyer's `X-UVD-Purchase`; a resend without them is

package/dist/adapters/index.d.mts

@@ -1,5 +1,5 @@
 import { X as X402Version, a as PaymentResult } from '../index-DagQ74ZQ.mjs';
-export { E as EnvKeyAdapter, O as OWSAccountInfo, a as OWSCore, b as OWSSignResult, c as OWSWallet, d as OWSWalletAdapter, e as OWSWalletAdapterOptions } from '../ows-9uNT7ZSZ.mjs';
+export { E as EnvKeyAdapter, O as OWSAccountInfo, a as OWSCore, b as OWSSignResult, c as OWSWallet, d as OWSWalletAdapter, e as OWSWalletAdapterOptions } from '../ows-DazT4KQH.mjs';
 import '../wallet-T0NFUUkT.mjs';
 import 'ethers';
 

package/dist/adapters/index.d.ts

@@ -1,5 +1,5 @@
 import { X as X402Version, a as PaymentResult } from '../index-DagQ74ZQ.js';
-export { E as EnvKeyAdapter, O as OWSAccountInfo, a as OWSCore, b as OWSSignResult, c as OWSWallet, d as OWSWalletAdapter, e as OWSWalletAdapterOptions } from '../ows-Tt33WE0s.js';
+export { E as EnvKeyAdapter, O as OWSAccountInfo, a as OWSCore, b as OWSSignResult, c as OWSWallet, d as OWSWalletAdapter, e as OWSWalletAdapterOptions } from '../ows-BB6Sgj0W.js';
 import '../wallet-T0NFUUkT.js';
 import 'ethers';
 

package/dist/adapters/index.js

@@ -103,10 +103,12 @@ var SUPPORTED_CHAINS = {
         name: "USD Coin",
         version: "2"
       },
+      // name() on-chain is "Euro Coin" here and "EURC" on Base: pinned to each
+      // contract's DOMAIN_SEPARATOR() by src/eurc-domains.test.ts.
       eurc: {
         address: "0xC891EB4cbdEFf6e073e859e987815Ed1505c2ACD",
         decimals: 6,
-        name: "EURC",
+        name: "Euro Coin",
         version: "2",
         usdPegged: false
       },
@@ -1443,6 +1445,110 @@ function useX402Wagmi(walletClient) {
     createPaymentFull
   };
 }
+var INTEGER_TYPE = /^u?int\d*$/;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function inexactNumberMessage(field, value) {
+  return `${field} is the JSON number ${String(value)}, larger in magnitude than Number.MAX_SAFE_INTEGER (2**53 - 1): JSON.parse has already rounded it, and signing it would sign a different integer than the one that was written. Send uints as decimal or 0x-hex strings (or a bigint)`;
+}
+function numberRefusal(path, value, code) {
+  return new X402Error(
+    Number.isInteger(value) ? inexactNumberMessage(path, value) : `${path} must be an integer, got the JSON number ${String(value)}`,
+    code
+  );
+}
+function findInexactNumber(value, path, seen = /* @__PURE__ */ new Set()) {
+  if (typeof value === "number") {
+    return Number.isSafeInteger(value) ? null : { path, value };
+  }
+  if (typeof value !== "object" || value === null || seen.has(value)) return null;
+  seen.add(value);
+  const entries = Array.isArray(value) ? value.map((item, i) => [`${path}[${i}]`, item]) : Object.entries(value).map(([key, item]) => [`${path}.${key}`, item]);
+  for (const [itemPath, item] of entries) {
+    const hit = findInexactNumber(item, itemPath, seen);
+    if (hit) return hit;
+  }
+  return null;
+}
+function assertNoInexactNumber(value, path, code = "INVALID_CONFIG") {
+  const hit = findInexactNumber(value, path);
+  if (hit) throw numberRefusal(hit.path, hit.value, code);
+}
+function rootStruct(structs, primaryType) {
+  try {
+    return ethers.ethers.TypedDataEncoder.from(
+      structs
+    ).primaryType;
+  } catch {
+    return typeof primaryType === "string" && Array.isArray(structs[primaryType]) ? primaryType : null;
+  }
+}
+function checkTyped(type, value, path, structs, code, ancestors = /* @__PURE__ */ new Set()) {
+  if (typeof value === "object" && value !== null) {
+    if (ancestors.has(value)) return;
+    ancestors.add(value);
+  }
+  try {
+    const array = /^(.*)\[(\d*)\]$/.exec(type);
+    if (array) {
+      if (Array.isArray(value)) {
+        value.forEach(
+          (item, i) => checkTyped(array[1], item, `${path}[${i}]`, structs, code, ancestors)
+        );
+      }
+      return;
+    }
+    const struct = structs[type];
+    if (Array.isArray(struct)) {
+      if (!isRecord(value)) return;
+      for (const field of struct) {
+        if (typeof field?.name === "string" && typeof field.type === "string") {
+          checkTyped(
+            field.type,
+            value[field.name],
+            `${path}.${field.name}`,
+            structs,
+            code,
+            ancestors
+          );
+        }
+      }
+      return;
+    }
+    if (INTEGER_TYPE.test(type) && typeof value === "number" && !Number.isSafeInteger(value)) {
+      throw numberRefusal(path, value, code);
+    }
+  } finally {
+    if (typeof value === "object" && value !== null) ancestors.delete(value);
+  }
+}
+function assertTypedDataIntegersExact(doc, where = "typed data", code = "INVALID_CONFIG") {
+  if (!isRecord(doc)) return;
+  const { domain, types, message, primaryType } = doc;
+  if (isRecord(domain) && typeof domain.chainId === "number" && !Number.isSafeInteger(domain.chainId)) {
+    throw numberRefusal(`${where} domain.chainId`, domain.chainId, code);
+  }
+  if (!isRecord(message)) return;
+  const structs = isRecord(types) ? { ...types } : {};
+  delete structs["EIP712Domain"];
+  const root = rootStruct(structs, primaryType);
+  if (root) {
+    checkTyped(root, message, `${where} message`, structs, code);
+    if (typeof primaryType === "string" && primaryType !== root && Array.isArray(structs[primaryType])) {
+      checkTyped(primaryType, message, `${where} message`, structs, code);
+    }
+    return;
+  }
+  assertNoInexactNumber(message, `${where} message`, code);
+}
+function parseTypedDataJson(text, where = "typed data", code = "INVALID_CONFIG") {
+  const doc = JSON.parse(text);
+  assertTypedDataIntegersExact(doc, where, code);
+  return doc;
+}
+
+// src/adapters/env-key.ts
 var EnvKeyAdapter = class {
   wallet;
   /**
@@ -1482,9 +1588,12 @@ var EnvKeyAdapter = class {
    *
    * @param typedData - JSON string with `domain`, `types`, `primaryType`, and `message` fields
    * @returns Object with signature and v/r/s components
+   * @throws {X402Error} `INVALID_CONFIG` when an integer field of `message`
+   *   (or `domain.chainId`) is a JSON number above 2**53 - 1: `JSON.parse`
+   *   rounded it, so it is refused instead of signed. Write uints as strings.
    */
   async signTypedData(typedData) {
-    const parsed = JSON.parse(typedData);
+    const parsed = parseTypedDataJson(typedData);
     const { domain, types, message } = parsed;
     const cleanTypes = { ...types };
     delete cleanTypes["EIP712Domain"];
@@ -1618,7 +1727,7 @@ var ETHERS_NAME_OF = { input: "data", gas: "gasLimit" };
 var TWO_127 = 1n << 127n;
 var TWO_128 = 1n << 128n;
 var TWO_256 = 1n << 256n;
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function shown(value) {
@@ -1635,6 +1744,7 @@ function refuse(message) {
 function toInteger(value, where) {
   if (typeof value === "bigint") return value;
   if (typeof value === "number" && Number.isSafeInteger(value)) return BigInt(value);
+  if (typeof value === "number" && Number.isInteger(value)) throw refuse(inexactNumberMessage(where, value));
   if (typeof value === "string" && /^-?(0[xX][0-9a-fA-F]+|[0-9]+)$/.test(value)) {
     return value.startsWith("-") ? -BigInt(value.slice(1)) : BigInt(value);
   }
@@ -1662,7 +1772,7 @@ function owsValue(kind, value, types, where) {
   }
   const struct = types[kind];
   if (struct) {
-    if (!isRecord(value)) throw refuse(`${where}: ${kind} needs an object, got ${shown(value)}`);
+    if (!isRecord2(value)) throw refuse(`${where}: ${kind} needs an object, got ${shown(value)}`);
     const out = {};
     for (const field of struct) {
       if (value[field.name] === void 0) throw refuse(`${where}: ${kind} lacks ${field.name}`);
@@ -1716,11 +1826,11 @@ function owsValue(kind, value, types, where) {
   throw refuse(`${where}: unsupported EIP-712 type ${kind}`);
 }
 function prepareTypedData(input) {
-  if (!isRecord(input)) throw refuse("typed data must be an object with domain, types and message");
+  if (!isRecord2(input)) throw refuse("typed data must be an object with domain, types and message");
   const { domain, types, message, primaryType } = input;
-  if (!isRecord(domain)) throw refuse("typed data needs a domain object");
-  if (!isRecord(types)) throw refuse("typed data needs a types object");
-  if (!isRecord(message)) throw refuse("typed data needs a message object");
+  if (!isRecord2(domain)) throw refuse("typed data needs a domain object");
+  if (!isRecord2(types)) throw refuse("typed data needs a types object");
+  if (!isRecord2(message)) throw refuse("typed data needs a message object");
   const structs = { ...types };
   delete structs["EIP712Domain"];
   let root;
@@ -1798,7 +1908,7 @@ var OWSWalletAdapter = class {
   #chain;
   #address;
   constructor(ows, options) {
-    if (isRecord(ows) && "accounts" in ows && (options === void 0 || typeof options === "number")) {
+    if (isRecord2(ows) && "accounts" in ows && (options === void 0 || typeof options === "number")) {
       throw new X402Error(
         `OWSWalletAdapter no longer takes a wallet object with accounts (the deprecated OWSWallet shape, which never worked with @open-wallet-standard/core 1.x); ${MIGRATION}. Nothing was signed.`,
         "INVALID_CONFIG"
@@ -1813,7 +1923,7 @@ var OWSWalletAdapter = class {
         "INVALID_CONFIG"
       );
     }
-    const opts = isRecord(options) ? options : {};
+    const opts = isRecord2(options) ? options : {};
     if (typeof opts.wallet !== "string" || opts.wallet === "") {
       throw new X402Error("OWSWalletAdapter needs options.wallet: the name or id of a wallet in the vault", "INVALID_CONFIG");
     }