openpay-x402-sdk 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.8.0
+
+- Add the typed `openpay-x402-sdk/delivery` Web-API-only subpath: strict Ed25519
+  delivery-ticket verification, request extraction, startup readiness and RFC 7638
+  thumbprints. Preserve all root exports and dependencies.
+- Bound JWKS fetches, enforce complete key-set validation, honor Age in a 300-second
+  cache, share concurrent fetches, throttle unknown-kid refresh and reject stale
+  trust. Supplied keys never fetch or automatically refresh.
+- Add optional atomic replay consumption with fail-closed errors and final expiry
+  rechecks; ship private R2/Durable Object and Node presigned-redirect templates.
+- Cross-check shared fixtures and fresh server signatures, packed subpath imports,
+  types, runtime capability failures, and template authorization boundaries.
+- Document bearer/session-wallet semantics and the Node/Workers acceptance matrix.
+  No dependencies added. Initial generation only: human review and real private R2
+  deployment acceptance remain required before adoption; publication is separate.
+
 ## 0.7.1
 
 - Add `resolveLicense({ product, origin?, fetch? })` for validated v1 product

package/README.md

@@ -374,6 +374,131 @@ 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.
 
+## 保護配布 (Delivery ticket)
+
+SDK 0.8.0 is an **initial generation** workspace release, not yet published or
+production-adopted. OpenPay signs a 60-second bearer ticket after checking
+entitlement. Sellers verify it with the public JWKS; no secret is shared with
+OpenPay. The token is signed, not encrypted, and its claims are readable.
+Possession authorizes admission during its lifetime; it is access control, not
+copy protection or an allowance/payment balance.
+
+Import the dedicated typed subpath. The existing package root remains Node-only
+and does **not** re-export delivery helpers or types.
+
+```js
+import { createDeliveryGate, DeliveryError } from 'openpay-x402-sdk/delivery';
+
+const delivery = createDeliveryGate({
+  product: 'h_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+  audience: 'https://files.example', // Trusted seller configuration, not Host/header input.
+});
+await delivery.ready(); // Probe standard Ed25519 and prefetch validated JWKS.
+
+async function authorize(request) {
+  try {
+    const { product, revision, exp, address } = await delivery.verifyRequest(request);
+    // Resolve (product, revision) using YOUR trusted map, then serve private bytes.
+    return { product, revision, exp, address };
+  } catch (error) {
+    if (error instanceof DeliveryError) return null; // Deny; never log the request/ticket.
+    throw error;
+  }
+}
+```
+
+`verifyDeliveryTicket({ ticket, product, audience, issuer?, origin?, fetch?, now?,
+keys?, maxSkewSeconds?, replayStore? })` returns
+`{ address, product, revision, basis, exp, iat, jti, kid }`.
+`createDeliveryGate` takes the same options except `ticket`, and exposes async
+`ready()`, `verify(ticket)`, and `verifyRequest(request)`.
+`ticketFromRequest(request)` reads exactly one `?ticket=` or
+`Authorization: Bearer <ticket>` and returns `null` if absent. Duplicate/query-plus-
+authorization credentials, empty tickets and malformed authorization are rejected.
+`deliveryKeyThumbprint(x)` computes the RFC 7638 public-key ID.
+
+The expected `issuer` defaults to `https://open-pay.jp`; `origin` defaults to
+`issuer` and controls only trusted HTTPS JWKS transport. Configure these yourself,
+never from token headers/claims. Issuer/audience configuration is normalized with
+`new URL(value).origin`; the signed claims must exactly match that normalized
+origin. `now` returns Unix **milliseconds** (default `Date.now`); returned `iat`
+and `exp` are Unix **seconds**. Future `iat` allows `maxSkewSeconds` (default 30);
+expiry is strict, never extended by skew, and rechecked after async verification
+and immediately before returning. `sub`/`address` means the session wallet at
+issuance, **not proof that the presenter controls that wallet**. The SDK checks
+`0x` plus 40 hex characters and preserves spelling; EIP-55 checksum is enforced
+server-side at issuance, without adding a crypto dependency to the subpath.
+
+Optional single-use storage must implement:
+
+```ts
+consume(jti: string, expSeconds: number): Promise<boolean>;
+```
+
+Reserve the jti **atomically across instances** until its absolute Unix-second
+expiry: true for the first consume, false for a replay, throw on storage failure.
+Namespace storage per issuer/product/audience. The SDK calls it only after full
+verification, and denies on false (`replay`) or exceptions (`replay_store_error`).
+Other return values also deny. Concurrent calls must yield exactly one true.
+Without a store, reuse within TTL is allowed. After consumption, a downstream
+failure, HEAD request or retry needs a fresh ticket; no consume is rolled back.
+Workers KV get/put is not equivalent to atomic consume; the bundled example uses
+a Durable Object. An admitted stream may finish after expiry; subsequent requests
+(including resume/Range) must authenticate again.
+
+Public keys are validated as a whole (at most 8, public Ed25519 only, matching
+thumbprints, no duplicate kids). Fetches use an 8-second deadline, manual redirect
+rejection and a 16 KiB response cap. Cache is scoped by issuer and configured key
+origin for at most 300 seconds, subtracting upstream `Age` and fetch elapsed time.
+Age >= 300 is rejected; expired cache entries are refetched and **never** used on
+failure. Concurrent fetches share a request. Unknown kids trigger at most one
+extra refresh per 60 seconds per scope, including failed attempts. Invalid refreshes
+never replace good keys: still-fresh known cached keys remain usable, while the
+failed refresh request denies. `keys` supplied directly are validated and used
+exclusively, never fetched or automatically refreshed (even if empty/invalid).
+
+Rotation must publish `old,new` before signing with new, wait at least 15 minutes,
+switch to `new,old`, and retain old through propagation plus ticket lifetime.
+Emergency removal requires CDN purge and verifier refresh/reconfiguration; leaked
+keys can sign new tickets while cached public keys remain trusted. Turning off
+issuance does not revoke an attacker's signing ability or recall downloaded bytes.
+
+| Runtime | Delivery subpath requirement / acceptance |
+| --- | --- |
+| Node 20.19+ | Global WebCrypto with standard Ed25519; package engine remains Node >=20. |
+| Node 22.13+ | Same Web API entry point. |
+| Node 24 | Same Web API entry point. |
+| Cloudflare Workers | Standard `Ed25519`, no `nodejs_compat`; run a real deployment smoke on the template's pinned compatibility date. |
+
+`ready()` detects missing Ed25519 support as `unsupported_crypto`; there is no
+algorithm downgrade. The matrix is a release target, not proof that every runtime
+was executed by package tests. A real Worker deployment/private R2 smoke is an
+acceptance step. See [Node WebCrypto](https://nodejs.org/api/webcrypto.html) and
+[Workers WebCrypto](https://developers.cloudflare.com/workers/runtime-apis/web-crypto/).
+
+Errors are `DeliveryError` with codes: `invalid_ticket`, `unsupported_algorithm`,
+`unknown_key`, `keys_unavailable`, `ticket_expired`, `ticket_not_yet_valid`,
+`wrong_issuer`, `wrong_audience`, `wrong_product`, `unsupported_crypto`, `replay`,
+`replay_store_error`. SDK errors omit raw tickets, URLs and upstream bodies.
+
+Start from the packaged [private R2 Worker template](examples/cloudflare-r2-delivery-gate/README.md)
+or [Node presigned-redirect example](examples/node-delivery-gate.mjs). The Node
+example uses `OPENPAY_PRODUCT_ID`, `AUDIENCE`, and optional `OBJECT_KEYS` (default
+`{ "1": "file-v1.zip" }`), listens on 127.0.0.1:8787 behind HTTPS, and requires you
+to implement the seller storage-SDK presigning stub. Its signature's absolute
+expiry must be <= the ticket's `exp`, even if presigning is slow; a duration alone
+must not extend that deadline. Presigned URLs are separate bearer capabilities.
+
+“Product ID only” is an onboarding simplification: audience, a trusted revision
+map, a private bucket binding and deployment compatibility still need configuration.
+Reject unmapped revisions instead of serving the latest file. Authenticate before
+all file/HEAD/Range/conditional paths and before any Cache API access. Close old
+unsigned/public-bucket URLs. Success, error and redirect responses need
+`Cache-Control: private, no-store`, `Referrer-Policy: no-referrer`, and attachment
+disposition. Redact tickets/URLs in seller/CDN logs, Location, JSON and exceptions;
+no-referrer does not erase history or existing logs. Use a stable gate destination,
+not a presigned URL that may be broken by query reserialization.
+
 ## Money guards
 
 | Option | Default | Guard |

package/delivery.d.ts

@@ -0,0 +1,68 @@
+export type DeliveryErrorCode =
+  | 'invalid_ticket' | 'unsupported_algorithm' | 'unknown_key' | 'keys_unavailable'
+  | 'ticket_expired' | 'ticket_not_yet_valid' | 'wrong_issuer' | 'wrong_audience'
+  | 'wrong_product' | 'unsupported_crypto' | 'replay' | 'replay_store_error';
+
+export class DeliveryError extends Error {
+  constructor(code: DeliveryErrorCode);
+  code: DeliveryErrorCode;
+}
+
+export interface DeliveryPublicJwk {
+  readonly kty: 'OKP';
+  readonly crv: 'Ed25519';
+  readonly x: string;
+  readonly kid: string;
+  readonly use: 'sig';
+  readonly alg: 'EdDSA';
+}
+
+export interface DeliveryReplayStore {
+  /** Atomically reserve jti until expSeconds (Unix seconds). Failure must throw. */
+  consume(jti: string, expSeconds: number): Promise<boolean>;
+}
+
+export interface DeliveryOptions {
+  product: string;
+  /** Trusted seller HTTPS URL; compared using new URL(audience).origin. */
+  audience: string;
+  /** Expected issuer; defaults to https://open-pay.jp. Never take it from a ticket. */
+  issuer?: string;
+  /** Trusted HTTPS key transport origin; defaults to issuer. */
+  origin?: string;
+  fetch?: typeof globalThis.fetch;
+  /** Unix milliseconds; defaults to Date.now. */
+  now?: () => number;
+  /** Use only these keys, without network access, caching or automatic rotation. */
+  keys?: readonly DeliveryPublicJwk[];
+  /** Nonnegative future-iat allowance in seconds, default 30; never extends exp. */
+  maxSkewSeconds?: number;
+  replayStore?: DeliveryReplayStore;
+}
+
+export interface DeliveryVerification {
+  /** Signed session wallet at issuance, preserved as-is; no presenter identity proof. */
+  address: string;
+  product: string;
+  revision: number;
+  basis: 'purchase' | 'holder';
+  /** Unix seconds. */
+  exp: number;
+  /** Unix seconds. */
+  iat: number;
+  jti: string;
+  kid: string;
+}
+
+export interface DeliveryGate {
+  /** Probe standard Ed25519 and validate supplied keys or prefetch the public JWKS. */
+  ready(): Promise<void>;
+  verify(ticket: string): Promise<DeliveryVerification>;
+  verifyRequest(request: Request): Promise<DeliveryVerification>;
+}
+
+export function verifyDeliveryTicket(options: DeliveryOptions & { ticket: string }): Promise<DeliveryVerification>;
+export function ticketFromRequest(request: Request): string | null;
+export function createDeliveryGate(options: DeliveryOptions): DeliveryGate;
+/** RFC 7638 SHA-256 thumbprint of a canonical base64url 32-byte Ed25519 x. */
+export function deliveryKeyThumbprint(x: string): Promise<string>;

package/examples/cloudflare-r2-delivery-gate/README.md

@@ -0,0 +1,62 @@
+# Private R2 delivery gate (SDK 0.8.0 initial generation)
+
+This template verifies an OpenPay 60-second bearer ticket before accessing R2.
+It uses `openpay-x402-sdk/delivery`, standard WebCrypto `Ed25519`, and no Node
+compatibility flag. Package source/tests are not a real Workers deployment proof.
+
+1. Use the reviewed 0.8.0 package artifact in a seller project; it is not assumed
+   published. After publication, the dependency can be installed from the official
+   npm registry. Copy `worker.mjs` and `wrangler.toml` together.
+2. Create a **private** R2 bucket, upload each immutable revision, and replace
+   `bucket_name`. Disable public r2.dev access and public bucket custom domains.
+   Remove any old unsigned object URL; ordinary product content should contain
+   instructions or a safe landing page, not a file bypass.
+3. Configure the variables below and bind the worker's public HTTPS hostname.
+   Set that stable gate URL as the OpenPay product's delivery destination.
+4. For single-use admission, uncomment both `REPLAY` and its SQLite migration in
+   `wrangler.toml`. Deploy through your reviewed release process. The compatibility
+   date is pinned to `2026-09-09`; test that date on a real Worker before adoption.
+
+| Setting | Meaning |
+| --- | --- |
+| `OPENPAY_PRODUCT_ID` | Exact `h_` + 32 lowercase hex product ID; never request-controlled. |
+| `AUDIENCE` | Worker's public HTTPS origin, e.g. `https://files.example`; must equal the configured destination's origin. |
+| `OBJECT_KEYS` | Optional JSON revision map, e.g. `{ "1": "file-v1.zip" }`. Default is exactly that map. Every unmapped revision is denied, with no latest-version fallback. |
+| `FILES` | R2 binding to the private bucket. |
+| `REPLAY` | Optional private Durable Object binding, one object per product/audience/jti. |
+
+`ready()` runs at isolate startup on its first request (network I/O is unavailable
+at module evaluation), before any file access. Failed startup denies and can
+retry. All GET/HEAD/Range/conditional requests authenticate first. This deliberately
+small template ignores Range and conditional headers: GET sends full content with
+200, HEAD sends metadata only. Add resumable/conditional responses only behind the
+same gate. No Cache API is consulted. All responses use `private, no-store`,
+`no-referrer`, and `Content-Disposition: attachment`; failures are generic 403 JSON.
+
+The Durable Object uses `blockConcurrencyWhile` around storage read/put/alarm,
+so simultaneous consumes cannot both succeed; an alarm removes state at expiry.
+Storage or alarm failures deny admission. **Workers KV is NOT equivalent** to
+atomic consume. Omit `REPLAY` only if replay during the ticket's TTL is acceptable.
+A consumed ticket stays consumed after R2 failure. HEAD consumes it too: acquire
+another ticket for GET, retries, ranges or restarts. A stream admitted before
+expiry may finish after expiry; the SDK does not cut it off at 60 seconds.
+
+`sub` is the issuance session's wallet, not proof of the presenter's identity.
+The token is readable and bearer-authorized, not DRM. Suppress or redact query
+strings, Authorization, Location and ticket-bearing errors throughout seller/CDN
+logs. `no-referrer` does not remove browser history or already stored logs.
+
+Release acceptance must run a private R2 end-to-end download on the pinned Worker:
+valid/expired/wrong-product/unmapped-revision tickets; missing/duplicate/conflicting
+credentials; HEAD/Range/conditional access; simultaneous replay (exactly one
+success); storage/downstream failure; and no unsigned/public/cache bypass. Run a
+cold-JWKS request and staged key rotation too. These are deployment checks, not
+claims established by mocked package tests. See the [SDK delivery documentation](../../README.md#保護配布-delivery-ticket)
+for cache/rotation and runtime boundaries. The [Node example](../node-delivery-gate.mjs)
+uses the same env names and map, but its seller presigning stub must be implemented;
+the storage signature's absolute deadline must be at most the ticket's `exp`.
+
+References: [standard WebCrypto](https://developers.cloudflare.com/workers/runtime-apis/web-crypto/),
+[Durable Object event isolation](https://developers.cloudflare.com/durable-objects/api/state/),
+[alarms](https://developers.cloudflare.com/durable-objects/api/alarms/),
+[Workers KV consistency](https://developers.cloudflare.com/kv/concepts/how-kv-works/).

package/examples/cloudflare-r2-delivery-gate/worker.mjs

@@ -0,0 +1,85 @@
+import { createDeliveryGate } from 'openpay-x402-sdk/delivery';
+
+const PRIVATE_HEADERS = {
+  'Cache-Control': 'private, no-store',
+  'Referrer-Policy': 'no-referrer',
+  'Content-Disposition': 'attachment',
+};
+const instances = new WeakMap();
+
+async function startup(env) {
+  if (!instances.has(env)) {
+    const pending = (async () => {
+      const objects = JSON.parse(env.OBJECT_KEYS ?? '{"1":"file-v1.zip"}');
+      if (!objects || Array.isArray(objects) || typeof objects !== 'object' ||
+        Object.entries(objects).some(([rev, key]) => !/^[1-9][0-9]*$/.test(rev) || typeof key !== 'string' || !key)) {
+        throw new Error('invalid_object_map');
+      }
+      const gate = createDeliveryGate({
+        product: env.OPENPAY_PRODUCT_ID, audience: env.AUDIENCE,
+        replayStore: env.REPLAY ? {
+          async consume(jti, expSeconds) {
+            const id = env.REPLAY.idFromName(`${env.OPENPAY_PRODUCT_ID}:${new URL(env.AUDIENCE).origin}:${jti}`);
+            const response = await env.REPLAY.get(id).fetch('https://replay.internal/consume', {
+              method: 'POST', body: JSON.stringify({ expSeconds }),
+            });
+            if (response.status !== 200) throw new Error('replay_store_error');
+            return response.json();
+          },
+        } : undefined,
+      });
+      // Workers cannot fetch at module evaluation: initialize on the first event,
+      // before any file operation. Failed startup can retry on the next request.
+      await gate.ready();
+      return { gate, objects };
+    })();
+    instances.set(env, pending);
+    pending.catch(() => instances.delete(env));
+  }
+  return instances.get(env);
+}
+
+const worker = {
+  async fetch(request, env) {
+    try {
+      const { gate, objects } = await startup(env);
+      const verified = await gate.verifyRequest(request);
+      if (new URL(request.url).origin !== new URL(env.AUDIENCE).origin ||
+        !['GET', 'HEAD'].includes(request.method) || !Object.hasOwn(objects, String(verified.revision))) {
+        throw new Error('denied');
+      }
+      // Product is pinned by the gate; revision selects only this trusted map.
+      // No Cache API lookup, request-derived object key, or public bucket URL.
+      const key = objects[String(verified.revision)];
+      const file = await (request.method === 'HEAD' ? env.FILES.head(key) : env.FILES.get(key));
+      if (!file || verified.exp * 1000 <= Date.now()) throw new Error('denied');
+      // This small template ignores Range/conditional headers and serves a full
+      // 200 (HEAD returns metadata). Every such request still requires a ticket.
+      return new Response(request.method === 'HEAD' ? null : file.body, {
+        headers: { ...PRIVATE_HEADERS, 'Content-Type': 'application/octet-stream', 'Content-Length': String(file.size) },
+      });
+    } catch {
+      // Do not expose request URLs, tickets, R2 keys or upstream exceptions.
+      return Response.json({ error: 'delivery_denied' }, { status: 403, headers: PRIVATE_HEADERS });
+    }
+  },
+};
+
+export default worker;
+
+// One private Durable Object per namespaced jti. Only the binding can reach it.
+export class Replay {
+  constructor(state) { this.state = state; }
+  async fetch(request) {
+    const { expSeconds } = await request.json();
+    const consumed = await this.state.blockConcurrencyWhile(async () => {
+      if (!Number.isSafeInteger(expSeconds) || expSeconds * 1000 <= Date.now() ||
+        await this.state.storage.get('consumed')) return false;
+      await this.state.storage.put('consumed', true);
+      await this.state.storage.setAlarm(expSeconds * 1000);
+      return true;
+    });
+    return Response.json(consumed);
+  }
+  async alarm() { await this.state.storage.deleteAll(); }
+}

package/examples/cloudflare-r2-delivery-gate/wrangler.toml

@@ -0,0 +1,23 @@
+name = "openpay-delivery-gate"
+main = "worker.mjs"
+compatibility_date = "2026-09-09"
+# No nodejs_compat flag: delivery uses standard Web APIs and Ed25519.
+
+[vars]
+OPENPAY_PRODUCT_ID = "h_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+AUDIENCE = "https://files.example"
+# Optional; default is revision 1 -> file-v1.zip. Reject every unmapped revision.
+OBJECT_KEYS = '{ "1": "file-v1.zip", "2": "file-v2.zip" }'
+
+[[r2_buckets]]
+binding = "FILES"
+bucket_name = "replace-with-your-private-bucket"
+
+# Optional single-use tickets: uncomment BOTH sections together.
+# [[durable_objects.bindings]]
+# name = "REPLAY"
+# class_name = "Replay"
+#
+# [[migrations]]
+# tag = "v1"
+# new_sqlite_classes = ["Replay"]

package/examples/node-delivery-gate.mjs

@@ -0,0 +1,54 @@
+import { createServer } from 'node:http';
+import { pathToFileURL } from 'node:url';
+import { createDeliveryGate } from 'openpay-x402-sdk/delivery';
+
+const PRIVATE_HEADERS = {
+  'Cache-Control': 'private, no-store', 'Referrer-Policy': 'no-referrer', 'Content-Disposition': 'attachment',
+};
+
+async function presignObject({ key, method, expiresAt, expiresInSeconds }) {
+  // Implement with YOUR storage SDK and private bucket. Bind key and method (GET/HEAD), and
+  // set the signature's absolute expiry <= expiresAt (not "now + 60"). If the
+  // SDK only takes a duration, anchor its signing time before this function's
+  // async work and cap it to expiresInSeconds. Never log the URL or ticket.
+  void key; void method; void expiresAt; void expiresInSeconds;
+  throw new Error('Implement seller presigning before starting this example');
+}
+
+export function createDeliveryHandler({ gate, audience, objectKeys, presign = presignObject, now = Date.now }) {
+  return async (req, res) => {
+    try {
+      // Preserve duplicate Authorization fields so the SDK rejects ambiguity.
+      const headers = new Headers();
+      for (let i = 0; i < req.rawHeaders.length; i += 2) headers.append(req.rawHeaders[i], req.rawHeaders[i + 1]);
+      const request = new Request(new URL(req.url, audience), { method: req.method, headers });
+      const verified = await gate.verifyRequest(request);
+      if (new URL(request.url).origin !== new URL(audience).origin ||
+        !['GET', 'HEAD'].includes(req.method) || !Object.hasOwn(objectKeys, String(verified.revision))) throw new Error('denied');
+      const key = objectKeys[String(verified.revision)];
+      if (typeof key !== 'string' || !key) throw new Error('denied');
+      const expiresAt = verified.exp * 1000;
+      const expiresInSeconds = Math.floor((expiresAt - now()) / 1000);
+      if (expiresInSeconds <= 0) throw new Error('expired');
+      const location = new URL(await presign({ key, method: req.method, expiresAt, expiresInSeconds }));
+      if (location.protocol !== 'https:' || location.username || location.password || now() >= expiresAt) throw new Error('denied');
+      // HEAD/Range/conditional requests are authorized here too. A presigned URL
+      // is a separate bearer capability; its expiry must satisfy the stub above.
+      res.writeHead(302, { ...PRIVATE_HEADERS, Location: location.href });
+      res.end();
+    } catch {
+      res.writeHead(403, { ...PRIVATE_HEADERS, 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'delivery_denied' }));
+    }
+  };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const audience = process.env.AUDIENCE;
+  const gate = createDeliveryGate({ product: process.env.OPENPAY_PRODUCT_ID, audience });
+  await gate.ready(); // Fail startup on unsupported Ed25519 or unavailable JWKS.
+  const objectKeys = JSON.parse(process.env.OBJECT_KEYS ?? '{"1":"file-v1.zip"}');
+  createServer(createDeliveryHandler({ gate, audience, objectKeys })).listen(8787, '127.0.0.1');
+  // Place behind HTTPS at AUDIENCE; keep the bucket private. This example permits
+  // ticket replay within its TTL; inject an atomic replayStore to make it single-use.
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openpay-x402-sdk",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Guarded Node.js buyer SDK for OpenPay x402 JPYC resources",
   "type": "module",
   "main": "./src/index.mjs",
@@ -9,13 +9,19 @@
     ".": {
       "types": "./index.d.ts",
       "import": "./src/index.mjs"
+    },
+    "./delivery": {
+      "types": "./delivery.d.ts",
+      "import": "./src/delivery.mjs"
     }
   },
   "files": [
     "src",
     "index.d.ts",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "delivery.d.ts",
+    "examples"
   ],
   "engines": {
     "node": ">=20"

package/src/delivery.mjs

@@ -0,0 +1,305 @@
+// Standalone Web API entry point: keep the Node-only package root out of this graph.
+const DEFAULT_ISSUER = 'https://open-pay.jp';
+const HEADER_FIELDS = ['alg', 'typ', 'kid'];
+const CLAIM_FIELDS = ['v', 'iss', 'aud', 'sub', 'product', 'rev', 'basis', 'iat', 'exp', 'jti'];
+const KEY_FIELDS = ['kty', 'crv', 'x', 'kid', 'use', 'alg'];
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const encoder = new TextEncoder();
+const caches = new Map();
+const cryptoProbes = new WeakMap();
+
+export class DeliveryError extends Error {
+  constructor(code) {
+    // Never retain a ticket, key response, request URL or upstream exception.
+    super(code);
+    this.name = 'DeliveryError';
+    this.code = code;
+  }
+}
+
+function fail(code = 'invalid_ticket') { throw new DeliveryError(code); }
+function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function exactFields(value, fields) {
+  return object(value) && Object.keys(value).length === fields.length && fields.every((key) => Object.hasOwn(value, key));
+}
+function encode(bytes) {
+  let result = '';
+  for (let i = 0; i < bytes.length; i += 3) {
+    const n = (bytes[i] << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+    result += ALPHABET[(n >>> 18) & 63] + ALPHABET[(n >>> 12) & 63];
+    if (i + 1 < bytes.length) result += ALPHABET[(n >>> 6) & 63];
+    if (i + 2 < bytes.length) result += ALPHABET[n & 63];
+  }
+  return result;
+}
+function decode(raw, max, code = 'invalid_ticket') {
+  if (typeof raw !== 'string' || !raw.length || raw.length > max || !/^[A-Za-z0-9_-]+$/.test(raw)) fail(code);
+  const bytes = new Uint8Array(Math.floor(raw.length * 6 / 8));
+  let bits = 0; let n = 0; let offset = 0;
+  for (const char of raw) {
+    n = (n << 6) | ALPHABET.indexOf(char);
+    bits += 6;
+    if (bits >= 8) { bits -= 8; bytes[offset++] = (n >>> bits) & 255; }
+  }
+  if (encode(bytes) !== raw) fail(code);
+  return bytes;
+}
+function parseJson(bytes, flat, code = 'invalid_ticket') {
+  try {
+    const raw = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    const value = JSON.parse(raw);
+    if (!object(value) || (flat && Object.values(value).some((v) => v !== null && typeof v === 'object'))) fail(code);
+    // JSON.parse validates grammar; scan complete string tokens to detect even
+    // escaped duplicate member names before accepting its last-member-wins result.
+    const stack = [];
+    for (const token of raw.matchAll(/"(?:[^"\\]|\\[\s\S])*"|[{}\[\]]/g)) {
+      const part = token[0];
+      if (part === '{') stack.push(new Set());
+      else if (part === '[') stack.push(null);
+      else if (part === '}' || part === ']') stack.pop();
+      else if (raw.slice(token.index + part.length).trimStart().startsWith(':')) {
+        const key = JSON.parse(part);
+        const members = stack[stack.length - 1];
+        if (members.has(key)) fail(code);
+        members.add(key);
+      }
+    }
+    return value;
+  } catch { fail(code); }
+}
+function subtleCrypto() {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle || typeof subtle.importKey !== 'function' || typeof subtle.verify !== 'function' ||
+    typeof subtle.digest !== 'function') fail('unsupported_crypto');
+  return subtle;
+}
+export async function deliveryKeyThumbprint(x) {
+  if (decode(x, 43, 'keys_unavailable').length !== 32) fail('keys_unavailable');
+  try {
+    return encode(new Uint8Array(await subtleCrypto().digest('SHA-256', encoder.encode(JSON.stringify({ crv: 'Ed25519', kty: 'OKP', x })))));
+  } catch { fail('unsupported_crypto'); }
+}
+async function importPublicKey(x) {
+  try {
+    return await subtleCrypto().importKey('jwk', { kty: 'OKP', crv: 'Ed25519', x }, { name: 'Ed25519' }, false, ['verify']);
+  } catch (error) {
+    if (error?.name === 'NotSupportedError' || error?.code === 'unsupported_crypto') fail('unsupported_crypto');
+    fail('keys_unavailable');
+  }
+}
+async function probeCrypto() {
+  const subtle = subtleCrypto();
+  if (!cryptoProbes.has(subtle)) {
+    // RFC 8032 test 1: public verification only, no seed or runtime key generation.
+    const probe = (async () => {
+      try {
+        const key = await importPublicKey('11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo');
+        const hex = 'e5564300c360ac729086e2cc806e828a84877f1eb8e5d974d873e065224901555fb8821590a33bacc61e39701cf9b46bd25bf5f0595bbe24655141438e7a100b';
+        const signature = Uint8Array.from(hex.match(/../g), (byte) => Number.parseInt(byte, 16));
+        if (!await subtle.verify('Ed25519', key, signature, new Uint8Array())) fail('unsupported_crypto');
+      } catch { fail('unsupported_crypto'); }
+    })();
+    cryptoProbes.set(subtle, probe);
+    // Allow a later startup retry after a failed capability probe.
+    probe.catch(() => cryptoProbes.delete(subtle));
+  }
+  await cryptoProbes.get(subtle);
+}
+function normalizedOrigin(value, code) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' || url.username || url.password) fail(code);
+    return url.origin;
+  } catch { fail(code); }
+}
+function options({ product, audience, issuer = DEFAULT_ISSUER, origin = issuer, fetch: fetchImpl = globalThis.fetch,
+  now = Date.now, keys, maxSkewSeconds = 30, replayStore }) {
+  if (typeof product !== 'string' || !/^h_[0-9a-f]{32}$/.test(product)) fail('wrong_product');
+  if (!Number.isFinite(maxSkewSeconds) || maxSkewSeconds < 0 || typeof now !== 'function') fail();
+  if (replayStore !== undefined && typeof replayStore?.consume !== 'function') fail('replay_store_error');
+  return { product, audience: normalizedOrigin(audience, 'wrong_audience'), issuer: normalizedOrigin(issuer, 'wrong_issuer'),
+    origin: normalizedOrigin(origin, 'keys_unavailable'), fetchImpl, now, keys, maxSkewSeconds, replayStore };
+}
+function timeMs(config) {
+  const time = config.now();
+  if (!Number.isFinite(time)) fail();
+  return time;
+}
+function checkTime(claims, config) {
+  const now = timeMs(config) / 1000;
+  if (claims.exp <= now) fail('ticket_expired');
+  if (claims.iat > now + config.maxSkewSeconds) fail('ticket_not_yet_valid');
+}
+async function validateKeys(keys) {
+  if (!Array.isArray(keys) || keys.length === 0 || keys.length > 8) fail('keys_unavailable');
+  const result = new Map();
+  for (const key of keys) {
+    if (!exactFields(key, KEY_FIELDS) || key.kty !== 'OKP' || key.crv !== 'Ed25519' || key.use !== 'sig' || key.alg !== 'EdDSA') fail('keys_unavailable');
+    // Copy before awaiting so supplied mutable objects cannot change validated trust.
+    const { x, kid } = key;
+    if (typeof kid !== 'string' || kid.length !== 43 || kid !== await deliveryKeyThumbprint(x) || result.has(kid)) fail('keys_unavailable');
+    result.set(kid, x);
+  }
+  return result;
+}
+async function readKeysResponse(response, config) {
+  if (response.status !== 200 || response.redirected || response.type === 'opaqueredirect' ||
+    (response.url && new URL(response.url).origin !== config.origin)) fail('keys_unavailable');
+  const length = response.headers.get('content-length');
+  if (length !== null && (!/^\d+$/.test(length) || Number(length) > 16_384)) fail('keys_unavailable');
+  const ageHeader = response.headers.get('age');
+  const age = ageHeader === null ? 0 : Number(ageHeader);
+  if (ageHeader !== null && (!/^\d+$/.test(ageHeader) || !Number.isSafeInteger(age))) fail('keys_unavailable');
+  if (age >= 300 || !response.body) fail('keys_unavailable');
+  const reader = response.body.getReader();
+  const chunks = []; let size = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > 16_384) fail('keys_unavailable');
+      chunks.push(value);
+    }
+  } finally {
+    // Do not let cancellation failure mask the bounded-read denial or hang it.
+    reader.cancel().catch(() => {});
+  }
+  const bytes = new Uint8Array(size); let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+  const body = parseJson(bytes, false, 'keys_unavailable');
+  if (!exactFields(body, ['keys'])) fail('keys_unavailable');
+  return { keys: await validateKeys(body.keys), age };
+}
+function cacheFor(config) {
+  // Isolate both the expected issuer and explicitly configured transport origin.
+  const id = `${config.issuer}\n${config.origin}`;
+  if (!caches.has(id)) caches.set(id, { current: null, flight: null, lastUnknownRefresh: -Infinity });
+  return caches.get(id);
+}
+function fresh(set, config) {
+  const now = timeMs(config);
+  return set && now >= set.fetchedAt && now < set.expiresAt;
+}
+async function refresh(cache, config) {
+  if (cache.flight) return cache.flight;
+  cache.flight = (async () => {
+    const fetchedAt = timeMs(config);
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => { controller.abort(); reject(new DeliveryError('keys_unavailable')); }, 8_000);
+    });
+    try {
+      const { keys, age } = await Promise.race([
+        (async () => readKeysResponse(await config.fetchImpl(`${config.origin}/.well-known/openpay-delivery-keys.json`, {
+          method: 'GET', redirect: 'manual', signal: controller.signal, headers: { accept: 'application/json' },
+        }), config))(), timeout,
+      ]);
+      const set = { keys, fetchedAt, expiresAt: fetchedAt + (300 - age) * 1000 };
+      if (!fresh(set, config)) fail('keys_unavailable');
+      cache.current = set;
+      return set;
+    } catch (error) {
+      // Transport/parser failures remain confined to delivery and disclose no body/URL.
+      if (error?.code === 'unsupported_crypto') throw error;
+      fail('keys_unavailable');
+    } finally {
+      clearTimeout(timer);
+      // Stop unread transport bodies on early status/size/age rejection as well.
+      controller.abort();
+    }
+  })();
+  try { return await cache.flight; } finally { cache.flight = null; }
+}
+async function selectKey(kid, config) {
+  if (config.keys !== undefined) {
+    const keys = await validateKeys(config.keys);
+    if (!keys.has(kid)) fail('unknown_key');
+    return keys.get(kid);
+  }
+  const cache = cacheFor(config);
+  let set = fresh(cache.current, config) ? cache.current : await refresh(cache, config);
+  if (!set.keys.has(kid)) {
+    const now = timeMs(config);
+    if (cache.flight) set = await cache.flight;
+    else if (now - cache.lastUnknownRefresh >= 60_000) {
+      cache.lastUnknownRefresh = now;
+      set = await refresh(cache, config);
+    }
+  }
+  if (!fresh(set, config)) fail('keys_unavailable');
+  if (!set.keys.has(kid)) fail('unknown_key');
+  return set.keys.get(kid);
+}
+
+export async function verifyDeliveryTicket({ ticket, ...input }) {
+  const config = options(input);
+  if (typeof ticket !== 'string' || ticket.length > 1024 + 4096 + 88) fail();
+  const segments = ticket.split('.');
+  if (segments.length !== 3) fail();
+  const header = parseJson(decode(segments[0], 1024), true);
+  const claims = parseJson(decode(segments[1], 4096), true);
+  const signature = decode(segments[2], 86);
+  if (!exactFields(header, HEADER_FIELDS)) fail();
+  if (header.alg !== 'EdDSA') fail('unsupported_algorithm');
+  if (header.typ !== 'openpay-delivery+jwt' || decode(header.kid, 43).length !== 32 || signature.length !== 64) fail();
+  if (!exactFields(claims, CLAIM_FIELDS) || claims.v !== 1 ||
+    typeof claims.sub !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(claims.sub) ||
+    !Number.isSafeInteger(claims.rev) || claims.rev <= 0 || !['purchase', 'holder'].includes(claims.basis) ||
+    typeof claims.jti !== 'string' || !/^[0-9a-f]{32}$/.test(claims.jti) ||
+    !Number.isSafeInteger(claims.iat) || !Number.isSafeInteger(claims.exp) || claims.exp !== claims.iat + 60) fail();
+  if (claims.iss !== config.issuer) fail('wrong_issuer');
+  if (claims.aud !== config.audience) fail('wrong_audience');
+  if (typeof claims.product !== 'string' || !/^h_[0-9a-f]{32}$/.test(claims.product) || claims.product !== config.product) fail('wrong_product');
+  const key = await importPublicKey(await selectKey(header.kid, config));
+  let verified;
+  try { verified = await subtleCrypto().verify('Ed25519', key, signature, encoder.encode(`${segments[0]}.${segments[1]}`)); } catch (error) {
+    if (error?.name === 'NotSupportedError' || error?.code === 'unsupported_crypto') fail('unsupported_crypto');
+    fail();
+  }
+  if (!verified) fail();
+  checkTime(claims, config);
+  if (config.replayStore !== undefined) {
+    let consumed;
+    try { consumed = await config.replayStore.consume(claims.jti, claims.exp); } catch { fail('replay_store_error'); }
+    if (consumed === false) fail('replay');
+    if (consumed !== true) fail('replay_store_error');
+  }
+  checkTime(claims, config);
+  // EIP-55 checksum is enforced at issuance; preserve the signed address as-is.
+  return { address: claims.sub, product: claims.product, revision: claims.rev, basis: claims.basis,
+    exp: claims.exp, iat: claims.iat, jti: claims.jti, kid: header.kid };
+}
+
+export function ticketFromRequest(request) {
+  try {
+    const tickets = new URL(request.url).searchParams.getAll('ticket');
+    const auth = request.headers.get('authorization');
+    if (tickets.length > 1 || (tickets.length && auth !== null)) fail();
+    if (tickets.length) { if (!tickets[0]) fail(); return tickets[0]; }
+    if (auth === null) return null;
+    // A combined duplicate Authorization field contains a comma and cannot match.
+    const match = /^Bearer ([^\s,]+)$/i.exec(auth);
+    if (!match) fail();
+    return match[1];
+  } catch { fail(); }
+}
+
+export function createDeliveryGate(input) {
+  input = { ...input };
+  const config = options(input);
+  const verify = (ticket) => verifyDeliveryTicket({ ...input, ticket });
+  return {
+    async ready() {
+      await probeCrypto();
+      if (config.keys !== undefined) await validateKeys(config.keys);
+      else {
+        const cache = cacheFor(config);
+        if (!fresh(cache.current, config)) await refresh(cache, config);
+      }
+    },
+    verify,
+    async verifyRequest(request) { return verify(ticketFromRequest(request)); },
+  };
+}