enigma-memory 0.1.17 → 0.1.22

package/packages/private-economy/src/credits.js

@@ -0,0 +1,447 @@
+import { createHash, randomBytes, randomUUID, scrypt as scryptCallback, timingSafeEqual } from 'node:crypto';
+import { mkdir, open, readFile, rename } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+export const ENIGMA_CREDITS_STORE_SCHEMA = 'enigma.private_credits_store.v1';
+export const ENIGMA_CREDITS_VAULT_SCHEMA = 'enigma.private_credits_vault.v1';
+export const MICROCREDITS_PER_CREDIT = 1_000_000;
+const ACCESS_PATTERN = /^enigma_cv_([A-Za-z0-9_-]{12})_([A-Za-z0-9_-]{43})$/;
+const RECOVERY_PATTERN = /^enigma_cr_([A-Za-z0-9_-]{16})_([A-Za-z0-9_-]{43})$/;
+const scrypt = promisify(scryptCallback);
+
+function requiredString(value, name, maximum = 512) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${name} is required`);
+  const normalized = value.trim();
+  if (normalized.length > maximum) throw new TypeError(`${name} exceeds ${maximum} characters`);
+  return normalized;
+}
+
+function boundedInteger(value, name, minimum, maximum, fallback) {
+  const resolved = value === undefined ? fallback : value;
+  if (!Number.isSafeInteger(resolved) || resolved < minimum || resolved > maximum) throw new TypeError(`${name} must be from ${minimum} through ${maximum}`);
+  return resolved;
+}
+
+function iso(clock) {
+  return new Date(clock()).toISOString();
+}
+function checkedAdd(left, right, name) {
+  if (!Number.isSafeInteger(left) || !Number.isSafeInteger(right)) throw new Error(`${name} contains a non-safe integer`);
+  const result = left + right;
+  if (!Number.isSafeInteger(result)) {
+    const error = new Error(`${name} exceeds the safe integer range`);
+    error.code = 'credits_overflow';
+    throw error;
+  }
+  return result;
+}
+
+function checkedSum(values, name) {
+  return values.reduce((sum, value) => checkedAdd(sum, value, name), 0);
+}
+
+
+function emptyState() {
+  return { schema: ENIGMA_CREDITS_STORE_SCHEMA, revision: 0, vaults: {}, recoveryIndex: {}, accessIndex: {} };
+}
+
+function publicVault(vault, now = Date.now()) {
+  const activeReservations = Object.values(vault.reservations).filter((reservation) => reservation.status === 'reserved' && Date.parse(reservation.expiresAt) > now);
+  const reservedMicrocredits = checkedSum(activeReservations.map((reservation) => reservation.amountMicrocredits), 'reserved microcredits');
+  return {
+    schema: ENIGMA_CREDITS_VAULT_SCHEMA,
+    id: vault.id,
+    balanceMicrocredits: vault.balanceMicrocredits,
+    reservedMicrocredits,
+    availableMicrocredits: checkedAdd(vault.balanceMicrocredits, -reservedMicrocredits, 'available microcredits'),
+    creditScale: MICROCREDITS_PER_CREDIT,
+    createdAt: vault.createdAt,
+    recoveredAt: vault.recoveredAt,
+    recoveryVersion: vault.recoveryVersion,
+    ledgerSequence: vault.ledgerSequence,
+    accountIdentityStored: false,
+    privacyBoundary: 'Accountless and pseudonymous. Network operators may still observe IP address, timing, and vault access patterns.',
+    paymentFundingBoundary: 'Funding is linkable: on-chain rails can reveal a wallet and Stripe can identify a customer. The separate payment ledger maps that funding event to this pseudonymous vault.',
+  };
+}
+
+async function derive(secret, salt) {
+  return Buffer.from(await scrypt(secret, Buffer.from(salt, 'base64url'), 32, { N: 16384, r: 8, p: 1, maxmem: 64 * 1024 * 1024 }));
+}
+
+function verifier() {
+  const locator = randomBytes(12).toString('base64url');
+  const secret = randomBytes(32).toString('base64url');
+  const salt = randomBytes(16).toString('base64url');
+  return { locator, secret, salt };
+}
+
+function accessCredential() {
+  const locator = randomBytes(9).toString('base64url');
+  const secret = randomBytes(32).toString('base64url');
+  const salt = randomBytes(16).toString('base64url');
+  return { locator, secret, salt };
+}
+
+function parseCredential(value, pattern) {
+  const match = pattern.exec(String(value || ''));
+  return match ? { locator: match[1], secret: match[2] } : null;
+}
+
+function createStoreAdapter(load, save, { clock, maxLedgerEntries }) {
+function fingerprint(value) {
+  return createHash('sha256').update(JSON.stringify(value)).digest('base64url');
+}
+
+function idempotencyConflict() {
+  const error = new Error('idempotency key was already used with different parameters');
+  error.code = 'idempotency_conflict';
+  return error;
+}
+
+  let queue = Promise.resolve();
+  const transaction = (operation) => {
+    const run = queue.then(async () => {
+      const state = await load();
+      const result = await operation(state);
+      for (const vault of Object.values(state.vaults)) {
+        if (vault.ledger.length > maxLedgerEntries) vault.ledger.splice(0, vault.ledger.length - maxLedgerEntries);
+      }
+      state.revision = checkedAdd(state.revision, 1, 'credits store revision');
+      await save(state);
+      return result;
+    });
+    queue = run.catch(() => undefined);
+    return run;
+  };
+  const view = async (operation) => {
+    await queue;
+    return operation(await load());
+  };
+  return Object.freeze({
+    async insert(vault) {
+      return transaction((state) => {
+        if (state.vaults[vault.id] || state.recoveryIndex[vault.recovery.locator] || state.accessIndex[vault.initialAccess.locator]) throw new Error('credits credential collision');
+        const stored = { ...structuredClone(vault), accessTokens: { [vault.initialAccess.locator]: structuredClone(vault.initialAccess) } };
+        delete stored.initialAccess;
+        state.vaults[stored.id] = stored;
+        state.recoveryIndex[stored.recovery.locator] = stored.id;
+        state.accessIndex[vault.initialAccess.locator] = stored.id;
+        return structuredClone(stored);
+      });
+    },
+    async recoveryByLocator(locator) {
+      return view((state) => {
+        const id = state.recoveryIndex[locator];
+        return id && state.vaults[id] ? structuredClone(state.vaults[id]) : null;
+      });
+    },
+    async rotateRecovery({ vaultId, expectedVersion, previousLocator, recovery, access }) {
+      return transaction((state) => {
+        const vault = state.vaults[vaultId];
+        if (!vault || vault.recoveryVersion !== expectedVersion || vault.recovery.locator !== previousLocator) return null;
+        delete state.recoveryIndex[vault.recovery.locator];
+        for (const [locator] of Object.entries(vault.accessTokens)) delete state.accessIndex[locator];
+        vault.accessTokens = { [access.locator]: structuredClone(access) };
+        vault.recovery = structuredClone(recovery);
+        vault.recoveryVersion = checkedAdd(vault.recoveryVersion, 1, 'recovery version');
+        vault.recoveredAt = iso(clock);
+        state.recoveryIndex[recovery.locator] = vault.id;
+        state.accessIndex[access.locator] = vault.id;
+        vault.ledgerSequence = checkedAdd(vault.ledgerSequence, 1, 'ledger sequence');
+        vault.ledger.push({ sequence: vault.ledgerSequence, action: 'recovered', at: vault.recoveredAt, amountMicrocredits: 0, reference: null });
+        return structuredClone(vault);
+      });
+    },
+    async accessByLocator(locator) {
+      return view((state) => {
+        const vaultId = state.accessIndex[locator];
+        const vault = vaultId ? state.vaults[vaultId] : null;
+        const access = vault?.accessTokens?.[locator];
+        return vault && access ? { vault: structuredClone(vault), access: structuredClone(access) } : null;
+      });
+    },
+    async touchAccess(vaultId, locator, at) {
+      return transaction((state) => {
+        const vault = state.vaults[vaultId];
+        const access = vault?.accessTokens?.[locator];
+        if (!access || access.revokedAt || Date.parse(access.expiresAt) <= clock()) return null;
+        access.lastUsedAt = at;
+        return structuredClone(vault);
+      });
+    },
+    async revokeAccess(vaultId, locator) {
+      return transaction((state) => {
+        const vault = state.vaults[vaultId];
+        const access = vault?.accessTokens?.[locator];
+        if (!access) return false;
+        access.revokedAt ||= iso(clock);
+        return true;
+      });
+    },
+    async getVault(vaultId) {
+      return view((state) => state.vaults[vaultId] ? structuredClone(state.vaults[vaultId]) : null);
+    },
+    async credit(vaultId, operation) {
+      return transaction((state) => {
+        const vault = state.vaults[vaultId];
+        if (!vault) return null;
+        const idempotencyKey = `credit:${operation.idempotencyKey}`;
+        const requestFingerprint = fingerprint({
+          amountMicrocredits: operation.amountMicrocredits,
+          reference: operation.reference,
+        });
+        const existing = vault.idempotency[idempotencyKey];
+        if (existing) {
+          if (existing.fingerprint !== requestFingerprint) throw idempotencyConflict();
+          return { vault: structuredClone(vault), ledger: structuredClone(existing.result), inserted: false };
+        }
+        vault.balanceMicrocredits = checkedAdd(vault.balanceMicrocredits, operation.amountMicrocredits, 'credits balance');
+        vault.ledgerSequence = checkedAdd(vault.ledgerSequence, 1, 'ledger sequence');
+        const ledger = {
+          sequence: vault.ledgerSequence,
+          action: 'credited',
+          at: iso(clock),
+          amountMicrocredits: operation.amountMicrocredits,
+          reference: operation.reference,
+          idempotencyKey: operation.idempotencyKey,
+        };
+        vault.ledger.push(ledger);
+        vault.idempotency[idempotencyKey] = { operation: 'credit', fingerprint: requestFingerprint, result: ledger };
+        return { vault: structuredClone(vault), ledger: structuredClone(ledger), inserted: true };
+      });
+    },
+    async reserve(vaultId, operation) {
+      return transaction((state) => {
+        const vault = state.vaults[vaultId];
+        if (!vault) return null;
+        const idempotencyKey = `reserve:${operation.idempotencyKey}`;
+        const requestFingerprint = fingerprint({
+          amountMicrocredits: operation.amountMicrocredits,
+          purpose: operation.purpose,
+        });
+        const existing = vault.idempotency[idempotencyKey];
+        if (existing) {
+          if (existing.fingerprint !== requestFingerprint) throw idempotencyConflict();
+          return { vault: structuredClone(vault), reservation: structuredClone(existing.result), inserted: false };
+        }
+        const now = clock();
+        const reserved = checkedSum(Object.values(vault.reservations)
+          .filter((reservation) => reservation.status === 'reserved' && Date.parse(reservation.expiresAt) > now)
+          .map((reservation) => reservation.amountMicrocredits), 'reserved microcredits');
+        if (checkedAdd(vault.balanceMicrocredits, -reserved, 'available microcredits') < operation.amountMicrocredits) return { insufficient: true, vault: structuredClone(vault) };
+        const reservation = {
+          id: randomUUID(),
+          amountMicrocredits: operation.amountMicrocredits,
+          purpose: operation.purpose,
+          status: 'reserved',
+          createdAt: iso(clock),
+          expiresAt: new Date(now + operation.ttlMs).toISOString(),
+          capturedAt: null,
+          releasedAt: null,
+        };
+        vault.reservations[reservation.id] = reservation;
+        vault.idempotency[idempotencyKey] = { operation: 'reserve', fingerprint: requestFingerprint, result: reservation };
+        return { vault: structuredClone(vault), reservation: structuredClone(reservation), inserted: true };
+      });
+    },
+    async settleReservation(vaultId, reservationId, action) {
+      return transaction((state) => {
+        const vault = state.vaults[vaultId];
+        const reservation = vault?.reservations?.[reservationId];
+        if (!vault || !reservation) return null;
+        if (reservation.status !== 'reserved') return { vault: structuredClone(vault), reservation: structuredClone(reservation), changed: false };
+        const at = iso(clock);
+        if (action === 'captured') {
+          if (Date.parse(reservation.expiresAt) <= clock()) throw new Error('credit reservation expired');
+          if (vault.balanceMicrocredits < reservation.amountMicrocredits) throw new Error('credits balance changed below reservation');
+          vault.balanceMicrocredits = checkedAdd(vault.balanceMicrocredits, -reservation.amountMicrocredits, 'credits balance');
+          reservation.capturedAt = at;
+        } else {
+          reservation.releasedAt = at;
+        }
+        reservation.status = action;
+        vault.ledgerSequence = checkedAdd(vault.ledgerSequence, 1, 'ledger sequence');
+        vault.ledger.push({ sequence: vault.ledgerSequence, action, at, amountMicrocredits: -reservation.amountMicrocredits, reference: reservation.id });
+        return { vault: structuredClone(vault), reservation: structuredClone(reservation), changed: true };
+      });
+    },
+  });
+}
+
+export function createEphemeralCreditsStore(options = {}) {
+  const clock = options.clock || Date.now;
+  const maxLedgerEntries = boundedInteger(options.maxLedgerEntries, 'maxLedgerEntries', 100, 1_000_000, 100_000);
+  let state = emptyState();
+  return createStoreAdapter(async () => structuredClone(state), async (next) => { state = structuredClone(next); }, { clock, maxLedgerEntries });
+}
+
+export function createFileCreditsStore(options = {}) {
+  const path = resolve(String(options.path || '.enigma/credits.json'));
+  const clock = options.clock || Date.now;
+  const maxLedgerEntries = boundedInteger(options.maxLedgerEntries, 'maxLedgerEntries', 100, 1_000_000, 100_000);
+  async function load() {
+    try {
+      const state = JSON.parse(await readFile(path, 'utf8'));
+      if (state?.schema !== ENIGMA_CREDITS_STORE_SCHEMA) throw new Error('unsupported private credits store schema');
+      return state;
+    } catch (error) {
+      if (error.code === 'ENOENT') return emptyState();
+      throw error;
+    }
+  }
+  async function save(state) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+      await handle.writeFile(JSON.stringify(state));
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temporary, path);
+  }
+  return createStoreAdapter(load, save, { clock, maxLedgerEntries });
+}
+
+export function createPrivateCreditsService(options = {}) {
+  const store = options.store;
+  if (!store || typeof store.insert !== 'function' || typeof store.recoveryByLocator !== 'function') throw new TypeError('private credits store is required');
+  const clock = options.clock || Date.now;
+  const accessTtlMs = boundedInteger(options.accessTtlSeconds, 'accessTtlSeconds', 300, 24 * 60 * 60, 15 * 60) * 1_000;
+  const reservationTtlMs = boundedInteger(options.reservationTtlSeconds, 'reservationTtlSeconds', 30, 60 * 60, 5 * 60) * 1_000;
+
+  async function materializeRecovery(candidate) {
+    return {
+      locator: candidate.locator,
+      salt: candidate.salt,
+      digest: (await derive(candidate.secret, candidate.salt)).toString('base64url'),
+    };
+  }
+
+  async function materializeAccess(candidate) {
+    return {
+      locator: candidate.locator,
+      salt: candidate.salt,
+      digest: (await derive(candidate.secret, candidate.salt)).toString('base64url'),
+      createdAt: iso(clock),
+      expiresAt: new Date(clock() + accessTtlMs).toISOString(),
+      lastUsedAt: null,
+      revokedAt: null,
+    };
+  }
+
+  function secretResponse(vault, recovery, access) {
+    return {
+      vault: publicVault(vault, clock()),
+      recoveryCode: `enigma_cr_${recovery.locator}_${recovery.secret}`,
+      accessToken: `enigma_cv_${access.locator}_${access.secret}`,
+      accessExpiresAt: new Date(clock() + accessTtlMs).toISOString(),
+      secretsShownOnce: true,
+    };
+  }
+
+  async function authenticate(accessToken) {
+    const parsed = parseCredential(accessToken, ACCESS_PATTERN);
+    if (!parsed) return null;
+    const found = await store.accessByLocator(parsed.locator);
+    if (!found || found.access.revokedAt || Date.parse(found.access.expiresAt) <= clock()) return null;
+    const actual = await derive(parsed.secret, found.access.salt);
+    const expected = Buffer.from(found.access.digest, 'base64url');
+    if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) return null;
+    const vault = await store.touchAccess(found.vault.id, parsed.locator, iso(clock));
+    if (!vault) return null;
+    return Object.freeze({ vaultId: vault.id, accessLocator: parsed.locator, authentication: 'private_credits', vault: publicVault(vault, clock()) });
+  }
+
+  return Object.freeze({
+    async create() {
+      const recovery = verifier();
+      const access = accessCredential();
+      const createdAt = iso(clock);
+      const vault = {
+        id: randomUUID(),
+        recovery: await materializeRecovery(recovery),
+        recoveryVersion: 1,
+        initialAccess: await materializeAccess(access),
+        balanceMicrocredits: 0,
+        createdAt,
+        recoveredAt: null,
+        ledgerSequence: 0,
+        ledger: [],
+        reservations: {},
+        idempotency: {},
+      };
+      const stored = await store.insert(vault);
+      return secretResponse(stored, recovery, access);
+    },
+    async recover(recoveryCode) {
+      const parsed = parseCredential(recoveryCode, RECOVERY_PATTERN);
+      if (!parsed) return null;
+      const found = await store.recoveryByLocator(parsed.locator);
+      if (!found) return null;
+      const actual = await derive(parsed.secret, found.recovery.salt);
+      const expected = Buffer.from(found.recovery.digest, 'base64url');
+      if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) return null;
+      const nextRecovery = verifier();
+      const access = accessCredential();
+      const rotated = await store.rotateRecovery({
+        vaultId: found.id,
+        expectedVersion: found.recoveryVersion,
+        previousLocator: parsed.locator,
+        recovery: await materializeRecovery(nextRecovery),
+        access: await materializeAccess(access),
+      });
+      if (!rotated) return null;
+      return secretResponse(rotated, nextRecovery, access);
+    },
+    authenticate,
+    async status(accessToken) {
+      const principal = await authenticate(accessToken);
+      return principal?.vault || null;
+    },
+    async logout(accessToken) {
+      const principal = await authenticate(accessToken);
+      return principal ? store.revokeAccess(principal.vaultId, principal.accessLocator) : false;
+    },
+    async credit(vaultId, input = {}) {
+      const result = await store.credit(requiredString(vaultId, 'vaultId'), {
+        amountMicrocredits: boundedInteger(input.amountMicrocredits, 'amountMicrocredits', 1, Number.MAX_SAFE_INTEGER),
+        idempotencyKey: requiredString(input.idempotencyKey, 'idempotencyKey'),
+        reference: input.reference ? requiredString(input.reference, 'reference', 1024) : null,
+      });
+      if (!result) throw new Error('credits vault not found');
+      return { vault: publicVault(result.vault, clock()), ledger: result.ledger, inserted: result.inserted };
+    },
+    async reserve(accessToken, input = {}) {
+      const principal = await authenticate(accessToken);
+      if (!principal) return null;
+      const result = await store.reserve(principal.vaultId, {
+        amountMicrocredits: boundedInteger(input.amountMicrocredits, 'amountMicrocredits', 1, Number.MAX_SAFE_INTEGER),
+        idempotencyKey: requiredString(input.idempotencyKey, 'idempotencyKey'),
+        purpose: requiredString(input.purpose || 'inference', 'purpose', 200),
+        ttlMs: reservationTtlMs,
+      });
+      if (result?.insufficient) {
+        const error = new Error('insufficient private credits');
+        error.code = 'insufficient_credits';
+        throw error;
+      }
+      return result ? { vault: publicVault(result.vault, clock()), reservation: result.reservation, inserted: result.inserted } : null;
+    },
+    async capture(accessToken, reservationId) {
+      const principal = await authenticate(accessToken);
+      if (!principal) return null;
+      const result = await store.settleReservation(principal.vaultId, requiredString(reservationId, 'reservationId'), 'captured');
+      return result ? { vault: publicVault(result.vault, clock()), reservation: result.reservation, changed: result.changed } : null;
+    },
+    async release(accessToken, reservationId) {
+      const principal = await authenticate(accessToken);
+      if (!principal) return null;
+      const result = await store.settleReservation(principal.vaultId, requiredString(reservationId, 'reservationId'), 'released');
+      return result ? { vault: publicVault(result.vault, clock()), reservation: result.reservation, changed: result.changed } : null;
+    },
+  });
+}

package/packages/private-economy/src/index.js

@@ -0,0 +1,5 @@
+export * from './credits.js';
+export * from './credits-http.js';
+export * from './payments.js';
+export * from './payments-http.js';
+export * from './x402.js';

package/packages/private-economy/src/payments-http.js

@@ -0,0 +1,120 @@
+const MAX_BODY_BYTES = 1024 * 1024;
+
+class PaymentHttpError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.name = 'PaymentHttpError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+function json(response, status, payload) {
+  const body = JSON.stringify(payload);
+  response.statusCode = status;
+  response.setHeader('Cache-Control', 'no-store');
+  response.setHeader('Content-Type', 'application/json; charset=utf-8');
+  response.setHeader('Content-Length', Buffer.byteLength(body));
+  response.setHeader('Referrer-Policy', 'no-referrer');
+  response.setHeader('X-Content-Type-Options', 'nosniff');
+  response.end(body);
+}
+
+async function rawBody(request) {
+  const chunks = [];
+  let size = 0;
+  let tooLarge = false;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > MAX_BODY_BYTES) tooLarge = true;
+    else chunks.push(chunk);
+  }
+  if (tooLarge) throw new PaymentHttpError(413, 'payload_too_large', 'payment request exceeds 1 MiB');
+  return Buffer.concat(chunks, size);
+}
+
+async function jsonBody(request) {
+  const contentType = String(request.headers['content-type'] || '').split(';', 1)[0].trim().toLowerCase();
+  if (contentType !== 'application/json') throw new PaymentHttpError(415, 'unsupported_media_type', 'Content-Type must be application/json');
+  try {
+    const value = JSON.parse((await rawBody(request)).toString('utf8') || '{}');
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error();
+    return value;
+  } catch (error) {
+    if (error instanceof PaymentHttpError) throw error;
+    throw new PaymentHttpError(400, 'invalid_json', 'payment request must be a JSON object');
+  }
+}
+
+function creditsBearer(request) {
+  const value = String(request.headers.authorization || '');
+  return value.startsWith('Bearer enigma_cv_') ? value.slice(7) : null;
+}
+
+function rejectUnknown(input, allowed) {
+  const unknown = Object.keys(input).find((key) => !allowed.has(key));
+  if (unknown) throw new PaymentHttpError(400, 'invalid_request', `unknown field: ${unknown}`);
+}
+
+export function createPaymentHttpHandler(options = {}) {
+  const payments = options.payments;
+  if (!payments || typeof payments.quote !== 'function' || typeof payments.settleOnchain !== 'function') throw new TypeError('credit payment service is required');
+  const stripe = options.stripe || null;
+  const basePath = String(options.basePath || '/v1/payments').replace(/\/+$/, '');
+
+  return async function paymentHttpHandler(request, response) {
+    const url = new URL(request.url || '/', 'http://localhost');
+    if (url.pathname !== basePath && !url.pathname.startsWith(`${basePath}/`)) return false;
+    try {
+      if (request.method === 'GET' && url.pathname === `${basePath}/packages`) {
+        json(response, 200, { schema: 'enigma.credit_packages.v1', packages: payments.listPackages() });
+        return true;
+      }
+      if (request.method === 'POST' && url.pathname === `${basePath}/stripe/webhook`) {
+        if (!stripe) throw new PaymentHttpError(503, 'stripe_unavailable', 'Stripe subscription rail is not configured');
+        const event = stripe.verifyWebhook(await rawBody(request), request.headers['stripe-signature']);
+        json(response, 200, await payments.processStripeWebhook(event));
+        return true;
+      }
+      const accessToken = creditsBearer(request);
+      if (!accessToken) throw new PaymentHttpError(401, 'credits_session_required', 'private credits access token is required');
+      if (request.method === 'POST' && url.pathname === `${basePath}/quote`) {
+        const input = await jsonBody(request);
+        rejectUnknown(input, new Set(['packageId', 'rail']));
+        json(response, 201, await payments.quote(accessToken, input));
+        return true;
+      }
+      if (request.method === 'POST' && url.pathname === `${basePath}/settle`) {
+        const input = await jsonBody(request);
+        rejectUnknown(input, new Set(['quoteId', 'signature']));
+        json(response, 200, await payments.settleOnchain(accessToken, input));
+        return true;
+      }
+      if (request.method === 'POST' && url.pathname === `${basePath}/subscription/checkout`) {
+        const successUrl = typeof options.successUrl === 'function' ? options.successUrl(request) : options.successUrl;
+        const cancelUrl = typeof options.cancelUrl === 'function' ? options.cancelUrl(request) : options.cancelUrl;
+        if (!successUrl || !cancelUrl) throw new PaymentHttpError(503, 'checkout_unavailable', 'subscription checkout return URLs are not configured');
+        const input = await jsonBody(request);
+        rejectUnknown(input, new Set(['quoteId']));
+        json(response, 201, await payments.createSubscriptionCheckout(accessToken, {
+          quoteId: input.quoteId,
+          successUrl,
+          cancelUrl,
+        }));
+        return true;
+      }
+      throw new PaymentHttpError(404, 'not_found', 'payment endpoint not found');
+    } catch (error) {
+      const known = error instanceof PaymentHttpError;
+      const message = error?.message || 'payment operation failed';
+      const status = known ? error.status
+        : /not found/i.test(message) ? 404
+          : /expired|already|different|invalid or expired/i.test(message) ? 409
+            : error instanceof TypeError ? 400 : 400;
+      const code = known ? error.code : status === 404 ? 'not_found' : status === 409 ? 'payment_conflict' : 'payment_failed';
+      if (status === 401) response.setHeader('WWW-Authenticate', 'Bearer');
+      json(response, status, { error: { code, message } });
+      return true;
+    }
+  };
+}