openpay-x402-sdk 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # 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

package/README.md

@@ -121,6 +121,54 @@ 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 |
@@ -159,9 +207,12 @@ atomic `reserve(key, amount, limit, reservation)` method; legacy
 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.
+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-canonical JPYC contracts or EIP-712 domains, seller timeouts above
@@ -172,9 +223,14 @@ 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.
+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,
@@ -182,6 +238,14 @@ 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
 
 Choose exactly one of `privateKey`, `steward`, or `signer`. Supplying more than

package/index.d.ts

@@ -75,6 +75,11 @@ export type SpendReservationResult =
       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 = (
@@ -97,9 +102,21 @@ export interface FileSpendStoreOptions {
     ): 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;
@@ -243,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 {
@@ -296,6 +333,94 @@ 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 }>;
 };

package/package.json

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

package/src/dualGate.mjs

@@ -0,0 +1,196 @@
+// dual-rail 出品者ゲート: createJpycGate (JPYC・Polygon) に USDC (Base・標準 x402) の面を重ねる。
+//
+// USDC 面は OpenPay のリレー (/api/x402/relay/*) から取得・中継する:
+//   - requirements: 402 に並記する完成形 (v1Accepts + PAYMENT-REQUIRED ヘッダ) を配布
+//   - verify/settle: CDP facilitator への中継 (支払いは購入者 → 出品者 payTo へ直接)
+//
+// 隔離 (最重要): USDC 面の取得失敗 (リレー未点灯・障害) は null に落とし、JPYC ゲートだけで
+// 継続する — 付帯面 (USDC) の障害が決済本体 (JPYC) を止めない。
+//
+// レール振り分け: PAYMENT-SIGNATURE ヘッダ (v2 = USDC クライアント)、または x-payment (v1) の
+// network が USDC 面と一致するときだけ USDC レール。その他は従来の JPYC ゲートへ委譲する。
+// JPYC レールの 402 には USDC accepts を追記 (decorate) して両面を常に見せる。
+
+import { createJpycGate } from './gate.mjs';
+
+const DEFAULT_OPENPAY_ORIGIN = 'https://open-pay.jp';
+const USDC_FACE_CACHE_MS = 5 * 60_000;
+
+function decodeBase64Json(value) {
+  const binary = atob(value);
+  const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+  return JSON.parse(new TextDecoder().decode(bytes));
+}
+
+function encodeBase64Json(value) {
+  const bytes = new TextEncoder().encode(JSON.stringify(value));
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+export function createDualGate({
+  resourceUrl,
+  resourceId,
+  openpayOrigin = DEFAULT_OPENPAY_ORIGIN,
+  fetchImpl = globalThis.fetch,
+  now = Date.now,
+  maxUpstreamSeconds,
+  settlementGraceSeconds,
+}) {
+  if (typeof resourceId !== 'string' || resourceId.length === 0) {
+    throw new Error('resourceId is required (shown as MY_RESOURCE_ID in your OpenPay listing)');
+  }
+  const jpyc = createJpycGate({
+    resourceUrl,
+    openpayOrigin,
+    fetchImpl,
+    now,
+    ...(maxUpstreamSeconds === undefined ? {} : { maxUpstreamSeconds }),
+    ...(settlementGraceSeconds === undefined ? {} : { settlementGraceSeconds }),
+  });
+  const origin = openpayOrigin.replace(/\/+$/, '');
+
+  let usdcCache = null;
+  let usdcCachedAt = 0;
+  async function usdcFace() {
+    if (usdcCache !== null && now() - usdcCachedAt < USDC_FACE_CACHE_MS) {
+      return usdcCache;
+    }
+    try {
+      const response = await fetchImpl(
+        `${origin}/api/x402/relay/requirements?resourceId=${encodeURIComponent(resourceId)}`,
+      );
+      if (!response.ok) return null;
+      const face = await response.json();
+      if (!face || typeof face !== 'object' || !face.v1Accepts) return null;
+      usdcCache = face;
+      usdcCachedAt = now();
+      return face;
+    } catch {
+      // リレー未点灯/障害 → USDC 面なしで継続 (JPYC 本体を止めない)。キャッシュしない
+      // (復旧したら次のリクエストで拾う)。
+      return null;
+    }
+  }
+
+  // JPYC ゲートが返した 402 に USDC 面 (accepts + PAYMENT-REQUIRED ヘッダ) を追記する。
+  // 402 以外・USDC 面なし・body が読めない場合はそのまま返す (壊さない)。
+  async function decorate402(response, usdc) {
+    if (!usdc || !(response instanceof Response) || response.status !== 402) {
+      return response;
+    }
+    let body;
+    try {
+      body = await response.clone().json();
+    } catch {
+      return response;
+    }
+    if (!body || !Array.isArray(body.accepts)) return response;
+    const headers = new Headers(response.headers);
+    headers.set('content-type', 'application/json');
+    if (typeof usdc.paymentRequiredHeader === 'string') {
+      headers.set('PAYMENT-REQUIRED', usdc.paymentRequiredHeader);
+    }
+    return new Response(
+      JSON.stringify({ ...body, accepts: [...body.accepts, usdc.v1Accepts] }),
+      { status: 402, headers },
+    );
+  }
+
+  // USDC レールの 402。JPYC accepts の取得失敗は握って USDC 面だけで返す
+  // (challenge の失敗で支払いエラーの伝達自体を落とさない)。
+  async function usdcChallenge(usdc, error) {
+    let jpycAccepts = [];
+    try {
+      const headerless = { url: resourceUrl, headers: { get: () => null } };
+      const challenge = await jpyc.verify(headerless);
+      if (challenge instanceof Response && challenge.status === 402) {
+        const body = await challenge.json();
+        if (Array.isArray(body.accepts)) jpycAccepts = body.accepts;
+      }
+    } catch {
+      /* JPYC カタログ未掲載などは USDC のみで継続 */
+    }
+    const headers = { 'content-type': 'application/json' };
+    if (typeof usdc.paymentRequiredHeader === 'string') {
+      headers['PAYMENT-REQUIRED'] = usdc.paymentRequiredHeader;
+    }
+    return new Response(
+      JSON.stringify({
+        x402Version: 1,
+        accepts: [...jpycAccepts, usdc.v1Accepts],
+        error,
+      }),
+      { status: 402, headers },
+    );
+  }
+
+  async function verify(request) {
+    const usdc = await usdcFace();
+    const signatureHeader = request.headers.get('payment-signature');
+    const v1Header = request.headers.get('x-payment');
+    let v1Network = null;
+    if (v1Header) {
+      try {
+        const decoded = decodeBase64Json(v1Header);
+        if (decoded && typeof decoded === 'object') v1Network = decoded.network;
+      } catch {
+        /* 不正 header は下のレール判定で JPYC 側に流し、そこで 402 になる */
+      }
+    }
+
+    const usdcRail =
+      usdc !== null &&
+      (Boolean(signatureHeader) ||
+        (typeof v1Network === 'string' && v1Network === usdc.v1Accepts.network));
+
+    if (usdcRail) {
+      const relay = async (path) => {
+        const response = await fetchImpl(`${origin}/api/x402/relay/${path}`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({
+            resourceId,
+            ...(signatureHeader
+              ? { paymentSignatureHeader: signatureHeader }
+              : { paymentHeader: v1Header }),
+          }),
+        });
+        return response.json();
+      };
+      const verification = await relay('verify');
+      if (verification.isValid !== true) {
+        return usdcChallenge(usdc, verification.invalidReason || 'payment_invalid');
+      }
+      return {
+        async settle() {
+          const settlement = await relay('settle');
+          if (settlement.success !== true) {
+            return usdcChallenge(usdc, settlement.errorReason || 'settlement_failed');
+          }
+          return { paymentResponseHeader: encodeBase64Json(settlement) };
+        },
+      };
+    }
+
+    const result = await jpyc.verify(request);
+    if (result instanceof Response) return decorate402(result, usdc);
+    return {
+      async settle() {
+        const settlement = await result.settle();
+        return settlement instanceof Response
+          ? decorate402(settlement, usdc)
+          : settlement;
+      },
+    };
+  }
+
+  async function handle(request) {
+    const verification = await verify(request);
+    if (verification instanceof Response) return verification;
+    return verification.settle();
+  }
+
+  return { handle, verify };
+}

