uvd-x402-sdk 2.104.1 → 2.104.3

package/README.md

@@ -684,7 +684,7 @@ const paymentAuth = await buildEscrowPreAuth(new EnvKeyAdapter(), {
 // Send as the X-Payment-Auth header (raw JSON, NOT base64).
 ```
 
-Any `SigningWalletAdapter` works as the signer (only `signTypedData` is used); browser wallets can pass a minimal `{ signTypedData }` wrapper. Validation fails loud instead of falling back: incomplete network config, unknown tier, bounty outside the on-chain deposit limit ($100), or a `maxFeeBps` below the operator's 1300 bps all throw before anything is signed. What the config asserts is also checked against the SDK's own tables before signing, as in the Python SDK: the `chain_id` against the `network` you name (a registry name or `eip155:<id>`), the escrow, token collector and USDC against `ESCROW_CONTRACTS`, the operator against `ESCROW_OPERATORS`, and `maxFeeBps` against the chain's ceiling in `ESCROW_MAX_FEE_BPS`. A contradiction throws `INVALID_CONFIG`, and so do a `network` the SDK does not register and a chain without a row in each of the three tables, with or without `network`; name the network you expect to pay on, from your own code, never one read from the config. A server-published tier window must be an integer from 0 to its `ESCROW_TIER_WINDOW_MAX`, and `authorizationExpiry` at most `ESCROW_MAX_AUTHORIZATION_SEC` after now: past either, the SDK refuses, it never clamps. `computeEscrowNonce` is exported to reproduce `AuthCaptureEscrow.getHash` externally.
+Any `SigningWalletAdapter` works as the signer (only `signTypedData` is used); browser wallets can pass a minimal `{ signTypedData }` wrapper. Validation fails loud instead of falling back: incomplete network config, unknown tier, bounty outside the on-chain deposit limit ($100), or a `maxFeeBps` below the operator's 1300 bps all throw before anything is signed. What the config asserts is also checked against the SDK's own tables before signing, as in the Python SDK: the `chain_id` against the `network` you name (a registry name or `eip155:<id>`), the escrow, token collector and USDC against `ESCROW_CONTRACTS`, the operator against `ESCROW_OPERATORS`, `maxFeeBps` against the chain's ceiling in `ESCROW_MAX_FEE_BPS`, and the USDC EIP-712 domain (`usdc_domain_name` / `usdc_domain_version`) against the token's on-chain domain in `VERIFIED_USDC_DOMAINS`. A contradiction throws `INVALID_CONFIG`, and so do a `network` the SDK does not register and a chain without a row in each of the four tables, with or without `network`; name the network you expect to pay on, from your own code, never one read from the config. A server-published tier window must be an integer from 0 to its `ESCROW_TIER_WINDOW_MAX`, and `authorizationExpiry` at most `ESCROW_MAX_AUTHORIZATION_SEC` after now: past either, the SDK refuses, it never clamps. `computeEscrowNonce` is exported to reproduce `AuthCaptureEscrow.getHash` externally.
 
 ## Multi-Stablecoin (EVM)
 
@@ -889,6 +889,8 @@ app.post('/api/premium', async (req, res) => {
 });
 ```
 
+To be listed in the facilitator's Bazaar after a paid call, flag the accepts as discoverable: `discoverable: true` in the options of `createHonoMiddleware()` or `createFetchPaywall()` writes `extra.discoverable: true` on every accept, in the 402 and in the requirements sent to `/verify` and `/settle`; the other `extra` fields (`name`, `version`) stay. `false` writes `discoverable: false`, overriding a hand-written `true`, as the Python SDK's `False` does (for the facilitator, `false` and no flag both mean "not listed"); without the option the accepts go out as given. Native Hedera accepts go out as given with either value: the facilitator allows only `feePayer` in their `extra`, so a Hedera settle is never listed. For one accept, or for `create402Response`, use `withDiscoverable(accept)` (`withDiscoverable(accept, false)` to opt out); it throws for a native Hedera accept. Neither modifies the object it is given. A `discoverable` that is not a boolean and an `extra` that is not a plain object throw when the paywall is built, before any 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).
@@ -2050,6 +2052,91 @@ const result = await anchorEvidence(body, {
 res.setHeader('X-Durable-Evidence', evidenceHeader(result));
 ```
 
+### Seller: from the paywall itself (`durable`)
+
+`createFetchPaywall`, `createHonoMiddleware` and `createPaymentMiddleware`
+(Express) take an opt-in `durable`. With it, a paid `2xx` answer that the
+handler did not anchor itself is captured once, sealed and anchored through
+`anchorEvidence`, and goes out with `X-Durable-Evidence`:
+
+```ts
+import { TypedDataEncoder, getBytes } from 'ethers';
+import { createFetchPaywall, type DurableEvidenceContext } from 'uvd-x402-sdk/backend';
+import { caip2ToChain, getChainByName, payerKeyFromEvmSignature } from 'uvd-x402-sdk';
+
+const TRANSFER_WITH_AUTHORIZATION = {
+  TransferWithAuthorization: [
+    { name: 'from', type: 'address' }, { name: 'to', type: 'address' },
+    { name: 'value', type: 'uint256' }, { name: 'validAfter', type: 'uint256' },
+    { name: 'validBefore', type: 'uint256' }, { name: 'nonce', type: 'bytes32' },
+  ],
+};
+
+// The key behind an EIP-3009 USDC payment: recovered from the signature over the
+// digest the buyer signed, with the token domain of the chain registry.
+const evmPayerKey = ({ payment }: DurableEvidenceContext) => {
+  const payload = payment.payment.payload;
+  if (!('authorization' in payload)) return undefined; // not an EVM payment: skipped
+  const network = payment.requirements.network;
+  const chain = getChainByName(caip2ToChain(network) ?? network);
+  if (!chain) return undefined;
+  const digest = TypedDataEncoder.hash(
+    { name: chain.usdc.name, version: chain.usdc.version, chainId: chain.chainId, verifyingContract: payment.requirements.asset },
+    TRANSFER_WITH_AUTHORIZATION,
+    payload.authorization,
+  );
+  return payerKeyFromEvmSignature(payload.signature, getBytes(digest));
+};
+
+const paywall = createFetchPaywall({
+  accepts,
+  durable: {
+    payerKey: evmPayerKey,   // Solana: ({ payment }) => payerKeyFromSolanaAddress(payment.verifyResult.payer!)
+    maxBodyBytes: 64 * 1024, // default ANCHOR_MAX_REQUEST_BYTES
+    timeoutMs: 5000,         // default DURABLE_DEFAULT_TIMEOUT_MS
+  },
+});
+```
+
+A wrong digest does not throw: it recovers another valid key, and the evidence
+would be sealed to it. `src/backend/durable-evidence.test.ts` checks this
+derivation against a signature made with a synthetic key.
+
+Without `durable` nothing changes and nothing is anchored. It anchors only a
+payment this request settled with a transaction hash (`'manual'`: once
+`x402.settle()` resolved successfully before the answer); a replayed settle, or
+one whose receipt is `pending`, `unknown` or `rejected`, is not anchored. The body is read once
+and held at most `maxBodyBytes`; past that, past `timeoutMs`, for an event
+stream, for a body already locked or read, or when the handler's own stream
+fails, the response goes out whole and unchanged except for a skip notice in
+the header, and nothing is anchored. A failed anchor is a skip notice too: the
+response and the payment stand. A `HEAD`, a non-`2xx` answer and a response that
+already has `X-Durable-Evidence` are left alone. Every field of `durable` but
+`payerKey`, `maxBodyBytes` and `timeoutMs` is the `anchorEvidence` option of the
+same name; `facilitator` defaults to the paywall's facilitator.
+
+The skip notices the paywall adds, besides those of `anchorEvidence`:
+
+| `skipped` | When |
+|---|---|
+| `no_payer_key` | `payerKey` returned `undefined` or an empty key, or threw |
+| `too_large` | the body is over `maxBodyBytes` (declared or read) |
+| `not_capturable` | an event stream, a body already sent, a chunk that is not bytes, or a handler stream that failed |
+| `timeout` | capture, `payerKey`, upload or anchor did not finish within `timeoutMs` |
+| `anchor_failed` | the anchor failed |
+
+In Express, the answer is held from the handler's `end()` until the anchor
+returns (at most `timeoutMs`). In that window `res.headersSent` and
+`res.writableEnded` are `true`, a further `write()` is refused as a write after
+end, a further `end()` only queues its callback, and headers can no longer be
+set: the paid answer goes out as the handler ended it. A close the server asks
+for in that window without an error (`res.destroy()` or `req.socket.destroy()`,
+which is what Express's final handler does on an error once headers are sent)
+waits until the body is written and then closes the connection. A close with an
+error, or one once the connection can no longer write, is not held. A client
+that hangs up its side during the window does not get the body: the window
+lengthens (up to `timeoutMs`) the time in which that happens.
+
 **It never throws.** Every failure resolves to `result.skipped`, because
 evidence is an addition to the payment path and must never be a gate in front of
 it. An unreachable facilitator costs the receipt, never the sale.

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-DazT4KQH.mjs';
+import { X as X402Version, a as PaymentResult } from '../index-DARXHuQl.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-DJu424iz.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-BB6Sgj0W.js';
+import { X as X402Version, a as PaymentResult } from '../index-DARXHuQl.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-CW-g7qGw.js';
 import '../wallet-T0NFUUkT.js';
 import 'ethers';
 

package/dist/adapters/index.js

@@ -1545,8 +1545,124 @@ function assertTypedDataIntegersExact(doc, where = "typed data", code = "INVALID
   }
   assertNoInexactNumber(message, `${where} message`, code);
 }
+var MIN_EXACT_DIGITS = 22;
+var MAX_EXACT_DIGITS = 78;
+var MAX_DOUBLE_DIGITS = 17;
+function doubleShaped(literal) {
+  const significant = literal.replace(/^-/, "").replace(/0+$/, "");
+  return significant.length <= MAX_DOUBLE_DIGITS || BigInt(literal) === BigInt(Number(literal));
+}
+var JSON_NUMBER = /-?(?:0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?/y;
+var JSON_SPACE = /[ \t\n\r]*/y;
+function dataDescriptor(value) {
+  const descriptor = /* @__PURE__ */ Object.create(null);
+  descriptor.value = value;
+  descriptor.writable = true;
+  descriptor.enumerable = true;
+  descriptor.configurable = true;
+  return descriptor;
+}
+function parseJsonExact(input) {
+  const text = String(input);
+  let pos = 0;
+  let wide = false;
+  const fail = (what) => {
+    throw new SyntaxError(`${what} in JSON at position ${pos}`);
+  };
+  const space = () => {
+    JSON_SPACE.lastIndex = pos;
+    if (JSON_SPACE.exec(text)) pos = JSON_SPACE.lastIndex;
+  };
+  const string = () => {
+    if (text[pos] !== '"') fail("Expected a string");
+    let end = pos + 1;
+    while (end < text.length && text[end] !== '"') end += text[end] === "\\" ? 2 : 1;
+    if (end >= text.length) fail("Unterminated string");
+    const value = JSON.parse(text.slice(pos, end + 1));
+    pos = end + 1;
+    return value;
+  };
+  const key = () => {
+    const name = string();
+    space();
+    if (text[pos] !== ":") fail("Expected ':'");
+    pos += 1;
+    space();
+    return name;
+  };
+  const scalar = () => {
+    if (text[pos] === '"') return string();
+    for (const [word, value] of [["true", true], ["false", false], ["null", null]]) {
+      if (text.startsWith(word, pos)) {
+        pos += word.length;
+        return value;
+      }
+    }
+    JSON_NUMBER.lastIndex = pos;
+    const match = JSON_NUMBER.exec(text);
+    if (!match) return fail("Unexpected token");
+    pos = JSON_NUMBER.lastIndex;
+    const literal = match[0];
+    const digits = literal.length - (literal.startsWith("-") ? 1 : 0);
+    if (match[1] === void 0 && match[2] === void 0 && digits >= MIN_EXACT_DIGITS && digits <= MAX_EXACT_DIGITS && !doubleShaped(literal)) {
+      wide = true;
+      return BigInt(literal);
+    }
+    return Number(literal);
+  };
+  const stack = [];
+  space();
+  for (; ; ) {
+    let value;
+    if (text[pos] === "[") {
+      pos += 1;
+      space();
+      if (text[pos] !== "]") {
+        stack.push({ kind: "array", items: [] });
+        continue;
+      }
+      pos += 1;
+      value = [];
+    } else if (text[pos] === "{") {
+      pos += 1;
+      space();
+      if (text[pos] !== "}") {
+        stack.push({ kind: "object", object: {}, key: key() });
+        continue;
+      }
+      pos += 1;
+      value = {};
+    } else {
+      value = scalar();
+    }
+    for (; ; ) {
+      space();
+      const top = stack[stack.length - 1];
+      if (top === void 0) {
+        if (pos !== text.length) fail("Unexpected non-whitespace character after JSON");
+        return wide ? value : JSON.parse(text);
+      }
+      const close = top.kind === "array" ? "]" : "}";
+      if (top.kind === "array") {
+        top.items.push(value);
+      } else {
+        Object.defineProperty(top.object, top.key, dataDescriptor(value));
+      }
+      if (text[pos] === ",") {
+        pos += 1;
+        space();
+        if (top.kind === "object") top.key = key();
+        break;
+      }
+      if (text[pos] !== close) fail(`Expected ',' or '${close}'`);
+      pos += 1;
+      stack.pop();
+      value = top.kind === "array" ? top.items : top.object;
+    }
+  }
+}
 function parseTypedDataJson(text, where = "typed data", code = "INVALID_CONFIG") {
-  const doc = JSON.parse(text);
+  const doc = parseJsonExact(text);
   assertTypedDataIntegersExact(doc, where, code);
   return doc;
 }
@@ -1589,11 +1705,18 @@ var EnvKeyAdapter = class {
   /**
    * Sign EIP-712 typed structured data.
    *
+   * An integer of 22 to 78 digits written as a JSON number (a 32-byte salt)
+   * is read with every digit, as Python's `json` reads it, not rounded the
+   * way `JSON.parse` rounds it.
+   *
    * @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.
+   *   (or `domain.chainId`) is a JSON number above 2**53 - 1 of up to 21
+   *   digits (a JavaScript hop may have rounded it and written it back in
+   *   digits) or written with an exponent or a fraction (`7.76e+76`): it is
+   *   refused instead of signed. Write uints as strings. An integer out of
+   *   its field's range is refused by ethers (`value out-of-bounds`).
    */
   async signTypedData(typedData) {
     const parsed = parseTypedDataJson(typedData);
@@ -1856,7 +1979,14 @@ function prepareTypedData(input) {
     EIP712Domain: EIP712_DOMAIN_FIELDS.filter(([name]) => domain[name] != null).map(
       ([name, type]) => ({ name, type })
     ),
-    ...structs
+    // Each field as ethers hashes it, name and type: any other key (a wide
+    // number in it is a bigint) never reaches OWS or JSON.stringify.
+    ...Object.fromEntries(
+      Object.entries(structs).map(([struct, fields]) => [
+        struct,
+        fields.map(({ name, type }) => ({ name, type }))
+      ])
+    )
   };
   const owsDomain = owsValue("EIP712Domain", domain, all, "domain");
   const owsMessage = owsValue(root, message, all, "message");
@@ -1988,7 +2118,7 @@ var OWSWalletAdapter = class {
   async signTypedData(typedData) {
     let parsed;
     try {
-      parsed = JSON.parse(typedData);
+      parsed = parseJsonExact(typedData);
     } catch {
       throw refuse("typedData is not a JSON string");
     }