openpay-x402-sdk 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.5.0
+
+- Reserve session and daily capacity immediately before exposing a signed
+  authorization. Non-2xx responses, timeouts, and connection failures retain
+  the reservation; successful 2xx responses keep the existing confirmed-spend
+  accounting.
+- Make the file daily store cross-process atomic with an exclusive lock, reject
+  UTC-crossing authorizations, and fail closed when a configured store is
+  unavailable.
+- Enforce host/catalog admission before target I/O, block private and rebinding
+  destinations, require exact catalog URLs, stop redirects, and bound buyer
+  requests with a timeout.
+- Bind supported networks to the canonical JPYC v3 contract/domain, cap
+  seller-declared authorization lifetimes, bind signature destinations to a
+  known or catalog-reviewed forwarder, and locally reserve seller-gate
+  authorizations across verify and settle without requiring facilitator tokens.
+- Verify facilitator-signed payment receipts against the advertised signer and
+  bind every money field and authorization nonce before returning them.
+
 ## 0.4.0
 
 - Add an opt-in persistent daily buyer limit with UTC signer/date keys, file and

package/README.md

@@ -3,6 +3,11 @@
 Node.js 20+ SDK for discovering, quoting, and buying OpenPay x402 resources priced
 in JPYC. It ships as plain ESM and has no build step.
 
+Wire compatibility: x402 v1 transport (JSON 402 body with `x402Version: 1`, plus the
+`X-PAYMENT` / `X-PAYMENT-RESPONSE` headers) with the OpenPay `extra.openpay`
+forwarder-split extension. OpenPay's first-party resources also accept the v2 header
+transport; this SDK speaks v1.
+
 ## Quick start
 
 ```bash
@@ -17,6 +22,7 @@ const client = createOpenPayClient({
   maxPerCallJpyc: '10',
   maxSessionJpyc: '100',
   maxDailyJpyc: '250',
+  maxTimeoutSeconds: 600,
   allowedHosts: 'open-pay.jp',
 });
 
@@ -35,6 +41,12 @@ concurrent calls so every call sees the latest session total.
 
 ## Sell with the SDK
 
+**An AI model is never the security boundary for payment state.** Do not unlock on any
+model- or tool-produced claim of payment — a "paid" string, a success message, or a
+transaction id appearing in text. The gate unlocks only on the facilitator's `verify` and
+`settle` responses, which are backed by on-chain settlement; replayed or already-used
+authorizations are refused at that layer.
+
 Create a gate with the exact resource URL registered in OpenPay discovery. For
 inexpensive content, `handle()` verifies and settles the payment in one call:
 
@@ -43,6 +55,7 @@ import { createJpycGate } from 'openpay-x402-sdk';
 
 const gate = createJpycGate({
   resourceUrl: process.env.MY_RESOURCE_URL,
+  maxUpstreamSeconds: 60,
 });
 
 export async function GET(request) {
@@ -91,6 +104,20 @@ minutes. Until `resourceUrl` is listed with a non-empty `accepts`, `handle()` an
 `verify()` throw; map that bootstrap condition to an HTTP 500 response. Pass
 `openpayOrigin` to use an origin other than `https://open-pay.jp`.
 
+Before `verify()` contacts the facilitator, each gate instance claims a canonical
+authorization identity until its `validBefore` time. Set `maxUpstreamSeconds`
+(default `60`) to the seller's worst-case upstream duration; the gate also
+retains `settlementGraceSeconds` (default `30`) and rejects a duplicate before
+upstream work begins. A failed facilitator verification releases the tentative
+claim, while a successful verification keeps it through settlement so an
+unknown settlement result cannot expose the same authorization twice.
+
+The facilitator reservation is an optional additional defense. The gate forwards
+its token when one is returned and continues on the established token-less wire
+when it is not. The local claim covers concurrent requests sharing one gate
+instance; separate processes or serverless isolates do not share its in-memory
+ledger.
+
 The copy-paste paywall snippet generated by OpenPay provides the same one-shot
 gate; `createJpycGate` is its importable SDK counterpart with split settlement.
 
@@ -99,37 +126,61 @@ gate; `createJpycGate` is its importable SDK counterpart with split settlement.
 | Option | Default | Guard |
 |---|---:|---|
 | `maxPerCallJpyc` | `10` | Upper bound for the caller-provided `maxTotalJpyc`. |
