openpay-x402-sdk 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 0.6.0
+
+- Add `createDualGate` — a dual-rail seller gate that serves both JPYC (Polygon,
+  OpenPay facilitator) and USDC (Base, standard x402 relayed via OpenPay to the
+  CDP facilitator). USDC payments settle directly to the seller wallet with 0%
+  OpenPay fee; if the USDC face cannot be fetched, the gate degrades to
+  JPYC-only and never blocks JPYC payments.
+- Add `createListingClient` — programmatic marketplace listing (register, list,
+  update, deactivate) with built-in SIWE sign-in, so sellers and agents can
+  publish listings without the web form. `register` requires an explicit
+  `attested: true` (the SDK never attests on your behalf); set `usdc` to also
+  appear on the x402 Bazaar after the first settled purchase.
+- Return an explicit `settlement` field from `pay()`, because HTTP `200` only
+  means the seller returned a body and is not evidence that the payment settled.
+  `verified` means a receipt header was present and the facilitator signature
+  bound it to this payment, `unverified` means a header was present but
+  unsigned, malformed, forged, or mismatched, and `receipt_unavailable` means no
+  header was returned or the facilitator signer could not be resolved. Treat
+  anything but `verified` as not proven paid. `receipt` keeps its previous
+  meaning and an unlocked response body is still never discarded.
+- Take over a spend lock left behind by a killed process instead of failing
+  budgeted payments forever. A lock whose last modification is older than
+  `SPEND_LOCK_STALE_MS` (60s, now exported) is moved aside with an atomic
+  `rename` — never `unlink` — and the mover re-inspects the moved file to prove
+  it took the very lock it measured, so two processes that observe the same
+  stale lock cannot both enter the critical section. A lock younger than the
+  window is left alone, so a live holder is never displaced.
+- Record the owning `pid` and `createdAt` in the lock file, name the lock path in
+  a new `detail` on `{ ok: false, reason: 'unavailable' }`, and treat an
+  already-absent lock at release time as a completed release. A custom `fsImpl`
+  without `stat`/`rename` keeps the previous fail-closed behavior and now warns
+  once instead of disabling the takeover silently.
+- Resolve the target hostname before calling an injected custom `fetchImpl`, so a
+  public name pointing at a private or link-local address is rejected before the
+  custom transport runs. Connection-time rebinding protection still requires
+  supplying `lookup`; a resolver failure does not block, since only the transport
+  that opens the socket can re-validate the address it connects to.
+- Require `DISCOVERY_URL` to be `https`, with plaintext `http` allowed only for
+  `localhost` / `127.0.0.1`. The discovery origin is the authority for catalog
+  trust — URLs it lists are payable without an `ALLOWED_HOSTS` entry — so a
+  substitutable plaintext catalog could pass an attacker's resource off as
+  reviewed. Both `readRuntimeConfig` and `parseClientOptions` enforce it.
+- Declare the new surface in `index.d.ts` (`SETTLEMENT`, `SettlementStatus`,
+  `PaymentResult.settlement`, `SPEND_LOCK_STALE_MS`, `SpendReservationResult.detail`,
+  `fsImpl.stat`, `createDualGate`, `createListingClient` and their inputs) and
+  document dual-rail selling, code-side listing, settlement truth, stale-lock
+  takeover, and the custom-transport boundary in the README.
+
+## 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,45 +104,147 @@ 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.
 
