openpay-x402-sdk 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # 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/
+  uint256 token identity, block-pinned reads, and typed RPC errors. Token IDs
+  accept bigint or hex, never JS numbers.
+- Add `verifyLicense` for the trusted HTTPS v1 status API, with schema and
+  address/product identity validation. Preserve `entitled: null` as unknown and
+  reject redirects; allow HTTP only on localhost/127.0.0.1.
+- Add `createLicenseGate`: five-minute EIP-4361-style EOA challenges, atomic
+  single-use nonces, on-chain ownership, and HMAC sessions bound to the service
+  origin and full license identity. Default sessions last five minutes; support
+  an injectable nonce store without adding other persistence.
+- Add TypeScript declarations, mocked RPC/fetch and real-signature unit tests,
+  and the entry-license + x402 pay-per-use README pattern. Keep existing exports'
+  behavior and spend defaults unchanged; add no dependencies.
+- Keep licenses standard ERC-1155; the ERC-8217 agent-binding format will be
+  published later. This release does not implement binding metadata.
+
 ## 0.6.0
 
 - Add `createDualGate` — a dual-rail seller gate that serves both JPYC (Polygon,

package/README.md

@@ -169,6 +169,211 @@ and `deactivate(id)` complete the lifecycle; `update` without `usdc` removes the
 USDC face, so pass the previous value to keep it. The private key signs locally
 and is never transmitted.
 
+## 利用ライセンス (License NFT)
+
+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
+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' });
+```
+
+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
+
+```js
+import { hasLicense, verifyLicense, LicenseRpcError } from 'openpay-x402-sdk';
+
+const status = await verifyLicense({ address: walletAddress, product: productId });
+if (status.entitled === null) {
+  // UNKNOWN: retry later; do not treat this as non-ownership or ask for repurchase.
+} else if (status.entitled === true) {
+  // The trusted API reports rights. Authenticate the wallet separately.
+}
+
+try {
+  const { holder, balance, blockNumber } = await hasLicense({
+    address: walletAddress,
+    product: productId,
+  });
+  console.log({ holder, balance, blockNumber });
+} catch (error) {
+  if (error instanceof LicenseRpcError) {
+    // Ownership is unconfirmed. Report/retry the failure; do not convert it to false.
+  } else throw error;
+}
+```
+
+`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,
+reverts and malformed RPC results throw `LicenseRpcError` (`code: 'rpc_error'`).
+Pass either `rpcUrl` or a viem `publicClient` implementing `getChainId`,
+`getBlockNumber` and `readContract`. Polygon (137) and Amoy (80002) use viem's
+public RPC defaults if neither is supplied; other chains need an explicit
+transport. Treat the chosen RPC/client as a trusted read source.
+
+`verifyLicense({ address, product, origin?, fetch? })` calls
+`GET /api/license/verify?address=…&product=…`. It validates version `1`, the
+address/product echoes, the full license identity and token derivation,
+`entitled`, `basis`, NFT status, optional mint transaction/observed block, and
+`checkedAt`. The typed response keeps `entitled: boolean | null`; **null means
+unknown**. `basis` is `purchase`, `holder` or `null`. NFT status is
+`awaiting_finality`, `pending`, `submitted`, `minted`, `registered`, `retryable`,
+`needs_repair` or `unknown`.
+
+This is a trusted HTTPS status API, not wallet authentication or portable signed
+proof. The default origin is `https://open-pay.jp`; an override must be a bare
+HTTPS origin without credentials, path, query or fragment. HTTP is allowed only
+for `localhost` and `127.0.0.1`. All redirects, including same-origin redirects,
+are rejected. Injected `fetch` must honor `redirect: 'manual'` and the 15-second
+AbortSignal. Invalid schemas, HTTP failures and transport failures throw
+`LicenseError` with `invalid_response`, `http_error` or `network_error`; redirects
+use `redirect`. Invalid caller options throw `TypeError`.
+
+### Authenticate at entry, charge separately for use
+
+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);
+// Wallet: sign the exact message with signMessage({ message }).
+// Server verify endpoint: receive the message and signature from the wallet.
+const token = await entry.verify({ message, signature });
+// On protected requests, extract the token from your cookie or Authorization header.
+const { address, tokenId, exp } = entry.check(token);
+// After entry.check succeeds, charge each paid call with the existing usage gate.
+const payment = await usage.handle(request);
+if (payment instanceof Response) return payment;
+// Return the paid content with payment.paymentResponseHeader as X-PAYMENT-RESPONSE.
+```
+
+`challenge` returns a five-minute [EIP-4361-style message](https://eips.ethereum.org/EIPS/eip-4361)
+with a random nonce and the full license identity in its Resources field.
+`verify` uses viem's EOA `verifyMessage` recovery, checks the exact issued message,
+domain, URI, identity and expiry, atomically consumes its nonce, reads ownership,
+then returns an HMAC-SHA256 session token. This version supports EOA signatures;
+contract-wallet ERC-1271 verification is not implemented. The optional
+`statement` must be single-line ASCII.
+
+`check` is synchronous and returns `{ address, tokenId: bigint, exp }`, with `exp`
+in Unix seconds. It authenticates the token and checks its audience, full license
+identity and expiry. It performs no RPC: a transfer/burn after entry remains
+effective in an existing session until expiry. `session.ttlSeconds` defaults to
+300 (allowed 1–86400); use a short lifetime or call `hasLicense` again when fresh
+ownership is required. The helper does not set cookies or expose HTTP endpoints;
+your framework handles token transport, secure cookies and endpoint rate limits.
+
+Authentication failures throw `LicenseError`: `invalid_challenge`,
+`challenge_expired`, `invalid_signature`, `invalid_nonce`, `no_license`,
+`invalid_session` or `session_expired`. RPC failures remain `LicenseRpcError`.
+Once a valid signature consumes a nonce, even an RPC failure or zero balance
+requires a fresh challenge. No session is issued on a nonce-store failure
+(`nonce_store_error`).
+
+The default nonce store is in memory per gate instance, prunes expired entries
+on challenge creation and caps pending entries at 10,000. For multiple workers
+or restarts, inject only a `nonceStore` with:
+
+```ts
+set(nonce: string, record: { message: string; expiresAt: number }): void | Promise<void>;
+consume(nonce: string): LicenseNonceRecord | null | undefined | Promise<LicenseNonceRecord | null | undefined>;
+```
+
+`expiresAt` is Unix milliseconds. `consume` must return and delete the record
+**atomically** across workers (for example with a Redis GETDEL); a separate
+get/delete pair is unsafe. Expire records at `expiresAt` and throw on storage
+failure. The SDK has no other persistence. Session tokens are bearer credentials;
+keep the HMAC secret on the server and use HTTPS to carry the token.
+
+`hasLicense` and `createLicenseGate` check NFT ownership only. OpenPay purchase
+rights can exist before minting, and non-transferable licenses retain purchase
+rights after burn; use the Verify API after separately authenticating the wallet
+if your service needs that purchase-rights policy. For transferable licenses,
+post-mint rights follow the current holder. Licenses carry no usage allowance or
+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.1 does not emit or validate binding metadata.
+
+### SDK verification in this repository
+
+```bash
+npm test --prefix packages/x402-sdk
+npx vitest run tests/packages/x402-sdk-*.test.ts
+```
+
+The package's unit tests use Node's built-in test runner with mocked RPC/fetch
+and real EOA signatures. Existing buyer/seller regression and tarball tests
+remain in the root Vitest suite; `npm run typecheck` also checks license API
+consumer types.
+
 ## Money guards
 
 | Option | Default | Guard |

package/index.d.ts

@@ -1,4 +1,4 @@
-import type { Address, Hex } from 'viem';
+import type { Address, Hex, PublicClient } from 'viem';
 
 export type JpycAmount = string | number;
 
@@ -333,6 +333,168 @@ export interface JpycGate {
 
 export function createJpycGate(options: JpycGateOptions): JpycGate;
 
+/** uint256 identity; JS numbers and decimal strings are intentionally unsupported. */
+export type LicenseTokenId = bigint | Hex;
+
+export interface LicenseIdentity {
+  chainId: number;
+  contract: Address;
+  tokenId: LicenseTokenId;
+}
+
+export type LicensePublicClient = Pick<PublicClient, 'getChainId' | 'getBlockNumber' | 'readContract'>;
+
+/** Polygon/Amoy public RPC defaults; other chains require an explicit transport. */
+export type LicenseTransport =
+  | { rpcUrl?: string; publicClient?: never }
+  | { rpcUrl?: never; publicClient: LicensePublicClient };
+
+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;
+  balance: bigint;
+  /** The block used for balanceOf, fetched without the viem block-number cache. */
+  blockNumber: bigint;
+}
+
+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' | 'not_ready';
+
+export class LicenseError extends Error {
+  readonly code: LicenseErrorCode;
+  constructor(code: LicenseErrorCode, message: string, options?: { cause?: unknown });
+}
+
+export class LicenseRpcError extends LicenseError {
+  readonly code: 'rpc_error';
+  constructor(message?: string, options?: { cause?: unknown });
+}
+
+/** RPC failures (including a wrong chain or malformed result) throw LicenseRpcError. */
+export function hasLicense(options: HasLicenseOptions): Promise<LicenseBalance>;
+
+export type LicenseNftStatus =
+  | 'awaiting_finality' | 'pending' | 'submitted' | 'minted' | 'registered'
+  | 'retryable' | 'needs_repair' | 'unknown';
+
+export interface VerifyLicenseOptions {
+  address: Address;
+  /** OpenPay hosted product ID: h_ followed by 32 lowercase hex digits. */
+  product: string;
+  /** Trusted HTTPS authority. Default: https://open-pay.jp. HTTP only on localhost/127.0.0.1. */
+  origin?: string;
+  /** Must honor redirect: 'manual' and the AbortSignal. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export interface LicenseVerification {
+  version: 1;
+  address: Address;
+  license: { chainId: number; contract: Address; tokenId: Hex; productId: string };
+  /** null means UNKNOWN, never false. This status response is not authentication. */
+  entitled: boolean | null;
+  basis: 'purchase' | 'holder' | null;
+  nft: { status: LicenseNftStatus; mintTxHash?: Hex };
+  observedBlock?: string;
+  checkedAt: string;
+}
+
+/** Validates the v1 response and address/product identity. Rejects all redirects. */
+export function verifyLicense(options: VerifyLicenseOptions): Promise<LicenseVerification>;
+
+export interface LicenseNonceRecord {
+  message: string;
+  /** Unix milliseconds. */
+  expiresAt: number;
+}
+
+export interface LicenseNonceStore {
+  /** Persist until expiresAt. Throw on failure. */
+  set(nonce: string, record: LicenseNonceRecord): void | Promise<void>;
+  /** Atomically return AND delete once across workers. Never implement as separate get/delete. */
+  consume(nonce: string): LicenseNonceRecord | null | undefined | Promise<LicenseNonceRecord | null | undefined>;
+}
+
+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;
+  };
+  /** 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;
+  /** Default: a bounded in-memory store for this gate instance. */
+  nonceStore?: LicenseNonceStore;
+  /** Clock in Unix milliseconds. Default Date.now. */
+  now?: () => number;
+};
+
+export interface LicenseSession {
+  address: Address;
+  tokenId: bigint;
+  /** Unix seconds. */
+  exp: number;
+}
+
+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 IO. Throws not_ready before discovery. */
+  check(token: string): LicenseSession;
+}
+
+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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpay-x402-sdk",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Guarded Node.js buyer SDK for OpenPay x402 JPYC resources",
   "type": "module",
   "main": "./src/index.mjs",
@@ -20,6 +20,9 @@
   "engines": {
     "node": ">=20"
   },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
   "dependencies": {
     "viem": "^2.45.0"
   }

package/src/index.mjs

@@ -4,6 +4,8 @@ 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,166 @@
+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, licenseProduct, licenseSelector,
+} 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, product, origin, fetch, chainId, contract, tokenId, rpcUrl, publicClient }) {
+  const holderAddress = licenseAddress(address);
+  const selected = licenseSelector({ product, chainId, contract, tokenId });
+  if (rpcUrl !== undefined && publicClient !== undefined) {
+    throw new TypeError('Provide rpcUrl or publicClient, not both');
+  }
+  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() !== 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({
+      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);
+  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(), {
+      method: 'GET', redirect: 'manual', signal: AbortSignal.timeout(15_000),
+      headers: { accept: 'application/json' },
+    });
+  } catch (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 ${label} redirects are not allowed`);
+  }
+  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 });
+  }
+}
+
+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

@@ -0,0 +1,70 @@
+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 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 && !httpsOnly)) ||
+    url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    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

@@ -0,0 +1,177 @@
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { verifyMessage } from 'viem';
+import { createSiweMessage, parseSiweMessage } from 'viem/siwe';
+import { hasLicense, resolveLicense } from './license.mjs';
+import {
+  DEFAULT_LICENSE_ORIGIN, LicenseError, licenseAddress, licenseIdentity, licenseOrigin, licenseSelector,
+} 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({
+  product, fetch, chainId, contract, tokenId, rpcUrl, publicClient,
+  session, origin = DEFAULT_LICENSE_ORIGIN,
+  statement = 'Sign in to use this license.', nonceStore, now = Date.now,
+}) {
+  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);
+  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');
+  }
+  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 holderAddress = licenseAddress(address);
+    await ready();
+    const nonce = randomBytes(32).toString('hex');
+    const issuedAt = now();
+    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');
+    }
+    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) {
+    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);
+    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 { ready, challenge, verify, check };
+}