-| `maxSessionJpyc` | `100` | Cumulative cap for successful payments made by this client instance. |
+| `maxSessionJpyc` | `100` | Cumulative cap for successful payments plus authorizations exposed to a seller. |
 | `maxDailyJpyc` | Not set | Persistent cumulative cap per signer and UTC calendar date. |
+| `maxTimeoutSeconds` | `600` | Reject seller-declared authorization lifetimes above this many seconds (maximum configurable value: `1200`). |
 | `allowedHosts` | `open-pay.jp` | Comma-separated bare host allowlist. |
-| `catalogTrust` | `true` | Also allows catalog URLs after the live challenge matches the catalog challenge. |
+| `catalogTrust` | `true` | Also allows exact catalog URLs after the live challenge matches the catalog challenge. |
 | `discoveryUrl` | `https://open-pay.jp/api/discovery` | Catalog and OpenPay origin used by the client. |
 
-Query string variants of a query-free listed URL are trusted after the same
-money-field verification. Exact query-bearing catalog entries remain exact-only.
+Catalog admission is exact URL only, including the query string. A query
+variant must have its own reviewed listing or an explicitly allowlisted host.
 
 `pay(url, { maxTotalJpyc })` always requires `maxTotalJpyc`. It is the maximum
 total—including the resource price and x402 fee—that this individual call is
 authorized to pay. It does not disable or raise `maxPerCallJpyc` or
 `maxSessionJpyc`; every configured limit must allow the payment.
 
-`maxDailyJpyc` is opt-in. When set, the client stores successful 2xx unlocks in
-`~/.openpay-x402/spend.json`, keyed by the lower-cased signer address and UTC
-date. A missing entry starts at zero. A corrupt/unreadable store or a custom
-store returning `null` rejects quotes and payments with `daily_spend_unavailable`
-(fail-closed). Use `spendStore` to inject another implementation of
-`{ load(key), save(key, atomicString) }`; `MAX_DAILY_JPYC` is the equivalent
-optional setting for the exported environment config readers.
-
-The file store uses best-effort read-modify-write across processes: payments are
-serialized within one client process, but separate processes can race and lose
-an increment. Use an atomic shared store when multiple processes share a signer.
-Persistence runs only after a successful unlock; a save failure cannot change an
-already completed payment response.
+`maxDailyJpyc` is opt-in. When set, the client atomically reserves the amount in
+`~/.openpay-x402/spend.json` immediately before sending a signed authorization,
+keyed by the lower-cased signer address and UTC date. A non-2xx response,
+connection loss, or timeout does not release that reservation: the seller may
+already have settled it. Authorizations that could remain valid across UTC
+midnight are refused instead of being charged to the wrong day.
+
+A missing entry starts at zero. A corrupt/unreadable store, a failed reservation,
+or a custom store returning `null` rejects payments with
+`daily_spend_unavailable` (fail-closed). The built-in file store uses an
+exclusive lock plus atomic replacement, so separate processes sharing a signer
+cannot both reserve the same remaining daily capacity. Custom stores can add an
+atomic `reserve(key, amount, limit, reservation)` method; legacy
+`{ load, save }` stores remain accepted with a verified pre-send write.
+`MAX_DAILY_JPYC` is the equivalent optional setting for the exported environment
+config readers.
+
+An abrupt process or machine stop can leave `spend.json.lock`; reservations then
+fail closed instead of paying without a limit. Stop every process that uses the
+same store before inspecting and manually removing a stale lock. Never remove
+the lock while another process may still own it.
 
 The client also rejects non-JPYC metadata, unsupported networks or schemes,
-non-OpenPay forwarder splits, amount inconsistencies, resource URL mismatches,
-and catalog bait-and-switches before requesting a signature.
+non-canonical JPYC contracts or EIP-712 domains, seller timeouts above
+`maxTimeoutSeconds`, unreviewed forwarder destinations, non-OpenPay forwarder
+splits, amount inconsistencies,
+resource URL mismatches, and catalog bait-and-switches before requesting a
+signature. `MAX_TIMEOUT_SECONDS` is the equivalent setting for the exported
+environment config readers. Target host/catalog admission and private-address
+checks run before buyer target requests. Those requests require HTTPS, do not
+follow redirects, and have a 15-second timeout. The default Node transport also
+validates DNS before and during connection to block rebinding; an explicitly
+injected custom `fetchImpl` is a trusted transport boundary and is responsible
+for equivalent connect-time enforcement.
+
+`pay()` returns a non-null `receipt` only when the facilitator signer advertised
+by `/api/facilitator/supported` signed it and the transaction, payer, network,
+asset, merchant amount, fee, chain, and authorization nonce all match this
+payment. A missing, malformed, forged, or mismatched seller response header
+becomes `receipt: null` without discarding the unlocked response body.
 
 ## Signers
 

