openpay-x402-sdk 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.4.0
+
+- Add an opt-in persistent daily buyer limit with UTC signer/date keys, file and
+  injectable spend stores, quote-time visibility, and fail-closed reads.
+- Record daily spend only after successful 2xx unlocks while isolating store
+  write failures from already completed payment responses.
+
+## 0.3.0
+
+- Add `createJpycGate` for seller-side x402 gates backed by the OpenPay catalog,
+  including five-minute `accepts` caching and request-specific resource URLs.
+- Support both one-shot verify-to-settle handling and split verification followed
+  by settlement after an expensive upstream operation succeeds.
+- Use Edge-compatible UTF-8 base64 handling for payment and settlement headers.
+
 ## 0.2.1
 
 - Compare `accept.resource` against the requested URL using decoded query

package/README.md

@@ -16,6 +16,7 @@ const client = createOpenPayClient({
   privateKey: process.env.BUYER_PRIVATE_KEY,
   maxPerCallJpyc: '10',
   maxSessionJpyc: '100',
+  maxDailyJpyc: '250',
   allowedHosts: 'open-pay.jp',
 });
 
@@ -32,12 +33,74 @@ inside `{ ok, status, body }`. `quote()` fetches and validates a 402 challenge b
 does not need a signer and never pays. `pay()` requires a signer and serializes
 concurrent calls so every call sees the latest session total.
 
+## Sell with the SDK
+
+Create a gate with the exact resource URL registered in OpenPay discovery. For
+inexpensive content, `handle()` verifies and settles the payment in one call:
+
+```js
+import { createJpycGate } from 'openpay-x402-sdk';
+
+const gate = createJpycGate({
+  resourceUrl: process.env.MY_RESOURCE_URL,
+});
+
+export async function GET(request) {
+  const payment = await gate.handle(request);
+  if (payment instanceof Response) return payment;
+
+  const response = Response.json({ your: 'paid content' });
+  response.headers.set(
+    'X-PAYMENT-RESPONSE',
+    payment.paymentResponseHeader,
+  );
+  return response;
+}
+```
+
+For an expensive upstream operation, verify first and settle only after the
+operation succeeds. If `callUpstream()` fails, return an error before calling
+`settle()` so the buyer remains uncharged:
+
+```js
+export async function GET(request) {
+  const payment = await gate.verify(request);
+  if (payment instanceof Response) return payment;
+
+  let data;
+  try {
+    data = await callUpstream();
+  } catch {
+    return Response.json({ error: 'upstream_failed' }, { status: 502 });
+  }
+
+  const settlement = await payment.settle();
+  if (settlement instanceof Response) return settlement;
+
+  const response = Response.json(data);
+  response.headers.set(
+    'X-PAYMENT-RESPONSE',
+    settlement.paymentResponseHeader,
+  );
+  return response;
+}
+```
+
+`createJpycGate` fetches `accepts` from `/api/discovery` and caches it for five
+minutes. Until `resourceUrl` is listed with a non-empty `accepts`, `handle()` and
+`verify()` throw; map that bootstrap condition to an HTTP 500 response. Pass
+`openpayOrigin` to use an origin other than `https://open-pay.jp`.
+
+The copy-paste paywall snippet generated by OpenPay provides the same one-shot
+gate; `createJpycGate` is its importable SDK counterpart with split settlement.
+
 ## 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. |
+| `maxDailyJpyc` | Not set | Persistent cumulative cap per signer and UTC calendar date. |
 | `allowedHosts` | `open-pay.jp` | Comma-separated bare host allowlist. |
 | `catalogTrust` | `true` | Also allows 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. |
@@ -48,7 +111,21 @@ money-field verification. Exact query-bearing catalog entries remain exact-only.
 `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`; all three limits must allow the payment.
