openpay-x402-sdk 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 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

@@ -577,6 +577,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,10 @@ export interface OpenPaySession {
 }
 
 export interface DiscoveryItem {
+  /** 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;
@@ -698,6 +702,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 +827,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.9.0",
   "description": "Guarded Node.js buyer SDK for OpenPay x402 JPYC resources",
   "type": "module",
   "main": "./src/index.mjs",

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