openpay-x402-sdk 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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
+  detached `fetch`, which Workers reject with "Illegal invocation", so every ticket
+  failed with `keys_unavailable`. Verified on a real Worker deployment (2026-09-10).
+- Templates: send `Content-Disposition: attachment; filename="<object key>"` only on
+  successful file responses. An error response carrying `attachment` made Chrome
+  show ERR_INVALID_RESPONSE instead of the JSON body.
+
 ## 0.8.0
 
 - Add the typed `openpay-x402-sdk/delivery` Web-API-only subpath: strict Ed25519

package/README.md

@@ -171,7 +171,7 @@ and is never transmitted.
 
 ## 利用ライセンス (License NFT)
 
-SDK 0.7.1 (workspace update; not yet published) resolves the NFT definition from
+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
 (for example 32 random bytes encoded as hex). Replace the service URLs below
@@ -376,8 +376,7 @@ consumer types.
 
 ## 保護配布 (Delivery ticket)
 
-SDK 0.8.0 is an **initial generation** workspace release, not yet published or
-production-adopted. OpenPay signs a 60-second bearer ticket after checking
+SDK 0.8.0 adds delivery-ticket verification. OpenPay signs a 60-second bearer ticket after checking
 entitlement. Sellers verify it with the public JWKS; no secret is shared with
 OpenPay. The token is signed, not encrypted, and its claims are readable.
 Possession authorizes admission during its lifetime; it is access control, not
@@ -468,7 +467,7 @@ issuance does not revoke an attacker's signing ability or recall downloaded byte
 | Node 20.19+ | Global WebCrypto with standard Ed25519; package engine remains Node >=20. |
 | Node 22.13+ | Same Web API entry point. |
 | Node 24 | Same Web API entry point. |
-| Cloudflare Workers | Standard `Ed25519`, no `nodejs_compat`; run a real deployment smoke on the template's pinned compatibility date. |
+| Cloudflare Workers | Standard `Ed25519`, no `nodejs_compat`. Verified end-to-end on a real Worker + private R2 deployment with SDK 0.8.1 (2026-09-10); re-run the smoke when you change the compatibility date. |
 
 `ready()` detects missing Ed25519 support as `unsupported_crypto`; there is no
 algorithm downgrade. The matrix is a release target, not proof that every runtime
@@ -578,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/examples/cloudflare-r2-delivery-gate/worker.mjs

@@ -3,8 +3,16 @@ import { createDeliveryGate } from 'openpay-x402-sdk/delivery';
 const PRIVATE_HEADERS = {
   'Cache-Control': 'private, no-store',
   'Referrer-Policy': 'no-referrer',
-  'Content-Disposition': 'attachment',
 };
+// Only successful file responses are downloads. An error response carrying
+// Content-Disposition: attachment makes Chrome show ERR_INVALID_RESPONSE instead of
+// the JSON body (observed on 2026-09-10). The filename comes from the trusted object
+// key, reduced to a safe ASCII token so no header injection is possible.
+function attachment(key) {
+  const base = key.split('/').pop() ?? '';
+  const name = base.replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '').slice(0, 100) || 'download';
+  return `attachment; filename="${name}"`;
+}
 const instances = new WeakMap();
 
 async function startup(env) {
@@ -56,7 +64,7 @@ const worker = {
       // This small template ignores Range/conditional headers and serves a full
       // 200 (HEAD returns metadata). Every such request still requires a ticket.
       return new Response(request.method === 'HEAD' ? null : file.body, {
-        headers: { ...PRIVATE_HEADERS, 'Content-Type': 'application/octet-stream', 'Content-Length': String(file.size) },
+        headers: { ...PRIVATE_HEADERS, 'Content-Disposition': attachment(key), 'Content-Type': 'application/octet-stream', 'Content-Length': String(file.size) },
       });
     } catch {
       // Do not expose request URLs, tickets, R2 keys or upstream exceptions.

package/examples/node-delivery-gate.mjs

@@ -2,8 +2,11 @@ import { createServer } from 'node:http';
 import { pathToFileURL } from 'node:url';
 import { createDeliveryGate } from 'openpay-x402-sdk/delivery';
 
+// No Content-Disposition here: the redirect target (your presigned URL) decides the
+// download name, and an error response carrying "attachment" makes Chrome show
+// ERR_INVALID_RESPONSE instead of the JSON body.
 const PRIVATE_HEADERS = {
-  'Cache-Control': 'private, no-store', 'Referrer-Policy': 'no-referrer', 'Content-Disposition': 'attachment',
+  'Cache-Control': 'private, no-store', 'Referrer-Policy': 'no-referrer',
 };
 
 async function presignObject({ key, method, expiresAt, expiresInSeconds }) {

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.0",
+  "version": "0.9.0",
   "description": "Guarded Node.js buyer SDK for OpenPay x402 JPYC resources",
   "type": "module",
   "main": "./src/index.mjs",

package/src/delivery.mjs

@@ -192,7 +192,9 @@ async function refresh(cache, config) {
     });
     try {
       const { keys, age } = await Promise.race([
-        (async () => readKeysResponse(await config.fetchImpl(`${config.origin}/.well-known/openpay-delivery-keys.json`, {
+        // Call with `this` = globalThis: Cloudflare Workers reject a detached `fetch`
+        // ("Illegal invocation") — observed on a real Worker on 2026-09-10; Node does not.
+        (async () => readKeysResponse(await config.fetchImpl.call(globalThis, `${config.origin}/.well-known/openpay-delivery-keys.json`, {
           method: 'GET', redirect: 'manual', signal: controller.signal, headers: { accept: 'application/json' },
         }), config))(), timeout,
       ]);

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