zklicensing 0.1.0-beta.2 → 0.1.0-beta.21

package/src/verifyService.ts

@@ -0,0 +1,982 @@
+#!/usr/bin/env node
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * verifyService.ts
+ *
+ * Lightweight, standalone license verification service.
+ *
+ * Exposes the same state endpoints as the backend but contains NO ZK prover —
+ * no circuit compilation, no o1js native backend. Starts in ~2 seconds and
+ * runs on any small VPS or container.
+ *
+ * Multi-network: one process can serve both devnet and mainnet. Every
+ * state endpoint receives a `zkAppAddress`, which routes unambiguously to
+ * one network via AppRecord.deployments (each generation has its own
+ * keypair — zkAppAddresses are globally unique across networks). The active
+ * o1js instance is switched per-request via withNetwork(), which also holds
+ * a process-global mutex so two concurrent handlers on different networks
+ * can't race the Mina.setActiveInstance swap.
+ *
+ * No write endpoints — chain events are the source of truth. License state
+ * is rebuilt from the archive node in three ways:
+ *   - auto-bootstrap on startup when licenses.json is empty (loops over
+ *     every configured network's apps),
+ *   - lazy bootstrap inside GET / when the computed Merkle root
+ *     disagrees with the on-chain root for the requested app,
+ *   - POST /bootstrap (admin) for ad-hoc reasons.
+ *
+ * Deployment modes
+ * ----------------
+ * 1. Same-machine as the backend
+ *    - Run from the backend's working directory so apps.json and licenses.json
+ *      are shared transparently. Optionally set LICENSE_STORE_PATH to point at
+ *      a shared file.
+ *
+ * 2. Separate machine (replica)
+ *    - Copy the backend's apps.json into the verifyService working directory.
+ *    - Set at least one of MINA_DEVNET_GRAPHQL_URL / MINA_MAINNET_GRAPHQL_URL.
+ *    - Optionally set MINA_{DEVNET,MAINNET}_{GRAPHQL,ARCHIVE}_FALLBACK for a
+ *      per-network fallback endpoint (used by the manual rotation on 5xx).
+ *    - Re-copying apps.json on a cron (or pulling it via GET /apps from the
+ *      backend) is the recommended way to keep the registry in sync.
+ *
+ * Usage:
+ *   node build/src/verifyService.js
+ *
+ * Configuration is read from environment variables (see README §Configuration).
+ * Required: at least one of MINA_DEVNET_GRAPHQL_URL or MINA_MAINNET_GRAPHQL_URL
+ *           (each also picks up MINA_{DEVNET,MAINNET}_ARCHIVE_URL, defaulting
+ *           to Minascan public archive per-network).
+ * Optional: VERIFY_PORT (default 8081), VERIFY_ADMIN_TOKEN,
+ *           MINA_{DEVNET,MAINNET}_{GRAPHQL,ARCHIVE}_FALLBACK (single fallback
+ *             URL per network — manual rotation retries it on 5xx).
+ *
+ * NOTE: the pre-multi-network single-network trio (MINA_NETWORK_ID +
+ * MINA_GRAPHQL_URL + MINA_ARCHIVE_URL) is no longer accepted. Operators must
+ * migrate systemd units to the per-network variable names.
+ *
+ * Endpoints:
+ *   GET  /health
+ *   GET  /?licenseHash=...&zkAppAddress=...        ← primary endpoint for apps
+ *   GET  /root?zkApp=...
+ *   GET  /witness/:zkAppAddress/:licenseHash
+ *   GET  /license/:zkAppAddress/:licenseHash
+ *   GET  /apps
+ *   POST /bootstrap                                 ← replay events from archive
+ */
+
+import fs from 'fs/promises';
+import express, { Request, Response } from 'express';
+import {
+  Field,
+  Mina,
+  NetworkId as O1NetworkId,
+  fetchLastBlock,
+  fetchAccount,
+  PublicKey,
+  setBackend,
+  setGraphqlEndpoint,
+  setArchiveGraphqlEndpoint,
+} from 'o1js';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { dirname, resolve as pathResolve } from 'path';
+import {
+  buildMap,
+  getLicense,
+  licenseStatus,
+  readRecords,
+  serializeWitness,
+  type LicenseRecord,
+} from './licenseStore.js';
+import { type VerifyResponse } from './verifyCore.js';
+import { verifyLicenseWithAncestors } from './verifyWithAncestors.js';
+import { bootstrapFromArchive, applyEventsToStore } from './archiveBootstrap.js';
+import {
+  CANONICAL_VK_HASHES,
+  LICENSING_APP_STATE,
+  SUPPORTED_LICENSING_APP_VERSIONS,
+  fetchLicensingAppVersion,
+} from './contractInterface.js';
+import { readJsonOr } from './atomicJson.js';
+
+setBackend('native');
+
+// ------------------------------------------------------------
+// CONFIG (env vars) & NETWORK
+// ------------------------------------------------------------
+
+// Local NetworkId — the two Mina chains we support. Distinct from o1js's
+// NetworkId (which is `'mainnet' | 'testnet' | { custom: string }`); we alias
+// o1js's as O1NetworkId above and use it only where a Mina.Network()
+// constructor demands it.
+type NetworkId = 'devnet' | 'mainnet';
+const NETWORKS: readonly NetworkId[] = ['devnet', 'mainnet'] as const;
+
+const MINA_DEVNET_GRAPHQL_URL       = process.env.MINA_DEVNET_GRAPHQL_URL;
+const MINA_DEVNET_ARCHIVE_URL       = process.env.MINA_DEVNET_ARCHIVE_URL;
+const MINA_DEVNET_GRAPHQL_FALLBACK  = process.env.MINA_DEVNET_GRAPHQL_FALLBACK;
+const MINA_DEVNET_ARCHIVE_FALLBACK  = process.env.MINA_DEVNET_ARCHIVE_FALLBACK;
+const MINA_MAINNET_GRAPHQL_URL      = process.env.MINA_MAINNET_GRAPHQL_URL;
+const MINA_MAINNET_ARCHIVE_URL      = process.env.MINA_MAINNET_ARCHIVE_URL;
+const MINA_MAINNET_GRAPHQL_FALLBACK = process.env.MINA_MAINNET_GRAPHQL_FALLBACK;
+const MINA_MAINNET_ARCHIVE_FALLBACK = process.env.MINA_MAINNET_ARCHIVE_FALLBACK;
+const PORT                          = parseInt(process.env.VERIFY_PORT ?? '8081', 10);
+
+// Default archive endpoint per network. Devnet uses o1Labs' Mesa archive
+// (devnet-archive-node-api.gcp.o1test.net); mainnet falls back to Minascan's
+// public archive. When the operator sets an explicit MINA_*_ARCHIVE_URL env
+// var, that value wins.
+const DEFAULT_ARCHIVE_URL: Record<NetworkId, string> = {
+  devnet:  'https://devnet-archive-node-api.gcp.o1test.net',
+  mainnet: 'https://api.minascan.io/archive/mainnet/v1/graphql',
+};
+
+type NetworkConfig = {
+  networkId:       NetworkId;
+  graphqlUrl:      string;
+  archiveUrl:      string;
+  graphqlFallback: string | null;
+  archiveFallback: string | null;
+  network:         ReturnType<typeof Mina.Network>;
+  // Same URLs but with fallback listed first — used by manual rotation on 5xx
+  // (see fetchAccountWithRotation). o1js's built-in fallback races both
+  // endpoints and returns whichever resolves first, so a fast 502 from primary
+  // beats a slower 200 from fallback. Manual rotation forces the second
+  // attempt onto fallback-first so we actually hit the healthy endpoint.
+  // Null when no fallback is configured.
+  fallbackNetwork: ReturnType<typeof Mina.Network> | null;
+};
+
+// Build per-network Mina.Network instances. Any network the operator didn't
+// configure (no RPC URL) stays out of the map — requests targeting it fall
+// through to `unregistered-address`. At least one must be configured.
+const NETWORK_CONFIG: Partial<Record<NetworkId, NetworkConfig>> = {};
+function buildNetworkConfig(
+  networkId: NetworkId,
+  graphqlUrl: string | undefined,
+  archiveEnv: string | undefined,
+  graphqlFallbackEnv: string | undefined,
+  archiveFallbackEnv: string | undefined,
+): void {
+  if (!graphqlUrl) return;
+  const archiveUrl = archiveEnv ?? DEFAULT_ARCHIVE_URL[networkId];
+  const trim = (s: string | undefined) => (s ? s.trim() : '');
+  const graphqlFallback = trim(graphqlFallbackEnv) && trim(graphqlFallbackEnv) !== graphqlUrl
+    ? trim(graphqlFallbackEnv) : null;
+  const archiveFallback = trim(archiveFallbackEnv) && trim(archiveFallbackEnv) !== archiveUrl
+    ? trim(archiveFallbackEnv) : null;
+  // See keeperService.ts for the full rationale: o1js's array-based fallback
+  // form (`mina: [primary, fallback]`) is unusable — Promise.race lets a fast
+  // 5xx from primary beat a slow 200 from fallback, and the winning-URL
+  // cache-key bug causes subsequent `.get()` calls to miss. Manual rotation
+  // via a second single-URL Mina.Network instance is the sole failover path.
+  const fallbackMinaArg    = graphqlFallback ? graphqlFallback : null;
+  const fallbackArchiveArg = graphqlFallback ? (archiveFallback ?? archiveUrl) : null;
+  NETWORK_CONFIG[networkId] = {
+    networkId,
+    graphqlUrl,
+    archiveUrl,
+    graphqlFallback,
+    archiveFallback,
+    network: Mina.Network({ networkId: networkId as O1NetworkId, mina: graphqlUrl, archive: archiveUrl }),
+    fallbackNetwork: fallbackMinaArg
+      ? Mina.Network({ networkId: networkId as O1NetworkId, mina: fallbackMinaArg, archive: fallbackArchiveArg! })
+      : null,
+  };
+  console.log(`🔗 ${networkId.padEnd(7)} Mina node:    ${graphqlUrl}`);
+  if (graphqlFallback) console.log(`   ${networkId.padEnd(7)}   fallback:   ${graphqlFallback}`);
+  console.log(`📚 ${networkId.padEnd(7)} Archive node: ${archiveUrl}${archiveEnv ? ' (from env)' : ' (default)'}`);
+  if (archiveFallback) console.log(`   ${networkId.padEnd(7)}   fallback:   ${archiveFallback}`);
+}
+buildNetworkConfig('devnet',  MINA_DEVNET_GRAPHQL_URL,  MINA_DEVNET_ARCHIVE_URL,  MINA_DEVNET_GRAPHQL_FALLBACK,  MINA_DEVNET_ARCHIVE_FALLBACK);
+buildNetworkConfig('mainnet', MINA_MAINNET_GRAPHQL_URL, MINA_MAINNET_ARCHIVE_URL, MINA_MAINNET_GRAPHQL_FALLBACK, MINA_MAINNET_ARCHIVE_FALLBACK);
+if (Object.keys(NETWORK_CONFIG).length === 0) {
+  console.error('❌ No Mina network configured. Set at least one of MINA_DEVNET_GRAPHQL_URL / MINA_MAINNET_GRAPHQL_URL.');
+  process.exit(1);
+}
+
+// Leaked-transaction-context reset scaffolding. The verifier has no
+// Mina.transaction() calls today, so the leak defense is theoretical — but
+// it's cheap (one dynamic import at boot) and future-proofs against a code
+// path we haven't accounted for taking the process out until systemd
+// restarts it. Same shape as keeperService.ts.
+const _o1jsRequire = createRequire(import.meta.url);
+let _o1jsCurrentTransaction: {
+  has(): boolean;
+  id(): number;
+  leave(id: number): unknown;
+} | null = null;
+try {
+  const o1jsMainPath = _o1jsRequire.resolve('o1js');
+  const contextUrl = pathToFileURL(
+    pathResolve(dirname(o1jsMainPath), 'lib/mina/v1/transaction-context.js')
+  ).href;
+  const mod = await import(contextUrl) as { currentTransaction?: NonNullable<typeof _o1jsCurrentTransaction> };
+  _o1jsCurrentTransaction = mod.currentTransaction ?? null;
+} catch (e: any) {
+  console.warn('[withNetwork] o1js leak defense disabled — could not reach internal transaction-context:', e?.message ?? e);
+}
+
+function resetLeakedTransactionContext(): void {
+  if (!_o1jsCurrentTransaction) return;
+  while (_o1jsCurrentTransaction.has()) {
+    try { _o1jsCurrentTransaction.leave(_o1jsCurrentTransaction.id()); }
+    catch { break; }
+  }
+}
+
+let _networkMutexTail: Promise<void> = Promise.resolve();
+
+// Which endpoint (primary vs fallback) currently succeeds for each network.
+// Updated by the rotation helpers whenever a call succeeds on a specific
+// endpoint. `withNetwork` restores from this map at region entry so that a
+// successful fallback rotation in one region persists into the next region
+// — otherwise a resetToPrimary here would stomp the fallback state and the
+// following .get() cache lookup would miss on primary (the o1js account
+// cache is keyed by graphql endpoint URL).
+//
+// Sticky-until-proven-broken semantics: we don't automatically retry primary
+// on every region entry. If primary comes back up, the next rotation call
+// will hit it first (attempt 1) and flip us back.
+const _activeEndpointByNetwork: Map<NetworkId, 'primary' | 'fallback'> = new Map();
+
+// Swap the active Mina instance AND the o1js module-global fetch endpoint
+// atomically. These are two independent globals inside o1js:
+//   - `activeInstance` (mina-instance.js) — what zkApp.<state>.get() closes
+//     over for its cache lookups
+//   - `networkConfig.minaEndpoint` (fetch.js) — the DEFAULT endpoint for
+//     bare `fetchAccount({publicKey})` / `fetchLastBlock()` calls
+// `Mina.setActiveInstance` only touches the first. Because we build TWO
+// Mina.Network() instances at startup (primary + fallback) and the second
+// call's Fetch.setGraphqlEndpoint side-effect leaves `networkConfig.minaEndpoint`
+// pinned to the LAST-constructed URL (the fallback), a plain
+// setActiveInstance(cfg.network) leaves fetchAccount hitting the fallback URL
+// while zkApp.<state>.get() looks up under the primary URL — cache miss →
+// "Could not find account". We must always keep the two endpoints in sync,
+// which this helper does.
+function activateNetworkEndpoints(cfg: NetworkConfig, useFallback: boolean): void {
+  if (useFallback && cfg.fallbackNetwork) {
+    Mina.setActiveInstance(cfg.fallbackNetwork);
+    setGraphqlEndpoint(cfg.graphqlFallback ?? cfg.graphqlUrl);
+    setArchiveGraphqlEndpoint(cfg.archiveFallback ?? cfg.archiveUrl);
+    _activeEndpointByNetwork.set(cfg.networkId, 'fallback');
+  } else {
+    Mina.setActiveInstance(cfg.network);
+    setGraphqlEndpoint(cfg.graphqlUrl);
+    setArchiveGraphqlEndpoint(cfg.archiveUrl);
+    _activeEndpointByNetwork.set(cfg.networkId, 'primary');
+  }
+}
+
+// Active-instance juggling: o1js/Mina keeps a single global active network
+// instance, so multi-network handlers must switch it before making any
+// on-chain call. Wrap the region that needs a specific network in
+// withNetwork(network, () => …). Handlers that don't touch chain state
+// (local record reads, witness computation) don't need this.
+async function withNetwork<T>(networkId: NetworkId, fn: () => Promise<T>): Promise<T> {
+  const cfg = NETWORK_CONFIG[networkId];
+  if (!cfg) throw new Error(`Network ${networkId} is not configured on this verifier`);
+  let release: () => void = () => {};
+  const prev = _networkMutexTail;
+  _networkMutexTail = new Promise<void>((r) => { release = r; });
+  await prev;
+  try {
+    const stickyFallback = _activeEndpointByNetwork.get(networkId) === 'fallback';
+    activateNetworkEndpoints(cfg, stickyFallback);
+    return await fn();
+  } catch (err) {
+    resetLeakedTransactionContext();
+    throw err;
+  } finally {
+    release();
+  }
+}
+
+// Per-attempt timeout for fetchLastBlock. Sized for the SLOW path: the
+// Minascan public node (often used as fallback) frequently rate-limits and
+// can take 60–120s to return during load spikes. Cutting the timeout shorter
+// would surface as a spurious "fetchLastBlock failed" after primary is down
+// — the exact situation this fallback exists to cover. Primary endpoints
+// (minataur, self-hosted) that return quickly aren't penalized because a
+// fast success short-circuits the timer.
+const CURRENT_SLOT_TIMEOUT_MS = 180_000;
+
+// 5xx and 408 (o1js's own timeout stand-in) rotate to the fallback. 404 means
+// "account genuinely doesn't exist" and short-circuits — no point rotating.
+// Anything else (4xx GraphQL error, 400 malformed request) also short-circuits
+// because it's not endpoint-health related.
+function shouldRotateOnError(statusCode: number | undefined): boolean {
+  if (statusCode === undefined) return true; // network throw with no status — treat as transport
+  if (statusCode === 408) return true;
+  if (statusCode >= 500 && statusCode <= 599) return true;
+  return false;
+}
+
+// Manual endpoint rotation for fetchAccount. Must be called from inside a
+// withNetwork() region so the mutex prevents concurrent handlers from
+// observing a mid-flight setActiveInstance swap. On success leaves the
+// winning instance active so the next zkApp.<state>.get() cache lookup finds
+// the freshly-fetched account under the same graphql-endpoint cache key.
+async function fetchAccountWithRotation(
+  networkId: NetworkId,
+  publicKey: PublicKey,
+  attempts: number,
+  backoffMs: (attempt: number) => number = (a) => 400 * a,
+): Promise<Awaited<ReturnType<typeof fetchAccount>>> {
+  const cfg = NETWORK_CONFIG[networkId];
+  if (!cfg) throw new Error(`Network ${networkId} is not configured on this verifier`);
+  let last: Awaited<ReturnType<typeof fetchAccount>> = { account: undefined, error: { statusCode: 500, statusText: 'no attempt made' } as any };
+  let succeededOn: 'primary' | 'fallback' | null = null;
+  const trace: Array<{ url: string; outcome: string }> = [];
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    // Alternate primary / fallback across attempts when fallback exists:
+    // attempt 1 → primary, 2 → fallback, 3 → primary, …
+    const useFallback = cfg.fallbackNetwork !== null && attempt % 2 === 0;
+    const url = useFallback ? (cfg.graphqlFallback ?? cfg.graphqlUrl) : cfg.graphqlUrl;
+    activateNetworkEndpoints(cfg, useFallback);
+    last = await fetchAccount({ publicKey });
+    if (last.account) {
+      succeededOn = useFallback ? 'fallback' : 'primary';
+      trace.push({ url, outcome: 'ok' });
+      break;
+    }
+    const status = last.error?.statusCode;
+    const outcome = status === 404 ? '404' : `HTTP ${status ?? '?'} ${last.error?.statusText ?? ''}`.trim();
+    trace.push({ url, outcome });
+    if (status === 404) break;                       // real not-found
+    if (!shouldRotateOnError(status)) break;         // non-transport error
+    if (attempt < attempts) await new Promise((r) => setTimeout(r, backoffMs(attempt)));
+  }
+  if (!last.account && last.error?.statusCode !== 404) {
+    logUtc('fetchAccountWithRotation', '✗ all attempts failed', {
+      network: networkId,
+      publicKey: publicKey.toBase58(),
+      attempts,
+      trace,
+    });
+  }
+  if (succeededOn === null) {
+    activateNetworkEndpoints(cfg, false);
+  }
+  return last;
+}
+
+// Same rotation semantics as fetchAccountWithRotation but for fetchLastBlock.
+// Wraps the o1js call in the CURRENT_SLOT_TIMEOUT_MS timeout race so a dead
+// endpoint doesn't hang the whole attempt. Must be called from inside a
+// withNetwork() region. Returns null on terminal failure so callers can decide
+// (throw, retry higher up, or degrade gracefully — currentSlot returns 0).
+async function fetchLastBlockWithRotation(
+  networkId: NetworkId,
+  attempts: number,
+  backoffMs: (attempt: number) => number = (a) => 400 * a,
+): Promise<Awaited<ReturnType<typeof fetchLastBlock>> | null> {
+  const cfg = NETWORK_CONFIG[networkId];
+  if (!cfg) throw new Error(`Network ${networkId} is not configured on this verifier`);
+  let succeededOn: 'primary' | 'fallback' | null = null;
+  const trace: Array<{ url: string; outcome: string }> = [];
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const useFallback = cfg.fallbackNetwork !== null && attempt % 2 === 0;
+    const url = useFallback ? (cfg.graphqlFallback ?? cfg.graphqlUrl) : cfg.graphqlUrl;
+    activateNetworkEndpoints(cfg, useFallback);
+    try {
+      const block = await Promise.race([
+        fetchLastBlock(),
+        new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error(`fetchLastBlock timed out after ${CURRENT_SLOT_TIMEOUT_MS}ms`)),
+            CURRENT_SLOT_TIMEOUT_MS),
+        ),
+      ]);
+      succeededOn = useFallback ? 'fallback' : 'primary';
+      trace.push({ url, outcome: 'ok' });
+      return block;
+    } catch (err: any) {
+      trace.push({ url, outcome: err?.message ?? String(err) });
+      if (attempt < attempts) await new Promise((r) => setTimeout(r, backoffMs(attempt)));
+    }
+  }
+  if (succeededOn === null) {
+    activateNetworkEndpoints(cfg, false);
+  }
+  logUtc('fetchLastBlockWithRotation', '✗ all attempts failed', {
+    network: networkId,
+    attempts,
+    trace,
+  });
+  return null;
+}
+
+// UTC-stamped structured log. Arrays/objects in `extra` are JSON-stringified
+// so per-attempt traces don't render as [object Object].
+function logUtc(scope: string, msg: string, extra?: Record<string, unknown>): void {
+  const ts = new Date().toISOString();
+  const tail = extra
+    ? ' ' + Object.entries(extra).map(([k, v]) => {
+        const s = (v !== null && typeof v === 'object') ? JSON.stringify(v) : `${v}`;
+        return `${k}=${s}`;
+      }).join(' ')
+    : '';
+  console.log(`[${ts}] [${scope}] ${msg}${tail}`);
+}
+
+// Default the active instance to whichever network is configured (mainnet
+// wins if both are up, so idle background code without explicit context lands
+// on the production network). withNetwork() overrides this per-request.
+activateNetworkEndpoints((NETWORK_CONFIG.mainnet ?? NETWORK_CONFIG.devnet!), false);
+
+
+// ------------------------------------------------------------
+// HELPERS
+// ------------------------------------------------------------
+
+// Fetch the current slot on the specified network. Rotation-aware. Callers
+// that need the value in a broader on-chain region should pass the network
+// they already resolved from the zkAppAddress.
+async function currentSlot(network: NetworkId): Promise<number> {
+  try {
+    const block = await withNetwork(network, () => fetchLastBlockWithRotation(network, 3));
+    if (!block) return 0;
+    return Number(block.globalSlotSinceGenesis.toString());
+  } catch (e: any) {
+    logUtc('currentSlot', '✗ fetchLastBlock failed', { network, reason: e?.message ?? String(e) });
+    return 0;
+  }
+}
+
+// Return an error message if `zkAppAddress` isn't a well-formed B62q address,
+// null otherwise. Called at request-parse time so garbage input fails with a
+// legible 400 in a couple of ms instead of ~1 s of proof-verify CPU followed
+// by a generic 502 from `fromBase58` throwing deep inside checkOnChainLicense.
+function validateZkAppAddress(zkAppAddress: string): string | null {
+  try {
+    PublicKey.fromBase58(zkAppAddress);
+    return null;
+  } catch (err: any) {
+    return `Invalid zkAppAddress: ${err?.message || 'not a valid Mina B62q address'}`;
+  }
+}
+
+// Resolve a zkAppAddress to its owning AppRecord + network + deployment
+// slice. Walks both networks' current-live address and every entry in
+// deploymentHistory. Under the backend-routing design a buyer who pinned an
+// original gen-1 address stays valid forever even after N generation bumps.
+function resolveAppAndNetwork(
+  apps: AppRecord[],
+  zkAppAddress: string,
+): { app: AppRecord; network: NetworkId; deployment: DeploymentInfo } | null {
+  for (const app of apps) {
+    for (const net of NETWORKS) {
+      const dep = app.deployments[net];
+      if (!dep) continue;
+      if (dep.zkAppAddress === zkAppAddress ||
+          (dep.deploymentHistory ?? []).some(h => h.zkAppAddress === zkAppAddress)) {
+        return { app, network: net, deployment: dep };
+      }
+    }
+  }
+  return null;
+}
+
+// Tagged verdict from checkOnChainLicense. Kept as a discriminated union
+// (rather than a boolean + error string) so the caller — GET / — can
+// pick its own response envelope per failure kind without leaking HTTP
+// concerns into the helper.
+type OnChainLicenseCheck =
+  | { kind: 'zkapp-not-found' }
+  | { kind: 'unregistered-address' }
+  | { kind: 'vk-mismatch'; generation: number }
+  | {
+      kind: 'checked';
+      onChainRoot: string;
+      currentSlot: number;
+      zkAppVersion: number;
+      generation: number;
+      resolvedAddress: string;
+      liveRecords: LicenseRecord[];
+      result: VerifyResponse;
+    };
+
+// Fetch fresh on-chain state and delegate address routing + ancestor walk
+// to verifyLicenseWithAncestors. Resolves the target network from the
+// zkAppAddress; unknown addresses (not in any configured network's registry)
+// surface as `unregistered-address`. Throws only on network / RPC failure.
+//
+// The `generation` field echoes the *request* address's own stable
+// generation, so a client that pinned an older address at build time sees
+// a token whose `g` still matches its local expectation across bumps.
+async function checkOnChainLicense(
+  zkAppAddress: string,
+  licenseHash: string,
+): Promise<OnChainLicenseCheck> {
+  const apps = await readApps();
+  const resolved = resolveAppAndNetwork(apps, zkAppAddress);
+  if (!resolved) return { kind: 'unregistered-address' };
+  const { network, deployment } = resolved;
+  if (!NETWORK_CONFIG[network]) return { kind: 'unregistered-address' };
+
+  const historyLen = deployment.deploymentHistory?.length ?? 0;
+  const currentGeneration = historyLen + 1;
+  const currentLive = deployment.zkAppAddress;
+
+  // Echo: the request address's own stable generation. Stays consistent
+  // across bumps for any client that pinned an older address.
+  let requestGeneration = currentGeneration;
+  if (zkAppAddress !== currentLive) {
+    const idx = (deployment.deploymentHistory ?? []).findIndex((d) => d.zkAppAddress === zkAppAddress);
+    if (idx >= 0) requestGeneration = idx + 1;
+  }
+
+  // Sequential (was Promise.all): the rotation helpers do Mina.setActiveInstance
+  // internally, so running fetchAccount + fetchLastBlock in parallel would race
+  // the instance swap. Same pattern as the backend sweep.
+  const records = await readRecords();
+  const { account } = await withNetwork(network, () =>
+    fetchAccountWithRotation(network, PublicKey.fromBase58(currentLive), 3));
+  const lastBlock = await withNetwork(network, () =>
+    fetchLastBlockWithRotation(network, 3));
+  if (!lastBlock) {
+    throw new Error('fetchLastBlock failed');
+  }
+
+  const currentRoot = account?.zkapp?.appState?.[0]?.toString();
+  if (!currentRoot) return { kind: 'zkapp-not-found' };
+  // `version` is state slot 5 (licensesRoot, vendor ×2, escrowRoot,
+  // pricesPacked, version, …).
+  const zkAppVersion = Number(account?.zkapp?.appState?.[5]?.toString() ?? '0');
+  // The live contract must run one of the published circuits. Pinned by
+  // circuit, not by this app's redeploy count: a redeploy doesn't imply a
+  // new circuit (and an app deployed after a circuit bump starts at app
+  // generation 1 on the newer circuit). Fail closed when the VK is missing
+  // or unknown — previously a redeployed app had no table entry for its
+  // generation and the check was skipped entirely.
+  const onChainVk = account?.zkapp?.verificationKey?.hash?.toString();
+  if (!onChainVk || !Object.values(CANONICAL_VK_HASHES).includes(onChainVk)) {
+    return { kind: 'vk-mismatch', generation: currentGeneration };
+  }
+
+  const currentSlotNum = Number(lastBlock.globalSlotSinceGenesis.toString());
+  // verifyLicenseWithAncestors uses bare fetchAccount internally on retired
+  // addresses — wrap it in withNetwork so the active instance points at the
+  // correct network for the whole walk.
+  const walked = await withNetwork(network, () => verifyLicenseWithAncestors({
+    deployment,
+    licenseHash,
+    currentSlot: currentSlotNum,
+    currentLiveRoot: currentRoot,
+    currentLiveForkSlot: Number(account?.zkapp?.appState?.[LICENSING_APP_STATE.forkActivationSlot]?.toString() ?? '0'),
+    records,
+  }));
+  return {
+    kind: 'checked',
+    onChainRoot: walked.onChainRoot,
+    currentSlot: currentSlotNum,
+    zkAppVersion,
+    generation: requestGeneration,
+    resolvedAddress: walked.resolvedAddress,
+    liveRecords: walked.liveRecords,
+    result: walked.result,
+  };
+}
+
+// ------------------------------------------------------------
+// APPS REGISTRY
+// ------------------------------------------------------------
+
+type Deployment = {
+  zkAppAddress: string;
+  txHash?: string;
+  verificationKeyHash?: string;
+  version?: number;
+  retiredAt?: string;
+};
+
+// Per-network on-chain slot on an AppRecord. Mirrors the backend-side
+// DeploymentInfo but only carries the fields verifyService needs (address
+// + retirement history). Each network keeps its own history — a mainnet
+// bump doesn't touch the devnet slot and vice-versa.
+type DeploymentInfo = {
+  zkAppAddress:        string;
+  txHash?:             string;
+  verificationKeyHash?: string;
+  forkActivationSlot?: number;
+  deploymentHistory?:  Deployment[];
+};
+
+type AppRecord = {
+  appId: string;
+  name: string;
+  description: string;
+  category: string;
+  website: string;
+  vendorAddress: string;
+  // Four-tier prices (MINA). 0 means the tier is not offered.
+  priceMonthlyMina:   number;
+  priceYearlyMina:    number;
+  priceFiveYearMina:  number;
+  pricePerpetualMina: number;
+  createdAt: string;
+  // Per-network on-chain state — a single AppRecord can carry both devnet
+  // and mainnet deployment slots simultaneously. Requests route to the slot
+  // matching the request's zkAppAddress (see resolveAppAndNetwork).
+  deployments: {
+    devnet?:  DeploymentInfo;
+    mainnet?: DeploymentInfo;
+  };
+};
+
+const APPS_FILE = 'apps.json';
+
+async function readApps(): Promise<AppRecord[]> {
+  return readJsonOr<AppRecord[]>(APPS_FILE, []);
+}
+
+// ------------------------------------------------------------
+// EXPRESS SERVER
+// ------------------------------------------------------------
+
+const app = express();
+app.use(express.json());
+app.use((_req, res, next) => {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, OPTIONS');
+  if (_req.method === 'OPTIONS') { res.status(204).end(); return; }
+  next();
+});
+
+// Per-request access log. One line per request: method + path + status + ms.
+// Skips CORS preflights (already short-circuited above with 204). Path is the
+// raw req.path — query strings are dropped so the licenseHash from `GET /`
+// doesn't leak into logs (the redacted-prefix log on the / handler below is
+// the canonical place to see which license was queried).
+// Toggle off with VERIFY_ACCESS_LOG=off if the verifier ever runs behind a
+// hot-path API where per-request lines become noise.
+const ACCESS_LOG_ENABLED = (process.env.VERIFY_ACCESS_LOG ?? '').toLowerCase() !== 'off';
+if (ACCESS_LOG_ENABLED) {
+  app.use((req, res, next) => {
+    const started = Date.now();
+    res.on('finish', () => {
+      logUtc('access', `${req.method} ${req.path}`, {
+        status:     res.statusCode,
+        elapsed_ms: Date.now() - started,
+      });
+    });
+    next();
+  });
+}
+
+const VERIFY_ADMIN_TOKEN = process.env.VERIFY_ADMIN_TOKEN ?? '';
+
+function requireAdmin(req: Request, res: Response, next: () => void): void {
+  if (!VERIFY_ADMIN_TOKEN) {
+    res.status(503).json({ error: 'Admin endpoint disabled (VERIFY_ADMIN_TOKEN env var not set)' });
+    return;
+  }
+  const auth = req.headers.authorization ?? '';
+  const match = auth.match(/^Bearer\s+(.+)$/);
+  if (!match || match[1] !== VERIFY_ADMIN_TOKEN) {
+    res.status(401).json({ error: 'Unauthorized' });
+    return;
+  }
+  next();
+}
+
+// Health.
+//
+// `networkId` per entry is the authoritative "which Mina chain" answer — a
+// stable identifier the client can compare against exactly. `network` (the
+// raw GraphQL URL) is kept for operator-facing observability only, since it
+// can rotate providers (Minascan ↔ Minataur ↔ self-hosted) without the chain
+// changing. `fallback` mirrors the same for the configured fallback endpoint.
+app.get('/health', (_req: Request, res: Response) => {
+  const networks: Record<string, { networkId: NetworkId; network: string; fallback: string | null }> = {};
+  for (const net of NETWORKS) {
+    const cfg = NETWORK_CONFIG[net];
+    if (!cfg) continue;
+    networks[net] = {
+      networkId: cfg.networkId,
+      network: cfg.graphqlUrl,
+      fallback: cfg.graphqlFallback,
+    };
+  }
+  res.json({ status: 'ok', service: 'verify', networks });
+});
+
+// Current MerkleMap root for a specific zkApp. Network-agnostic — reads local
+// records only.
+app.get('/root', async (req: Request, res: Response) => {
+  const zkAppAddress = (req.query.zkApp as string | undefined) ?? '';
+  if (!zkAppAddress) {
+    return res.status(400).json({ error: 'Missing zkApp query param' });
+  }
+  const records = await readRecords();
+  const map = buildMap(records, zkAppAddress);
+  res.json({ root: map.getRoot().toString() });
+});
+
+
+// GET /?licenseHash=...&zkAppAddress=...
+// Primary endpoint for Android, PWA, and Node SDK license verification.
+// Describes the on-chain state of the requested license leaf — validity,
+// expiry slot, grace-period flag, purchaseSlot. Callers that need to prove
+// ownership of the license (e.g. before revealing app features) do so via
+// the passphrase-derived Pallas Schnorr keypair off-band — this endpoint is
+// state-only.
+app.get('/', async (req: Request, res: Response) => {
+  const { licenseHash: licenseHashStr, zkAppAddress } = req.query as {
+    licenseHash?: string;
+    zkAppAddress?: string;
+  };
+
+  if (!licenseHashStr || !zkAppAddress) {
+    return res.status(400).json({ error: 'Missing required query params: licenseHash, zkAppAddress' });
+  }
+
+  // Per-request verdict log. Redacts licenseHash to a 12-char prefix so logs
+  // stay pseudonymous but retain enough entropy to correlate a user's report
+  // ("my activation says invalid at 03:52") to the exact decision without
+  // grepping full hashes. resolvedAddress lets you see when an older
+  // generation was the actual match (pre-bump buyer).
+  const startedAt = Date.now();
+  const hashShort = licenseHashStr.slice(0, 12) + '…';
+  const emitVerdict = (verdict: string, reason?: string | null, resolvedAddress?: string): void => {
+    logUtc('verify', 'verdict', {
+      licenseHash:     hashShort,
+      zkAppAddress:    zkAppAddress.slice(0, 12) + '…',
+      resolvedAddress: resolvedAddress ? resolvedAddress.slice(0, 12) + '…' : undefined,
+      verdict,
+      reason:          reason ?? undefined,
+      elapsed_ms:      Date.now() - startedAt,
+    });
+  };
+
+  // Defense-in-depth against impersonation: the helper resolves the address's
+  // generation via backend deploymentHistory and asserts its on-chain VK equals
+  // that generation's canonical hash. Two rejection modes it covers: (a) the
+  // address is not in any registered app's deployment history — stops a
+  // genuine old circuit redeployed at a fresh address; (b) the address is
+  // listed but its VK doesn't match — a loud index-corruption tripwire.
+  try {
+    const onChain = await checkOnChainLicense(zkAppAddress, licenseHashStr);
+    switch (onChain.kind) {
+      case 'zkapp-not-found':
+        emitVerdict('zkapp-not-found');
+        return res.status(404).json({ error: 'zkApp not found on chain' });
+      case 'unregistered-address':
+        emitVerdict('unregistered-address');
+        return res.json({
+          valid: false,
+          expiresAt: null,
+          expirySlot: 0,
+          inGracePeriod: false,
+          remainingDays: 0,
+          reason: 'zkAppAddress is not in any registered app deployment history',
+        });
+      case 'vk-mismatch':
+        emitVerdict('vk-mismatch', `generation=${onChain.generation}`);
+        return res.json({
+          valid: false,
+          expiresAt: null,
+          expirySlot: 0,
+          inGracePeriod: false,
+          remainingDays: 0,
+          reason: `zkApp verification key does not match generation ${onChain.generation}'s canonical LicensingApp circuit`,
+        });
+      case 'checked': {
+        // Key on resolvedAddress (the address the license was actually found
+        // under) rather than the request address — for pre-bump buyers who
+        // never migrated, these differ: request is the retired addr the
+        // client pinned, resolved is the retired addr the record lives on.
+        const record = onChain.liveRecords.find(r => r.zkAppAddress === onChain.resolvedAddress && r.licenseHash === licenseHashStr);
+        // Collapse the VerifyResponse shape into a single-word verdict for
+        // log scanning: valid | grace | invalid. `invalid` carries the
+        // core's own reason string ("License not found", "License state
+        // does not match on-chain root", …) so the log line is enough to
+        // triage without opening the JSON body.
+        const verdict = onChain.result.valid
+          ? (onChain.result.inGracePeriod ? 'grace' : 'valid')
+          : 'invalid';
+        emitVerdict(verdict, onChain.result.reason, onChain.resolvedAddress);
+        return res.json({
+          ...onChain.result,
+          currentSlot: onChain.currentSlot,
+          purchaseSlot: record?.purchaseSlot ?? 0,
+          zkAppVersion: onChain.zkAppVersion,
+        });
+      }
+    }
+  } catch (err: any) {
+    emitVerdict('error', err?.message ?? String(err));
+    console.error('[verify]', err?.message ?? err);
+    res.status(500).json({ error: err?.message ?? 'Verification failed' });
+  }
+});
+
+// License map witness — composite (zkAppAddress, licenseHash) key. Network-
+// agnostic — witness comes from the local MerkleMap of records.
+app.get('/witness/:zkAppAddress/:licenseHash', async (req: Request, res: Response) => {
+  const { zkAppAddress, licenseHash } = req.params as { zkAppAddress: string; licenseHash: string };
+  try {
+    const records = await readRecords();
+    const map = buildMap(records, zkAppAddress);
+    const key = Field(licenseHash);
+    const witness = map.getWitness(key);
+    res.json({
+      root: map.getRoot().toString(),
+      currentValue: map.get(key).toString(),
+      ...serializeWitness(witness),
+    });
+  } catch (err: any) {
+    res.status(400).json({ error: err.message });
+  }
+});
+
+// License status — composite (zkAppAddress, licenseHash) key.
+// deviceCap + devices ride along so vendor SDKs can drive their bind flow
+// (activate() reads these to decide whether to prompt for a bind and which
+// slot to target). Sourced from the license record, which is the on-chain
+// mirror populated by eventSyncLoop from DeviceBound/DeviceUnbound events.
+app.get('/license/:zkAppAddress/:licenseHash', async (req: Request, res: Response) => {
+  const { zkAppAddress, licenseHash } = req.params as { zkAppAddress: string; licenseHash: string };
+  const record = await getLicense(zkAppAddress, licenseHash);
+  // Resolve the address's network so currentSlot hits the right chain. An
+  // unregistered address (or one whose network isn't configured here) falls
+  // back to slot 0 — status computation still returns a sensible verdict from
+  // the record's own expirySlot.
+  const apps = await readApps();
+  const resolved = resolveAppAndNetwork(apps, zkAppAddress);
+  const slot = resolved && NETWORK_CONFIG[resolved.network]
+    ? await currentSlot(resolved.network)
+    : 0;
+  const fork = resolved?.deployment.zkAppAddress === zkAppAddress ? resolved.deployment.forkActivationSlot ?? 0 : 0;
+  const status = licenseStatus(record, slot, fork);
+  res.json({
+    found: record !== null,
+    expirySlot: record?.expirySlot ?? 0,
+    status,
+    txHash: record?.txHash ?? null,
+    deviceCap: record?.deviceCap ?? 0,
+    devices: record?.devices ?? [],
+  });
+});
+
+// List registered apps
+app.get('/apps', async (_req: Request, res: Response) => {
+  const apps = await readApps();
+  res.json({ apps });
+});
+
+// POST /bootstrap — admin
+// Body: { zkAppAddress: string }
+// Replays all canonical events from the archive node and rebuilds licenses.json.
+// Gated because an open archive-replay endpoint is a DoS vector (each call hits
+// the archive node and rewrites the local store).
+app.post('/bootstrap', requireAdmin, async (req: Request, res: Response) => {
+  const { zkAppAddress } = req.body as { zkAppAddress?: string };
+  if (!zkAppAddress) {
+    return res.status(400).json({ error: 'Missing zkAppAddress' });
+  }
+  const addrErr = validateZkAppAddress(zkAppAddress);
+  if (addrErr) return res.status(400).json({ error: addrErr });
+  try {
+    const apps = await readApps();
+    const resolved = resolveAppAndNetwork(apps, zkAppAddress);
+    if (!resolved) {
+      return res.status(400).json({ error: `zkAppAddress not in any registered app deployment history` });
+    }
+    const { network } = resolved;
+    if (!NETWORK_CONFIG[network]) {
+      return res.status(400).json({ error: `zkAppAddress belongs to ${network} but that network is not configured on this verifier` });
+    }
+    // Refuse to replay a zkApp whose immutable source-version tag doesn't match
+    // one this verifier understands. Otherwise a v2-deployed contract's events
+    // could be decoded with a v1 schema and yield subtly wrong state.
+    const onChainVersion = await withNetwork(network, () => fetchLicensingAppVersion(zkAppAddress));
+    if (onChainVersion === null) {
+      return res.status(400).json({ error: `zkApp ${zkAppAddress.slice(0, 16)}… not visible on chain` });
+    }
+    if (!SUPPORTED_LICENSING_APP_VERSIONS.includes(onChainVersion)) {
+      return res.status(400).json({
+        error: `unsupported LicensingApp version — on-chain v${onChainVersion}, this verifier supports v${SUPPORTED_LICENSING_APP_VERSIONS.join(', v')}`,
+      });
+    }
+    const cfg = NETWORK_CONFIG[network]!;
+    console.log(`[bootstrap] Replaying events for ${zkAppAddress.slice(0, 16)}… (${network} v${onChainVersion}) from ${cfg.archiveUrl}`);
+    const { events } = await withNetwork(network, () => bootstrapFromArchive(zkAppAddress));
+    const { count, warnings } = await applyEventsToStore(zkAppAddress, events);
+    for (const w of warnings) console.warn('[bootstrap]', w);
+    console.log(`[bootstrap] Done — ${count} license records written`);
+    res.json({ ok: true, count, warnings, onChainVersion });
+  } catch (err: any) {
+    console.error('[bootstrap]', err?.message ?? err);
+    res.status(500).json({ error: err?.message ?? 'Bootstrap failed' });
+  }
+});
+
+
+// ------------------------------------------------------------
+// START
+// ------------------------------------------------------------
+
+let records = await readRecords();
+
+// Auto-bootstrap from archive if store is empty. Iterates every configured
+// network and each of that network's registered apps. Apps whose network
+// isn't configured on this verifier are skipped silently.
+if (records.length === 0) {
+  const apps = await readApps();
+  const configuredNetworks = NETWORKS.filter(n => !!NETWORK_CONFIG[n]);
+  const bootstrapPlan: Array<{ network: NetworkId; app: AppRecord; dep: DeploymentInfo }> = [];
+  for (const network of configuredNetworks) {
+    for (const app of apps) {
+      const dep = app.deployments[network];
+      if (dep) bootstrapPlan.push({ network, app, dep });
+    }
+  }
+  if (bootstrapPlan.length > 0) {
+    console.log(`📦 licenses.json is empty — bootstrapping ${bootstrapPlan.length} app deployment(s) from archive node…`);
+    for (const { network, app: appRecord, dep } of bootstrapPlan) {
+      try {
+        // Same version guard as POST /bootstrap — refuse to replay any address
+        // whose on-chain source-version tag this verifier doesn't understand.
+        const onChainVersion = await withNetwork(network, () => fetchLicensingAppVersion(dep.zkAppAddress));
+        if (onChainVersion === null) {
+          console.warn(`   ⚠️  ${appRecord.name} (${network}): zkApp not visible on chain — skipping`);
+          continue;
+        }
+        if (!SUPPORTED_LICENSING_APP_VERSIONS.includes(onChainVersion)) {
+          console.warn(`   ⚠️  ${appRecord.name} (${network}): on-chain v${onChainVersion} not supported (supports v${SUPPORTED_LICENSING_APP_VERSIONS.join(', v')}) — skipping`);
+          continue;
+        }
+        const { events } = await withNetwork(network, () => bootstrapFromArchive(dep.zkAppAddress));
+        const { count, warnings } = await applyEventsToStore(dep.zkAppAddress, events);
+        for (const w of warnings) console.warn('⚠️', w);
+        console.log(`   ✅ ${appRecord.name} (${network} v${onChainVersion}): ${count} records`);
+      } catch (err: any) {
+        console.warn(`   ⚠️  ${appRecord.name} (${network}): bootstrap failed — ${err?.message ?? err}`);
+      }
+    }
+    records = await readRecords();
+  }
+}
+
+console.log(`📋 Loaded ${records.length} license records across ${new Set(records.map(r => r.zkAppAddress)).size} zkApp(s)`);
+
+app.listen(PORT, () => {
+  console.log(`🔍 Verify service listening on http://localhost:${PORT}`);
+  console.log(`   GET  /?licenseHash=...&zkAppAddress=...`);
+  console.log(`   GET  /witness/:zkAppAddress/:licenseHash`);
+  console.log(`   GET  /license/:zkAppAddress/:licenseHash`);
+  console.log(`   GET  /apps`);
+  console.log(`   POST /bootstrap`);
+  if (VERIFY_ADMIN_TOKEN) {
+    console.log(`🔒 Admin endpoints (bootstrap) enabled`);
+  } else {
+    console.log(`⚠️  Admin endpoints disabled (set VERIFY_ADMIN_TOKEN to enable)`);
+  }
+  console.log(`🔁 Lazy bootstrap on root mismatch (no periodic poller)`);
+  console.log(`📝 Access log: ${ACCESS_LOG_ENABLED ? 'ON' : 'off (VERIFY_ACCESS_LOG=off)'}`);
+});