+### Dual-rail: also sell in USDC (Base) and appear on the x402 Bazaar
+
+If your listing has the USDC face enabled, use `createDualGate` with the listing
+id (shown as `MY_RESOURCE_ID` in the generated snippet). The 402 then carries
+both JPYC and USDC `accepts` plus a `PAYMENT-REQUIRED` header; USDC payments are
+relayed by OpenPay to the CDP facilitator and settle directly to your Base
+address with 0% OpenPay fee. If the USDC face cannot be fetched (relay off or
+unavailable), the gate degrades to JPYC-only — USDC never blocks JPYC payments.
+
+```js
+import { createDualGate } from 'openpay-x402-sdk';
+
+const gate = createDualGate({
+  resourceUrl: process.env.MY_RESOURCE_URL,
+  resourceId: process.env.MY_RESOURCE_ID,
+});
+```
+
+`handle()` / `verify()` work exactly like `createJpycGate`, on both rails.
+
+### Register listings without the web form
+
+`createListingClient` signs in with SIWE and manages your marketplace listings
+programmatically — so a seller (or an agent) can go from nothing to a dual-rail
+listing entirely in code:
+
+```js
+import { createListingClient } from 'openpay-x402-sdk';
+
+const listings = createListingClient({ privateKey: process.env.SELLER_PRIVATE_KEY });
+const { resource, paywallSnippet } = await listings.register({
+  url: 'https://api.example.com/paid/report',
+  description: 'What the purchase completes, in one paragraph.',
+  priceJpyc: '100',
+  category: 'api',
+  usdc: { priceUsd: '0.01', serviceName: 'Example Report API' }, // optional USDC face
+  attested: true, // your personal attestation — the SDK never sets this for you
+});
+// resource.id → pass to createDualGate; paywallSnippet → or paste the snippet instead
+```
+
+`register` refuses to run without an explicit `attested: true`: you must
+personally affirm that you have the right to provide and charge for the
+resource and that it is payment-gated (HTTP 402). `list()`, `update(id, input)`,
+and `deactivate(id)` complete the lifecycle; `update` without `usdc` removes the
+USDC face, so pass the previous value to keep it. The private key signs locally
+and is never transmitted.
+
 ## Money guards
 
 | 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. The lock file records the owning
+`pid` and `createdAt`, and a lock whose last modification is older than 60
+seconds is taken over automatically on the next reservation, so a killed process
+no longer blocks budgeted payments forever. A lock younger than that is left
+alone and the rejection names the lock path in its `detail`. Stop every process
+that uses the same store before removing a lock by hand.
 
 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. A custom
+`fetchImpl` still gets the pre-connection resolution check — a hostname that
+resolves to a private or link-local address is rejected before the injected
+transport is called — but connection-time rebinding protection requires also
+supplying `lookup`, because only the transport that opens the socket can
+re-validate the address it actually connects to. A custom `fetchImpl` without
+`lookup` therefore remains a trusted transport boundary for 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.
+
+`pay()` also returns an explicit `settlement` field, because an HTTP `200` only
+means the seller returned a body and is not evidence that the payment settled.
+`verified` means a receipt header was present and its facilitator signature was
+bound to this payment; `unverified` means a header was present but unsigned,
+malformed, forged, or mismatched; `receipt_unavailable` means no header was
+returned or the facilitator signer could not be resolved. Treat `unverified` and
+`receipt_unavailable` as not proven paid.
 
 ## Signers
 

package/index.d.ts

@@ -44,10 +44,48 @@ 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;
+      /**
+       * Operator-facing hint for `unavailable`, present only when the block came from the
+       * lock file (it names the lock path). Never parse it; it is diagnostic text.
+       */
+      detail?: string;
+    };
+
+export type PaymentLookup = (
+  hostname: string,
+) => Promise<Array<{ address: string; family?: number }>>;
+
 export interface FileSpendStoreOptions {
   path?: string;
   fsImpl?: {
@@ -58,18 +96,39 @@ 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>;
+    /**
+     * Required (together with `rename`) for taking over a lock left behind by a killed
+     * process. When either is missing the takeover is disabled and the SDK warns once —
+     * a stale lock then blocks budgeted payments until it is removed by hand.
+     */
+    stat?(path: string): Promise<{ mtimeMs?: number; mtime?: Date | number }>;
   };
 }
 
+/**
+ * A spend lock older than this cannot belong to a live holder, so it may be taken over.
+ * Exported so operators and tests can reason about the same window as the store.
+ */
+export const SPEND_LOCK_STALE_MS: number;
+
 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 +173,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;
