openpay-x402-sdk 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.7.1
+
+- Add `resolveLicense({ product, origin?, fetch? })` for validated v1 product
+  descriptors, HTTPS-only discovery, redirect rejection and token derivation checks.
+- Let `hasLicense` and `createLicenseGate` accept a product ID in place of the
+  explicit chain/contract/token tuple. Polygon/Amoy RPC remains optional.
+- Discover gate identity at first challenge/verify or `await gate.ready()`, sharing
+  concurrent discovery and caching the descriptor for the gate lifetime. Failed
+  discovery can retry. Synchronous `check()` throws `not_ready` until initialized.
+- Preserve explicit identity and synchronous session checks. Add `session.origin`
+  to bind signatures to your service independently of descriptor discovery.
+- Document integration with `LICENSE_PRODUCT_ID` and `LICENSE_SESSION_SECRET`.
+  No new dependencies. This workspace release has not been published.
+
 ## 0.7.0
 
 - Add `hasLicense` for standard ERC-1155 ownership with a required chain/contract/

package/README.md

@@ -171,20 +171,60 @@ and is never transmitted.
 
 ## 利用ライセンス (License NFT)
 
-SDK 0.7.0 adds license reads and a server-side entry gate. The two-line pattern is:
+SDK 0.7.1 (workspace update; not yet published) 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
+with your own:
 
 ```js
-const entry = createLicenseGate({ ...licenseIdentity, origin: 'https://service.example', session: { secret: sessionSecret } });
+import { createLicenseGate, createJpycGate } from 'openpay-x402-sdk';
+
+const entry = createLicenseGate({
+  product: process.env.LICENSE_PRODUCT_ID,
+  session: {
+    secret: process.env.LICENSE_SESSION_SECRET,
+    origin: 'https://service.example',
+  },
+});
+await entry.ready();
 const usage = createJpycGate({ resourceUrl: 'https://service.example/api/paid' });
 ```
 
-Import these helpers from `openpay-x402-sdk`. `licenseIdentity` is the full
-`{ chainId, contract, tokenId }` tuple for your product; obtain it from the product
-definition or the trusted Verify API. `tokenId` must be a `bigint` or `0x` hex
-string representing a uint256, never a JS number or decimal string. OpenPay
-derives it as `keccak256(UTF8('openpay:license:' + productId))`, including the
-entire `h_…` product ID. A token ID alone does not identify a license across
-chains and contracts.
+Polygon (137) and Amoy (80002) use public RPC defaults; `rpcUrl` is optional.
+`origin` defaults to `https://open-pay.jp` for product discovery. `session.origin`
+binds the wallet signature and session to **your service**, independently of the
+OpenPay descriptor origin; this is application configuration, not another secret.
+If omitted, the signing origin remains the top-level `origin` for compatibility.
+
+`createLicenseGate({ chainId, contract, tokenId, origin, session, ... })` remains
+supported without discovery. An explicit `tokenId` must be a `bigint` or `0x` hex
+uint256, never a JS number or decimal string. Do not mix `product` and an explicit
+identity. OpenPay derives token IDs as
+`keccak256(UTF8('openpay:license:' + productId))`, including the entire `h_…` ID.
+
+### Resolve product metadata
+
+```js
+import { resolveLicense } from 'openpay-x402-sdk';
+const descriptor = await resolveLicense({ product: process.env.LICENSE_PRODUCT_ID });
+```
+
+`resolveLicense({ product, origin?, fetch? })` calls
+`GET /api/license/products/<id>`. It validates the v1 schema, product echo,
+chain/contract/hex token identity and token derivation, terms, supply and remaining
+stock, sale/registration booleans, canonical product/Verify links and seller role.
+It returns only these public fields. `remaining: null` means unknown stock;
+`remaining` and `saleActive` are cached display information, not reservations or
+proof of ownership. Paused or unregistered products still have descriptors.
+`verifyUrl` includes `product`; append `address` to query wallet rights.
+
+Descriptor origins must be bare **HTTPS** origins, including on localhost.
+Redirects are rejected and the injected `fetch` must honor `redirect: 'manual'`
+and the 15-second AbortSignal. Failures throw `LicenseError` (`invalid_response`,
+`redirect`, `http_error`, `network_error`); invalid options throw `TypeError`.
+The selected origin is a trusted source, not a signed attestation. Descriptor
+responses use `public, s-maxage=60, stale-while-revalidate=300`.
 
 ### Read ownership or purchase rights
 