+`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.
 
 The client also rejects non-JPYC metadata, unsupported networks or schemes,
 non-OpenPay forwarder splits, amount inconsistencies, resource URL mismatches,

package/index.d.ts

@@ -37,13 +37,41 @@ export interface PaymentSigner {
   signTypedData(typedData: PaymentTypedData): Hex | Promise<Hex>;
 }
 
+export interface SpendStore {
+  /**
+   * Return the atomic JPYC spent for the key, `'0'` when no record exists, or
+   * `null` only on read failure. `null` fails closed (payments are refused),
+   * so an absent entry must be reported as `'0'`, never `null`.
+   */
+  load(key: string): Promise<string | null>;
+  /** Persist the new cumulative atomic amount. Failures must not throw. */
+  save(key: string, atomicString: string): Promise<void>;
+}
+
+export interface FileSpendStoreOptions {
+  path?: string;
+  fsImpl?: {
+    readFile(path: string, encoding: 'utf8'): Promise<string>;
+    mkdir(path: string, options: { recursive: true }): Promise<unknown>;
+    writeFile(
+      path: string,
+      data: string,
+      encoding: 'utf8',
+    ): Promise<unknown>;
+  };
+}
+
 interface ClientCommonOptions {
   maxPerCallJpyc?: JpycAmount;
   maxSessionJpyc?: JpycAmount;
+  maxDailyJpyc?: JpycAmount;
+  spendStore?: SpendStore;
   allowedHosts?: string;
   catalogTrust?: boolean;
   discoveryUrl?: string;
   fetchImpl?: typeof globalThis.fetch;
+  nowSec?: () => number;
+  now?: () => Date | number;
 }
 
 type NoSignerOptions = {
@@ -85,6 +113,7 @@ export interface RuntimeConfig {
   stewardSignerSecret: string | null;
   maxPerCallAtomic: bigint;
   maxSessionAtomic: bigint;
+  maxDailyAtomic: bigint | null;
   allowedHosts: string[];
   catalogTrust: boolean;
   discoveryUrl: string;
@@ -194,6 +223,28 @@ export function createOpenPayClient(
   options?: OpenPayClientOptions,
 ): OpenPayClient;
 
+export interface JpycGateOptions {
+  resourceUrl: string;
+  openpayOrigin?: string;
+  fetchImpl?: typeof globalThis.fetch;
+  now?: () => number;
+}
+
+export interface JpycGatePaymentResponse {
+  paymentResponseHeader: string;
+}
+
+export interface VerifiedJpycPayment {
+  settle(): Promise<Response | JpycGatePaymentResponse>;
+}
+
+export interface JpycGate {
+  handle(request: Request): Promise<Response | JpycGatePaymentResponse>;
+  verify(request: Request): Promise<Response | VerifiedJpycPayment>;
+}
+
+export function createJpycGate(options: JpycGateOptions): JpycGate;
+
 export const RECEIVE_WITH_AUTHORIZATION_TYPES: {
   ReceiveWithAuthorization: Array<{ name: string; type: string }>;
 };
@@ -299,6 +350,8 @@ export const REASONS: {
   maxTotalAbovePerCallLimit: 'max_total_above_per_call_limit';
   perCallLimitExceeded: 'per_call_limit_exceeded';
   sessionLimitExceeded: 'session_limit_exceeded';
+  dailyLimitExceeded: 'daily_limit_exceeded';
+  dailySpendUnavailable: 'daily_spend_unavailable';
   buyerPrivateKeyMissing: 'buyer_private_key_missing';
   stewardSignerUnconfigured: 'steward_signer_unconfigured';
   catalogAcceptMismatch: 'catalog_accept_mismatch';
@@ -336,6 +389,9 @@ export function parseClientOptions(
   options?: OpenPayClientOptions,
 ): RuntimeConfig;
 export function createPaymentSession(initialSpentAtomic?: bigint): PaymentSession;
+export function createFileSpendStore(
+  options?: FileSpendStoreOptions,
+): SpendStore;
 export function recordSuccessfulPayment(
   session: PaymentSession,
   amountAtomic: bigint,
@@ -353,6 +409,7 @@ export function evaluatePaymentGuards(options: {
   accept: unknown;
   config: Omit<RuntimeConfig, 'discoveryUrl'> | RuntimeConfig;
   sessionSpentAtomic?: bigint;
+  dailySpentAtomic?: bigint | null;
   maxTotalJpyc?: JpycAmount;
   requireMaxTotal?: boolean;
   requirePrivateKey?: boolean;
@@ -422,7 +479,10 @@ export function createPaymentExecutor(options: {
   config: RuntimeConfig;
   session: PaymentSession;
   signer?: PaymentSigner | null;
+  signerAddress?: Address | null;
+  spendStore?: SpendStore | null;
   fetchImpl?: typeof globalThis.fetch;
   nowSec?: () => number;
+  now?: () => Date | number;
   resolveCatalogListings?: () => Promise<Map<string, unknown> | null>;
 }): PaymentExecutor;

package/package.json

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

package/src/client.mjs

@@ -7,6 +7,7 @@ import {
   safeErrorMessage,
 } from './guards.mjs';
 import { createSignerFromOptions } from './signer.mjs';
+import { createFileSpendStore } from './spendStore.mjs';
 
 function isObject(value) {
   return typeof value === 'object' && value !== null;
@@ -63,13 +64,20 @@ export function createOpenPayClient(options = {}) {
   }
   const signer = createSignerFromOptions(options, { fetchImpl });
   const session = createPaymentSession();
+  const spendStore =
+    config.maxDailyAtomic === null
+      ? null
+      : options.spendStore ?? createFileSpendStore();
   const resolveCatalogListings = createCatalogResolver({ config, fetchImpl });
   const executor = createPaymentExecutor({
     config,
     session,
     signer,
+    signerAddress: signer?.address ?? null,
+    spendStore,
     fetchImpl,
     nowSec: options.nowSec,
+    now: options.now,
     resolveCatalogListings,
   });
 

package/src/executor.mjs

@@ -55,10 +55,54 @@ export function createPaymentExecutor({
   config,
   session,
   signer = null,
+  signerAddress = signer?.address ?? null,
+  spendStore = null,
   fetchImpl = fetch,
   nowSec = () => Math.floor(Date.now() / 1000),
+  now = () => new Date(),
   resolveCatalogListings = async () => null,
 }) {
+  const dailyLimitEnabled =
+    config.maxDailyAtomic !== null &&
+    config.maxDailyAtomic !== undefined &&
+    spendStore !== null;
+  const guardConfig =
+    !dailyLimitEnabled && config.maxDailyAtomic != null
+      ? { ...config, maxDailyAtomic: null }
+      : config;
+
+  async function loadDailySpend() {
+    if (!dailyLimitEnabled || typeof signerAddress !== 'string') {
+      return { key: null, spentAtomic: null };
+    }
+    const current = now();
+    const date = (current instanceof Date ? current : new Date(current))
+      .toISOString()
+      .slice(0, 10);
+    const key = `${signerAddress.toLowerCase()}:${date}`;
+    try {
+      const stored = await spendStore.load(key);
+      if (typeof stored !== 'string' || !/^[0-9]+$/.test(stored)) {
+        return { key, spentAtomic: null };
+      }
+      return { key, spentAtomic: BigInt(stored) };
+    } catch {
+      return { key, spentAtomic: null };
+    }
+  }
+
+  async function saveDailySpend(dailySpend, amountAtomic) {
+    if (dailySpend.key === null || dailySpend.spentAtomic === null) return;
+    try {
+      await spendStore.save(
+        dailySpend.key,
+        (dailySpend.spentAtomic + amountAtomic).toString(),
+      );
+    } catch {
+      // The unlock already succeeded; store failure must not replace the payment response.
+    }
+  }
+
   async function quoteImpl(url) {
     if (typeof url !== 'string') throw new Error('url is required');
     const response = await fetchImpl(url, {
@@ -74,11 +118,13 @@ export function createPaymentExecutor({
         reasons: ['expected_402_with_accepts'],
       };
     }
+    const dailySpend = dailyLimitEnabled ? await loadDailySpend() : null;
     const guard = evaluatePaymentGuards({
       url,
       accept,
-      config,
+      config: guardConfig,
       sessionSpentAtomic: session.spentAtomic,
+      dailySpentAtomic: dailySpend?.spentAtomic ?? null,
       catalogListings: await resolveCatalogListings(),
     });
     return quoteShape(url, response.status, guard);
@@ -107,11 +153,13 @@ export function createPaymentExecutor({
         reasons: ['expected_402_with_accepts'],
       };
     }
+    const dailySpend = dailyLimitEnabled ? await loadDailySpend() : null;
     const guard = evaluatePaymentGuards({
       url,
       accept,
-      config,
+      config: guardConfig,
       sessionSpentAtomic: session.spentAtomic,
+      dailySpentAtomic: dailySpend?.spentAtomic ?? null,
       maxTotalJpyc,
       requireMaxTotal: true,
       requireSigner: true,
@@ -142,6 +190,9 @@ export function createPaymentExecutor({
     const unlockedBody = await readJson(unlocked);
     if (unlocked.status >= 200 && unlocked.status < 300) {
       recordSuccessfulPayment(session, guard.summary.totalAtomic);
+      if (dailySpend !== null) {
+        await saveDailySpend(dailySpend, guard.summary.totalAtomic);
+      }
     }
     const receipt = decodePaymentResponse(
       unlocked.headers.get('x-payment-response'),

package/src/gate.mjs

@@ -0,0 +1,119 @@
+const DEFAULT_OPENPAY_ORIGIN = 'https://open-pay.jp';
+const ACCEPTS_CACHE_MS = 5 * 60_000;
+
+function json402(accepts, error) {
+  return new Response(JSON.stringify({ x402Version: 1, accepts, error }), {
+    status: 402,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+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 createJpycGate({
+  resourceUrl,
+  openpayOrigin = DEFAULT_OPENPAY_ORIGIN,
+  fetchImpl = globalThis.fetch,
+  now = Date.now,
+}) {
+  const origin = openpayOrigin.replace(/\/+$/, '');
+  let acceptsCache = null;
+  let acceptsCachedAt = 0;
+
+  async function catalogAccepts() {
+    if (
+      acceptsCache !== null &&
+      now() - acceptsCachedAt < ACCEPTS_CACHE_MS
+    ) {
+      return acceptsCache;
+    }
+
+    const response = await fetchImpl(`${origin}/api/discovery`);
+    const { items } = await response.json();
+    const mine = (items || []).find((item) => item.resource === resourceUrl);
+    if (!mine || !mine.accepts || mine.accepts.length === 0) {
+      throw new Error(`resource not found in OpenPay catalog: ${resourceUrl}`);
+    }
+    acceptsCache = mine.accepts;
+    acceptsCachedAt = now();
+    return acceptsCache;
+  }
+
+  async function facilitator(path, paymentPayload, paymentRequirements) {
+    const response = await fetchImpl(`${origin}/api/facilitator/${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        x402Version: 1,
+        paymentPayload,
+        paymentRequirements,
+      }),
+    });
+    return response.json();
+  }
+
+  async function verify(request) {
+    const accepts = (await catalogAccepts()).map((accept) => ({
+      ...accept,
+      resource: request.url,
+    }));
+    const header = request.headers.get('x-payment');
+    if (!header) return json402(accepts, 'payment_required');
+
+    let paymentPayload;
+    try {
+      paymentPayload = decodeBase64Json(header);
+    } catch {
+      return json402(accepts, 'invalid_payment_payload');
+    }
+
+    const paymentRequirements = accepts[0];
+    const verification = await facilitator(
+      'verify',
+      paymentPayload,
+      paymentRequirements,
+    );
+    if (verification.isValid !== true) {
+      return json402(
+        accepts,
+        verification.invalidReason || 'payment_invalid',
+      );
+    }
+
+    return {
+      async settle() {
+        const settlement = await facilitator(
+          'settle',
+          paymentPayload,
+          paymentRequirements,
+        );
+        if (settlement.success !== true) {
+          return json402(
+            accepts,
+            settlement.errorReason || 'settlement_failed',
+          );
+        }
+        return { paymentResponseHeader: encodeBase64Json(settlement) };
+      },
+    };
+  }
+
+  async function handle(request) {
+    const verification = await verify(request);
+    if (verification instanceof Response) return verification;
+    return verification.settle();
+  }
+
+  return { handle, verify };
+}