package/src/executor.mjs

@@ -127,36 +127,53 @@ function utcDate(value) {
   return instant.toISOString().slice(0, 10);
 }
 
-async function safeReceipt(
+// Settlement truth for one paid call. HTTP 200 only means the seller returned a body; it is not
+// evidence that the facilitator settled on chain, and an LLM reading `status: 200` will assume it is.
+//   '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 const SETTLEMENT = Object.freeze({
+  verified: 'verified',
+  unverified: 'unverified',
+  unavailable: 'receipt_unavailable',
+});
+
+async function settlementOutcome(
   raw,
   reservation,
   normalizedAccept,
   resolveReceiptSigner,
 ) {
+  if (typeof raw !== 'string' || raw.length === 0) {
+    return { receipt: null, settlement: SETTLEMENT.unavailable };
+  }
   try {
     const decoded = decodePaymentResponse(raw);
-    if (decoded === null) return null;
+    // A header that cannot be decoded is a seller claim we could not check, not an absent claim.
+    if (decoded === null) {
+      return { receipt: null, settlement: SETTLEMENT.unverified };
+    }
     const expectedSigner = await resolveReceiptSigner();
-    if (
-      expectedSigner === null ||
-      !(await verifyBoundPaymentResponse(decoded, {
-        expectedSigner,
-        payer: reservation.payer,
-        network: reservation.network,
-        asset: reservation.asset,
-        chainId: normalizedAccept.chainId,
-        merchant: normalizedAccept.extra.openpay.merchant,
-        merchantValue: normalizedAccept.extra.openpay.merchantValue,
-        feeValue: normalizedAccept.extra.openpay.feeValue,
-        nonce: reservation.id,
-      }))
-    ) {
-      return null;
+    if (expectedSigner === null) {
+      return { receipt: null, settlement: SETTLEMENT.unavailable };
     }
-    return decoded;
+    const bound = await verifyBoundPaymentResponse(decoded, {
+      expectedSigner,
+      payer: reservation.payer,
+      network: reservation.network,
+      asset: reservation.asset,
+      chainId: normalizedAccept.chainId,
+      merchant: normalizedAccept.extra.openpay.merchant,
+      merchantValue: normalizedAccept.extra.openpay.merchantValue,
+      feeValue: normalizedAccept.extra.openpay.feeValue,
+      nonce: reservation.id,
+    });
+    return bound
+      ? { receipt: decoded, settlement: SETTLEMENT.verified }
+      : { receipt: null, settlement: SETTLEMENT.unverified };
   } catch {
     // A seller-controlled receipt header must not erase an unlocked body and invite a duplicate payment.
-    return null;
+    return { receipt: null, settlement: SETTLEMENT.unverified };
   }
 }
 
@@ -533,7 +550,7 @@ export function createPaymentExecutor({
         await confirmDailyReservation(reservation.id);
       }
     }
-    const receipt = await safeReceipt(
+    const { receipt, settlement } = await settlementOutcome(
       unlocked.headers.get('x-payment-response'),
       reservation,
       normalizedAccept,
@@ -543,6 +560,7 @@ export function createPaymentExecutor({
       status: unlocked.status,
       body: unlockedBody,
       receipt,
+      settlement,
     };
   }
 

package/src/guards.mjs

@@ -167,9 +167,20 @@ function parseHttpUrl(raw, label) {
   }
 }
 
-function requireHttpUrl(raw, label) {
+// DISCOVERY_URL は catalog trust の権威 (ここに載る URL は ALLOWED_HOSTS への手動追加なしで
+// 支払える)。平文 http はネットワーク上で差し替え可能なので、攻撃者のカタログが「審査済み」に
+// 化けて支払い先を乗っ取る波及を断つため https に限る。例外はローカル開発 (localhost /
+// 127.0.0.1) のみ — 自機の facilitator/カタログを立てて配線を確かめる用途。
+function requireDiscoveryUrl(raw, label) {
   const url = parseHttpUrl(raw, label);
   if (url === null) throw new Error(`${label} must be an http(s) URL`);
+  if (
+    url.protocol === 'http:' &&
+    url.hostname !== 'localhost' &&
+    url.hostname !== '127.0.0.1'
+  ) {
+    throw new Error(`${label} must use https (http is allowed only for localhost)`);
+  }
   return url.toString();
 }
 
@@ -206,7 +217,7 @@ export function readMoneyConfig(env = process.env) {
 export function readRuntimeConfig(env = process.env) {
   return {
     ...readMoneyConfig(env),
-    discoveryUrl: requireHttpUrl(
+    discoveryUrl: requireDiscoveryUrl(
       nonEmpty(env.DISCOVERY_URL) ?? DEFAULT_DISCOVERY_URL,
       'DISCOVERY_URL',
     ),
@@ -264,7 +275,7 @@ export function parseClientOptions(options = {}) {
         : parseJpycToAtomic(options.maxDailyJpyc, 'MAX_DAILY_JPYC'),
     allowedHosts: parseAllowedHosts(options.allowedHosts),
     catalogTrust: options.catalogTrust ?? DEFAULT_CATALOG_TRUST,
-    discoveryUrl: requireHttpUrl(
+    discoveryUrl: requireDiscoveryUrl(
       nonEmpty(options.discoveryUrl) ?? DEFAULT_DISCOVERY_URL,
       'DISCOVERY_URL',
     ),

package/src/index.mjs

@@ -1,5 +1,7 @@
 export * from './catalog.mjs';
 export * from './client.mjs';
+export * from './dualGate.mjs';
+export * from './listing.mjs';
 export * from './executor.mjs';
 export * from './gate.mjs';
 export * from './guards.mjs';

package/src/listing.mjs

@@ -0,0 +1,173 @@
+// コード出品クライアント: 出品フォームを開かずに、SIWE サインイン込みで AI ストアの
+// 出品を登録・一覧・更新・無効化する (POST/GET/PATCH/DELETE /api/facilitator/resources)。
+//
+// 法的に重要: register には **attested: true の明示が必須** (自動付与しない)。これは
+// 「登録するリソースを提供・課金する正当な権利を有し、支払い (HTTP 402 等) でゲートして
+// いる」という出品者本人の表明であり、SDK が代わりに宣言してよいものではない。
+//
+// セッション: 初回操作時に SIWE (EIP-4361) でサインインし cookie を保持・再利用する。
+// 鍵はメモリ内でのみ使用し、どこにも送信しない (署名のみ)。
+
+import { privateKeyToAccount } from 'viem/accounts';
+import { createSiweMessage } from 'viem/siwe';
+
+const DEFAULT_OPENPAY_ORIGIN = 'https://open-pay.jp';
+const SIWE_MESSAGE_TTL_MS = 5 * 60_000;
+const DEFAULT_SIWE_CHAIN_ID = 137; // Polygon (OpenPay の常時サポートチェーン)
+const DEFAULT_STATEMENT = 'Sign in to OpenPay to manage your x402 listings.';
+
+async function readJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+export function createListingClient({
+  privateKey,
+  openpayOrigin = DEFAULT_OPENPAY_ORIGIN,
+  fetchImpl = globalThis.fetch,
+  chainId = DEFAULT_SIWE_CHAIN_ID,
+  statement = DEFAULT_STATEMENT,
+  now = Date.now,
+}) {
+  if (typeof privateKey !== 'string' || !privateKey.startsWith('0x')) {
+    throw new Error('privateKey (0x...) is required');
+  }
+  const account = privateKeyToAccount(privateKey);
+  const origin = openpayOrigin.replace(/\/+$/, '');
+  let cookie = null;
+
+  async function signIn() {
+    const nonceResponse = await fetchImpl(`${origin}/api/auth/siwe/nonce`, {
+      method: 'POST',
+    });
+    const nonceBody = await readJson(nonceResponse);
+    if (!nonceResponse.ok || typeof nonceBody?.nonce !== 'string') {
+      throw new Error(`siwe nonce failed: HTTP ${nonceResponse.status}`);
+    }
+    const issuedAt = new Date(now());
+    const message = createSiweMessage({
+      domain: new URL(origin).host,
+      address: account.address,
+      statement,
+      uri: origin,
+      version: '1',
+      chainId,
+      nonce: nonceBody.nonce,
+      issuedAt,
+      expirationTime: new Date(issuedAt.getTime() + SIWE_MESSAGE_TTL_MS),
+    });
+    const signature = await account.signMessage({ message });
+    const verifyResponse = await fetchImpl(`${origin}/api/auth/siwe/verify`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ message, signature }),
+    });
+    if (!verifyResponse.ok) {
+      const body = await readJson(verifyResponse);
+      throw new Error(`siwe verify failed: ${body?.error ?? `HTTP ${verifyResponse.status}`}`);
+    }
+    const setCookie = verifyResponse.headers.get('set-cookie') ?? '';
+    const sessionCookie = setCookie.split(';')[0];
+    if (!sessionCookie.includes('=')) {
+      throw new Error('siwe verify returned no session cookie');
+    }
+    cookie = sessionCookie;
+  }
+
+  async function authedFetch(path, init = {}, retried = false) {
+    if (cookie === null) await signIn();
+    const response = await fetchImpl(`${origin}${path}`, {
+      ...init,
+      headers: { ...(init.headers ?? {}), cookie },
+    });
+    // セッション失効 (401) は一度だけサインインし直して再試行する。
+    if (response.status === 401 && !retried) {
+      cookie = null;
+      return authedFetch(path, init, true);
+    }
+    return response;
+  }
+
+  function buildBody(input) {
+    const { url, description, priceJpyc, category, docsUrl, license, payTo, usdc } = input;
+    return {
+      url,
+      description,
+      priceJpyc,
+      category,
+      ...(docsUrl ? { docsUrl } : {}),
+      ...(license ? { license } : {}),
+      ...(payTo ? { payTo } : {}),
+      ...(usdc ? { usdc } : {}),
+    };
+  }
+
+  async function expectOk(response, okStatus) {
+    const body = await readJson(response);
+    if (response.status !== okStatus) {
+      throw new Error(
+        `openpay listing API failed: HTTP ${response.status} ${body?.error ?? ''}`.trim(),
+      );
+    }
+    return body;
+  }
+
+  return {
+    /** SIWE でサインインする出品者アドレス (checksum)。 */
+    address: account.address,
+
+    /**
+     * 出品を登録する。attested: true の明示が必須 —
+     * 「このリソースを提供・課金する正当な権利があり、402 等の支払いゲートを実装している」
+     * という出品者本人の表明で、SDK は代行しない。
+     * 戻り値: { resource, paywallSnippet } (usdc 面つきなら dual-rail スニペット)。
+     */
+    async register(input) {
+      if (input?.attested !== true) {
+        throw new Error(
+          'attested: true is required — you must personally affirm that you have the right ' +
+            'to provide and charge for this resource and that it is payment-gated (HTTP 402).',
+        );
+      }
+      const response = await authedFetch('/api/facilitator/resources', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ ...buildBody(input), attested: true }),
+      });
+      return expectOk(response, 201);
+    },
+
+    /** 自分の出品一覧 (paywallSnippet つき)。 */
+    async list() {
+      const response = await authedFetch('/api/facilitator/resources');
+      const body = await expectOk(response, 200);
+      return body.resources ?? [];
+    },
+
+    /** 出品を編集する (usdc を省略すると USDC 面は外れる — 現状維持は前回の値を渡す)。 */
+    async update(id, input) {
+      const response = await authedFetch(
+        `/api/facilitator/resources/${encodeURIComponent(id)}`,
+        {
+          method: 'PATCH',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(buildBody(input)),
+        },
+      );
+      return expectOk(response, 200);
+    },
+
+    /** 出品を無効化する (公開カタログから外す・履歴は残る)。 */
+    async deactivate(id) {
+      const response = await authedFetch(
+        `/api/facilitator/resources/${encodeURIComponent(id)}`,
+        { method: 'DELETE' },
+      );
+      await expectOk(response, 200);
+      return true;
+    },
+  };
+}

package/src/network.mjs

@@ -240,6 +240,25 @@ export async function fetchPaymentTarget(
     normalizedAddresses(
       await lookupWithSignal(resolver, parsed.hostname, signal),
     );
+  } else {
+    // A custom fetchImpl used to skip pre-resolution entirely, so a public hostname pointing at
+    // 169.254.169.254 or another private target reached the injected transport unchecked. Resolve
+    // with the default resolver and reject a proven-private target before the transport runs.
+    // A resolver failure is not itself proof of a private target and the custom transport resolves
+    // independently, so it does not block here; connection-time rebinding protection still
+    // requires supplying `lookup` (documented in the README).
+    let addresses = null;
+    try {
+      addresses = await lookupWithSignal(resolver, parsed.hostname, signal);
+    } catch (error) {
+      // An aborted pre-resolution is the caller's timeout, not a DNS verdict; continuing would
+      // hand the transport a dead signal.
+      if (signal.aborted) throw error;
+      addresses = null;
+    }
+    if (Array.isArray(addresses) && addresses.length > 0) {
+      normalizedAddresses(addresses);
+    }
   }
 
   const init = {

package/src/spendStore.mjs

@@ -3,6 +3,12 @@ import { randomUUID } from 'node:crypto';
 const RESERVATIONS_KEY = '__openpayReservations';
 const LOCK_RETRY_COUNT = 40;
 const LOCK_RETRY_MS = 25;
+// A lock older than this cannot belong to a live holder: the retry loop above waits only
+// LOCK_RETRY_COUNT * LOCK_RETRY_MS (1s) and every critical section is a small read plus an
+// atomic replace, so a live process either finishes or dies far inside this window. Without the
+// takeover a SIGKILL leaves spend.json.lock behind and every budgeted payment fails forever.
+export const SPEND_LOCK_STALE_MS = 60_000;
+const LOCK_ERROR_CODE = 'ESPENDLOCK';
 
 function isObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -42,6 +48,14 @@ function reservationMatches(existing, reservation) {
   );
 }
 
+// Only a lock error carries a path we raised ourselves; arbitrary errors stay opaque so a
+// filesystem message cannot leak into a caller-visible field.
+function unavailableDetail(error) {
+  return isObject(error) && error.code === LOCK_ERROR_CODE
+    ? { detail: error.message }
+    : {};
+}
+
 function supportsAtomicFileUpdates(fileSystem) {
   return (
     typeof fileSystem.open === 'function' &&
@@ -50,6 +64,26 @@ function supportsAtomicFileUpdates(fileSystem) {
   );
 }
 
+// stale takeover は「古さの判定 (stat)」と「奪取の原子化 (rename)」の両方を要する。
+function supportsStaleTakeover(fileSystem) {
+  return (
+    typeof fileSystem.stat === 'function' && typeof fileSystem.rename === 'function'
+  );
+}
+
+let staleTakeoverWarned = false;
+
+// 掟13: takeover が無効な fsImpl を **黙って** 素通りさせない。無効なら「SIGKILL で残った
+// ロックが予算つき支払いを永久に止める」状態に戻るので、運用者が気づけるよう一度だけ警告する。
+function warnStaleTakeoverUnavailable() {
+  if (staleTakeoverWarned) return;
+  staleTakeoverWarned = true;
+  console.warn(
+    'openpay-x402-sdk: fsImpl lacks stat/rename — stale spend-lock takeover is disabled; ' +
+      'a lock left behind by a killed process will block budgeted payments until it is removed.',
+  );
+}
+
 export function createFileSpendStore({ path, fsImpl } = {}) {
   let runtimePromise;
 
@@ -87,17 +121,134 @@ export function createFileSpendStore({ path, fsImpl } = {}) {
     return document;
   }
 
+  function lockUnavailable(lockPath, detail) {
+    return Object.assign(
+      new Error(
+        `spend store lock unavailable: ${lockPath}${detail === undefined ? '' : ` (${detail})`}`,
+      ),
+      { code: LOCK_ERROR_CODE, lockPath },
+    );
+  }
+
+  // Record who holds the lock so an operator inspecting a stuck store can tell whether the pid
+  // is still alive. Failure to annotate must not release a lock we successfully created.
+  async function annotateLock(handle, lockPath) {
+    if (typeof handle?.writeFile !== 'function') return;
+    try {
+      await handle.writeFile(
+        JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }),
+        'utf8',
+      );
+    } catch {
+      // The lock is held either way; the owner note is diagnostic only.
+    }
+  }
+
+  // 「そのロックファイルが何者か」を age と同一性 (inode + mtime) の両方で捉える。takeover は
+  // 「stat した stale そのものを奪えたか」を後段で照合する必要があるため、age だけでは足りない。
+  async function lockIdentity(fileSystem, lockPath) {
+    try {
+      const stats = await fileSystem.stat(lockPath);
+      const modified = Number(stats?.mtimeMs ?? stats?.mtime);
+      if (!Number.isFinite(modified)) return null;
+      return { ageMs: Date.now() - modified, modified, ino: stats?.ino };
+    } catch {
+      // A lock that vanished or cannot be inspected is not provably stale.
+      return null;
+    }
+  }
+
+  // inode が取れる実 fs では inode 一致が同一ファイルの証明。inode を返さない fsImpl では
+  // mtime 一致で代替する (takeover 直後の新しいロックは必ず mtime が今なので判別できる)。
+  function isSameLockFile(observed, moved) {
+    if (observed === null || moved === null) return false;
+    if (observed.ino !== undefined && moved.ino !== undefined) {
+      return observed.ino === moved.ino && observed.modified === moved.modified;
+    }
+    return observed.modified === moved.modified;
+  }
+
   async function acquireLock(fileSystem, lockPath) {
     for (let attempt = 0; attempt < LOCK_RETRY_COUNT; attempt += 1) {
       try {
-        return await fileSystem.open(lockPath, 'wx');
+        const handle = await fileSystem.open(lockPath, 'wx');
+        await annotateLock(handle, lockPath);
+        return handle;
       } catch (error) {
         if (!isLockHeld(error)) throw error;
-        if (attempt === LOCK_RETRY_COUNT - 1) throw error;
+        if (attempt === LOCK_RETRY_COUNT - 1) break;
         await wait(LOCK_RETRY_MS);
       }
     }
-    throw new Error('spend store lock unavailable');
+
+    // Stale takeover. A fresh lock is left alone, so a live holder is never displaced; only a lock
+    // that outlived the 1s contention window is taken over.
+    //
+    // ⚠️ The takeover MUST NOT unlink lockPath. `unlink(lockPath)` then `open(lockPath,'wx')` lets
+    // two processes that both saw the same stale lock interleave as
+    //   A: unlink → open (holds the lock)
+    //   B: unlink (deletes A's *fresh* lock) → open (succeeds)
+    // so both run the critical section at once and one reservation is lost. `rename` is atomic and
+    // exactly one process can move the stale file away, so ownership of the takeover is proven
+    // before lockPath is recreated.
+    //
+    // ⚠️ rename が原子的なのは「移動」だけで、「stat した stale を移動した」ことまでは保証しない。
+    // stat と rename の間に相手が takeover を終えていると、掴むのは相手の **新しい** ロックになる
+    // (A: rename → open(保持) / B: rename で A のロックを退避 → open 成功 = 両者が臨界区間)。
+    // だから移動先を stat し直し、奪ったのが stat した stale 本人であることを照合する。
+    if (!supportsStaleTakeover(fileSystem)) {
+      warnStaleTakeoverUnavailable();
+      throw lockUnavailable(lockPath, 'held (stale takeover unavailable)');
+    }
+    const observed = await lockIdentity(fileSystem, lockPath);
+    if (observed === null || observed.ageMs < SPEND_LOCK_STALE_MS) {
+      throw lockUnavailable(
+        lockPath,
+        observed === null
+          ? 'held'
+          : `held for ${Math.round(observed.ageMs / 1000)}s`,
+      );
+    }
+    const stalePath = `${lockPath}.stale-${process.pid}-${randomUUID()}`;
+    try {
+      await fileSystem.rename(lockPath, stalePath);
+    } catch (error) {
+      // ENOENT = another process won the same takeover and its lock is now fresh. Report the
+      // contention instead of guessing; the caller retries from the normal acquisition loop.
+      throw lockUnavailable(
+        lockPath,
+        isMissingFile(error)
+          ? 'reacquired by another process'
+          : 'stale, takeover failed',
+      );
+    }
+    // 退避したのが stat した stale 本人でなければ、生きた保持者のロックを奪ってしまっている。
+    // 元に戻してから撤退する (戻さないと保持者の解放が空振りし、次の到着者が素通りで入れてしまう)。
+    if (!isSameLockFile(observed, await lockIdentity(fileSystem, stalePath))) {
+      try {
+        await fileSystem.rename(stalePath, lockPath);
+      } catch {
+        // 復元できないケースまで握るのは危険だが、ここで投げても保持者のロックは戻らない。
+        // 呼び出し側には下の unavailable で「入れなかった」と伝わる方が安全側。
+      }
+      throw lockUnavailable(lockPath, 'reacquired by another process');
+    }
+    let handle;
+    try {
+      handle = await fileSystem.open(lockPath, 'wx');
+    } catch (error) {
+      if (!isLockHeld(error)) throw error;
+      throw lockUnavailable(lockPath, 'reacquired by another process');
+    } finally {
+      try {
+        await fileSystem.unlink(stalePath);
+      } catch {
+        // The stale file is already out of the lock path, so a leftover copy cannot hand the
+        // critical section to anyone; only disk tidiness suffers.
+      }
+    }
+    await annotateLock(handle, lockPath);
+    return handle;
   }
 
   async function withLock(operation) {
@@ -113,7 +264,14 @@ export function createFileSpendStore({ path, fsImpl } = {}) {
       try {
         await handle.close();
       } finally {
-        await runtime.fileSystem.unlink(runtime.lockPath);
+        try {
+          await runtime.fileSystem.unlink(runtime.lockPath);
+        } catch (error) {
+          // ENOENT = ロックは既に無い (takeover を試みた相手が一瞬退避した等) = 解放の目的は達成済み。
+          // 解放の空振りで、書き込みまで終えた予約を unavailable に化けさせない。ENOENT 以外は
+          // 「ロックが残る」ので握りつぶさず投げる。
+          if (!isMissingFile(error)) throw error;
+        }
       }
     }
   }
@@ -237,8 +395,10 @@ export function createFileSpendStore({ path, fsImpl } = {}) {
         await writeDocument(runtime, current);
         return { ok: true, totalAtomic: next.toString() };
       });
-    } catch {
-      return { ok: false, reason: 'unavailable' };
+    } catch (error) {
+      // Name the lock file when the block came from it. A bare "unavailable" sends operators
+      // hunting through the payment path for a failure that is one leftover file.
+      return { ok: false, reason: 'unavailable', ...unavailableDetail(error) };
     }
   }