openpay-x402-sdk 0.5.0 → 0.7.0

package/src/dualGate.mjs

@@ -0,0 +1,196 @@
+// dual-rail 出品者ゲート: createJpycGate (JPYC・Polygon) に USDC (Base・標準 x402) の面を重ねる。
+//
+// USDC 面は OpenPay のリレー (/api/x402/relay/*) から取得・中継する:
+//   - requirements: 402 に並記する完成形 (v1Accepts + PAYMENT-REQUIRED ヘッダ) を配布
+//   - verify/settle: CDP facilitator への中継 (支払いは購入者 → 出品者 payTo へ直接)
+//
+// 隔離 (最重要): USDC 面の取得失敗 (リレー未点灯・障害) は null に落とし、JPYC ゲートだけで
+// 継続する — 付帯面 (USDC) の障害が決済本体 (JPYC) を止めない。
+//
+// レール振り分け: PAYMENT-SIGNATURE ヘッダ (v2 = USDC クライアント)、または x-payment (v1) の
+// network が USDC 面と一致するときだけ USDC レール。その他は従来の JPYC ゲートへ委譲する。
+// JPYC レールの 402 には USDC accepts を追記 (decorate) して両面を常に見せる。
+
+import { createJpycGate } from './gate.mjs';
+
+const DEFAULT_OPENPAY_ORIGIN = 'https://open-pay.jp';
+const USDC_FACE_CACHE_MS = 5 * 60_000;
+
+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 createDualGate({
+  resourceUrl,
+  resourceId,
+  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)');
+  }
+  const jpyc = createJpycGate({
+    resourceUrl,
+    openpayOrigin,
+    fetchImpl,
+    now,
+    ...(maxUpstreamSeconds === undefined ? {} : { maxUpstreamSeconds }),
+    ...(settlementGraceSeconds === undefined ? {} : { settlementGraceSeconds }),
+  });
+  const origin = openpayOrigin.replace(/\/+$/, '');
+
+  let usdcCache = null;
+  let usdcCachedAt = 0;
+  async function usdcFace() {
+    if (usdcCache !== null && now() - usdcCachedAt < USDC_FACE_CACHE_MS) {
+      return usdcCache;
+    }
+    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;
+    } catch {
+      // リレー未点灯/障害 → USDC 面なしで継続 (JPYC 本体を止めない)。キャッシュしない
+      // (復旧したら次のリクエストで拾う)。
+      return null;
+    }
+  }
+
+  // JPYC ゲートが返した 402 に USDC 面 (accepts + PAYMENT-REQUIRED ヘッダ) を追記する。
+  // 402 以外・USDC 面なし・body が読めない場合はそのまま返す (壊さない)。
+  async function decorate402(response, usdc) {
+    if (!usdc || !(response instanceof Response) || response.status !== 402) {
+      return response;
+    }
+    let body;
+    try {
+      body = await response.clone().json();
+    } catch {
+      return response;
+    }
+    if (!body || !Array.isArray(body.accepts)) return response;
+    const headers = new Headers(response.headers);
+    headers.set('content-type', 'application/json');
+    if (typeof usdc.paymentRequiredHeader === 'string') {
+      headers.set('PAYMENT-REQUIRED', usdc.paymentRequiredHeader);
+    }
+    return new Response(
+      JSON.stringify({ ...body, accepts: [...body.accepts, usdc.v1Accepts] }),
+      { status: 402, headers },
+    );
+  }
+
+  // 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 のみで継続 */
+    }
+    const headers = { 'content-type': 'application/json' };
+    if (typeof usdc.paymentRequiredHeader === 'string') {
+      headers['PAYMENT-REQUIRED'] = usdc.paymentRequiredHeader;
+    }
+    return new Response(
+      JSON.stringify({
+        x402Version: 1,
+        accepts: [...jpycAccepts, usdc.v1Accepts],
+        error,
+      }),
+      { status: 402, headers },
+    );
+  }
+
+  async function verify(request) {
+    const usdc = await usdcFace();
+    const signatureHeader = request.headers.get('payment-signature');
+    const v1Header = request.headers.get('x-payment');
+    let v1Network = null;
+    if (v1Header) {
+      try {
+        const decoded = decodeBase64Json(v1Header);
+        if (decoded && typeof decoded === 'object') v1Network = decoded.network;
+      } catch {
+        /* 不正 header は下のレール判定で JPYC 側に流し、そこで 402 になる */
+      }
+    }
+
+    const usdcRail =
+      usdc !== null &&
+      (Boolean(signatureHeader) ||
+        (typeof v1Network === 'string' && v1Network === usdc.v1Accepts.network));
+
+    if (usdcRail) {
+      const relay = async (path) => {
+        const response = await fetchImpl(`${origin}/api/x402/relay/${path}`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({
+            resourceId,
+            ...(signatureHeader
+              ? { paymentSignatureHeader: signatureHeader }
+              : { paymentHeader: v1Header }),
+          }),
+        });
+        return response.json();
+      };
+      const verification = await relay('verify');
+      if (verification.isValid !== true) {
+        return usdcChallenge(usdc, verification.invalidReason || 'payment_invalid');
+      }
+      return {
+        async settle() {
+          const settlement = await relay('settle');
+          if (settlement.success !== true) {
+            return usdcChallenge(usdc, settlement.errorReason || 'settlement_failed');
+          }
+          return { paymentResponseHeader: encodeBase64Json(settlement) };
+        },
+      };
+    }
+
+    const result = await jpyc.verify(request);
+    if (result instanceof Response) return decorate402(result, usdc);
+    return {
+      async settle() {
+        const settlement = await result.settle();
+        return settlement instanceof Response
+          ? decorate402(settlement, usdc)
+          : settlement;
+      },
+    };
+  }
+
+  async function handle(request) {
+    const verification = await verify(request);
+    if (verification instanceof Response) return verification;
+    return verification.settle();
+  }
+
+  return { handle, verify };
+}

