openpay-x402-sdk 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.10.2 — unreleased
+
+- Fix `createDualGate` USDC authorization reuse before settlement. Reuse JPYC's
+  local claim manager for v1/v2 payments, keyed by pinned chain, asset, payer and
+  nonce; share the USDC ledger across gate instances and endpoints in one process
+  to reject duplicates before relay verification and upstream execution.
+- Enforce the configured upstream plus settlement validity margin before USDC
+  verify and again before granting upstream work. Reject unclaimable payloads.
+  Release tentative claims on verify rejection/failure; retain claims after
+  verification through upstream abandonment, settlement success, rejection and
+  ambiguous settlement until authorization expiry. Margins remain specific to each
+  calling gate. JPYC behavior/wire is unchanged.
+- Clarify README/types: USDC claims are process-local, are lost on restart, and
+  provide no coordination across processes/isolates. Holding after definitive
+  settlement rejection is deliberate; retrying upstream requires a fresh nonce
+  and signature. Claims do not reserve funds or guarantee settlement.
+  No dependencies added.
+
+## 0.10.1 — 2026-09-23
+
+- Create spend-store directories with mode 0700, including compatibility saves,
+  so an env-key user's spend directory can later hold an MCP keystore without
+  failing its permission checks. Existing directories are never chmod-ed; inspect
+  and manually repair legacy 0755 directories before switching to keystore mode.
+  Mode 0700 also applies to newly created intermediate directories at custom
+  spend-store paths; pre-existing shared/group directories keep their permissions.
+- Preserve spend reservations, locks, accounting and wallet 0600/0700 checks.
+  No dependencies added.
+
 ## 0.10.0 — 2026-09-23
 
 - Breaking: seller gates require a trusted `resourceId` and `expectedRecipient`;
@@ -16,8 +45,7 @@
   `SellerPinError` and still stop both rails.
 - Update seller types, examples and generated snippets. Existing sellers must
   configure pins and redeploy the SDK/snippet; deploy the matching relay update
-  first. No dependencies added. Unpublished; rule-15 human review is required
-  before adoption.
+  first. No dependencies added.
 
 ## 0.9.0 — 2026-09-21
 

package/README.md

@@ -113,13 +113,13 @@ before a 402, verification or settlement; map these errors to an HTTP 500 respon
 Each payment retains its validated requirements through settlement. Pass
 `openpayOrigin` to use an origin other than `https://open-pay.jp`.
 
-Upgrade existing seller deployments to 0.10.0 and configure the required pins,
+Upgrade existing seller deployments to 0.10.2 and configure the required pins,
 or regenerate and redeploy your snippet from your own dashboard. Old installed
 SDKs and pasted snippets remain vulnerable until replaced; a package release does
 not update them. Register the listing, then retrieve its pinned snippet from the
 dashboard before serving payments.
 
-Before `verify()` contacts the facilitator, each gate instance claims a canonical
+Before `verify()` contacts the facilitator, each JPYC gate instance claims a canonical
 authorization identity until its `validBefore` time. Set `maxUpstreamSeconds`
 (default `60`) to the seller's worst-case upstream duration; the gate also
 retains `settlementGraceSeconds` (default `30`) and rejects a duplicate before
@@ -127,9 +127,9 @@ upstream work begins. A failed facilitator verification releases the tentative
 claim, while a successful verification keeps it through settlement so an
 unknown settlement result cannot expose the same authorization twice.
 
-The facilitator reservation is an optional additional defense. The gate forwards
+The JPYC facilitator reservation is an optional additional defense. The gate forwards
 its token when one is returned and continues on the established token-less wire
-when it is not. The local claim covers concurrent requests sharing one gate
+when it is not. The JPYC local claim covers concurrent requests sharing one gate
 instance; separate processes or serverless isolates do not share its in-memory
 ledger.
 
