openpay-x402-sdk 0.5.0 → 0.7.0

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) };
     }
   }