openpay-x402-sdk 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.10.0 — 2026-09-23
+
+- Breaking: seller gates require a trusted `resourceId` and `expectedRecipient`;
+  dual gates also require `expectedUsdcRecipient`. Missing/invalid pins fail at
+  construction. JPYC pins `extra.openpay.merchant`; USDC pins `payTo` in every
+  advertised representation. Mismatches log and throw before payment advertising
+  or processing, without a fallback to registry-supplied recipients.
+- Fetch seller listings by exact ID using `/api/discovery/{resourceId}`, independent
+  of duplicate URLs, catalog order or pagination. Cache only validated requirements
+  and retain each payment's snapshot through verify/settle. USDC relay requests
+  carry the snapshot for comparison of money fields against the current registry.
+  On relay 409, discard the USDC cache and return freshly pinned terms without
+  replaying payment. JPYC unavailability does not block USDC; trust failures use
+  `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.
+
+## 0.9.0 — 2026-09-21
+
+- Add explicit `keystore` signer mode and `wallet_not_initialized` guard reason. `createSigner` requires the caller to supply keystore keys via `createSignerFromOptions`; no env-key fallback.
+- Redact any `0x` + 64-hex value in error text as `[redacted_32byte_hex]` (a key configured through the SDK is still replaced as `[redacted_private_key]`). The generic label is deliberate: the same shape is also a transaction hash or a nonce, and it must not read as "your key leaked". Signature redaction is unchanged. Update public types; existing env-key / Steward behavior is unchanged.
+
 ## 0.8.1
 
 - Fix `openpay-x402-sdk/delivery` on Cloudflare Workers: the JWKS fetch called a

package/README.md

@@ -47,14 +47,19 @@ transaction id appearing in text. The gate unlocks only on the facilitator's `ve
 `settle` responses, which are backed by on-chain settlement; replayed or already-used
 authorizations are refused at that layer.
 
-Create a gate with the exact resource URL registered in OpenPay discovery. For
-inexpensive content, `handle()` verifies and settles the payment in one call:
+Create a gate with the resource URL, listing ID and expected recipient from your
+own seller dashboard/config. Never obtain these pins from the discovery response
+being checked. In 0.10.0, `resourceId` and `expectedRecipient` are required;
+missing/invalid pins throw at construction. 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,
+  resourceId: process.env.MY_RESOURCE_ID,
+  expectedRecipient: process.env.EXPECTED_RECIPIENT,
   maxUpstreamSeconds: 60,
 });
 
@@ -99,11 +104,21 @@ export async function GET(request) {
 }
 ```
 
-`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
+`createJpycGate` fetches the single public listing at `/api/discovery/{resourceId}`,
+checks its ID/URL and every JPYC `extra.openpay.merchant` against your recipient,
+and caches only validated requirements for five minutes. JPYC's top-level `payTo`
+is the OpenPay forwarder, not your recipient. Hidden/inactive/missing listings
+cannot bootstrap a gate. Identity/recipient mismatches log an error and throw
+before a 402, verification or settlement; map these errors to an HTTP 500 response.
+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,
+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
 authorization identity until its `validBefore` time. Set `maxUpstreamSeconds`
 (default `60`) to the seller's worst-case upstream duration; the gate also
@@ -124,11 +139,22 @@ 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
+id and both expected recipients from your own config (shown in the generated
+snippet). `expectedUsdcRecipient` is also required, even if both addresses match.
+USDC uses `payTo`; it is checked in the v1 body, v2 accept and every accept in the
+`PAYMENT-REQUIRED` header before caching or advertising. 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.
+unavailable), the gate degrades to JPYC-only. JPYC catalog unavailability likewise
+allows USDC-only challenges and payments. Identity/recipient mismatches raise
+`SellerPinError` and stop both rails. The gate sends the same validated USDC
+requirements to relay verify/settle; the relay compares payTo, amount, asset,
+network and scheme against the registry. Display metadata edits do not interrupt
+payments. A relay 409 clears the USDC cache and returns a freshly fetched,
+pin-validated 402 without replaying the payment. A poisoned refresh still fails
+closed; an unavailable refresh never re-advertises the stale USDC terms. Deploy
+the matching OpenPay relay update before upgrading seller gates.
 
 ```js
 import { createDualGate } from 'openpay-x402-sdk';
@@ -136,6 +162,8 @@ import { createDualGate } from 'openpay-x402-sdk';
 const gate = createDualGate({
   resourceUrl: process.env.MY_RESOURCE_URL,
   resourceId: process.env.MY_RESOURCE_ID,
+  expectedRecipient: process.env.EXPECTED_RECIPIENT,
+  expectedUsdcRecipient: process.env.EXPECTED_USDC_RECIPIENT,
 });
 ```
 