@@ -196,10 +260,30 @@ export interface InvalidChallengeQuote {
 
 export type QuoteResult = GuardedQuote | InvalidChallengeQuote;
 
+/**
+ * Settlement truth for one paid call. `status: 200` alone is not evidence of settlement.
+ * - `verified`: a receipt header was present and the facilitator signature bound it to this payment.
+ * - `unverified`: a receipt header was present but unsigned, malformed, forged, or mismatched.
+ * - `receipt_unavailable`: no receipt header, or the facilitator signer could not be resolved.
+ */
+export type SettlementStatus = 'verified' | 'unverified' | 'receipt_unavailable';
+
+/** The `SettlementStatus` values as a runtime object (`unavailable` = `receipt_unavailable`). */
+export const SETTLEMENT: {
+  readonly verified: 'verified';
+  readonly unverified: 'unverified';
+  readonly unavailable: 'receipt_unavailable';
+};
+
 export interface PaymentResult {
   status: number;
   body: unknown;
   receipt: unknown;
+  /**
+   * Optional so objects built before this field existed stay source-compatible. Absent must be
+   * read the same way as `receipt_unavailable`: no settlement was proven.
+   */
+  settlement?: SettlementStatus;
 }
 
 export interface OpenPayClient {
@@ -228,6 +312,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 {
@@ -245,9 +333,98 @@ export interface JpycGate {
 
 export function createJpycGate(options: JpycGateOptions): JpycGate;
 
+export interface DualGateOptions extends JpycGateOptions {
+  /** OpenPay listing id (MY_RESOURCE_ID in the generated snippet). Enables the USDC (Base) rail. */
+  resourceId: string;
+}
+
+/**
+ * Dual-rail seller gate: JPYC (Polygon, OpenPay facilitator) plus USDC (Base, standard x402
+ * relayed to the CDP facilitator via OpenPay). If the USDC face cannot be fetched (relay off
+ * or unavailable), the gate degrades to JPYC-only — the USDC side never blocks JPYC payments.
+ */
+export function createDualGate(options: DualGateOptions): JpycGate;
+
+export interface ListingUsdcInput {
+  /** USD price without a $ sign, up to 6 decimals (e.g. "0.005"). */
+  priceUsd: string;
+  /** USDC (Base) receiving address. Defaults to the JPYC payTo. */
+  payTo?: string;
+  /** Display name for x402 Bazaar search (max 60 chars). */
+  serviceName?: string;
+}
+
+export interface ListingInput {
+  url: string;
+  description: string;
+  /** Integer JPYC price as a string (e.g. "100"). */
+  priceJpyc: string;
+  category: string;
+  docsUrl?: string;
+  license?: string;
+  /** JPYC receiving address. Defaults to the signed-in wallet. */
+  payTo?: string;
+  /** Enable the USDC (Base) face — also lists on the x402 Bazaar after the first settle. */
+  usdc?: ListingUsdcInput;
+}
+
+export interface RegisterListingInput extends ListingInput {
+  /**
+   * Required, must be literally true: your personal attestation that you have the right to
+   * provide and charge for this resource and that it is payment-gated (HTTP 402).
+   * The SDK never sets this for you.
+   */
+  attested: true;
+}
+
+export interface ListingRecord {
+  id: string;
+  url: string;
+  description: string;
+  priceJpyc: string;
+  category: string;
+  payTo: string;
+  docsUrl?: string;
+  license?: string;
+  usdc?: { payTo: string; priceUsd: string; serviceName?: string };
+  paywallSnippet?: string;
+  hidden?: boolean;
+}
+
+export interface RegisterListingResult {
+  resource: ListingRecord;
+  /** Copy-paste 402 gate for your server (dual-rail x402Gate when usdc is set). */
+  paywallSnippet: string;
+}
+
+export interface ListingClient {
+  /** The seller wallet address that signs in via SIWE (checksummed). */
+  address: Address;
+  register(input: RegisterListingInput): Promise<RegisterListingResult>;
+  list(): Promise<ListingRecord[]>;
+  update(id: string, input: ListingInput): Promise<{ resource: ListingRecord }>;
+  deactivate(id: string): Promise<boolean>;
+}
+
+/**
+ * Programmatic listing client — register, list, update, and deactivate OpenPay marketplace
+ * listings without the web form. Signs in with SIWE using the given private key on first use;
+ * the key is only used to sign locally and is never transmitted.
+ */
+export function createListingClient(options: {
+  privateKey: string;
+  openpayOrigin?: string;
+  fetchImpl?: typeof globalThis.fetch;
+  /** SIWE chainId (default 137 = Polygon). */
+  chainId?: number;
+  statement?: string;
+  now?: () => number;
+}): ListingClient;
+
 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 +508,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 +519,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 +533,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 +690,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 +717,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.6.0",
   "description": "Guarded Node.js buyer SDK for OpenPay x402 JPYC resources",
   "type": "module",
   "main": "./src/index.mjs",