zklicensing 0.1.0-beta.0

package/build/verifyService.js

@@ -0,0 +1,690 @@
+#!/usr/bin/env node
+// Copyright (c) 2025-2026 zkLicensing project developers
+// All rights reserved.
+/**
+ * verifyService.ts
+ *
+ * Lightweight, standalone license verification service.
+ *
+ * Exposes the same state endpoints as the keeper but contains NO ZK prover —
+ * no circuit compilation, no o1js native backend. Starts in ~2 seconds and
+ * runs on any small VPS or container.
+ *
+ * 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,
+ *   - lazy bootstrap inside GET / when the computed Merkle root
+ *     disagrees with the on-chain root for the requested app (the canonical
+ *     "we're stale" signal). One replay + one retry is enough — root is
+ *     consensus. This catches licenses issued, renewed, or refunded after
+ *     boot on the very next verify call, with zero work done when no one is
+ *     asking. Concurrent verifies for the same app share one in-flight
+ *     bootstrap so a popular license under load does not stampede the
+ *     archive node.
+ *   - POST /bootstrap (admin) for ad-hoc reasons: a newly registered zkApp
+ *     (verify won't trigger a sync for an app no client knows about yet), a
+ *     corrupted licenses.json, or repopulating the offline /license/...
+ *     debug endpoint without first hitting /verify.
+ *
+ * Deployment modes
+ * ----------------
+ * 1. Same-machine as the keeper
+ *    - Run from the keeper'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 keeper's apps.json into the verifyService working directory.
+ *      apps.json tells the service which zkApp addresses to replay events for.
+ *    - Start the service. On boot it auto-bootstraps every app in apps.json
+ *      from the archive node. MINA_ARCHIVE_URL defaults to the Minascan public
+ *      archive matching MINA_NETWORK_ID:
+ *        mainnet → https://api.minascan.io/archive/mainnet/v1/graphql
+ *        else    → https://api.minascan.io/archive/devnet/v1/graphql
+ *      Override by setting MINA_ARCHIVE_URL in the environment.
+ *    - To register a NEW app on the replica afterwards:
+ *        a) Re-copy apps.json from the keeper (it owns the registry), then
+ *        b) POST /bootstrap with the new zkAppAddress to ingest its events.
+ *    - Re-copying apps.json on a cron (or pulling it via GET /apps from the
+ *      keeper) 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: MINA_GRAPHQL_URL, PLATFORM_ADDRESS.
+ * Optional: MINA_NETWORK_ID (default testnet), MINA_ARCHIVE_URL (defaults by
+ * network), VERIFY_PORT (default 8081), VERIFY_ADMIN_TOKEN.
+ *
+ * Endpoints:
+ *   GET  /health
+ *   GET  /?licenseHash=...&zkAppAddress=...        ← primary endpoint for apps
+ *   GET  /challenge?licenseHash=...                 ← ownership nonce
+ *   POST /respond                                   ← ownership proof + token
+ *   POST /refresh                                   ← extend token TTL (no re-prove)
+ *   POST /releaseSeat                                ← release this device's seat
+ *   POST /reset-sessions                            ← drop all sessions (re-prove)
+ *   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 { mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import express from 'express';
+import { Field, Mina, fetchLastBlock, fetchAccount, PublicKey, Cache, setBackend, verify, } from 'o1js';
+import { buildMap, getLicense, licenseStatus, readRecords, serializeWitness, } from './licenseStore.js';
+import { verifyLicenseCore } from './verifyCore.js';
+import { bootstrapFromArchive, applyEventsToStore, lazyBootstrap } from './archiveBootstrap.js';
+import { LicenseProof, LicenseProofProof } from './licenseProof.js';
+import { CANONICAL_VK_HASHES, CANONICAL_LICENSE_PROOF_VK_HASH, SUPPORTED_LICENSING_APP_VERSIONS, fetchLicensingAppVersion, } from './contractInterface.js';
+import { createChallengeStore, createSessionStore, newJti, signOwnershipToken, verifyOwnershipToken, newOwnershipKey, OWNERSHIP_TOKEN_TTL_MS, } from './ownership.js';
+setBackend('native');
+const CIRCUIT_CACHE_DIR = join(homedir(), '.cache', 'zklic-verifier');
+mkdirSync(CIRCUIT_CACHE_DIR, { recursive: true });
+// ------------------------------------------------------------
+// CONFIG (env vars) & NETWORK
+// ------------------------------------------------------------
+function requireEnv(name, hint) {
+    const v = process.env[name];
+    if (!v) {
+        console.error(`❌ ${name} env var is required. ${hint}`);
+        process.exit(1);
+    }
+    return v;
+}
+const MINA_NETWORK_ID = process.env.MINA_NETWORK_ID ?? 'devnet';
+const MINA_GRAPHQL_URL = requireEnv('MINA_GRAPHQL_URL', 'e.g. https://api.minascan.io/node/devnet/v1/graphql');
+const PORT = parseInt(process.env.VERIFY_PORT ?? '8081', 10);
+function defaultArchiveUrl(networkId) {
+    switch (networkId) {
+        case 'mainnet':
+            return 'https://api.minascan.io/archive/mainnet/v1/graphql';
+        case 'devnet':
+            return 'https://api.minascan.io/archive/devnet/v1/graphql';
+        default:
+            return null;
+    }
+}
+const archiveUrl = process.env.MINA_ARCHIVE_URL ?? defaultArchiveUrl(MINA_NETWORK_ID);
+if (!archiveUrl) {
+    console.error(`❌ No archive URL for MINA_NETWORK_ID="${MINA_NETWORK_ID}" and no built-in default for this network.\n` +
+        `   Set MINA_ARCHIVE_URL to the archive node GraphQL endpoint.`);
+    process.exit(1);
+}
+console.log(`🔗 Mina node:    ${MINA_GRAPHQL_URL}`);
+console.log(`📚 Archive node: ${archiveUrl}${process.env.MINA_ARCHIVE_URL ? ' (from MINA_ARCHIVE_URL)' : ' (default — set MINA_ARCHIVE_URL to override)'}`);
+Mina.setActiveInstance(Mina.Network({
+    networkId: MINA_NETWORK_ID,
+    mina: MINA_GRAPHQL_URL,
+    archive: archiveUrl,
+}));
+// ------------------------------------------------------------
+// CIRCUIT — LicenseProof (ownership challenge/response)
+// ------------------------------------------------------------
+let licenseProofVk = null;
+let licenseProofCompile = null;
+async function ensureCompiled() {
+    if (licenseProofVk)
+        return;
+    licenseProofCompile ??= (async () => {
+        const cached = Cache.FileSystem(CIRCUIT_CACHE_DIR);
+        const t = Date.now();
+        console.log(`[verify-prover] Compiling LicenseProof (cache: ${CIRCUIT_CACHE_DIR})…`);
+        const lpVk = await LicenseProof.compile({ cache: cached });
+        const vk = lpVk.verificationKey;
+        if (CANONICAL_LICENSE_PROOF_VK_HASH && vk.hash.toString() !== CANONICAL_LICENSE_PROOF_VK_HASH) {
+            throw new Error(`LicenseProof VK hash ${vk.hash.toString()} does not match CANONICAL_LICENSE_PROOF_VK_HASH ${CANONICAL_LICENSE_PROOF_VK_HASH}`);
+        }
+        licenseProofVk = vk;
+        console.log(`[verify-prover] Ready in ${((Date.now() - t) / 1000).toFixed(1)}s — vk ${vk.hash.toString().slice(0, 16)}…`);
+    })();
+    await licenseProofCompile;
+}
+ensureCompiled().catch((e) => console.error('[verify-prover] Compile failed:', e));
+// ------------------------------------------------------------
+// OWNERSHIP — challenge + activation token (helpers live in ownership.ts)
+// ------------------------------------------------------------
+const ownershipChallenges = createChallengeStore();
+setInterval(() => { /* opportunistic GC */ ownershipChallenges.size(); }, 30_000).unref();
+// Per-license active-device session store. Backs the concurrent-device cap
+// (AppRecord.maxConcurrentDevices), /releaseSeat, and /reset-sessions. In-memory
+// by design — a keeper restart drops every session, forcing devices to
+// re-prove ownership. That is a security feature: persisted sessions would
+// let a stolen token bypass concurrency caps across restarts.
+const ownershipSessions = createSessionStore();
+setInterval(() => { /* opportunistic GC — activeCount touches prune */ ownershipSessions.size(); }, 30_000).unref();
+async function loadAppByAddress(zkAppAddress) {
+    const apps = await readApps();
+    return apps.find((a) => a.zkAppAddress === zkAppAddress) ?? null;
+}
+// Resolve which generation a zkAppAddress claims to belong to by walking the
+// keeper's AppRecord.deploymentHistory[]. The top-level address is the current
+// generation (history.length + 1); older addresses live in history at
+// increasing index. Returns null when the address is not present in any
+// app's history — which is exactly what stops a "genuine v1 circuit
+// redeployed at a fresh address" impersonation: unlisted address → no
+// generation → verify rejects. See CANONICAL_VK_HASHES in contractInterface.ts.
+async function resolveGenerationByAddress(zkAppAddress) {
+    const apps = await readApps();
+    for (const a of apps) {
+        const historyLen = a.deploymentHistory?.length ?? 0;
+        if (a.zkAppAddress === zkAppAddress)
+            return historyLen + 1;
+        if (a.deploymentHistory) {
+            for (let i = 0; i < a.deploymentHistory.length; i++) {
+                if (a.deploymentHistory[i].zkAppAddress === zkAppAddress)
+                    return i + 1;
+            }
+        }
+    }
+    return null;
+}
+const OWNERSHIP_KEY_PATH = process.env.OWNERSHIP_KEY_PATH ?? join(CIRCUIT_CACHE_DIR, 'ownership-hmac.key');
+let ownershipKey;
+try {
+    ownershipKey = await fs.readFile(OWNERSHIP_KEY_PATH);
+    console.log(`🔑 Ownership HMAC key loaded from ${OWNERSHIP_KEY_PATH}`);
+}
+catch {
+    ownershipKey = newOwnershipKey();
+    await fs.writeFile(OWNERSHIP_KEY_PATH, ownershipKey, { mode: 0o600 });
+    console.log(`🔑 Ownership HMAC key generated → ${OWNERSHIP_KEY_PATH}`);
+}
+// ------------------------------------------------------------
+// HELPERS
+// ------------------------------------------------------------
+async function currentSlot() {
+    try {
+        const block = await fetchLastBlock();
+        return Number(block.globalSlotSinceGenesis.toString());
+    }
+    catch {
+        return 0;
+    }
+}
+const APPS_FILE = 'apps.json';
+async function readApps() {
+    try {
+        return JSON.parse(await fs.readFile(APPS_FILE, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+// ------------------------------------------------------------
+// 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();
+});
+const VERIFY_ADMIN_TOKEN = process.env.VERIFY_ADMIN_TOKEN ?? '';
+function requireAdmin(req, res, next) {
+    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
+app.get('/health', (_req, res) => {
+    res.json({ status: 'ok', service: 'verify', network: MINA_GRAPHQL_URL });
+});
+// Current MerkleMap root for a specific zkApp.
+app.get('/root', async (req, res) => {
+    const zkAppAddress = req.query.zkApp ?? '';
+    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 /challenge?licenseHash=...
+// Issues a nonce for the ownership challenge-response flow.
+app.get('/challenge', (req, res) => {
+    const licenseHash = String(req.query.licenseHash ?? '');
+    if (!licenseHash) {
+        return res.status(400).json({ error: 'Missing licenseHash' });
+    }
+    res.json(ownershipChallenges.issue(licenseHash));
+});
+// POST /respond — body: { zkAppAddress, proof }
+// Verifies a LicenseProof against the issued nonce, consumes the nonce,
+// enforces the vendor's concurrent-device cap (if any), and returns
+// { ownership: 'verified', token, expiresAt, jti, activeSessions, deviceLimit }
+// on success. On cap overflow returns 429 without minting a token — clients
+// must release a seat (POST /releaseSeat), reset all sessions (POST
+// /reset-sessions), or wait for the oldest to hit TTL.
+app.post('/respond', async (req, res) => {
+    await ensureCompiled();
+    if (!licenseProofVk) {
+        return res.status(503).json({ error: 'Verify service not ready — circuits compiling' });
+    }
+    const { zkAppAddress, proof: proofJson } = req.body;
+    if (!zkAppAddress || !proofJson) {
+        return res.status(400).json({ error: 'Missing zkAppAddress or proof' });
+    }
+    let proof;
+    try {
+        proof = await LicenseProofProof.fromJSON(proofJson);
+    }
+    catch {
+        return res.status(400).json({ error: 'Invalid proof format' });
+    }
+    let proofValid = false;
+    try {
+        proofValid = await verify(proof, licenseProofVk);
+    }
+    catch {
+        return res.status(400).json({ error: 'Proof verification threw' });
+    }
+    if (!proofValid) {
+        return res.status(400).json({ error: 'Proof is cryptographically invalid' });
+    }
+    const licenseHash = proof.publicInput.licenseHash.toString();
+    const nonce = proof.publicInput.nonce.toString();
+    const nonceState = ownershipChallenges.consume(licenseHash, nonce);
+    if (nonceState !== 'ok') {
+        return res.status(400).json({ error: `Nonce ${nonceState} — request a fresh /challenge` });
+    }
+    // Concurrent-device cap enforcement. Read the vendor's per-app limit
+    // (0/undefined = unlimited) and try to reserve a session slot BEFORE
+    // minting the HMAC — a token without a matching session-store entry is
+    // dead on arrival at GET / anyway, so refusing here avoids handing the
+    // caller a bearer that they can only use to be rejected.
+    const app_record = await loadAppByAddress(zkAppAddress);
+    const cap = Math.max(0, Math.floor(app_record?.maxConcurrentDevices ?? 0));
+    const jti = newJti();
+    const exp = Date.now() + OWNERSHIP_TOKEN_TTL_MS;
+    const reserved = ownershipSessions.insert(licenseHash, jti, exp, cap);
+    if (reserved.state === 'at-cap') {
+        return res.status(429).json({
+            error: 'Concurrent-device limit reached — release a seat, run POST /reset-sessions, or wait for the oldest session to expire',
+            activeSessions: reserved.active,
+            deviceLimit: cap,
+        });
+    }
+    const token = signOwnershipToken(ownershipKey, { z: zkAppAddress, l: licenseHash, e: exp, jti });
+    res.json({
+        ownership: 'verified',
+        token,
+        expiresAt: exp,
+        jti,
+        activeSessions: reserved.active,
+        deviceLimit: cap,
+    });
+});
+// POST /releaseSeat — body: { token }
+// Releases the seat identified by the token's jti. Possession of the token
+// is authorization to release it (same threat model as any bearer token);
+// no proof-of-ownership is required. Enables an in-app "log out this device"
+// button. Idempotent — a second call with the same token silently no-ops.
+app.post('/releaseSeat', (req, res) => {
+    const { token } = req.body;
+    if (!token)
+        return res.status(400).json({ error: 'Missing token' });
+    const payload = verifyOwnershipToken(ownershipKey, token);
+    if (!payload)
+        return res.status(401).json({ error: 'Invalid or expired token' });
+    if (!payload.jti) {
+        // Pre-jti tokens aren't tracked in the session store, so there's no seat
+        // to release. Return 200 for idempotency — the caller's intent (log this
+        // device out) is satisfied by the local token delete.
+        return res.json({ ok: true, released: false, reason: 'token has no jti (pre-jti issue)' });
+    }
+    const released = ownershipSessions.releaseSeat(payload.l, payload.jti);
+    res.json({ ok: true, released, jti: payload.jti });
+});
+// POST /refresh — body: { token }
+// Extends the lifetime of the current session without a fresh ownership proof.
+// The caller sends the token they already hold; the server verifies the HMAC,
+// checks the jti is still active in the session store (i.e. not released or
+// evicted), and issues a new token with the same jti and a fresh exp. The
+// session store's insert is idempotent per jti, so no cap check is needed —
+// the slot was already reserved at /respond time.
+//
+// Intended for background renewal from a running app: the client polls this
+// endpoint before the token expires so a user who keeps the app open never
+// has to redo the passphrase-gated challenge/response. A stolen token can be
+// refreshed too, which is why /releaseSeat exists — losing a device means the
+// owner explicitly logs it out, and subsequent refreshes fail.
+//
+// Pre-jti tokens (legacy /respond without session tracking) can also refresh:
+// they're valid HMAC, they carry no jti, and there's no session-store row to
+// gate against. The reissued token is identically pre-jti. Callers that want
+// concurrency enforcement must reissue via /respond so a jti gets minted.
+app.post('/refresh', (req, res) => {
+    const { token } = req.body;
+    if (!token)
+        return res.status(400).json({ error: 'Missing token' });
+    const payload = verifyOwnershipToken(ownershipKey, token);
+    if (!payload)
+        return res.status(401).json({ error: 'Invalid or expired token' });
+    const newExp = Date.now() + OWNERSHIP_TOKEN_TTL_MS;
+    if (payload.jti) {
+        if (!ownershipSessions.has(payload.l, payload.jti)) {
+            return res.status(401).json({ error: 'Seat released' });
+        }
+        // Idempotent for existing jti — updates the expiry, never trips the cap.
+        ownershipSessions.insert(payload.l, payload.jti, newExp, 0);
+    }
+    const next = {
+        z: payload.z,
+        l: payload.l,
+        e: newExp,
+        ...(payload.jti ? { jti: payload.jti } : {}),
+    };
+    const nextToken = signOwnershipToken(ownershipKey, next);
+    res.json({ token: nextToken, expiresAt: newExp, jti: payload.jti });
+});
+// POST /reset-sessions — body: { zkAppAddress, proof }
+// Drops ALL active sessions for the licenseHash proved by the LicenseProof.
+// Requires the same challenge/response as /respond — only the passphrase
+// holder can invoke it. Intended for "reinstall unsticks a device that
+// burned a slot without logging out" recovery. After this returns, the
+// caller runs a fresh /respond to re-provision a session under a zero
+// active count.
+app.post('/reset-sessions', async (req, res) => {
+    await ensureCompiled();
+    if (!licenseProofVk) {
+        return res.status(503).json({ error: 'Verify service not ready — circuits compiling' });
+    }
+    const { zkAppAddress, proof: proofJson } = req.body;
+    if (!zkAppAddress || !proofJson) {
+        return res.status(400).json({ error: 'Missing zkAppAddress or proof' });
+    }
+    let proof;
+    try {
+        proof = await LicenseProofProof.fromJSON(proofJson);
+    }
+    catch {
+        return res.status(400).json({ error: 'Invalid proof format' });
+    }
+    let proofValid = false;
+    try {
+        proofValid = await verify(proof, licenseProofVk);
+    }
+    catch {
+        return res.status(400).json({ error: 'Proof verification threw' });
+    }
+    if (!proofValid) {
+        return res.status(400).json({ error: 'Proof is cryptographically invalid' });
+    }
+    const licenseHash = proof.publicInput.licenseHash.toString();
+    const nonce = proof.publicInput.nonce.toString();
+    const nonceState = ownershipChallenges.consume(licenseHash, nonce);
+    if (nonceState !== 'ok') {
+        return res.status(400).json({ error: `Nonce ${nonceState} — request a fresh /challenge` });
+    }
+    const dropped = ownershipSessions.reset(licenseHash);
+    res.json({ ok: true, dropped });
+});
+// GET /?licenseHash=...&zkAppAddress=...[&token=...]
+// Primary endpoint for Android, iOS, PWA, and Node SDK license verification.
+//
+// Ownership semantics:
+//  - Without `token`, the response describes the state of the on-chain leaf
+//    only — it does NOT prove the caller owns the license. This is fine for
+//    status displays; gate access behind /respond or pass a fresh
+//    activation `token` in the query string.
+//  - With `token`, the service checks the HMAC and refuses if the token isn't
+//    for this (zkAppAddress, licenseHash) pair.
+app.get('/', async (req, res) => {
+    const { licenseHash: licenseHashStr, zkAppAddress, token } = req.query;
+    if (!licenseHashStr || !zkAppAddress) {
+        return res.status(400).json({ error: 'Missing required query params: licenseHash, zkAppAddress' });
+    }
+    let ownershipVerified = false;
+    if (token) {
+        const payload = verifyOwnershipToken(ownershipKey, token);
+        if (!payload || payload.z !== zkAppAddress || payload.l !== licenseHashStr) {
+            return res.status(401).json({ error: 'Invalid or expired ownership token' });
+        }
+        // Session-store gate: a jti-bearing token must still be in the active-
+        // session set for its license. A token whose jti was released (via
+        // /releaseSeat, /reset-sessions, or evicted by TTL prune) is refused even if
+        // it's still HMAC-valid and inside its exp. Pre-jti tokens (issued
+        // before the session-tracking rollout) skip this check and remain
+        // usable until their exp — no forced logout across the migration.
+        if (payload.jti && !ownershipSessions.has(payload.l, payload.jti)) {
+            return res.status(401).json({ error: 'Seat released — call POST /respond to acquire a fresh token' });
+        }
+        ownershipVerified = true;
+    }
+    try {
+        const [records, { account }, lastBlock] = await Promise.all([
+            readRecords(),
+            fetchAccount({ publicKey: PublicKey.fromBase58(zkAppAddress) }),
+            fetchLastBlock(),
+        ]);
+        const onChainRoot = account?.zkapp?.appState?.[0]?.toString();
+        if (!onChainRoot) {
+            return res.status(404).json({ error: 'zkApp not found on chain' });
+        }
+        // Source-version tag from the already-fetched account state — free byte
+        // for the SDK / dashboard to label which protocol revision a license lives
+        // on. Not a security gate (that's the boot + bootstrap check); purely
+        // informational.
+        const zkAppVersion = Number(account?.zkapp?.appState?.[7]?.toString() ?? '0');
+        // Defense in depth against impersonation. The contract locks
+        // `setVerificationKey` via `Permissions.VerificationKey
+        // .impossibleDuringCurrentVersion()` plus deploy-key disposal, so VK
+        // rotation post-deploy is impossible for any *listed* address. The check
+        // below resolves the address's generation via keeper deploymentHistory
+        // and asserts its on-chain VK equals that generation's canonical hash.
+        // Two failure modes: (a) the address is unknown (not the current live
+        // deployment of any registered app, not in any deploymentHistory[]) —
+        // reject; that stops a genuine old circuit deployed at a fresh address.
+        // (b) the address is listed but its VK doesn't equal its generation's
+        // hash — reject; that's a loud index-corruption tripwire.
+        const onChainVk = account?.zkapp?.verificationKey?.hash?.toString();
+        const generation = await resolveGenerationByAddress(zkAppAddress);
+        if (generation === null) {
+            return res.json({
+                valid: false,
+                expiresAt: null,
+                expirySlot: 0,
+                inGracePeriod: false,
+                remainingDays: 0,
+                reason: 'zkAppAddress is not in any registered app deployment history',
+                ownership: ownershipVerified ? 'verified' : 'unverified',
+            });
+        }
+        const expectedVk = CANONICAL_VK_HASHES[generation];
+        if (expectedVk && onChainVk !== expectedVk) {
+            return res.json({
+                valid: false,
+                expiresAt: null,
+                expirySlot: 0,
+                inGracePeriod: false,
+                remainingDays: 0,
+                reason: `zkApp verification key does not match generation ${generation}'s canonical LicensingApp circuit`,
+                ownership: ownershipVerified ? 'verified' : 'unverified',
+            });
+        }
+        const currentSlot = Number(lastBlock.globalSlotSinceGenesis.toString());
+        let liveRecords = records;
+        let result = verifyLicenseCore({
+            zkAppAddress,
+            licenseHash: licenseHashStr,
+            records: liveRecords,
+            onChainRoot,
+            currentSlot,
+        });
+        // Lazy self-heal: a root mismatch means the local store is stale (a
+        // license has been bought, renewed, or refunded since we last replayed).
+        // One replay + one retry is enough — the on-chain root is the source of
+        // truth and the archive node will reflect it.
+        if (!result.valid && result.reason === 'License state does not match on-chain root') {
+            await lazyBootstrap(zkAppAddress);
+            liveRecords = await readRecords();
+            result = verifyLicenseCore({
+                zkAppAddress,
+                licenseHash: licenseHashStr,
+                records: liveRecords,
+                onChainRoot,
+                currentSlot,
+            });
+        }
+        const record = liveRecords.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHashStr);
+        return res.json({
+            ...result,
+            currentSlot,
+            purchaseSlot: record?.purchaseSlot ?? 0,
+            ownership: ownershipVerified ? 'verified' : 'unverified',
+            zkAppVersion,
+        });
+    }
+    catch (err) {
+        console.error('[verify]', err?.message ?? err);
+        res.status(500).json({ error: err?.message ?? 'Verification failed' });
+    }
+});
+// License map witness — composite (zkAppAddress, licenseHash) key.
+app.get('/witness/:zkAppAddress/:licenseHash', async (req, res) => {
+    const { zkAppAddress, licenseHash } = req.params;
+    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) {
+        res.status(400).json({ error: err.message });
+    }
+});
+// License status — composite (zkAppAddress, licenseHash) key.
+app.get('/license/:zkAppAddress/:licenseHash', async (req, res) => {
+    const { zkAppAddress, licenseHash } = req.params;
+    const record = await getLicense(zkAppAddress, licenseHash);
+    const slot = await currentSlot();
+    const status = licenseStatus(record, slot);
+    res.json({
+        found: record !== null,
+        expirySlot: record?.expirySlot ?? 0,
+        status,
+        txHash: record?.txHash ?? null,
+    });
+});
+// List registered apps
+app.get('/apps', async (_req, res) => {
+    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, res) => {
+    const { zkAppAddress } = req.body;
+    if (!zkAppAddress) {
+        return res.status(400).json({ error: 'Missing zkAppAddress' });
+    }
+    try {
+        // 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 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')}`,
+            });
+        }
+        console.log(`[bootstrap] Replaying events for ${zkAppAddress.slice(0, 16)}… (v${onChainVersion}) from ${archiveUrl}`);
+        const { events } = await 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) {
+        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.
+if (records.length === 0) {
+    const apps = await readApps();
+    if (apps.length > 0) {
+        console.log(`📦 licenses.json is empty — bootstrapping ${apps.length} app(s) from archive node…`);
+        for (const appRecord of apps) {
+            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 fetchLicensingAppVersion(appRecord.zkAppAddress);
+                if (onChainVersion === null) {
+                    console.warn(`   ⚠️  ${appRecord.name}: zkApp not visible on chain — skipping`);
+                    continue;
+                }
+                if (!SUPPORTED_LICENSING_APP_VERSIONS.includes(onChainVersion)) {
+                    console.warn(`   ⚠️  ${appRecord.name}: on-chain v${onChainVersion} not supported (supports v${SUPPORTED_LICENSING_APP_VERSIONS.join(', v')}) — skipping`);
+                    continue;
+                }
+                const { events } = await bootstrapFromArchive(appRecord.zkAppAddress);
+                const { count, warnings } = await applyEventsToStore(appRecord.zkAppAddress, events);
+                for (const w of warnings)
+                    console.warn('⚠️', w);
+                console.log(`   ✅ ${appRecord.name} (v${onChainVersion}): ${count} records`);
+            }
+            catch (err) {
+                console.warn(`   ⚠️  ${appRecord.name}: 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=...[&token=...]`);
+    console.log(`   GET  /challenge?licenseHash=...`);
+    console.log(`   POST /respond`);
+    console.log(`   POST /refresh`);
+    console.log(`   POST /releaseSeat`);
+    console.log(`   POST /reset-sessions`);
+    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)`);
+});
+//# sourceMappingURL=verifyService.js.map