@@ -159,7 +187,8 @@ const { resource, paywallSnippet } = await listings.register({
   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
+// Pin resource.id, your JPYC payTo and your USDC payTo in createDualGate,
+// or paste paywallSnippet from this authenticated registration response.
 ```
 
 `register` refuses to run without an explicit `attested: true`: you must
@@ -171,9 +200,11 @@ and is never transmitted.
 
 ## 利用ライセンス (License NFT)
 
-SDK 0.7.1 resolves the NFT definition from
-one product ID. Set only `LICENSE_PRODUCT_ID` and `LICENSE_SESSION_SECRET` on
-your server. The secret must contain at least 32 random bytes of key material
+SDK 0.10.0 resolves the NFT definition from
+one product ID. For the license gate, set `LICENSE_PRODUCT_ID` and
+`LICENSE_SESSION_SECRET` on your server. The usage gate below also requires your
+own `MY_RESOURCE_ID` and `EXPECTED_RECIPIENT` pins. The license session secret must
+contain at least 32 random bytes of key material
 (for example 32 random bytes encoded as hex). Replace the service URLs below
 with your own:
 
@@ -188,7 +219,11 @@ const entry = createLicenseGate({
   },
 });
 await entry.ready();
-const usage = createJpycGate({ resourceUrl: 'https://service.example/api/paid' });
+const usage = createJpycGate({
+  resourceUrl: 'https://service.example/api/paid',
+  resourceId: process.env.MY_RESOURCE_ID,
+  expectedRecipient: process.env.EXPECTED_RECIPIENT,
+});
 ```
 
 Polygon (137) and Amoy (80002) use public RPC defaults; `rpcUrl` is optional.
@@ -577,6 +612,20 @@ returned or the facilitator signer could not be resolved. Treat `unverified` and
 
 ## Signers
 
+The environment adapter accepts `SIGNER_MODE=env-key` (default), `steward`, or
+`keystore`. Keystore is an explicit caller-managed mode: `createSigner(env)`
+throws instead of loading a file or falling back to `BUYER_PRIVATE_KEY`. A caller
+such as `openpay-x402-mcp` loads its wallet and uses
+`createSignerFromOptions({ privateKey })`, passing the signer to the executor.
+The keystore guard returns `wallet_not_initialized` when `signerAvailable` is
+false; env-key and Steward retain their existing guard behavior. File storage
+and the default daily limit for keystore are MCP responsibilities.
+
+`safeErrorMessage` / `redactSensitiveText` redact 32-byte key hex and 65-byte
+signature hex in error text. Do not apply these functions to payment payloads:
+authorization nonces are also 32-byte hex. OpenPay does not receive, store, or
+recover local wallet keys (OpenPay は鍵を受け取らない・保管しない・復元できない).
+
 Choose exactly one of `privateKey`, `steward`, or `signer`. Supplying more than
 one is a startup error. A custom signer has an EVM `address` and an async
 `signTypedData(typedData)` method.

package/index.d.ts

@@ -166,7 +166,7 @@ export type OpenPayClientOptions = ClientCommonOptions &
   );
 
 export interface RuntimeConfig {
-  signerMode: 'env-key' | 'steward';
+  signerMode: 'env-key' | 'steward' | 'keystore';
   buyerPrivateKey: string | null;
   stewardApiKey: string | null;
   stewardSignerSecret: string | null;
@@ -193,6 +193,12 @@ export interface OpenPaySession {
 }
 
 export interface DiscoveryItem {
+  /** Present for registered seller listings; obtain trusted gate pins from your own config. */
+  id?: string;
+  /** Short display name (first-party, or seller-provided). */
+  title?: string;
+  /** One line describing when an agent should buy this resource (optional). */
+  trigger?: string;
   resource: string;
   description?: string;
   category?: string;
@@ -309,6 +315,10 @@ export function createOpenPayClient(
 
 export interface JpycGateOptions {
   resourceUrl: string;
+  /** Trusted listing ID from your own seller dashboard/config; never a URL search result. */
+  resourceId: string;
+  /** Seller JPYC recipient (extra.openpay.merchant), NOT the forwarder payTo. */
+  expectedRecipient: Address;
   openpayOrigin?: string;
   fetchImpl?: typeof globalThis.fetch;
   now?: () => number;
@@ -496,14 +506,15 @@ export interface LicenseGate {
 export function createLicenseGate(options: LicenseGateOptions): LicenseGate;
 
 export interface DualGateOptions extends JpycGateOptions {
-  /** OpenPay listing id (MY_RESOURCE_ID in the generated snippet). Enables the USDC (Base) rail. */
-  resourceId: string;
+  /** Trusted USDC recipient (payTo); required even when equal to the JPYC recipient. */
+  expectedUsdcRecipient: Address;
 }
 
 /**
  * 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.
+ * 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.
  */
 export function createDualGate(options: DualGateOptions): JpycGate;
 
@@ -698,6 +709,7 @@ export const REASONS: {
   dailyAuthorizationCrossesUtcDay: 'daily_authorization_crosses_utc_day';
   buyerPrivateKeyMissing: 'buyer_private_key_missing';
   stewardSignerUnconfigured: 'steward_signer_unconfigured';
+  walletNotInitialized: 'wallet_not_initialized';
   catalogAcceptMismatch: 'catalog_accept_mismatch';
 };
 export const SUPPORTED_JPYC_ASSETS: Readonly<
@@ -822,10 +834,11 @@ export function safeErrorMessage(
 export const SIGNER_MODES: {
   envKey: 'env-key';
   steward: 'steward';
+  keystore: 'keystore';
 };
 export function readSignerMode(
   env?: Record<string, string | undefined>,
-): 'env-key' | 'steward';
+): 'env-key' | 'steward' | 'keystore';
 export function createSigner(
   env?: Record<string, string | undefined>,
   options?: { fetchImpl?: typeof globalThis.fetch },

package/package.json

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

package/src/dualGate.mjs

@@ -5,13 +5,14 @@
 //   - verify/settle: CDP facilitator への中継 (支払いは購入者 → 出品者 payTo へ直接)
 //
 // 隔離 (最重要): USDC 面の取得失敗 (リレー未点灯・障害) は null に落とし、JPYC ゲートだけで
-// 継続する — 付帯面 (USDC) の障害が決済本体 (JPYC) を止めない。
+// 継続する — 付帯面 (USDC) の障害が決済本体 (JPYC) を止めない。宛先不一致は両面を停止する。
 //
 // レール振り分け: PAYMENT-SIGNATURE ヘッダ (v2 = USDC クライアント)、または x-payment (v1) の
 // network が USDC 面と一致するときだけ USDC レール。その他は従来の JPYC ゲートへ委譲する。
 // JPYC レールの 402 には USDC accepts を追記 (decorate) して両面を常に見せる。
 
 import { createJpycGate } from './gate.mjs';
+import { assertSellerPins, SellerPinError, validateUsdcFace } from './sellerPins.mjs';
 
 const DEFAULT_OPENPAY_ORIGIN = 'https://open-pay.jp';
 const USDC_FACE_CACHE_MS = 5 * 60_000;
@@ -32,17 +33,20 @@ function encodeBase64Json(value) {
 export function createDualGate({
   resourceUrl,
   resourceId,
+  expectedRecipient,
+  expectedUsdcRecipient,
   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)');
-  }
+} = {}) {
+  assertSellerPins(resourceId, expectedRecipient);
+  assertSellerPins(resourceId, expectedUsdcRecipient, 'expectedUsdcRecipient');
   const jpyc = createJpycGate({
     resourceUrl,
+    resourceId,
+    expectedRecipient,
     openpayOrigin,
     fetchImpl,
     now,
@@ -57,21 +61,23 @@ export function createDualGate({
     if (usdcCache !== null && now() - usdcCachedAt < USDC_FACE_CACHE_MS) {
       return usdcCache;
     }
+    let face;
     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;
+      face = await response.json();
     } catch {
       // リレー未点灯/障害 → USDC 面なしで継続 (JPYC 本体を止めない)。キャッシュしない
       // (復旧したら次のリクエストで拾う)。
       return null;
     }
+    // Keep trust failures outside the availability fallback: poisoning must stop both rails.
+    validateUsdcFace(face, resourceId, expectedUsdcRecipient, decodeBase64Json);
+    usdcCache = face;
+    usdcCachedAt = now();
+    return face;
   }
 
   // JPYC ゲートが返した 402 に USDC 面 (accepts + PAYMENT-REQUIRED ヘッダ) を追記する。
@@ -98,20 +104,8 @@ export function createDualGate({
     );
   }
 
-  // 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 のみで継続 */
-    }
+  // Reuse this payment's validated JPYC/USDC snapshot even if another request refreshes the cache.
+  async function usdcChallenge(usdc, jpycAccepts, error) {
     const headers = { 'content-type': 'application/json' };
     if (typeof usdc.paymentRequiredHeader === 'string') {
       headers['PAYMENT-REQUIRED'] = usdc.paymentRequiredHeader;
@@ -126,6 +120,17 @@ export function createDualGate({
     );
   }
 
+  async function availableJpycAccepts(request) {
+    try {
+      const challenge = await jpyc.verify({ url: request.url, headers: { get: () => null } });
+      return (await challenge.json()).accepts;
+    } catch (error) {
+      // A JPYC outage must not block USDC; trust failures must still stop both rails.
+      if (error instanceof SellerPinError) throw error;
+      return [];
+    }
+  }
+
   async function verify(request) {
     const usdc = await usdcFace();
     const signatureHeader = request.headers.get('payment-signature');
@@ -146,34 +151,50 @@ export function createDualGate({
         (typeof v1Network === 'string' && v1Network === usdc.v1Accepts.network));
 
     if (usdcRail) {
+      const jpycAccepts = await availableJpycAccepts(request);
       const relay = async (path) => {
         const response = await fetchImpl(`${origin}/api/x402/relay/${path}`, {
           method: 'POST',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({
             resourceId,
+            paymentRequirements: usdc.v1Accepts,
             ...(signatureHeader
               ? { paymentSignatureHeader: signatureHeader }
               : { paymentHeader: v1Header }),
           }),
         });
+        if (response.status === 409) {
+          // A stale price must not wedge payments for the cache TTL. Re-pin fresh terms,
+          // then ask the buyer again without replaying the old authorization.
+          usdcCache = null;
+          const fresh = await usdcFace();
+          if (!fresh) throw new Error('OpenPay USDC requirements unavailable');
+          return usdcChallenge(fresh, jpycAccepts, 'requirements_mismatch');
+        }
         return response.json();
       };
       const verification = await relay('verify');
+      if (verification instanceof Response) return verification;
       if (verification.isValid !== true) {
-        return usdcChallenge(usdc, verification.invalidReason || 'payment_invalid');
+        return usdcChallenge(usdc, jpycAccepts, verification.invalidReason || 'payment_invalid');
       }
       return {
         async settle() {
           const settlement = await relay('settle');
+          if (settlement instanceof Response) return settlement;
           if (settlement.success !== true) {
-            return usdcChallenge(usdc, settlement.errorReason || 'settlement_failed');
+            return usdcChallenge(usdc, jpycAccepts, settlement.errorReason || 'settlement_failed');
           }
           return { paymentResponseHeader: encodeBase64Json(settlement) };
         },
       };
     }
 
+    if (usdc && !signatureHeader && !v1Header) {
+      return usdcChallenge(usdc, await availableJpycAccepts(request), 'payment_required');
+    }
+
     const result = await jpyc.verify(request);
     if (result instanceof Response) return decorate402(result, usdc);
     return {

package/src/gate.mjs

@@ -1,3 +1,5 @@
+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;
@@ -93,12 +95,15 @@ function authorizationClaim(paymentPayload, paymentRequirements) {
 
 export function createJpycGate({
   resourceUrl,
+  resourceId,
+  expectedRecipient,
   openpayOrigin = DEFAULT_OPENPAY_ORIGIN,
   fetchImpl = globalThis.fetch,
   now = Date.now,
   maxUpstreamSeconds = DEFAULT_MAX_UPSTREAM_SECONDS,
   settlementGraceSeconds = DEFAULT_SETTLEMENT_GRACE_SECONDS,
-}) {
+} = {}) {
+  assertSellerPins(resourceId, expectedRecipient);
   if (!Number.isSafeInteger(maxUpstreamSeconds) || maxUpstreamSeconds < 0) {
     throw new Error('maxUpstreamSeconds must be a non-negative integer');
   }
@@ -160,12 +165,12 @@ export function createJpycGate({
       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}`);
-    }
+    const response = await fetchImpl(`${origin}/api/discovery/${encodeURIComponent(resourceId)}`);
+    if (response.status === 404) throw new Error(`resource not found in OpenPay catalog: ${resourceId}`);
+    if (!response.ok) throw new Error(`OpenPay catalog request failed (HTTP ${response.status}): ${resourceId}`);
+    const mine = await response.json();
+    // A poisoned listing must not reach a challenge, cache, or facilitator payment.
+    validateJpycListing(mine, resourceId, resourceUrl, expectedRecipient);
     acceptsCache = mine.accepts;
     acceptsCachedAt = now();
     return acceptsCache;

package/src/guards.mjs

@@ -47,6 +47,7 @@ export const REASONS = {
   dailyAuthorizationCrossesUtcDay: 'daily_authorization_crosses_utc_day',
   buyerPrivateKeyMissing: 'buyer_private_key_missing',
   stewardSignerUnconfigured: 'steward_signer_unconfigured',
+  walletNotInitialized: 'wallet_not_initialized',
   // catalog trust 経由 (第三者ドメイン) の URL で、支払い時にライブ fetch した accept が
   // discovery 掲載 accept (OpenPay サーバー生成の権威値) と食い違う = bait-and-switch。
   catalogAcceptMismatch: 'catalog_accept_mismatch',
@@ -554,6 +555,8 @@ export function evaluatePaymentGuards({
   if (requirePrivateKey || requireSigner) {
     if (config.signerMode === SIGNER_MODES.steward) {
       if (!signerAvailable) reasons.push(REASONS.stewardSignerUnconfigured);
+    } else if (config.signerMode === SIGNER_MODES.keystore) {
+      if (!signerAvailable) reasons.push(REASONS.walletNotInitialized);
     } else if (config.buyerPrivateKey === null) {
       reasons.push(REASONS.buyerPrivateKeyMissing);
     }
@@ -574,7 +577,11 @@ export function redactSensitiveText(text, secrets = []) {
       out = out.split(secret).join('[redacted_private_key]');
     }
   }
-  return out.replace(/\b0x[0-9a-fA-F]{130}\b/g, '[redacted_signature]');
+  return out
+    .replace(/\b0x[0-9a-fA-F]{130}\b/g, '[redacted_signature]')
+    // 32 バイトの hex は秘密鍵と同じ形だが、取引ハッシュや nonce でもあり得る。「鍵が漏れた」と
+    // 誤解させないラベルにする (既知の秘密の置換は上の [redacted_private_key] のまま)。
+    .replace(/\b0x[0-9a-fA-F]{64}\b/g, '[redacted_32byte_hex]');
 }
 
 export function safeErrorMessage(error, config = {}) {

package/src/sellerPins.mjs

@@ -0,0 +1,75 @@
+function address(value) {
+  return typeof value === 'string' && /^0x[0-9a-fA-F]{40}$/.test(value)
+    ? value.toLowerCase() : null;
+}
+
+export class SellerPinError extends Error {
+  constructor(reason) {
+    super(`OpenPay seller gate: ${reason}`);
+    this.name = 'SellerPinError';
+  }
+}
+
+export function assertSellerPins(resourceId, expectedRecipient, name = 'expectedRecipient') {
+  if (typeof resourceId !== 'string' || resourceId.trim().length === 0) {
+    throw new Error('resourceId is required from your own OpenPay listing');
+  }
+  if (!address(expectedRecipient)) {
+    throw new Error(`${name} is required and must be a seller wallet address from your own config`);
+  }
+}
+
+export function rejectSellerRequirements(reason) {
+  // A registry mismatch must stop payment advertising/settlement, not become a rail fallback.
+  console.error(`[openpay-x402] ${reason}`);
+  throw new SellerPinError(reason);
+}
+
+export function validateJpycListing(item, resourceId, resourceUrl, expectedRecipient) {
+  if (item?.id !== resourceId || item.resource !== resourceUrl) {
+    rejectSellerRequirements('resource identity mismatch');
+  }
+  if (!Array.isArray(item.accepts)) {
+    rejectSellerRequirements('resource has no payment requirements');
+  }
+  // Empty requirements signal JPYC configuration/availability, not a substituted recipient.
+  if (item.accepts.length === 0) throw new Error('resource has no payment requirements');
+  for (const accept of item.accepts) {
+    const split = accept?.extra?.openpay;
+    if (address(split?.merchant) !== address(expectedRecipient)) {
+      rejectSellerRequirements('JPYC recipient mismatch');
+    }
+    if (split.mode !== 'forwarder-split' || !address(split.forwarder) ||
+        address(accept.payTo) !== address(split.forwarder)) {
+      rejectSellerRequirements('JPYC forwarder mismatch');
+    }
+  }
+}
+
+export function validateUsdcFace(face, resourceId, expectedRecipient, decode) {
+  if (face?.resourceId !== resourceId) rejectSellerRequirements('USDC resource identity mismatch');
+  let required;
+  try {
+    required = decode(face.paymentRequiredHeader);
+  } catch {
+    rejectSellerRequirements('invalid USDC payment requirements header');
+  }
+  if (!Array.isArray(required?.accepts) || required.accepts.length === 0) {
+    rejectSellerRequirements('USDC header has no payment requirements');
+  }
+  const accepts = [face.v1Accepts, face.v2Accept, ...required.accepts];
+  for (const accept of accepts) {
+    if (address(accept?.payTo) !== address(expectedRecipient)) {
+      rejectSellerRequirements('USDC recipient mismatch');
+    }
+  }
+  const v1 = face.v1Accepts;
+  const network = { base: 'eip155:8453', 'base-sepolia': 'eip155:84532' }[v1.network];
+  for (const accept of accepts.slice(1)) {
+    if (!network || accept.network !== network || accept.scheme !== v1.scheme ||
+        !address(v1.asset) || address(accept.asset) !== address(v1.asset) ||
+        accept.amount !== v1.maxAmountRequired) {
+      rejectSellerRequirements('USDC requirements mismatch');
+    }
+  }
+}

package/src/signer.mjs

@@ -4,6 +4,7 @@ import { privateKeyToAccount } from 'viem/accounts';
 export const SIGNER_MODES = {
   envKey: 'env-key',
   steward: 'steward',
+  keystore: 'keystore',
 };
 
 function nonEmpty(raw) {
@@ -12,8 +13,8 @@ function nonEmpty(raw) {
 
 export function readSignerMode(env = process.env) {
   const mode = nonEmpty(env.SIGNER_MODE) ?? SIGNER_MODES.envKey;
-  if (mode !== SIGNER_MODES.envKey && mode !== SIGNER_MODES.steward) {
-    throw new Error('SIGNER_MODE must be "env-key" or "steward"');
+  if (mode !== SIGNER_MODES.envKey && mode !== SIGNER_MODES.steward && mode !== SIGNER_MODES.keystore) {
+    throw new Error('SIGNER_MODE must be "env-key", "steward", or "keystore"');
   }
   return mode;
 }
@@ -182,6 +183,9 @@ function createStewardSigner(env, fetchImpl) {
 
 export function createSigner(env = process.env, { fetchImpl = fetch } = {}) {
   const mode = readSignerMode(env);
+  if (mode === SIGNER_MODES.keystore) {
+    throw new Error('keystore keys must be supplied by the caller via createSignerFromOptions');
+  }
   if (mode === SIGNER_MODES.envKey) return createEnvKeySigner(env);
   return createStewardSigner(env, fetchImpl);
 }