@@ -167,7 +167,33 @@ const gate = createDualGate({
 });
 ```
 
-`handle()` / `verify()` work exactly like `createJpycGate`, on both rails.
+`handle()` / `verify()` support the same verify → upstream → settle pattern on
+both rails. Starting in 0.10.2, USDC v1 and v2 requests share a claim keyed by the
+pinned chain and asset plus the authorization's payer and nonce. Header formatting,
+address/nonce casing, request URL and other envelope metadata do not create new
+claims. USDC authorizations are not bound to a resource, so the USDC ledger is
+shared across gate instances and endpoints in the same process. It is lost on
+restart; separate processes and serverless isolates do not coordinate. JPYC
+claims remain per gate instance.
+
+USDC rejects duplicate authorizations with `authorization_reserved` and requires
+at least `maxUpstreamSeconds + settlementGraceSeconds` remaining before relay
+verification and again before returning the upstream capability (defaults: 60 + 30
+seconds). Each call uses its gate's configured margin even though USDC claims
+are shared. Insufficient time returns `insufficient_validity_window`; an unreadable
+authorization identity or expiry returns `invalid_payment_payload`.
+
+Verify rejection or failure releases the tentative USDC claim because upstream
+work has not been authorized and verify cannot settle. After verification grants
+upstream work, the claim remains until `validBefore`, including when upstream is
+abandoned, settlement succeeds, settlement rejects (including a relay 409), or its
+outcome is unknown due to transport/JSON/503 errors. Holding after a definitive
+settle rejection is deliberate: it does not undo upstream work. Even after a
+balance top-up, that signature cannot start new work before `validBefore`; a retry
+requires a newly signed authorization with a fresh nonce. Claims do not reserve
+buyer funds: different nonces may all verify against the same balance and later
+fail to settle. This local claim does not guarantee settlement or replace
+facilitator/on-chain verification, and USDC does not use JPYC's reservation token.
 
 ### Register listings without the web form
 

package/index.d.ts

@@ -322,7 +322,7 @@ export interface JpycGateOptions {
   openpayOrigin?: string;
   fetchImpl?: typeof globalThis.fetch;
   now?: () => number;
-  /** Worst-case seller upstream duration protected by the local claim. Default: 60. */
+  /** Worst-case seller upstream duration; applies to both rails in createDualGate. Default: 60. */
   maxUpstreamSeconds?: number;
   /** Extra validity retained for settlement after upstream work. Default: 30. */
   settlementGraceSeconds?: number;
@@ -515,6 +515,14 @@ export interface DualGateOptions extends JpycGateOptions {
  * relayed to the CDP facilitator via OpenPay). If the USDC face cannot be fetched (relay off
  * or unavailable), the gate degrades to JPYC-only. Identity/recipient mismatches throw and log
  * before any 402 or payment call; they never trigger a rail fallback.
+ * USDC authorizations are not resource-bound: all gate instances in one process share a pinned
+ * chain/asset + payer/nonce ledger, lost on restart and not shared across processes/isolates.
+ * JPYC claims remain per instance. USDC v1/v2 require the calling gate's upstream + settlement
+ * validity margin before relay verify and before granting upstream work. Tentative verify failures
+ * release the claim; after upstream is granted, it remains until validBefore even if upstream is
+ * abandoned or settlement fails/has an unknown outcome. Holding after definitive rejection is
+ * deliberate: retrying upstream requires a fresh nonce/signature. Claims do not reserve buyer
+ * funds or guarantee settlement. USDC has no JPYC reservation token.
  */
 export function createDualGate(options: DualGateOptions): JpycGate;
 

package/package.json

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

package/src/authorizationClaims.mjs

@@ -0,0 +1,143 @@
+// Process-local claims prevent one authorization from starting upstream work twice.
+const DEFAULT_MAX_UPSTREAM_SECONDS = 60;
+const DEFAULT_SETTLEMENT_GRACE_SECONDS = 30;
+
+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;
+}
+
+export function jpycAuthorizationClaim(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 usdcAuthorizationClaim(paymentPayload, paymentRequirements) {
+  const authorization = paymentPayload?.payload?.authorization;
+  if (!isObject(authorization)) return null;
+  // The relay rebuilds the signed domain from these pinned requirements. Untrusted
+  // envelope metadata must not split one on-chain nonce into separate upstream claims.
+  const network = canonicalNetwork(paymentRequirements.network);
+  const asset = canonicalAddress(paymentRequirements.asset);
+  const from = canonicalAddress(authorization.from);
+  const nonce = canonicalBytes32(authorization.nonce);
+  const validBefore = canonicalDecimal(authorization.validBefore);
+  const parts = [network, asset, from, nonce];
+  if (parts.some((part) => part === null) || validBefore === null) return null;
+  return { key: JSON.stringify(parts), validBefore: BigInt(validBefore) };
+}
+
+export function createAuthorizationClaims({
+  now = Date.now,
+  maxUpstreamSeconds = DEFAULT_MAX_UPSTREAM_SECONDS,
+  settlementGraceSeconds = DEFAULT_SETTLEMENT_GRACE_SECONDS,
+} = {}, authorizationClaims = new Map()) {
+  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');
+  }
+  function claimAuthorization(claim) {
+    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);
+    }
+
+    if (!hasValidityWindow(claim, nowSec)) {
+      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) {
+    // An expired verify attempt must not release a newer owner's claim for the same identity.
+    if (
+      claim !== null &&
+      authorizationClaims.get(claim.key)?.owner === claim.owner
+    ) {
+      authorizationClaims.delete(claim.key);
+    }
+  }
+
+  function hasValidityWindow(claim, nowSec = BigInt(Math.ceil(now() / 1000))) {
+    return claim.validBefore - nowSec >= BigInt(maxUpstreamSeconds + settlementGraceSeconds);
+  }
+
+  return { claimAuthorization, releaseAuthorization, hasValidityWindow };
+}

package/src/dualGate.mjs

@@ -12,10 +12,14 @@
 // JPYC レールの 402 には USDC accepts を追記 (decorate) して両面を常に見せる。
 
 import { createJpycGate } from './gate.mjs';
+import { createAuthorizationClaims, usdcAuthorizationClaim } from './authorizationClaims.mjs';
 import { assertSellerPins, SellerPinError, validateUsdcFace } from './sellerPins.mjs';
 
 const DEFAULT_OPENPAY_ORIGIN = 'https://open-pay.jp';
 const USDC_FACE_CACHE_MS = 5 * 60_000;
+// USDC authorizations are not resource-bound: share claims so another endpoint's gate
+// cannot start duplicate upstream work with the same chain/asset/payer/nonce.
+const usdcAuthorizationClaims = new Map();
 
 function decodeBase64Json(value) {
   const binary = atob(value);
@@ -54,6 +58,9 @@ export function createDualGate({
     ...(settlementGraceSeconds === undefined ? {} : { settlementGraceSeconds }),
   });
   const origin = openpayOrigin.replace(/\/+$/, '');
+  const { claimAuthorization, releaseAuthorization, hasValidityWindow } = createAuthorizationClaims({
+    now, maxUpstreamSeconds, settlementGraceSeconds,
+  }, usdcAuthorizationClaims);
 
   let usdcCache = null;
   let usdcCachedAt = 0;
@@ -152,6 +159,19 @@ export function createDualGate({
 
     if (usdcRail) {
       const jpycAccepts = await availableJpycAccepts(request);
+      let paymentPayload;
+      try {
+        paymentPayload = decodeBase64Json(signatureHeader || v1Header);
+      } catch {
+        // A malformed preferred header must not bypass the claim via the other rail/header.
+        return usdcChallenge(usdc, jpycAccepts, 'invalid_payment_payload');
+      }
+      const authorization = usdcAuthorizationClaim(paymentPayload, usdc.v2Accept);
+      // Without a usable identity/expiry, verification cannot safely grant upstream work.
+      if (authorization === null) return usdcChallenge(usdc, jpycAccepts, 'invalid_payment_payload');
+      const claimed = claimAuthorization(authorization);
+      if (!claimed.ok) return usdcChallenge(usdc, jpycAccepts, claimed.reason);
+
       const relay = async (path) => {
         const response = await fetchImpl(`${origin}/api/x402/relay/${path}`, {
           method: 'POST',
@@ -174,11 +194,29 @@ export function createDualGate({
         }
         return response.json();
       };
-      const verification = await relay('verify');
-      if (verification instanceof Response) return verification;
+      let verification;
+      try {
+        verification = await relay('verify');
+      } catch (error) {
+        // Verify cannot settle or grant upstream work on failure; release only this tentative owner.
+        releaseAuthorization(claimed.claim);
+        throw error;
+      }
+      if (verification instanceof Response) {
+        releaseAuthorization(claimed.claim);
+        return verification;
+      }
       if (verification.isValid !== true) {
+        releaseAuthorization(claimed.claim);
         return usdcChallenge(usdc, jpycAccepts, verification.invalidReason || 'payment_invalid');
       }
+      // A slow verify must not consume the margin promised to the seller's upstream work.
+      if (!hasValidityWindow(authorization)) {
+        return usdcChallenge(usdc, jpycAccepts, 'insufficient_validity_window');
+      }
+      // As in JPYC, keep the claim until validBefore once upstream can run. Settlement
+      // errors (including ambiguous transport/JSON/503 and 409) must not repeat that work;
+      // even a definitive settle rejection cannot undo an already executed upstream call.
       return {
         async settle() {
           const settlement = await relay('settle');

package/src/gate.mjs

@@ -1,9 +1,8 @@
+import { createAuthorizationClaims, jpycAuthorizationClaim } from './authorizationClaims.mjs';
 import { assertSellerPins, validateJpycListing } from './sellerPins.mjs';
 
 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 }), {
@@ -25,74 +24,6 @@ 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,
   resourceId,
@@ -100,62 +31,16 @@ export function createJpycGate({
   openpayOrigin = DEFAULT_OPENPAY_ORIGIN,
   fetchImpl = globalThis.fetch,
   now = Date.now,
-  maxUpstreamSeconds = DEFAULT_MAX_UPSTREAM_SECONDS,
-  settlementGraceSeconds = DEFAULT_SETTLEMENT_GRACE_SECONDS,
+  maxUpstreamSeconds,
+  settlementGraceSeconds,
 } = {}) {
   assertSellerPins(resourceId, expectedRecipient);
-  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 { claimAuthorization, releaseAuthorization } = createAuthorizationClaims({
+    now, maxUpstreamSeconds, settlementGraceSeconds,
+  });
   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 (
@@ -211,7 +96,7 @@ export function createJpycGate({
     }
 
     const paymentRequirements = accepts[0];
-    const claimed = claimAuthorization(paymentPayload, paymentRequirements);
+    const claimed = claimAuthorization(jpycAuthorizationClaim(paymentPayload, paymentRequirements));
     if (!claimed.ok) return json402(accepts, claimed.reason);
 
     let verification;

package/src/spendStore.mjs

@@ -256,7 +256,9 @@ export function createFileSpendStore({ path, fsImpl } = {}) {
     if (!supportsAtomicFileUpdates(runtime.fileSystem)) {
       throw new Error('atomic spend store file operations are unavailable');
     }
-    await runtime.fileSystem.mkdir(runtime.directory, { recursive: true });
+    // Spend storage shares the default wallet directory: public directory bits would block
+    // a later keystore migration. Keep new directories private without chmod-ing existing ones.
+    await runtime.fileSystem.mkdir(runtime.directory, { recursive: true, mode: 0o700 });
     const handle = await acquireLock(runtime.fileSystem, runtime.lockPath);
     try {
       return await operation(runtime);
@@ -438,7 +440,8 @@ export function createFileSpendStore({ path, fsImpl } = {}) {
         }
         const current = documentForDate(document, key.slice(-10));
         current[key] = atomicString;
-        await runtime.fileSystem.mkdir(runtime.directory, { recursive: true });
+        // Compatibility saves must not create a shared directory the keystore would reject.
+        await runtime.fileSystem.mkdir(runtime.directory, { recursive: true, mode: 0o700 });
         await runtime.fileSystem.writeFile(
           runtime.targetPath,
           `${JSON.stringify(current, null, 2)}\n`,