@@ -201,9 +241,7 @@ if (status.entitled === null) {
 try {
   const { holder, balance, blockNumber } = await hasLicense({
     address: walletAddress,
-    chainId: status.license.chainId,
-    contract: status.license.contract,
-    tokenId: status.license.tokenId,
+    product: productId,
   });
   console.log({ holder, balance, blockNumber });
 } catch (error) {
@@ -213,7 +251,9 @@ try {
 }
 ```
 
-`hasLicense` calls standard ERC-1155 `balanceOf(address, tokenId)` at the returned
+`hasLicense({ address, product, origin?, fetch?, rpcUrl? })` resolves once per call;
+the explicit identity form also supports the same RPC transports. `hasLicense`
+calls standard ERC-1155 `balanceOf(address, tokenId)` at the returned
 `blockNumber`, using the latest block (not a finality guarantee). It checks the
 RPC chain ID and returns `{ holder: boolean, balance: bigint, blockNumber: bigint }`.
 Zero balance is a successful negative result; network errors, a wrong chain,
@@ -243,13 +283,22 @@ use `redirect`. Invalid caller options throw `TypeError`.
 
 ### Authenticate at entry, charge separately for use
 
-Create one `entry` instance on your server using the two-line pattern above.
-Set `origin` to **your service's origin** (default `https://open-pay.jp`) so the
-signing domain and session audience are correct. `sessionSecret` must be a
+Create one `entry` instance on your server using the pattern above. Set
+`session.origin` to **your service's origin** so the signing domain and session
+audience are correct. The explicit identity form can still use top-level `origin`
+for this. `LICENSE_SESSION_SECRET` must be a
 server-only, cryptographically random secret of at least 32 UTF-8 bytes, for
 example a random 32-byte value encoded as hex. All workers must use the same
 configuration and secret.
 
+Product gates discover at the first `challenge()` or `verify()`, or explicitly
+with `await entry.ready()` at startup. Concurrent initialization shares one
+request. A successful descriptor is frozen and cached for the gate lifetime;
+`ready()` returns it (or `undefined` for explicit identity). A failed request
+installs no identity and a later call can retry. `check()` remains synchronous:
+it throws `not_ready` before initialization and never performs discovery or RPC.
+Call `ready()` at worker startup when accepting sessions issued by another worker.
+
 ```js
 // Server challenge endpoint: send this message to the wallet.
 const message = await entry.challenge(walletAddress);
@@ -311,7 +360,7 @@ spend balance; `createJpycGate` handles separate x402 pay-per-use. SDK spend
 defaults remain unchanged.
 
 ERC-8217 note: the license remains a standard ERC-1155. The agent-binding format
-will be published later; SDK 0.7.0 does not emit or validate binding metadata.
+will be published later; SDK 0.7.1 does not emit or validate binding metadata.
 
 ### SDK verification in this repository
 

package/index.d.ts

@@ -349,7 +349,43 @@ export type LicenseTransport =
   | { rpcUrl?: string; publicClient?: never }
   | { rpcUrl?: never; publicClient: LicensePublicClient };
 
-export type HasLicenseOptions = LicenseIdentity & LicenseTransport & { address: Address };
+export interface ResolveLicenseOptions {
+  /** OpenPay product ID: h_ followed by 32 lowercase hex digits. */
+  product: string;
+  /** Trusted descriptor authority; HTTPS only, even on localhost. Default https://open-pay.jp. */
+  origin?: string;
+  /** Must honor redirect: 'manual' and the AbortSignal. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export interface LicenseDescriptor {
+  version: 1;
+  productId: string;
+  chainId: 137 | 80002;
+  contract: Address;
+  tokenId: Hex;
+  transferable: boolean;
+  termsUrl: string;
+  termsVersion: string;
+  supply: number;
+  /** Display only; null means stock could not be read. */
+  remaining: number | null;
+  saleActive: boolean;
+  registered: boolean;
+  productUrl: string;
+  /** Append the wallet address query parameter to check rights. */
+  verifyUrl: string;
+  sellerRole: 'operator' | 'third_party';
+}
+
+/** Validates the v1 descriptor, product echo and token derivation; rejects all redirects. */
+export function resolveLicense(options: ResolveLicenseOptions): Promise<LicenseDescriptor>;
+
+export type LicenseSelector =
+  | (LicenseIdentity & { product?: never })
+  | (ResolveLicenseOptions & { chainId?: never; contract?: never; tokenId?: never });
+
+export type HasLicenseOptions = LicenseSelector & LicenseTransport & { address: Address };
 
 export interface LicenseBalance {
   holder: boolean;
@@ -362,7 +398,7 @@ export type LicenseErrorCode =
   | 'rpc_error' | 'network_error' | 'http_error' | 'redirect' | 'invalid_response'
   | 'nonce_store_error' | 'invalid_challenge' | 'challenge_expired'
   | 'invalid_signature' | 'invalid_nonce' | 'no_license'
-  | 'invalid_session' | 'session_expired';
+  | 'invalid_session' | 'session_expired' | 'not_ready';
 
 export class LicenseError extends Error {
   readonly code: LicenseErrorCode;
@@ -419,14 +455,17 @@ export interface LicenseNonceStore {
   consume(nonce: string): LicenseNonceRecord | null | undefined | Promise<LicenseNonceRecord | null | undefined>;
 }
 
-export type LicenseGateOptions = LicenseIdentity & LicenseTransport & {
+export type LicenseGateOptions = LicenseSelector & LicenseTransport & {
   session: {
     /** Server-only random secret, at least 32 UTF-8 bytes. */
     secret: string;
     /** Seconds, 1–86400. Default 300. Ownership is cached for this lifetime. */
     ttlSeconds?: number;
+    /** Your service's signing origin/session audience. Defaults to the top-level origin. */
+    origin?: string;
   };
-  /** Your service's signing origin and session audience. Default https://open-pay.jp. */
+  /** Product form: descriptor authority (HTTPS only). Explicit identity: signing origin.
+   * Defaults to https://open-pay.jp. Set session.origin to use a separate signing origin. */
   origin?: string;
   /** Single-line ASCII SIWE statement. */
   statement?: string;
@@ -444,11 +483,13 @@ export interface LicenseSession {
 }
 
 export interface LicenseGate {
+  /** Resolve and cache the product identity for this gate's lifetime; no IO for explicit identity. */
+  ready(): Promise<Readonly<LicenseDescriptor> | undefined>;
   /** An EIP-4361-style message, valid for five minutes. */
   challenge(address: Address): Promise<string>;
   /** EOA signature recovery, atomic nonce consumption, balanceOf, then HMAC session issuance. */
   verify(input: { message: string; signature: Hex }): Promise<string>;
-  /** Synchronous signature/scope/expiry validation; no RPC and no ownership refresh. */
+  /** Synchronous signature/scope/expiry validation; no IO. Throws not_ready before discovery. */
   check(token: string): LicenseSession;
 }
 

package/package.json

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

package/src/license.mjs

@@ -2,7 +2,7 @@ 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,
+  licenseAddress, licenseIdentity, licenseOrigin, licenseProduct, licenseSelector,
 } from './licenseCommon.mjs';
 
 export { LicenseError, LicenseRpcError } from './licenseCommon.mjs';
@@ -13,26 +13,27 @@ const NFT_STATUSES = new Set([
   'retryable', 'needs_repair', 'unknown',
 ]);
 
-export async function hasLicense({ address, chainId, contract, tokenId, rpcUrl, publicClient }) {
+export async function hasLicense({ address, product, origin, fetch, chainId, contract, tokenId, rpcUrl, publicClient }) {
   const holderAddress = licenseAddress(address);
-  const identity = licenseIdentity({ chainId, contract, tokenId });
+  const selected = licenseSelector({ product, 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 identity = selected ?? licenseIdentity(await resolveLicense({ product, origin, fetch }));
+  const chain = [polygon, polygonAmoy].find((value) => value.id === identity.chainId);
+  if (publicClient === undefined && rpcUrl === undefined && !chain) {
+    throw new TypeError('rpcUrl or publicClient is required for this chainId');
+  }
   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');
+    if (await client.getChainId() !== identity.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({
@@ -91,13 +92,15 @@ function validateResponse(body, address, product) {
 
 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)');
-  }
+  licenseProduct(product);
   const trustedOrigin = licenseOrigin(origin);
   const url = new URL('/api/license/verify', trustedOrigin);
   url.searchParams.set('address', expectedAddress);
   url.searchParams.set('product', product);
+  return validateResponse(await fetchLicenseJson(url, trustedOrigin, fetchImpl), expectedAddress, product);
+}
+
+async function fetchLicenseJson(url, trustedOrigin, fetchImpl, label = 'verify') {
   let response;
   try {
     response = await fetchImpl(url.toString(), {
@@ -105,19 +108,59 @@ export async function verifyLicense({ address, product, origin = DEFAULT_LICENSE
       headers: { accept: 'application/json' },
     });
   } catch (cause) {
-    throw new LicenseError('network_error', 'License verify request failed', { cause });
+    throw new LicenseError('network_error', `License ${label} 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');
+    throw new LicenseError('redirect', `License ${label} 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 });
+  if (!response.ok) throw new LicenseError('http_error', `License ${label} failed: HTTP ${response.status}`);
+  try { return await response.json(); } catch (cause) {
+    throw new LicenseError('invalid_response', `License ${label} response must be JSON`, { cause });
   }
-  return validateResponse(body, expectedAddress, product);
+}
+
+function httpsUrl(value) {
+  if (typeof value !== 'string') throw new Error('URL must be a string');
+  const url = new URL(value);
+  if (url.protocol !== 'https:' || url.username || url.password) throw new Error('Invalid HTTPS URL');
+  return url;
+}
+
+export async function resolveLicense({ product, origin = DEFAULT_LICENSE_ORIGIN, fetch: fetchImpl = globalThis.fetch }) {
+  licenseProduct(product);
+  const trustedOrigin = licenseOrigin(origin, { httpsOnly: true });
+  const body = await fetchLicenseJson(new URL(`/api/license/products/${product}`, trustedOrigin), trustedOrigin, fetchImpl, 'descriptor');
+  try {
+    if (!object(body) || body.version !== 1 || body.productId !== product ||
+      ![137, 80002].includes(body.chainId) || typeof body.tokenId !== 'string' ||
+      !/^0x[0-9a-f]{64}$/.test(body.tokenId) ||
+      licenseIdentity(body).tokenId !== BigInt(keccak256(toBytes(`openpay:license:${product}`))) ||
+      typeof body.transferable !== 'boolean' || typeof body.saleActive !== 'boolean' || typeof body.registered !== 'boolean' ||
+      typeof body.termsVersion !== 'string' || !body.termsVersion.trim() || body.termsVersion.length > 128 ||
+      typeof body.termsUrl !== 'string' || body.termsUrl.length > 512 ||
+      !Number.isSafeInteger(body.supply) || body.supply < 1 || body.supply > 10000 ||
+      (body.remaining !== null && (!Number.isSafeInteger(body.remaining) || body.remaining < 0 || body.remaining > body.supply)) ||
+      !['operator', 'third_party'].includes(body.sellerRole)) throw new Error('Invalid descriptor fields');
+    httpsUrl(body.termsUrl);
+    const productUrl = httpsUrl(body.productUrl);
+    const verifyUrl = httpsUrl(body.verifyUrl);
+    if (productUrl.origin !== DEFAULT_LICENSE_ORIGIN || !/^\/@[^/]+$/.test(productUrl.pathname) || productUrl.hash ||
+      productUrl.search !== `?product=${product}` || verifyUrl.origin !== DEFAULT_LICENSE_ORIGIN ||
+      verifyUrl.pathname !== '/api/license/verify' || verifyUrl.search !== `?product=${product}` || verifyUrl.hash) {
+      throw new Error('Invalid descriptor links');
+    }
+  } catch (cause) {
+    // Untrusted descriptor fields must never become a gate's ownership identity.
+    throw new LicenseError('invalid_response', 'Invalid license product descriptor', { cause });
+  }
+  return {
+    version: 1, productId: body.productId, chainId: body.chainId, contract: body.contract, tokenId: body.tokenId,
+    transferable: body.transferable, termsUrl: body.termsUrl, termsVersion: body.termsVersion,
+    supply: body.supply, remaining: body.remaining, saleActive: body.saleActive, registered: body.registered,
+    productUrl: body.productUrl, verifyUrl: body.verifyUrl, sellerRole: body.sellerRole,
+  };
 }

package/src/licenseCommon.mjs

@@ -38,16 +38,33 @@ export function licenseIdentity({ chainId, contract, tokenId }) {
   return { chainId, contract: licenseAddress(contract, 'contract'), tokenId: id };
 }
 
-export function licenseOrigin(value) {
+export function licenseProduct(value) {
+  if (typeof value !== 'string' || !/^h_[0-9a-f]{32}$/.test(value)) {
+    throw new TypeError('product must be an OpenPay product ID (h_ plus 32 lowercase hex digits)');
+  }
+  return value;
+}
+
+export function licenseSelector({ product, chainId, contract, tokenId }) {
+  if (product === undefined) return licenseIdentity({ chainId, contract, tokenId });
+  licenseProduct(product);
+  if (chainId !== undefined || contract !== undefined || tokenId !== undefined) {
+    throw new TypeError('Provide product or chainId/contract/tokenId, not both');
+  }
+  return null;
+}
+
+export function licenseOrigin(value, { httpsOnly = false } = {}) {
   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)) ||
+  if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && local && !httpsOnly)) ||
     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');
+    throw new TypeError(httpsOnly ? 'origin must use HTTPS, without credentials or a path' :
+      'origin must use HTTPS (HTTP only for localhost/127.0.0.1), without credentials or a path');
   }
   return url.origin;
 }

package/src/licenseGate.mjs

@@ -1,9 +1,9 @@
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { verifyMessage } from 'viem';
 import { createSiweMessage, parseSiweMessage } from 'viem/siwe';
-import { hasLicense } from './license.mjs';
+import { hasLicense, resolveLicense } from './license.mjs';
 import {
-  DEFAULT_LICENSE_ORIGIN, LicenseError, licenseAddress, licenseIdentity, licenseOrigin,
+  DEFAULT_LICENSE_ORIGIN, LicenseError, licenseAddress, licenseIdentity, licenseOrigin, licenseSelector,
 } from './licenseCommon.mjs';
 
 const CHALLENGE_TTL_MS = 5 * 60_000;
@@ -28,15 +28,38 @@ function memoryNonceStore(now) {
 }
 
 export function createLicenseGate({
-  chainId, contract, tokenId, rpcUrl, publicClient,
+  product, fetch, 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);
+  let identity = licenseSelector({ product, chainId, contract, tokenId });
+  if (product !== undefined) licenseOrigin(origin, { httpsOnly: true });
+  const audience = licenseOrigin(session?.origin ?? origin);
   const url = new URL(audience);
-  const idHex = `0x${identity.tokenId.toString(16)}`;
-  const resource = `urn:openpay:license:${chainId}:${identity.contract.toLowerCase()}:${idHex}`;
+  let idHex;
+  let resource;
+  function setIdentity(value) {
+    identity = value;
+    chainId = identity.chainId;
+    idHex = `0x${identity.tokenId.toString(16)}`;
+    resource = `urn:openpay:license:${chainId}:${identity.contract.toLowerCase()}:${idHex}`;
+  }
+  if (identity) setIdentity(identity);
+  let descriptor;
+  let pending;
+  async function ready() {
+    if (identity) return descriptor;
+    pending ??= resolveLicense({ product, origin, fetch }).then((value) => {
+      descriptor = Object.freeze(value);
+      setIdentity(licenseIdentity(descriptor));
+    }).catch((error) => {
+      // A failed discovery must not install a partial identity. A later call can retry.
+      pending = undefined;
+      throw error;
+    });
+    await pending;
+    return descriptor;
+  }
   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');
   }
@@ -73,14 +96,17 @@ export function createLicenseGate({
   }
 
   async function challenge(address) {
+    const holderAddress = licenseAddress(address);
+    await ready();
     const nonce = randomBytes(32).toString('hex');
     const issuedAt = now();
-    const message = messageFor(licenseAddress(address), nonce, issuedAt);
+    const message = messageFor(holderAddress, nonce, issuedAt);
     await storeCall('set', nonce, { message, expiresAt: issuedAt + CHALLENGE_TTL_MS });
     return message;
   }
 
   async function verify({ message, signature }) {
+    await ready();
     if (typeof message !== 'string' || message.length > 8192) {
       throw new LicenseError('invalid_challenge', 'Invalid license challenge');
     }
@@ -125,6 +151,7 @@ export function createLicenseGate({
   }
 
   function check(token) {
+    if (!identity) throw new LicenseError('not_ready', 'Call await gate.ready() before checking sessions');
     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);
@@ -146,5 +173,5 @@ export function createLicenseGate({
     return { address, tokenId: identity.tokenId, exp: payload.exp };
   }
 
-  return { challenge, verify, check };
+  return { ready, challenge, verify, check };
 }