package/index.d.ts

@@ -44,10 +44,43 @@ export interface SpendStore {
    * so an absent entry must be reported as `'0'`, never `null`.
    */
   load(key: string): Promise<string | null>;
+  /**
+   * Atomically check the limit and reserve an authorization before it is sent.
+   * Custom legacy stores may omit this method; new cross-process stores should
+   * implement it to avoid lost updates.
+   */
+  reserve?(
+    key: string,
+    amountAtomic: string,
+    limitAtomic: string,
+    reservation: SpendReservation,
+  ): Promise<SpendReservationResult>;
+  /** Mark reservation metadata confirmed without reducing the reserved total. */
+  confirm?(id: string): Promise<boolean>;
   /** Persist the new cumulative atomic amount. Failures must not throw. */
   save(key: string, atomicString: string): Promise<void>;
 }
 
+export interface SpendReservation {
+  id: string;
+  payer: Address;
+  network: string;
+  asset: Address;
+  validBefore: string;
+}
+
+export type SpendReservationResult =
+  | { ok: true; totalAtomic: string }
+  | {
+      ok: false;
+      reason: 'limit_exceeded' | 'unavailable';
+      totalAtomic?: string;
+    };
+
+export type PaymentLookup = (
+  hostname: string,
+) => Promise<Array<{ address: string; family?: number }>>;
+
 export interface FileSpendStoreOptions {
   path?: string;
   fsImpl?: {
@@ -58,6 +91,12 @@ export interface FileSpendStoreOptions {
       data: string,
       encoding: 'utf8',
     ): Promise<unknown>;
+    open?(
+      path: string,
+      flags: 'wx',
+    ): Promise<{ close(): Promise<unknown> }>;
+    rename?(from: string, to: string): Promise<unknown>;
+    unlink?(path: string): Promise<unknown>;
   };
 }
 
@@ -65,11 +104,14 @@ interface ClientCommonOptions {
   maxPerCallJpyc?: JpycAmount;
   maxSessionJpyc?: JpycAmount;
   maxDailyJpyc?: JpycAmount;
+  maxTimeoutSeconds?: number;
   spendStore?: SpendStore;
   allowedHosts?: string;
   catalogTrust?: boolean;
   discoveryUrl?: string;
   fetchImpl?: typeof globalThis.fetch;
+  lookup?: PaymentLookup;
+  requestTimeoutMs?: number;
   nowSec?: () => number;
   now?: () => Date | number;
 }