package/src/executor.mjs

@@ -127,36 +127,53 @@ function utcDate(value) {
   return instant.toISOString().slice(0, 10);
 }
 
-async function safeReceipt(
+// Settlement truth for one paid call. HTTP 200 only means the seller returned a body; it is not
+// evidence that the facilitator settled on chain, and an LLM reading `status: 200` will assume it is.
+//   'verified'            — a receipt header was present and the facilitator signature bound it to this payment
+//   'unverified'          — a receipt header was present but unsigned, malformed, forged, or mismatched
+//   'receipt_unavailable' — no receipt header, or the facilitator signer could not be resolved
+export const SETTLEMENT = Object.freeze({
+  verified: 'verified',
+  unverified: 'unverified',
+  unavailable: 'receipt_unavailable',
+});
+
+async function settlementOutcome(
   raw,
   reservation,
   normalizedAccept,
   resolveReceiptSigner,
 ) {
+  if (typeof raw !== 'string' || raw.length === 0) {
+    return { receipt: null, settlement: SETTLEMENT.unavailable };
+  }
   try {
     const decoded = decodePaymentResponse(raw);
-    if (decoded === null) return null;
+    // A header that cannot be decoded is a seller claim we could not check, not an absent claim.
+    if (decoded === null) {
+      return { receipt: null, settlement: SETTLEMENT.unverified };
+    }
     const expectedSigner = await resolveReceiptSigner();
-    if (
-      expectedSigner === null ||
-      !(await verifyBoundPaymentResponse(decoded, {
-        expectedSigner,
-        payer: reservation.payer,
-        network: reservation.network,
-        asset: reservation.asset,
-        chainId: normalizedAccept.chainId,
-        merchant: normalizedAccept.extra.openpay.merchant,
-        merchantValue: normalizedAccept.extra.openpay.merchantValue,
-        feeValue: normalizedAccept.extra.openpay.feeValue,
-        nonce: reservation.id,
-      }))
-    ) {
-      return null;
+    if (expectedSigner === null) {
+      return { receipt: null, settlement: SETTLEMENT.unavailable };
     }
-    return decoded;
+    const bound = await verifyBoundPaymentResponse(decoded, {
+      expectedSigner,
+      payer: reservation.payer,
+      network: reservation.network,
+      asset: reservation.asset,
+      chainId: normalizedAccept.chainId,
+      merchant: normalizedAccept.extra.openpay.merchant,
+      merchantValue: normalizedAccept.extra.openpay.merchantValue,
+      feeValue: normalizedAccept.extra.openpay.feeValue,
+      nonce: reservation.id,
+    });
+    return bound
+      ? { receipt: decoded, settlement: SETTLEMENT.verified }
+      : { receipt: null, settlement: SETTLEMENT.unverified };
   } catch {
     // A seller-controlled receipt header must not erase an unlocked body and invite a duplicate payment.
-    return null;
+    return { receipt: null, settlement: SETTLEMENT.unverified };
   }
 }
 
@@ -533,7 +550,7 @@ export function createPaymentExecutor({
         await confirmDailyReservation(reservation.id);
       }
     }
-    const receipt = await safeReceipt(
+    const { receipt, settlement } = await settlementOutcome(
       unlocked.headers.get('x-payment-response'),
       reservation,
       normalizedAccept,
@@ -543,6 +560,7 @@ export function createPaymentExecutor({
       status: unlocked.status,
       body: unlockedBody,
       receipt,
+      settlement,
     };
   }
 

package/src/guards.mjs

@@ -167,9 +167,20 @@ function parseHttpUrl(raw, label) {
   }
 }
 
-function requireHttpUrl(raw, label) {
+// DISCOVERY_URL は catalog trust の権威 (ここに載る URL は ALLOWED_HOSTS への手動追加なしで
+// 支払える)。平文 http はネットワーク上で差し替え可能なので、攻撃者のカタログが「審査済み」に
+// 化けて支払い先を乗っ取る波及を断つため https に限る。例外はローカル開発 (localhost /
+// 127.0.0.1) のみ — 自機の facilitator/カタログを立てて配線を確かめる用途。
+function requireDiscoveryUrl(raw, label) {
   const url = parseHttpUrl(raw, label);
   if (url === null) throw new Error(`${label} must be an http(s) URL`);
+  if (
+    url.protocol === 'http:' &&
+    url.hostname !== 'localhost' &&
+    url.hostname !== '127.0.0.1'
+  ) {
+    throw new Error(`${label} must use https (http is allowed only for localhost)`);
+  }
   return url.toString();
 }
 
@@ -206,7 +217,7 @@ export function readMoneyConfig(env = process.env) {
 export function readRuntimeConfig(env = process.env) {
   return {
     ...readMoneyConfig(env),
-    discoveryUrl: requireHttpUrl(
+    discoveryUrl: requireDiscoveryUrl(
       nonEmpty(env.DISCOVERY_URL) ?? DEFAULT_DISCOVERY_URL,
       'DISCOVERY_URL',
     ),
@@ -264,7 +275,7 @@ export function parseClientOptions(options = {}) {
         : parseJpycToAtomic(options.maxDailyJpyc, 'MAX_DAILY_JPYC'),
     allowedHosts: parseAllowedHosts(options.allowedHosts),
     catalogTrust: options.catalogTrust ?? DEFAULT_CATALOG_TRUST,
-    discoveryUrl: requireHttpUrl(
+    discoveryUrl: requireDiscoveryUrl(
       nonEmpty(options.discoveryUrl) ?? DEFAULT_DISCOVERY_URL,
       'DISCOVERY_URL',
     ),

package/src/index.mjs

@@ -1,7 +1,11 @@
 export * from './catalog.mjs';
 export * from './client.mjs';
+export * from './dualGate.mjs';
+export * from './listing.mjs';
 export * from './executor.mjs';
 export * from './gate.mjs';
+export * from './license.mjs';
+export * from './licenseGate.mjs';
 export * from './guards.mjs';
 export * from './network.mjs';
 export * from './payment.mjs';

package/src/license.mjs

@@ -0,0 +1,123 @@
+import { createPublicClient, http, keccak256, parseAbi, toBytes } from 'viem';
+import { polygon, polygonAmoy } from 'viem/chains';
+import {
+  DEFAULT_LICENSE_ORIGIN, MAX_LICENSE_UINT256, LicenseError, LicenseRpcError,
+  licenseAddress, licenseIdentity, licenseOrigin,
+} from './licenseCommon.mjs';
+
+export { LicenseError, LicenseRpcError } from './licenseCommon.mjs';
+
+const BALANCE_ABI = parseAbi(['function balanceOf(address account, uint256 id) view returns (uint256)']);
+const NFT_STATUSES = new Set([
+  'awaiting_finality', 'pending', 'submitted', 'minted', 'registered',
+  'retryable', 'needs_repair', 'unknown',
+]);
+
+export async function hasLicense({ address, chainId, contract, tokenId, rpcUrl, publicClient }) {
+  const holderAddress = licenseAddress(address);
+  const identity = licenseIdentity({ chainId, contract, tokenId });
+  if (rpcUrl !== undefined && publicClient !== undefined) {
+    throw new TypeError('Provide rpcUrl or publicClient, not both');
+  }
+  const chain = [polygon, polygonAmoy].find((value) => value.id === chainId);
+  if (publicClient === undefined && rpcUrl === undefined && !chain) {
+    throw new TypeError('rpcUrl or publicClient is required for this chainId');
+  }
+  if (rpcUrl !== undefined && (typeof rpcUrl !== 'string' || !/^https?:\/\//.test(rpcUrl))) {
+    throw new TypeError('rpcUrl must be an HTTP(S) URL');
+  }
+  const client = publicClient ?? createPublicClient({
+    chain, transport: http(rpcUrl, { retryCount: 0, timeout: 10_000 }),
+  });
+  try {
+    // Verify the endpoint's chain, then pin balanceOf to the reported block. A wrong
+    // network or partial RPC response must never become a false ownership verdict.
+    if (await client.getChainId() !== chainId) throw new Error('RPC chainId mismatch');
+    const blockNumber = await client.getBlockNumber({ cacheTime: 0 });
+    if (typeof blockNumber !== 'bigint' || blockNumber < 0n) throw new Error('Invalid RPC block number');
+    const balance = await client.readContract({
+      address: identity.contract, abi: BALANCE_ABI, functionName: 'balanceOf',
+      args: [holderAddress, identity.tokenId], blockNumber,
+    });
+    if (typeof balance !== 'bigint' || balance < 0n || balance > MAX_LICENSE_UINT256) {
+      throw new Error('Invalid RPC balance');
+    }
+    return { holder: balance > 0n, balance, blockNumber };
+  } catch (cause) {
+    throw new LicenseRpcError('Unable to read license ownership on the requested chain', { cause });
+  }
+}
+
+function object(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function validateResponse(body, address, product) {
+  try {
+    if (!object(body) || body.version !== 1 || licenseAddress(body.address) !== address ||
+      !object(body.license) || body.license.productId !== product ||
+      typeof body.license.tokenId !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(body.license.tokenId)) {
+      throw new Error('Invalid version, address echo or license identity');
+    }
+    const identity = licenseIdentity(body.license);
+    if (identity.tokenId !== BigInt(keccak256(toBytes(`openpay:license:${product}`))) ||
+      (typeof body.entitled !== 'boolean' && body.entitled !== null) ||
+      ![null, 'purchase', 'holder'].includes(body.basis) ||
+      (body.entitled === null && body.basis !== null) ||
+      (body.entitled === true && body.basis === null) ||
+      !object(body.nft) || !NFT_STATUSES.has(body.nft.status) ||
+      (body.nft.mintTxHash !== undefined &&
+        (typeof body.nft.mintTxHash !== 'string' || !/^0x[0-9a-fA-F]{64}$/.test(body.nft.mintTxHash))) ||
+      (body.observedBlock !== undefined &&
+        (typeof body.observedBlock !== 'string' || !/^(0|[1-9][0-9]*)$/.test(body.observedBlock))) ||
+      typeof body.checkedAt !== 'string' || !Number.isFinite(Date.parse(body.checkedAt))) {
+      throw new Error('Invalid license status');
+    }
+  } catch (cause) {
+    // Reject untrusted/malformed state rather than granting or denying access from it.
+    throw new LicenseError('invalid_response', 'Invalid license verify response', { cause });
+  }
+  // Project only the validated v1 fields; null remains the API's unknown state.
+  return {
+    version: 1, address: body.address,
+    license: { chainId: body.license.chainId, contract: body.license.contract,
+      tokenId: body.license.tokenId, productId: body.license.productId },
+    entitled: body.entitled, basis: body.basis,
+    nft: { status: body.nft.status, ...(body.nft.mintTxHash !== undefined ? { mintTxHash: body.nft.mintTxHash } : {}) },
+    ...(body.observedBlock !== undefined ? { observedBlock: body.observedBlock } : {}),
+    checkedAt: body.checkedAt,
+  };
+}
+
+export async function verifyLicense({ address, product, origin = DEFAULT_LICENSE_ORIGIN, fetch: fetchImpl = globalThis.fetch }) {
+  const expectedAddress = licenseAddress(address);
+  if (typeof product !== 'string' || !/^h_[0-9a-f]{32}$/.test(product)) {
+    throw new TypeError('product must be an OpenPay product ID (h_ plus 32 lowercase hex digits)');
+  }
+  const trustedOrigin = licenseOrigin(origin);
+  const url = new URL('/api/license/verify', trustedOrigin);
+  url.searchParams.set('address', expectedAddress);
+  url.searchParams.set('product', product);
+  let response;
+  try {
+    response = await fetchImpl(url.toString(), {
+      method: 'GET', redirect: 'manual', signal: AbortSignal.timeout(15_000),
+      headers: { accept: 'application/json' },
+    });
+  } catch (cause) {
+    throw new LicenseError('network_error', 'License verify request failed', { cause });
+  }
+  // Never send the query to a redirect destination. Also reject an injected fetch
+  // that reports following a redirect or returning a different origin's response.
+  if (response.redirected || response.type === 'opaqueredirect' ||
+    (response.status >= 300 && response.status < 400) ||
+    (response.url && new URL(response.url).origin !== trustedOrigin)) {
+    throw new LicenseError('redirect', 'License verify redirects are not allowed');
+  }
+  if (!response.ok) throw new LicenseError('http_error', `License verify failed: HTTP ${response.status}`);
+  let body;
+  try { body = await response.json(); } catch (cause) {
+    throw new LicenseError('invalid_response', 'License verify response must be JSON', { cause });
+  }
+  return validateResponse(body, expectedAddress, product);
+}

package/src/licenseCommon.mjs

@@ -0,0 +1,53 @@
+import { getAddress, isAddress, zeroAddress } from 'viem';
+
+export const DEFAULT_LICENSE_ORIGIN = 'https://open-pay.jp';
+export const MAX_LICENSE_UINT256 = (1n << 256n) - 1n;
+
+export class LicenseError extends Error {
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = 'LicenseError';
+    this.code = code;
+  }
+}
+
+export class LicenseRpcError extends LicenseError {
+  constructor(message = 'License RPC failed', options) {
+    super('rpc_error', message, options);
+    this.name = 'LicenseRpcError';
+  }
+}
+
+export function licenseAddress(value, label = 'address') {
+  if (typeof value !== 'string' || !isAddress(value) || value.toLowerCase() === zeroAddress) {
+    throw new TypeError(`${label} must be a non-zero EVM address`);
+  }
+  return getAddress(value);
+}
+
+export function licenseIdentity({ chainId, contract, tokenId }) {
+  if (!Number.isSafeInteger(chainId) || chainId <= 0) {
+    throw new TypeError('chainId must be a positive safe integer');
+  }
+  if (typeof tokenId !== 'bigint' &&
+    !(typeof tokenId === 'string' && /^0x[0-9a-fA-F]{1,64}$/.test(tokenId))) {
+    throw new TypeError('tokenId must be a uint256 bigint or 0x-hex string, never a number');
+  }
+  const id = BigInt(tokenId);
+  if (id < 0n || id > MAX_LICENSE_UINT256) throw new TypeError('tokenId must fit uint256');
+  return { chainId, contract: licenseAddress(contract, 'contract'), tokenId: id };
+}
+
+export function licenseOrigin(value) {
+  let url;
+  try { url = new URL(value); } catch {
+    throw new TypeError('origin must be an HTTPS origin');
+  }
+  // The status authority and signing domain must not be substituted over plaintext.
+  const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+  if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) ||
+    url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    throw new TypeError('origin must use HTTPS (HTTP only for localhost/127.0.0.1), without credentials or a path');
+  }
+  return url.origin;
+}

package/src/licenseGate.mjs

@@ -0,0 +1,150 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { verifyMessage } from 'viem';
+import { createSiweMessage, parseSiweMessage } from 'viem/siwe';
+import { hasLicense } from './license.mjs';
+import {
+  DEFAULT_LICENSE_ORIGIN, LicenseError, licenseAddress, licenseIdentity, licenseOrigin,
+} from './licenseCommon.mjs';
+
+const CHALLENGE_TTL_MS = 5 * 60_000;
+const MAX_PENDING_NONCES = 10_000;
+
+function memoryNonceStore(now) {
+  const entries = new Map();
+  return {
+    set(nonce, record) {
+      for (const [key, value] of entries) {
+        if (value.expiresAt <= now()) entries.delete(key);
+      }
+      if (entries.size >= MAX_PENDING_NONCES) throw new Error('Too many pending license challenges');
+      entries.set(nonce, record);
+    },
+    consume(nonce) {
+      const record = entries.get(nonce);
+      entries.delete(nonce);
+      return record;
+    },
+  };
+}
+
+export function createLicenseGate({
+  chainId, contract, tokenId, rpcUrl, publicClient,
+  session, origin = DEFAULT_LICENSE_ORIGIN,
+  statement = 'Sign in to use this license.', nonceStore, now = Date.now,
+}) {
+  const identity = licenseIdentity({ chainId, contract, tokenId });
+  const audience = licenseOrigin(origin);
+  const url = new URL(audience);
+  const idHex = `0x${identity.tokenId.toString(16)}`;
+  const resource = `urn:openpay:license:${chainId}:${identity.contract.toLowerCase()}:${idHex}`;
+  if (typeof session?.secret !== 'string' || Buffer.byteLength(session.secret, 'utf8') < 32) {
+    throw new TypeError('session.secret must contain at least 32 bytes of secret key material');
+  }
+  const secret = session.secret;
+  const ttlSeconds = session.ttlSeconds ?? 300;
+  if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds <= 0 || ttlSeconds > 86_400) {
+    throw new TypeError('session.ttlSeconds must be an integer between 1 and 86400');
+  }
+  if (typeof statement !== 'string' || !/^[\x20-\x7e]*$/.test(statement)) {
+    throw new TypeError('statement must be a single-line ASCII string');
+  }
+  const store = nonceStore ?? memoryNonceStore(now);
+  if (typeof store.set !== 'function' || typeof store.consume !== 'function') {
+    throw new TypeError('nonceStore must implement set and atomic consume');
+  }
+
+  function messageFor(address, nonce, issuedAt) {
+    return createSiweMessage({
+      address, chainId, domain: url.host, scheme: url.protocol.slice(0, -1),
+      uri: audience, version: '1', statement, nonce, issuedAt: new Date(issuedAt),
+      expirationTime: new Date(issuedAt + CHALLENGE_TTL_MS), resources: [resource],
+    });
+  }
+
+  async function storeCall(method, ...args) {
+    try { return await store[method](...args); } catch (cause) {
+      // A failed nonce write/consume must not produce a usable authentication session.
+      throw new LicenseError('nonce_store_error', 'License nonce store failed', { cause });
+    }
+  }
+
+  function mac(value) {
+    return createHmac('sha256', secret).update(value).digest();
+  }
+
+  async function challenge(address) {
+    const nonce = randomBytes(32).toString('hex');
+    const issuedAt = now();
+    const message = messageFor(licenseAddress(address), nonce, issuedAt);
+    await storeCall('set', nonce, { message, expiresAt: issuedAt + CHALLENGE_TTL_MS });
+    return message;
+  }
+
+  async function verify({ message, signature }) {
+    if (typeof message !== 'string' || message.length > 8192) {
+      throw new LicenseError('invalid_challenge', 'Invalid license challenge');
+    }
+    const parsed = parseSiweMessage(message);
+    const issuedAt = parsed.issuedAt?.getTime();
+    const expiresAt = parsed.expirationTime?.getTime();
+    if (!Number.isFinite(issuedAt) || !Number.isFinite(expiresAt) || issuedAt > now()) {
+      throw new LicenseError('invalid_challenge', 'Invalid license challenge time');
+    }
+    if (expiresAt <= now()) throw new LicenseError('challenge_expired', 'License challenge expired');
+    let expected;
+    try { expected = messageFor(licenseAddress(parsed.address), parsed.nonce, issuedAt); } catch {
+      throw new LicenseError('invalid_challenge', 'Invalid license challenge fields');
+    }
+    // Exact reconstruction binds domain, URI, chain, contract, token, statement and
+    // expiry, including fields a permissive SIWE parser would otherwise ignore.
+    if (message !== expected) throw new LicenseError('invalid_challenge', 'License challenge does not match this gate');
+    let valid = false;
+    try {
+      valid = typeof signature === 'string' && /^0x[0-9a-fA-F]+$/.test(signature) &&
+        await verifyMessage({ address: parsed.address, message, signature });
+    } catch {
+      // Malformed signatures and signatures from a different EOA both deny entry.
+      throw new LicenseError('invalid_signature', 'Invalid license signature');
+    }
+    if (!valid) throw new LicenseError('invalid_signature', 'Invalid license signature');
+    // consume must be atomic across callers; a get/delete pair permits concurrent replay.
+    const record = await storeCall('consume', parsed.nonce);
+    if (!record || record.message !== message || record.expiresAt !== expiresAt) {
+      throw new LicenseError('invalid_nonce', 'License nonce is missing, used or mismatched');
+    }
+    if (expiresAt <= now()) throw new LicenseError('challenge_expired', 'License challenge expired');
+    const address = licenseAddress(parsed.address);
+    const ownership = await hasLicense({ ...identity, address, rpcUrl, publicClient });
+    if (expiresAt <= now()) throw new LicenseError('challenge_expired', 'License challenge expired');
+    if (!ownership.holder) throw new LicenseError('no_license', 'Wallet does not hold this license');
+    const iat = Math.floor(now() / 1000);
+    const payload = { version: 1, aud: audience, chainId, contract: identity.contract,
+      tokenId: idHex, address, iat, exp: iat + ttlSeconds };
+    const value = `opl1.${Buffer.from(JSON.stringify(payload)).toString('base64url')}`;
+    return `${value}.${mac(value).toString('base64url')}`;
+  }
+
+  function check(token) {
+    const invalid = () => new LicenseError('invalid_session', 'Invalid license session');
+    if (typeof token !== 'string' || token.length > 4096) throw invalid();
+    const match = /^(opl1\.[A-Za-z0-9_-]+)\.([A-Za-z0-9_-]{43})$/.exec(token);
+    if (!match) throw invalid();
+    const tag = Buffer.from(match[2], 'base64url');
+    if (tag.toString('base64url') !== match[2] || !timingSafeEqual(tag, mac(match[1]))) throw invalid();
+    let payload;
+    try { payload = JSON.parse(Buffer.from(match[1].slice(5), 'base64url').toString('utf8')); } catch {
+      throw invalid();
+    }
+    if (!payload || payload.version !== 1 || payload.aud !== audience ||
+      payload.chainId !== chainId || payload.contract !== identity.contract || payload.tokenId !== idHex ||
+      !Number.isSafeInteger(payload.iat) || !Number.isSafeInteger(payload.exp) ||
+      payload.iat < 0 || payload.iat > Math.floor(now() / 1000) ||
+      payload.exp <= payload.iat || payload.exp - payload.iat > ttlSeconds) throw invalid();
+    let address;
+    try { address = licenseAddress(payload.address); } catch { throw invalid(); }
+    if (payload.exp <= Math.floor(now() / 1000)) throw new LicenseError('session_expired', 'License session expired');
+    return { address, tokenId: identity.tokenId, exp: payload.exp };
+  }
+
+  return { challenge, verify, check };
+}