openpay-x402-sdk 0.4.0 → 0.6.0

package/src/gate.mjs

@@ -1,5 +1,7 @@
 const DEFAULT_OPENPAY_ORIGIN = 'https://open-pay.jp';
 const ACCEPTS_CACHE_MS = 5 * 60_000;
+const DEFAULT_MAX_UPSTREAM_SECONDS = 60;
+const DEFAULT_SETTLEMENT_GRACE_SECONDS = 30;
 
 function json402(accepts, error) {
   return new Response(JSON.stringify({ x402Version: 1, accepts, error }), {
@@ -21,15 +23,134 @@ function encodeBase64Json(value) {
   return btoa(binary);
 }
 
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function canonicalAddress(value) {
+  return typeof value === 'string' && /^0x[0-9a-fA-F]{40}$/.test(value)
+    ? value.toLowerCase()
+    : null;
+}
+
+function canonicalBytes32(value) {
+  return typeof value === 'string' && /^0x[0-9a-fA-F]{64}$/.test(value)
+    ? value.toLowerCase()
+    : null;
+}
+
+function canonicalDecimal(value) {
+  return typeof value === 'string' && /^[0-9]+$/.test(value)
+    ? BigInt(value).toString()
+    : null;
+}
+
+function canonicalNetwork(value) {
+  if (typeof value !== 'string') return null;
+  const match = /^eip155:([0-9]+)$/.exec(value);
+  return match ? `eip155:${BigInt(match[1]).toString()}` : null;
+}
+
+function authorizationClaim(paymentPayload, paymentRequirements) {
+  if (!isObject(paymentPayload) || !isObject(paymentRequirements)) return null;
+  const inner = paymentPayload.payload;
+  const extra = paymentRequirements.extra;
+  if (!isObject(inner) || !isObject(extra)) return null;
+  const authorization = inner.authorization;
+  const openpay = extra.openpay;
+  if (!isObject(authorization) || !isObject(openpay)) return null;
+
+  const network = canonicalNetwork(paymentPayload.network);
+  const asset = canonicalAddress(paymentRequirements.asset);
+  const from = canonicalAddress(authorization.from);
+  const forwarder = canonicalAddress(openpay.forwarder);
+  const merchant = canonicalAddress(openpay.merchant);
+  const merchantValue = canonicalDecimal(openpay.merchantValue);
+  const feeReceiver = canonicalAddress(openpay.feeReceiver);
+  const feeValue = canonicalDecimal(openpay.feeValue);
+  const validAfter = canonicalDecimal(authorization.validAfter);
+  const validBefore = canonicalDecimal(authorization.validBefore);
+  const intentSalt = canonicalBytes32(authorization.intentSalt);
+  const parts = [
+    network,
+    asset,
+    from,
+    forwarder,
+    merchant,
+    merchantValue,
+    feeReceiver,
+    feeValue,
+    validAfter,
+    validBefore,
+    intentSalt,
+  ];
+  if (parts.some((part) => part === null)) return null;
+  return {
+    key: JSON.stringify(parts),
+    validBefore: BigInt(validBefore),
+  };
+}
+
 export function createJpycGate({
   resourceUrl,
   openpayOrigin = DEFAULT_OPENPAY_ORIGIN,
   fetchImpl = globalThis.fetch,
   now = Date.now,
+  maxUpstreamSeconds = DEFAULT_MAX_UPSTREAM_SECONDS,
+  settlementGraceSeconds = DEFAULT_SETTLEMENT_GRACE_SECONDS,
 }) {
+  if (!Number.isSafeInteger(maxUpstreamSeconds) || maxUpstreamSeconds < 0) {
+    throw new Error('maxUpstreamSeconds must be a non-negative integer');
+  }
+  if (
+    !Number.isSafeInteger(settlementGraceSeconds) ||
+    settlementGraceSeconds <= 0
+  ) {
+    throw new Error('settlementGraceSeconds must be a positive integer');
+  }
+  if (!Number.isSafeInteger(maxUpstreamSeconds + settlementGraceSeconds)) {
+    throw new Error('reservation validity window must be a safe integer');
+  }
   const origin = openpayOrigin.replace(/\/+$/, '');
   let acceptsCache = null;
   let acceptsCachedAt = 0;
+  const authorizationClaims = new Map();
+
+  function claimAuthorization(paymentPayload, paymentRequirements) {
+    const claim = authorizationClaim(paymentPayload, paymentRequirements);
+    if (claim === null) return { ok: true, claim: null };
+
+    const nowSec = BigInt(Math.ceil(now() / 1000));
+    for (const [key, existing] of authorizationClaims) {
+      if (existing.validBefore <= nowSec) authorizationClaims.delete(key);
+    }
+
+    const requiredValidity = BigInt(
+      maxUpstreamSeconds + settlementGraceSeconds,
+    );
+    if (claim.validBefore - nowSec < requiredValidity) {
+      return { ok: false, reason: 'insufficient_validity_window' };
+    }
+    if (authorizationClaims.has(claim.key)) {
+      return { ok: false, reason: 'authorization_reserved' };
+    }
+
+    const owner = Symbol();
+    authorizationClaims.set(claim.key, {
+      owner,
+      validBefore: claim.validBefore,
+    });
+    return { ok: true, claim: { key: claim.key, owner } };
+  }
+
+  function releaseAuthorization(claim) {
+    if (
+      claim !== null &&
+      authorizationClaims.get(claim.key)?.owner === claim.owner
+    ) {
+      authorizationClaims.delete(claim.key);
+    }
+  }
 
   async function catalogAccepts() {
     if (
@@ -50,7 +171,12 @@ export function createJpycGate({
     return acceptsCache;
   }
 
-  async function facilitator(path, paymentPayload, paymentRequirements) {
+  async function facilitator(
+    path,
+    paymentPayload,
+    paymentRequirements,
+    reservationToken,
+  ) {
     const response = await fetchImpl(`${origin}/api/facilitator/${path}`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
@@ -58,6 +184,7 @@ export function createJpycGate({
         x402Version: 1,
         paymentPayload,
         paymentRequirements,
+        ...(reservationToken === undefined ? {} : { reservationToken }),
       }),
     });
     return response.json();
@@ -79,17 +206,34 @@ export function createJpycGate({
     }
 
     const paymentRequirements = accepts[0];
-    const verification = await facilitator(
-      'verify',
-      paymentPayload,
-      paymentRequirements,
-    );
+    const claimed = claimAuthorization(paymentPayload, paymentRequirements);
+    if (!claimed.ok) return json402(accepts, claimed.reason);
+
+    let verification;
+    try {
+      verification = await facilitator(
+        'verify',
+        paymentPayload,
+        paymentRequirements,
+      );
+    } catch (error) {
+      releaseAuthorization(claimed.claim);
+      throw error;
+    }
     if (verification.isValid !== true) {
+      releaseAuthorization(claimed.claim);
       return json402(
         accepts,
         verification.invalidReason || 'payment_invalid',
       );
     }
+    // 検証成功後は settle の結果にかかわらず期限まで claim を残し、結果不明や再試行が
+    // 同じ authorization で別の upstream 実行へ波及するのを断つ。
+    const reservationToken =
+      typeof verification.reservationToken === 'string' &&
+      verification.reservationToken.length > 0
+        ? verification.reservationToken
+        : undefined;
 
     return {
       async settle() {
@@ -97,6 +241,7 @@ export function createJpycGate({
           'settle',
           paymentPayload,
           paymentRequirements,
+          reservationToken,
         );
         if (settlement.success !== true) {
           return json402(

package/src/guards.mjs

@@ -1,5 +1,8 @@
 import { formatUnits, isHex } from 'viem';
-import { normalizePaymentRequirements } from './payment.mjs';
+import {
+  MAX_AUTHORIZATION_TIMEOUT_SECONDS,
+  normalizePaymentRequirements,
+} from './payment.mjs';
 import {
   parseSignerOptions,
   readSignerMode,
@@ -9,6 +12,10 @@ import {
 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;
+// OpenPay facilitator の有効期限上限 (20分) より長い authorization を設定で
+// 許可すると、売り手が facilitator を迂回して後日直接 settle できる波及を残す。
+export const MAX_SUPPORTED_TIMEOUT_SECONDS = MAX_AUTHORIZATION_TIMEOUT_SECONDS;
 export const DEFAULT_ALLOWED_HOSTS = 'open-pay.jp';
 // カタログ信頼 (既定 ON): OpenPay の審査済みカタログ (/api/discovery) に載っている URL への
 // 支払いを、ALLOWED_HOSTS への手動追加なしで許可する。掲載は 402 ゲート実在 + OpenPay 方式
@@ -23,8 +30,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',
@@ -35,6 +44,7 @@ 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',
   // catalog trust 経由 (第三者ドメイン) の URL で、支払い時にライブ fetch した accept が
@@ -42,14 +52,35 @@ export const REASONS = {
   catalogAcceptMismatch: 'catalog_accept_mismatch',
 };
 
-export const SUPPORTED_NETWORKS = new Set([
-  'eip155:137',
-  'eip155:80002',
-  'eip155:8217',
-  'eip155:1001',
-  'eip155:43114',
-  'eip155:43113',
-]);
+const JPYC_V3_ADDRESS = '0xE7C3D8C9a439feDe00D2600032D5dB0Be71C3c29';
+const JPYC_V3_DEFINITION = Object.freeze({
+  address: JPYC_V3_ADDRESS,
+  name: 'JPY Coin',
+  version: '1',
+  decimals: JPYC_DECIMALS,
+});
+
+// Buyer が署名してよい JPYC v3 domain の単一情報源。asset と自己申告 metadata を
+// network ごとの既知値へ束縛し、allowlist 済み売り手が別 token の署名を得る波及を断つ。
+export const SUPPORTED_JPYC_ASSETS = Object.freeze({
+  'eip155:137': JPYC_V3_DEFINITION,
+  'eip155:80002': JPYC_V3_DEFINITION,
+  'eip155:8217': JPYC_V3_DEFINITION,
+  'eip155:1001': JPYC_V3_DEFINITION,
+  'eip155:43114': JPYC_V3_DEFINITION,
+  'eip155:43113': JPYC_V3_DEFINITION,
+});
+
+export const SUPPORTED_NETWORKS = new Set(Object.keys(SUPPORTED_JPYC_ASSETS));
+
+// OpenPay が deploy 済みとして公開している Eip3009Forwarder。未掲載 chain の
+// forwarder は審査済み catalog accept との完全一致が取れた場合だけ許可する。
+// ホスト allowlist だけで署名の `to` を攻撃者 EOA へ差し替え、表示した分配を
+// 迂回して総額を直接受領する波及を断つ。
+export const SUPPORTED_JPYC_FORWARDERS = Object.freeze({
+  'eip155:137': '0x0F4560a777415580F0680F8B56a79B0022C6B848',
+  'eip155:80002': '0x752B7AaD0089286EB7b553d84D05233d80c9FCB4',
+});
 
 function nonEmpty(raw) {
   return typeof raw === 'string' && raw.length > 0 ? raw : undefined;
@@ -63,6 +94,21 @@ function isObject(value) {
   return typeof value === 'object' && value !== null;
 }
 
+function parseMaxTimeoutSeconds(value, label) {
+  const parsed =
+    typeof value === 'string' && /^[0-9]+$/.test(value) ? Number(value) : value;
+  if (
+    !Number.isSafeInteger(parsed) ||
+    parsed <= 0 ||
+    parsed > MAX_SUPPORTED_TIMEOUT_SECONDS
+  ) {
+    throw new Error(
+      `${label} must be an integer between 1 and ${MAX_SUPPORTED_TIMEOUT_SECONDS}`,
+    );
+  }
+  return parsed;
+}
+
 export function parseJpycToAtomic(value, label) {
   const raw = typeof value === 'number' ? String(value) : value;
   if (typeof raw !== 'string' || !/^[0-9]+(?:\.[0-9]{1,18})?$/.test(raw)) {
@@ -121,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();
 }
 
@@ -141,6 +198,10 @@ export function readMoneyConfig(env = process.env) {
       nonEmpty(env.MAX_SESSION_JPYC) ?? DEFAULT_MAX_SESSION_JPYC,
       'MAX_SESSION_JPYC',
     ),
+    maxTimeoutSeconds: parseMaxTimeoutSeconds(
+      nonEmpty(env.MAX_TIMEOUT_SECONDS) ?? DEFAULT_MAX_TIMEOUT_SECONDS,
+      'MAX_TIMEOUT_SECONDS',
+    ),
     maxDailyAtomic:
       nonEmpty(env.MAX_DAILY_JPYC) === undefined
         ? null
@@ -156,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',
     ),
@@ -204,13 +265,17 @@ export function parseClientOptions(options = {}) {
       optionAmount(options.maxSessionJpyc, DEFAULT_MAX_SESSION_JPYC),
       'MAX_SESSION_JPYC',
     ),
+    maxTimeoutSeconds: parseMaxTimeoutSeconds(
+      optionAmount(options.maxTimeoutSeconds, DEFAULT_MAX_TIMEOUT_SECONDS),
+      'maxTimeoutSeconds',
+    ),
     maxDailyAtomic:
       options.maxDailyJpyc === undefined || options.maxDailyJpyc === ''
         ? null
         : 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',
     ),
@@ -250,12 +315,17 @@ function reasonFromNormalizeError(error) {
   return REASONS.invalidAccept;
 }
 
-function addAssetReasons(reasons, rawAccept) {
+function addAssetReasons(reasons, rawAccept, accept) {
   const extra = isObject(rawAccept) ? rawAccept.extra : undefined;
+  const expected =
+    accept === null ? undefined : SUPPORTED_JPYC_ASSETS[accept.network];
   if (
+    expected === undefined ||
+    accept.asset !== expected.address ||
     !isObject(extra) ||
-    extra.name !== 'JPY Coin' ||
-    extra.decimals !== JPYC_DECIMALS
+    extra.name !== expected.name ||
+    extra.version !== expected.version ||
+    extra.decimals !== expected.decimals
   ) {
     reasons.push(REASONS.invalidJpycAsset);
   }
@@ -326,7 +396,7 @@ export function validateAcceptForPayment(rawAccept, requestUrl) {
   if (accept !== null && !SUPPORTED_NETWORKS.has(accept.network)) {
     reasons.push(REASONS.unsupportedNetwork);
   }
-  addAssetReasons(reasons, rawAccept);
+  addAssetReasons(reasons, rawAccept, accept);
   addResourceReason(reasons, rawAccept, requestUrl);
 
   return {
@@ -338,7 +408,7 @@ export function validateAcceptForPayment(rawAccept, requestUrl) {
 }
 
 // catalog trust の掲載 accept (discovery = OpenPay サーバー権威) とライブ accept が、金銭に効く
-// 全フィールド (asset/forwarder/受取先/各金額/commit) まで一致するかを照合する。第三者ドメインが
+// 全フィールド (asset/有効期限/forwarder/受取先/各金額/commit) まで一致するかを照合する。第三者ドメインが
 // 掲載時と別の forwarder/asset を bait-and-switch して buyer に攻撃者宛の署名を作らせる P0 を塞ぐ。
 // どちらかが正規化不能なら不一致 (fail-close)。
 function catalogAcceptConsistent(liveRawAccept, listedRawAccept) {
@@ -348,6 +418,7 @@ function catalogAcceptConsistent(liveRawAccept, listedRawAccept) {
     return (
       a.network === b.network &&
       a.asset === b.asset &&
+      a.maxTimeoutSeconds === b.maxTimeoutSeconds &&
       a.extra.openpay.forwarder === b.extra.openpay.forwarder &&
       a.extra.openpay.merchant === b.extra.openpay.merchant &&
       a.extra.openpay.merchantValue === b.extra.openpay.merchantValue &&
@@ -390,31 +461,39 @@ export function evaluatePaymentGuards({
 }) {
   const reasons = [];
   const maxDailyAtomic = config.maxDailyAtomic ?? null;
+  const configuredMaxTimeoutSeconds =
+    config.maxTimeoutSeconds ?? DEFAULT_MAX_TIMEOUT_SECONDS;
+  // 公開 primitive では config を手組みできるため、parser を迂回した不正な上限値が
+  // authorization の絶対上限を広げる波及を断ち、無効値は 0 扱いで fail-close する。
+  const maxTimeoutSeconds =
+    Number.isSafeInteger(configuredMaxTimeoutSeconds) &&
+    configuredMaxTimeoutSeconds > 0
+      ? Math.min(
+          configuredMaxTimeoutSeconds,
+          MAX_SUPPORTED_TIMEOUT_SECONDS,
+        )
+      : 0;
   const parsedUrl = parseHttpUrl(url, 'url');
+  let catalogAcceptMatches = false;
   if (parsedUrl === null) {
     reasons.push(REASONS.invalidUrl);
   } else {
     const hostAllowed = config.allowedHosts.includes(parsedUrl.hostname.toLowerCase());
-    // 完全一致を先に維持し、miss 時だけ query/hash を除いた同一 origin+pathname を引く。
-    // userinfo は origin に含まれないため、query variant ではない credential 付き URL へは緩和しない。
+    // catalog admission は完全一致だけ。query-free 掲載を任意 query へ広げると、
+    // GET 副作用を持つ未審査 URL へ buyer を到達させる波及が残る。
     let listedAccept;
     if (config.catalogTrust && catalogListings instanceof Map) {
       listedAccept = catalogListings.get(parsedUrl.toString());
-      if (
-        listedAccept === undefined &&
-        parsedUrl.username === '' &&
-        parsedUrl.password === ''
-      ) {
-        listedAccept = catalogListings.get(`${parsedUrl.origin}${parsedUrl.pathname}`);
-      }
     }
     const catalogListed = listedAccept !== undefined;
+    catalogAcceptMatches =
+      catalogListed && catalogAcceptConsistent(accept, listedAccept);
     if (!hostAllowed && !catalogListed) {
       reasons.push(REASONS.hostNotAllowed);
     } else if (!hostAllowed && catalogListed) {
       // ALLOWED_HOSTS 直 (open-pay.jp) はサーバー権威ゆえ照合不要。catalog trust 経由 (第三者
       // ドメイン) でのみ、ライブ accept が掲載 accept と金銭フィールドまで一致するか照合する。
-      if (!catalogAcceptConsistent(accept, listedAccept)) {
+      if (!catalogAcceptMatches) {
         reasons.push(REASONS.catalogAcceptMismatch);
       }
     }
@@ -422,6 +501,16 @@ export function evaluatePaymentGuards({
 
   const acceptValidation = validateAcceptForPayment(accept, url);
   reasons.push(...acceptValidation.reasons);
+  if (acceptValidation.accept !== null) {
+    const knownForwarder =
+      SUPPORTED_JPYC_FORWARDERS[acceptValidation.accept.network];
+    if (
+      acceptValidation.accept.extra.openpay.forwarder !== knownForwarder &&
+      !catalogAcceptMatches
+    ) {
+      reasons.push(REASONS.invalidOpenpayForwarder);
+    }
+  }
 
   let maxTotalAtomic = null;
   if (requireMaxTotal) {
@@ -451,6 +540,13 @@ export function evaluatePaymentGuards({
     }
   }
 
+  if (
+    acceptValidation.accept !== null &&
+    acceptValidation.accept.maxTimeoutSeconds > maxTimeoutSeconds
+  ) {
+    reasons.push(REASONS.timeoutTooLong);
+  }
+
   if (maxDailyAtomic !== null && dailySpentAtomic === null) {
     reasons.push(REASONS.dailySpendUnavailable);
   }

package/src/index.mjs

@@ -1,8 +1,12 @@
 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';
+export * from './network.mjs';
 export * from './payment.mjs';
+export * from './receipt.mjs';
 export * from './signer.mjs';
 export * from './spendStore.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;
+    },
+  };
+}