@@ -114,6 +156,11 @@ export interface RuntimeConfig {
   maxPerCallAtomic: bigint;
   maxSessionAtomic: bigint;
   maxDailyAtomic: bigint | null;
+  /**
+   * Maximum seller-declared authorization lifetime. Optional here so existing
+   * consumers that construct RuntimeConfig manually remain source-compatible.
+   */
+  maxTimeoutSeconds?: number;
   allowedHosts: string[];
   catalogTrust: boolean;
   discoveryUrl: string;
@@ -228,6 +275,10 @@ export interface JpycGateOptions {
   openpayOrigin?: string;
   fetchImpl?: typeof globalThis.fetch;
   now?: () => number;
+  /** Worst-case seller upstream duration protected by the local claim. Default: 60. */
+  maxUpstreamSeconds?: number;
+  /** Extra validity retained for settlement after upstream work. Default: 30. */
+  settlementGraceSeconds?: number;
 }
 
 export interface JpycGatePaymentResponse {
@@ -248,6 +299,7 @@ export function createJpycGate(options: JpycGateOptions): JpycGate;
 export const RECEIVE_WITH_AUTHORIZATION_TYPES: {
   ReceiveWithAuthorization: Array<{ name: string; type: string }>;
 };
+export const MAX_AUTHORIZATION_TIMEOUT_SECONDS: 1200;
 
 export interface NormalizedPaymentRequirements {
   scheme: 'exact';
@@ -331,6 +383,8 @@ export function paymentPayloadFor(
 export const JPYC_DECIMALS: 18;
 export const DEFAULT_MAX_PER_CALL_JPYC: '10';
 export const DEFAULT_MAX_SESSION_JPYC: '100';
+export const DEFAULT_MAX_TIMEOUT_SECONDS: 600;
+export const MAX_SUPPORTED_TIMEOUT_SECONDS: 1200;
 export const DEFAULT_ALLOWED_HOSTS: 'open-pay.jp';
 export const DEFAULT_CATALOG_TRUST: true;
 export const DEFAULT_DISCOVERY_URL: 'https://open-pay.jp/api/discovery';
@@ -340,8 +394,10 @@ export const REASONS: {
   unsupportedScheme: 'unsupported_scheme';
   unsupportedNetwork: 'unsupported_network';
   invalidOpenpayMode: 'invalid_openpay_mode';
+  invalidOpenpayForwarder: 'invalid_openpay_forwarder';
   amountMismatch: 'amount_mismatch';
   invalidJpycAsset: 'invalid_jpyc_asset';
+  timeoutTooLong: 'timeout_too_long';
   resourceMismatch: 'resource_mismatch';
   invalidAccept: 'invalid_accept';
   maxTotalRequired: 'max_total_required';
@@ -352,12 +408,62 @@ export const REASONS: {
   sessionLimitExceeded: 'session_limit_exceeded';
   dailyLimitExceeded: 'daily_limit_exceeded';
   dailySpendUnavailable: 'daily_spend_unavailable';
+  dailyAuthorizationCrossesUtcDay: 'daily_authorization_crosses_utc_day';
   buyerPrivateKeyMissing: 'buyer_private_key_missing';
   stewardSignerUnconfigured: 'steward_signer_unconfigured';
   catalogAcceptMismatch: 'catalog_accept_mismatch';
 };
+export const SUPPORTED_JPYC_ASSETS: Readonly<
+  Record<
+    string,
+    Readonly<{
+      address: Address;
+      name: 'JPY Coin';
+      version: '1';
+      decimals: 18;
+    }>
+  >
+>;
+export const SUPPORTED_JPYC_FORWARDERS: Readonly<
+  Partial<Record<string, Address>>
+>;
 export const SUPPORTED_NETWORKS: Set<string>;
 
+export const DEFAULT_PAYMENT_FETCH_TIMEOUT_MS: 15000;
+export function isPrivatePaymentHost(hostname: string): boolean;
+export function parseSafePaymentUrl(raw: unknown): URL | null;
+export function fetchPaymentTarget(
+  url: string,
+  options?: {
+    fetchImpl?: typeof globalThis.fetch;
+    headers?: HeadersInit;
+    lookup?: PaymentLookup;
+    timeoutMs?: number;
+  },
+): Promise<Response>;
+
+export type ReceiptSignerResolver = () => Promise<Address | null>;
+export function createReceiptSignerResolver(options: {
+  discoveryUrl: string;
+  fetchImpl?: typeof globalThis.fetch;
+  lookup?: PaymentLookup;
+  requestTimeoutMs?: number;
+}): ReceiptSignerResolver;
+export function verifyBoundPaymentResponse(
+  paymentResponse: unknown,
+  expected: {
+    expectedSigner: Address;
+    payer: Address;
+    network: string;
+    asset: Address;
+    chainId: number;
+    merchant: Address;
+    merchantValue: bigint;
+    feeValue: bigint;
+    nonce: Hex;
+  },
+): Promise<boolean>;
+
 export interface AcceptSummary {
   priceAtomic: bigint;
   feeAtomic: bigint;
@@ -459,12 +565,16 @@ export function createCatalogCache(): CatalogCache;
 export function resolveCatalogListings(options: {
   config: Pick<RuntimeConfig, 'catalogTrust' | 'discoveryUrl'>;
   fetchImpl?: typeof globalThis.fetch;
+  lookup?: PaymentLookup;
+  requestTimeoutMs?: number;
   now?: () => number;
   cache?: CatalogCache;
 }): Promise<Map<string, unknown> | null>;
 export function createCatalogResolver(options: {
   config: Pick<RuntimeConfig, 'catalogTrust' | 'discoveryUrl'>;
   fetchImpl?: typeof globalThis.fetch;
+  lookup?: PaymentLookup;
+  requestTimeoutMs?: number;
   now?: () => number;
 }): () => Promise<Map<string, unknown> | null>;
 
@@ -482,7 +592,10 @@ export function createPaymentExecutor(options: {
   signerAddress?: Address | null;
   spendStore?: SpendStore | null;
   fetchImpl?: typeof globalThis.fetch;
+  lookup?: PaymentLookup;
+  requestTimeoutMs?: number;
   nowSec?: () => number;
   now?: () => Date | number;
   resolveCatalogListings?: () => Promise<Map<string, unknown> | null>;
+  resolveReceiptSigner?: ReceiptSignerResolver;
 }): PaymentExecutor;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpay-x402-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Guarded Node.js buyer SDK for OpenPay x402 JPYC resources",
   "type": "module",
   "main": "./src/index.mjs",

package/src/catalog.mjs

@@ -1,3 +1,8 @@
+import {
+  DEFAULT_PAYMENT_FETCH_TIMEOUT_MS,
+  fetchPaymentTarget,
+} from './network.mjs';
+
 export const CATALOG_CACHE_MS = 5 * 60_000;
 
 function isObject(value) {
@@ -21,6 +26,8 @@ export function createCatalogCache() {
 export async function resolveCatalogListings({
   config,
   fetchImpl = fetch,
+  lookup,
+  requestTimeoutMs = DEFAULT_PAYMENT_FETCH_TIMEOUT_MS,
   now = Date.now,
   cache = createCatalogCache(),
 }) {
@@ -33,7 +40,10 @@ export async function resolveCatalogListings({
   }
 
   try {
-    const response = await fetchImpl(config.discoveryUrl, {
+    const response = await fetchPaymentTarget(config.discoveryUrl, {
+      fetchImpl,
+      lookup,
+      timeoutMs: requestTimeoutMs,
       headers: { accept: 'application/json' },
     });
     const body = await readJson(response);
@@ -64,7 +74,21 @@ export async function resolveCatalogListings({
   }
 }
 
-export function createCatalogResolver({ config, fetchImpl = fetch, now = Date.now }) {
+export function createCatalogResolver({
+  config,
+  fetchImpl = fetch,
+  lookup,
+  requestTimeoutMs = DEFAULT_PAYMENT_FETCH_TIMEOUT_MS,
+  now = Date.now,
+}) {
   const cache = createCatalogCache();
-  return () => resolveCatalogListings({ config, fetchImpl, now, cache });
+  return () =>
+    resolveCatalogListings({
+      config,
+      fetchImpl,
+      lookup,
+      requestTimeoutMs,
+      now,
+      cache,
+    });
 }

package/src/client.mjs

@@ -8,6 +8,7 @@ import {
 } from './guards.mjs';
 import { createSignerFromOptions } from './signer.mjs';
 import { createFileSpendStore } from './spendStore.mjs';
+import { createReceiptSignerResolver } from './receipt.mjs';
 
 function isObject(value) {
   return typeof value === 'object' && value !== null;
@@ -68,7 +69,18 @@ export function createOpenPayClient(options = {}) {
     config.maxDailyAtomic === null
       ? null
       : options.spendStore ?? createFileSpendStore();
-  const resolveCatalogListings = createCatalogResolver({ config, fetchImpl });
+  const resolveCatalogListings = createCatalogResolver({
+    config,
+    fetchImpl,
+    lookup: options.lookup,
+    requestTimeoutMs: options.requestTimeoutMs,
+  });
+  const resolveReceiptSigner = createReceiptSignerResolver({
+    discoveryUrl: config.discoveryUrl,
+    fetchImpl,
+    lookup: options.lookup,
+    requestTimeoutMs: options.requestTimeoutMs,
+  });
   const executor = createPaymentExecutor({
     config,
     session,
@@ -76,9 +88,12 @@ export function createOpenPayClient(options = {}) {
     signerAddress: signer?.address ?? null,
     spendStore,
     fetchImpl,
+    lookup: options.lookup,
+    requestTimeoutMs: options.requestTimeoutMs,
     nowSec: options.nowSec,
     now: options.now,
     resolveCatalogListings,
+    resolveReceiptSigner,
   });
 
   async function withSafeErrors(operation) {