package/src/guards.mjs

@@ -33,6 +33,8 @@ export const REASONS = {
   maxTotalAbovePerCallLimit: 'max_total_above_per_call_limit',
   perCallLimitExceeded: 'per_call_limit_exceeded',
   sessionLimitExceeded: 'session_limit_exceeded',
+  dailyLimitExceeded: 'daily_limit_exceeded',
+  dailySpendUnavailable: 'daily_spend_unavailable',
   buyerPrivateKeyMissing: 'buyer_private_key_missing',
   stewardSignerUnconfigured: 'steward_signer_unconfigured',
   // catalog trust 経由 (第三者ドメイン) の URL で、支払い時にライブ fetch した accept が
@@ -139,6 +141,10 @@ export function readMoneyConfig(env = process.env) {
       nonEmpty(env.MAX_SESSION_JPYC) ?? DEFAULT_MAX_SESSION_JPYC,
       'MAX_SESSION_JPYC',
     ),
+    maxDailyAtomic:
+      nonEmpty(env.MAX_DAILY_JPYC) === undefined
+        ? null
+        : parseJpycToAtomic(env.MAX_DAILY_JPYC, 'MAX_DAILY_JPYC'),
     allowedHosts: parseAllowedHosts(env.ALLOWED_HOSTS),
     catalogTrust:
       env.CATALOG_TRUST === undefined || env.CATALOG_TRUST === ''
@@ -198,6 +204,10 @@ export function parseClientOptions(options = {}) {
       optionAmount(options.maxSessionJpyc, DEFAULT_MAX_SESSION_JPYC),
       'MAX_SESSION_JPYC',
     ),
+    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(
@@ -368,6 +378,7 @@ export function evaluatePaymentGuards({
   accept,
   config,
   sessionSpentAtomic = 0n,
+  dailySpentAtomic = null,
   maxTotalJpyc,
   requireMaxTotal = false,
   requirePrivateKey = false,
@@ -378,6 +389,7 @@ export function evaluatePaymentGuards({
   catalogListings = null,
 }) {
   const reasons = [];
+  const maxDailyAtomic = config.maxDailyAtomic ?? null;
   const parsedUrl = parseHttpUrl(url, 'url');
   if (parsedUrl === null) {
     reasons.push(REASONS.invalidUrl);
@@ -430,6 +442,17 @@ export function evaluatePaymentGuards({
     if (sessionSpentAtomic + total > config.maxSessionAtomic) {
       reasons.push(REASONS.sessionLimitExceeded);
     }
+    if (
+      maxDailyAtomic !== null &&
+      dailySpentAtomic !== null &&
+      dailySpentAtomic + total > maxDailyAtomic
+    ) {
+      reasons.push(REASONS.dailyLimitExceeded);
+    }
+  }
+
+  if (maxDailyAtomic !== null && dailySpentAtomic === null) {
+    reasons.push(REASONS.dailySpendUnavailable);
   }
 
   if (requirePrivateKey || requireSigner) {

package/src/index.mjs

@@ -1,6 +1,8 @@
 export * from './catalog.mjs';
 export * from './client.mjs';
 export * from './executor.mjs';
+export * from './gate.mjs';
 export * from './guards.mjs';
 export * from './payment.mjs';
 export * from './signer.mjs';
+export * from './spendStore.mjs';

package/src/spendStore.mjs

@@ -0,0 +1,86 @@
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isMissingFile(error) {
+  return isObject(error) && error.code === 'ENOENT';
+}
+
+function isAtomicString(value) {
+  return typeof value === 'string' && /^[0-9]+$/.test(value);
+}
+
+export function createFileSpendStore({ path, fsImpl } = {}) {
+  let runtimePromise;
+
+  async function resolveRuntime() {
+    runtimePromise ??= (async () => {
+      const fileSystem = fsImpl ?? (await import('node:fs/promises'));
+      const pathModule = await import('node:path');
+      const targetPath =
+        path ??
+        pathModule.join(
+          (await import('node:os')).homedir(),
+          '.openpay-x402',
+          'spend.json',
+        );
+      return {
+        fileSystem,
+        targetPath,
+        directory: pathModule.dirname(targetPath),
+      };
+    })();
+    return runtimePromise;
+  }
+
+  async function load(key) {
+    try {
+      const { fileSystem, targetPath } = await resolveRuntime();
+      let raw;
+      try {
+        raw = await fileSystem.readFile(targetPath, 'utf8');
+      } catch (error) {
+        return isMissingFile(error) ? '0' : null;
+      }
+      const document = JSON.parse(raw);
+      if (!isObject(document)) return null;
+      const value = document[key];
+      return value === undefined ? '0' : isAtomicString(value) ? value : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async function save(key, atomicString) {
+    try {
+      const { fileSystem, targetPath, directory } = await resolveRuntime();
+      let document = {};
+      try {
+        const raw = await fileSystem.readFile(targetPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (isObject(parsed)) document = parsed;
+      } catch {
+        document = {};
+      }
+
+      const date = key.slice(-10);
+      const current = Object.fromEntries(
+        Object.entries(document).filter(
+          ([storedKey, value]) =>
+            storedKey.endsWith(`:${date}`) && isAtomicString(value),
+        ),
+      );
+      current[key] = atomicString;
+      await fileSystem.mkdir(directory, { recursive: true });
+      await fileSystem.writeFile(
+        targetPath,
+        `${JSON.stringify(current, null, 2)}\n`,
+        'utf8',
+      );
+    } catch {
+      // The payment is already complete; persistence failure must not replace its response.
+    }
+  }
+
+  return { load, save };
+}