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

package/src/verifyWithAncestors.ts

@@ -0,0 +1,163 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * verifyWithAncestors.ts
+ *
+ * Shared address-routing core used by both verifyService.ts and
+ * keeperService.ts. Given an already-resolved AppRecord, an already-fetched
+ * current-live on-chain root, and the current set of license records, this
+ * helper:
+ *
+ *   1. Tries verifyLicenseCore against the current live contract (a
+ *      redeployed app's successor starts with its predecessor's licenses,
+ *      so licenses bought on any generation land here).
+ *   2. On "License not found" in current-live, walks the app's
+ *      deploymentHistory[] newest-first, fetching each retired contract's
+ *      own on-chain root and re-checking with records filtered to that
+ *      retired address (a request naming a retired address before the
+ *      keeper carried the records over).
+ *   3. Applies one lazy-bootstrap replay per address on
+ *      "License state does not match on-chain root" — same self-heal the
+ *      callers used to do inline.
+ *
+ * The helper does NOT do VK-hash validation or version admission — those
+ * are caller-specific policy (verifyService uses per-generation
+ * CANONICAL_VK_HASHES; the backend uses its single compiled canonicalVkHash).
+ * Callers do their VK check up front against the current-live account they
+ * fetched, then hand the fetched root here.
+ */
+
+import { PublicKey, fetchAccount } from 'o1js';
+import { LICENSING_APP_STATE } from './contractInterface.js';
+import { verifyLicenseCore, type VerifyResponse } from './verifyCore.js';
+import { readRecords, type LicenseRecord } from './licenseStore.js';
+import { lazyBootstrap } from './archiveBootstrap.js';
+import type { LookupableDeployment } from './appsLookup.js';
+
+export type VerifyWithAncestorsInput = {
+  // The per-network deployment slice (current live address + retired history).
+  // Callers project this from the resolved AppRecord: for a verify request the
+  // caller determines which network's deployment to walk (typically the one
+  // whose current address matched, or the one the client-pinned address lives
+  // on). Cross-network walks aren't needed — mainnet and devnet each keep
+  // their own generation history.
+  deployment: LookupableDeployment;
+  licenseHash: string;
+  currentSlot: number;
+  currentLiveRoot: string;
+  // The current live app's forkActivationSlot state (0 or absent: none).
+  currentLiveForkSlot?: number;
+  // Callers pre-load records in parallel with the current-live fetch. The
+  // helper may reload once after a lazy-bootstrap replay, so also returns
+  // the (possibly refreshed) records for the caller to reuse when looking
+  // up per-record fields like purchaseSlot.
+  records: LicenseRecord[];
+};
+
+export type VerifyWithAncestorsResult = {
+  result: VerifyResponse;
+  // Address the license was actually found under — usually the current live
+  // one, but falls back to a retired address for pre-bump buyers. Callers
+  // must key any LicenseRecord lookup on this, not on the request address.
+  resolvedAddress: string;
+  onChainRoot: string;
+  liveRecords: LicenseRecord[];
+};
+
+// One-shot internal retry for a single network call. Absorbs a lone
+// transient blip from the Mina GraphQL node. Duplicated shape from
+// verifyService's fetchWithOneRetry — kept local to this module so the
+// helper stays self-contained and the two callers don't need to inject
+// their own retry strategy.
+async function fetchWithOneRetry<T>(fn: () => Promise<T>, delayMs = 500): Promise<T> {
+  try {
+    return await fn();
+  } catch {
+    await new Promise(r => setTimeout(r, delayMs));
+    return fn();
+  }
+}
+
+export async function verifyLicenseWithAncestors(
+  input: VerifyWithAncestorsInput,
+): Promise<VerifyWithAncestorsResult> {
+  const { deployment, licenseHash, currentSlot, currentLiveRoot } = input;
+  let liveRecords = input.records;
+  const currentLive = deployment.zkAppAddress;
+
+  // Step 1: try current-live first.
+  let result = verifyLicenseCore({
+    zkAppAddress: currentLive,
+    licenseHash,
+    records: liveRecords,
+    onChainRoot: currentLiveRoot,
+    currentSlot,
+    forkActivationSlot: input.currentLiveForkSlot,
+  });
+  if (!result.valid && result.reason === 'License state does not match on-chain root') {
+    // Local Merkle root diverged from on-chain — either the archive-sync loop
+    // hasn't caught up yet or (bug) the local mirror silently drifted. Log the
+    // trigger so operators can correlate a spike of these with either a lag
+    // window or a genuine drift regression.
+    console.log(`[lazy-bootstrap] triggered current-live=${currentLive.slice(0, 12)}… licenseHash=${licenseHash.slice(0, 12)}… reason=root-mismatch`);
+    await lazyBootstrap(currentLive);
+    liveRecords = await readRecords();
+    result = verifyLicenseCore({
+      zkAppAddress: currentLive,
+      licenseHash,
+      records: liveRecords,
+      onChainRoot: currentLiveRoot,
+      currentSlot,
+      forkActivationSlot: input.currentLiveForkSlot,
+    });
+  }
+  if (result.valid || result.reason !== 'License not found') {
+    return { result, resolvedAddress: currentLive, onChainRoot: currentLiveRoot, liveRecords };
+  }
+
+  // Step 2: walk retired addresses newest-first.
+  const retiredAddrs = (deployment.deploymentHistory ?? []).map(d => d.zkAppAddress).reverse();
+  for (const retired of retiredAddrs) {
+    let retiredAccount;
+    try {
+      const fetched = await fetchWithOneRetry(() => fetchAccount({ publicKey: PublicKey.fromBase58(retired) }));
+      retiredAccount = fetched.account;
+    } catch {
+      continue;
+    }
+    const retiredRoot = retiredAccount?.zkapp?.appState?.[0]?.toString();
+    if (!retiredRoot) continue;
+    const retiredForkSlot = Number(retiredAccount?.zkapp?.appState?.[LICENSING_APP_STATE.forkActivationSlot]?.toString() ?? '0');
+    let retiredResult = verifyLicenseCore({
+      zkAppAddress: retired,
+      licenseHash,
+      records: liveRecords,
+      onChainRoot: retiredRoot,
+      currentSlot,
+      forkActivationSlot: retiredForkSlot,
+    });
+    if (!retiredResult.valid && retiredResult.reason === 'License state does not match on-chain root') {
+      // Same trigger as the current-live path but on a retired generation —
+      // e.g. a pre-bump buyer's request address never got its full history
+      // replayed after the process restart.
+      console.log(`[lazy-bootstrap] triggered retired=${retired.slice(0, 12)}… licenseHash=${licenseHash.slice(0, 12)}… reason=root-mismatch`);
+      await lazyBootstrap(retired);
+      liveRecords = await readRecords();
+      retiredResult = verifyLicenseCore({
+        zkAppAddress: retired,
+        licenseHash,
+        records: liveRecords,
+        onChainRoot: retiredRoot,
+        currentSlot,
+        forkActivationSlot: retiredForkSlot,
+      });
+    }
+    if (retiredResult.valid || retiredResult.reason !== 'License not found') {
+      return { result: retiredResult, resolvedAddress: retired, onChainRoot: retiredRoot, liveRecords };
+    }
+  }
+
+  // Not found anywhere — return the current-live "License not found" verdict.
+  return { result, resolvedAddress: currentLive, onChainRoot: currentLiveRoot, liveRecords };
+}

package/src/zipToState.ts

@@ -0,0 +1,94 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * zipToState.ts
+ *
+ * US ZIP-code prefix → 2-letter state code lookup. Used by countryStats.ts to
+ * roll US buyers up into per-state buckets for sales-tax reporting. Prefix is
+ * the first three digits of the ZIP; every US ZIP starts with three digits
+ * that resolve to exactly one state (source: USPS ZIP Code Directory).
+ *
+ * Data model: inclusive [lo, hi] prefix ranges → state code. Ranges are
+ * ordered by lo for readability but the lookup does a linear scan since the
+ * table is small (~55 rows) and this runs once per record on a background
+ * aggregation, not in a hot loop.
+ *
+ * Coverage: 50 states, DC, military APO/FPO (AA/AE/AP), Puerto Rico (PR), Guam
+ * and adjacent Pacific territories (GU). US Virgin Islands (VI), American
+ * Samoa (AS), and Northern Mariana Islands (MP) share prefixes with the
+ * Pacific block; we return 'GU' for that range — good enough for
+ * digital-goods reporting where those territories don't have their own tax.
+ * Returns undefined for prefixes that don't map (very few — USPS reserves
+ * some for future assignment).
+ */
+
+const RANGES: ReadonlyArray<readonly [number, number, string]> = [
+  [  5,   5, 'NY'],
+  [  6,   9, 'PR'],
+  [ 10,  27, 'MA'],
+  [ 28,  29, 'RI'],
+  [ 30,  38, 'NH'],
+  [ 39,  49, 'ME'],
+  [ 50,  59, 'VT'],
+  [ 60,  69, 'CT'],
+  [ 70,  89, 'NJ'],
+  [ 90,  99, 'AE'],
+  [100, 149, 'NY'],
+  [150, 196, 'PA'],
+  [197, 199, 'DE'],
+  [200, 205, 'DC'],
+  [206, 219, 'MD'],
+  [220, 246, 'VA'],
+  [247, 268, 'WV'],
+  [270, 289, 'NC'],
+  [290, 299, 'SC'],
+  [300, 319, 'GA'],
+  [320, 349, 'FL'],
+  [350, 369, 'AL'],
+  [370, 385, 'TN'],
+  [386, 397, 'MS'],
+  [398, 399, 'GA'],
+  [400, 427, 'KY'],
+  [430, 459, 'OH'],
+  [460, 479, 'IN'],
+  [480, 499, 'MI'],
+  [500, 528, 'IA'],
+  [530, 549, 'WI'],
+  [550, 567, 'MN'],
+  [570, 577, 'SD'],
+  [580, 588, 'ND'],
+  [590, 599, 'MT'],
+  [600, 629, 'IL'],
+  [630, 658, 'MO'],
+  [660, 679, 'KS'],
+  [680, 693, 'NE'],
+  [700, 714, 'LA'],
+  [716, 729, 'AR'],
+  [730, 749, 'OK'],
+  [750, 799, 'TX'],
+  [800, 816, 'CO'],
+  [820, 831, 'WY'],
+  [832, 838, 'ID'],
+  [840, 847, 'UT'],
+  [850, 865, 'AZ'],
+  [870, 884, 'NM'],
+  [889, 898, 'NV'],
+  [900, 961, 'CA'],
+  [962, 966, 'AP'],
+  [967, 968, 'HI'],
+  [969, 969, 'GU'],
+  [970, 979, 'OR'],
+  [980, 994, 'WA'],
+  [995, 999, 'AK'],
+];
+
+export function zipToState(zip: string): string | undefined {
+  const m = /^(\d{3})/.exec(zip);
+  if (!m) return undefined;
+  const n = parseInt(m[1], 10);
+  for (const [lo, hi, st] of RANGES) {
+    if (n >= lo && n <= hi) return st;
+  }
+  return undefined;
+}

package/build/licenseProof.d.ts

@@ -1,26 +0,0 @@
-// Hand-written declarations for licenseProof.ts.
-// tsc can't emit these automatically because the inferred return types of
-// Struct() and ZkProgram() reference internal o1js paths outside this
-// package's rootDir, triggering TS2742. Callers get full typing on the
-// methods they actually invoke by importing the corresponding o1js types
-// directly (Field, Proof, etc.) in their own code.
-
-export const OwnershipChallenge: any;
-export type OwnershipChallenge = any;
-
-export const LicenseProof: any;
-
-export class LicenseProofProof {
-  static publicInputType: any;
-  static publicOutputType: any;
-  static fromJSON(json: any): Promise<LicenseProofProof>;
-  static dummy(...args: any[]): Promise<LicenseProofProof>;
-  publicInput: any;
-  publicOutput: any;
-  proof: any;
-  maxProofsVerified: 0 | 1 | 2;
-  shouldVerify: any;
-  verify(): void;
-  verifyIf(condition: any): void;
-  toJSON(): { publicInput: string[]; publicOutput: string[]; maxProofsVerified: 0 | 1 | 2; proof: string };
-}

package/build/licenseProof.js

@@ -1,41 +0,0 @@
-// Copyright (c) 2025-2026 zkLicensing project developers
-// All rights reserved.
-/**
- * licenseProof.ts — ZkProgram for ownership challenge-response.
- *
- * Loaded only when the caller needs to *produce* an ownership proof on the
- * client (the verify path never imports this file). Lives in a dedicated
- * subpath (`zklicensing/prove`) so the verify-only entry stays free of o1js.
- *
- * Proves: Poseidon.hash([secretHash]) === licenseHash
- * where  secretHash = Poseidon.hash(Encoding.stringToFields(rawSecret)).
- *
- * The nonce sits in the public input. Its sole purpose is replay-resistance:
- * a proof generated for nonce A is mathematically distinct from one for nonce
- * B, so a verifier that issued nonce A will reject any proof not produced for
- * exactly that challenge.
- */
-import { ZkProgram, Field, Poseidon, Struct } from 'o1js';
-// Struct() / ZkProgram / ZkProgram.Proof() return types reference o1js
-// internal paths outside this package's rootDir, triggering TS2742 on
-// declaration emit. Annotating each export as `any` suppresses the inference;
-// consumers get real types via the hand-written licenseProof.d.ts shim.
-// See contractInterface.ts for the longer rationale on why this workaround.
-export const OwnershipChallenge = Struct({
-    licenseHash: Field,
-    nonce: Field,
-});
-export const LicenseProof = ZkProgram({
-    name: 'license-proof',
-    publicInput: OwnershipChallenge,
-    methods: {
-        prove: {
-            privateInputs: [Field], // secretHash — never sent anywhere
-            async method(pub, secretHash) {
-                Poseidon.hash([secretHash]).assertEquals(pub.licenseHash);
-            },
-        },
-    },
-});
-export const LicenseProofProof = ZkProgram.Proof(LicenseProof);
-//# sourceMappingURL=licenseProof.js.map

package/build/migrateClient.d.ts

@@ -1,43 +0,0 @@
-/**
- * migrateClient.ts
- *
- * Browser-safe client for /prove/migrate. Assembles a single-hop cross-
- * generation proof against the current live map — the keeper walks the
- * deploymentHistory once, gathers all three witnesses (ancestor / pred /
- * live-empty), and returns a signable tx.
- *
- * Failure surfaces:
- *   - 404 "license refunded or unknown": no leaf anywhere in history for
- *     this licenseHash. Caller should not retry — it's terminal.
- *   - 409 "already migrated": leaf is present in the live map. Caller
- *     should refresh their license record and stop.
- *   - 409 "migration in flight": another caller is proving right now.
- *     `retryAfterMs` on the error tells the caller how long to wait
- *     before trying again. See `ProveMigrateError.retryAfterMs`.
- */
-export interface ProveMigrateRequest {
-    keeperUrl: string;
-    licenseHash: string;
-    appId: string;
-    buyerAddress: string;
-    fetcher?: typeof fetch;
-    signal?: AbortSignal;
-}
-export interface ProveMigrateResponse {
-    provenTxJson: string;
-    ancestorGen: number;
-    expirySlot: number;
-    licenseHash: string;
-    zkAppAddress: string;
-}
-/**
- * Extends Error with the retryAfterMs hint the keeper returns on the
- * "migration in flight" 409. Callers ignore it for other 4xx surfaces.
- */
-export declare class ProveMigrateError extends Error {
-    readonly status: number;
-    readonly retryAfterMs?: number;
-    constructor(message: string, status: number, retryAfterMs?: number);
-}
-export declare function proveMigrate(req: ProveMigrateRequest): Promise<ProveMigrateResponse>;
-//# sourceMappingURL=migrateClient.d.ts.map

package/build/migrateClient.js

@@ -1,47 +0,0 @@
-// Copyright (c) 2025-2026 zkLicensing project developers
-// All rights reserved.
-/**
- * Extends Error with the retryAfterMs hint the keeper returns on the
- * "migration in flight" 409. Callers ignore it for other 4xx surfaces.
- */
-export class ProveMigrateError extends Error {
-    status;
-    retryAfterMs;
-    constructor(message, status, retryAfterMs) {
-        super(message);
-        this.name = 'ProveMigrateError';
-        this.status = status;
-        this.retryAfterMs = retryAfterMs;
-    }
-}
-function baseUrl(url) {
-    return url.replace(/\/+$/, '');
-}
-export async function proveMigrate(req) {
-    const fetcher = req.fetcher ?? fetch;
-    const resp = await fetcher(`${baseUrl(req.keeperUrl)}/prove/migrate`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        signal: req.signal,
-        body: JSON.stringify({
-            licenseHash: req.licenseHash,
-            appId: req.appId,
-            buyerAddress: req.buyerAddress,
-        }),
-    });
-    if (!resp.ok) {
-        let msg = `HTTP ${resp.status}`;
-        let retryAfterMs;
-        try {
-            const body = await resp.json();
-            if (typeof body.error === 'string')
-                msg = body.error;
-            if (typeof body.retryAfterMs === 'number')
-                retryAfterMs = body.retryAfterMs;
-        }
-        catch { /* body wasn't JSON */ }
-        throw new ProveMigrateError(msg, resp.status, retryAfterMs);
-    }
-    return await resp.json();
-}
-//# sourceMappingURL=migrateClient.js.map

package/build/ownership.d.ts

@@ -1,34 +0,0 @@
-export declare const OWNERSHIP_CHALLENGE_TTL_MS = 600000;
-export declare const OWNERSHIP_TOKEN_TTL_MS: number;
-export type OwnershipTokenPayload = {
-    z: string;
-    l: string;
-    e: number;
-    jti?: string;
-};
-export declare function newJti(): string;
-export type ChallengeStore = {
-    issue(licenseHash: string): {
-        nonce: string;
-        ttl: number;
-    };
-    consume(licenseHash: string, nonce: string): 'ok' | 'unknown' | 'expired';
-    size(): number;
-};
-export declare function createChallengeStore(ttlMs?: number): ChallengeStore;
-export declare function signOwnershipToken(key: Buffer, payload: OwnershipTokenPayload): string;
-export declare function verifyOwnershipToken(key: Buffer, token: string): OwnershipTokenPayload | null;
-export declare function newOwnershipKey(): Buffer;
-export type SessionStore = {
-    insert(licenseHash: string, jti: string, exp: number, cap: number): {
-        state: 'ok' | 'at-cap';
-        active: number;
-    };
-    has(licenseHash: string, jti: string): boolean;
-    releaseSeat(licenseHash: string, jti: string): boolean;
-    reset(licenseHash: string): number;
-    activeCount(licenseHash: string): number;
-    size(): number;
-};
-export declare function createSessionStore(): SessionStore;
-//# sourceMappingURL=ownership.d.ts.map

package/build/ownership.js

@@ -1,147 +0,0 @@
-// Copyright (c) 2025-2026 zkLicensing project developers
-// All rights reserved.
-/**
- * ownership.ts
- *
- * Ownership-token helpers and a small in-memory nonce store for the
- * challenge-response /verify flow.
- *
- * Replay-resistance: the LicenseProof's public input binds (licenseHash,
- * nonce). The keeper hands out a nonce, the client proves against it, the
- * keeper consumes the nonce on the way through. Tokens are HMAC-SHA256 of
- * the (zkAppAddress, licenseHash, exp, jti?) tuple so signature validation
- * is purely cryptographic — no server-side lookup, restart-safe as long as
- * the HMAC key persists.
- *
- * Session tracking: the optional `jti` field lets the caller run a
- * revocation / concurrency layer on top of the stateless HMAC — the token
- * is still validated cryptographically, but the caller can also check that
- * the jti is present in a per-license active-session set. Absent jti keeps
- * old callers working unchanged (there is no session tracking to begin with,
- * so nothing needs to migrate).
- */
-import { createHmac, randomBytes, timingSafeEqual } from 'crypto';
-import { Field } from 'o1js';
-export const OWNERSHIP_CHALLENGE_TTL_MS = 600_000;
-// A device that stays active refreshes via a fresh /challenge + /respond;
-// a lost/uninstalled device burns its slot for at most this long before
-// the server prunes it (see verifyService session store). 7 days keeps
-// re-prove pressure low on daily-use apps while still bounding the recovery
-// window for owners hitting the concurrent-device cap.
-export const OWNERSHIP_TOKEN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
-// Generate a 128-bit random jti. base64url so it drops into token payloads
-// and query strings without escaping.
-export function newJti() {
-    return randomBytes(16).toString('base64url');
-}
-export function createChallengeStore(ttlMs = OWNERSHIP_CHALLENGE_TTL_MS) {
-    const issued = new Map(); // `${lh}:${nonce}` → expiresAt
-    return {
-        issue(licenseHash) {
-            const nonce = Field.random().toString();
-            issued.set(`${licenseHash}:${nonce}`, Date.now() + ttlMs);
-            return { nonce, ttl: ttlMs };
-        },
-        consume(licenseHash, nonce) {
-            const key = `${licenseHash}:${nonce}`;
-            const expiresAt = issued.get(key);
-            if (expiresAt === undefined)
-                return 'unknown';
-            issued.delete(key);
-            if (Date.now() > expiresAt)
-                return 'expired';
-            return 'ok';
-        },
-        size: () => issued.size,
-    };
-}
-// --- token signing -----------------------------------------------------------
-export function signOwnershipToken(key, payload) {
-    const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
-    const mac = createHmac('sha256', key).update(body).digest('base64url');
-    return `${body}.${mac}`;
-}
-export function verifyOwnershipToken(key, token) {
-    const dot = token.indexOf('.');
-    if (dot < 0)
-        return null;
-    const body = token.slice(0, dot);
-    const mac = token.slice(dot + 1);
-    const expected = createHmac('sha256', key).update(body).digest('base64url');
-    const a = Buffer.from(mac);
-    const b = Buffer.from(expected);
-    if (a.length !== b.length || !timingSafeEqual(a, b))
-        return null;
-    try {
-        const payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
-        if (Date.now() > payload.e)
-            return null;
-        return payload;
-    }
-    catch {
-        return null;
-    }
-}
-export function newOwnershipKey() {
-    return randomBytes(32);
-}
-export function createSessionStore() {
-    // licenseHash → jti → expiresAt
-    const sessions = new Map();
-    const pruneLicense = (licenseHash) => {
-        const perLic = sessions.get(licenseHash);
-        if (!perLic)
-            return undefined;
-        const now = Date.now();
-        for (const [jti, exp] of perLic)
-            if (exp <= now)
-                perLic.delete(jti);
-        if (perLic.size === 0) {
-            sessions.delete(licenseHash);
-            return undefined;
-        }
-        return perLic;
-    };
-    return {
-        insert(licenseHash, jti, exp, cap) {
-            const perLic = pruneLicense(licenseHash) ?? new Map();
-            if (cap > 0 && perLic.size >= cap && !perLic.has(jti)) {
-                return { state: 'at-cap', active: perLic.size };
-            }
-            perLic.set(jti, exp);
-            sessions.set(licenseHash, perLic);
-            return { state: 'ok', active: perLic.size };
-        },
-        has(licenseHash, jti) {
-            const perLic = pruneLicense(licenseHash);
-            return perLic?.has(jti) ?? false;
-        },
-        releaseSeat(licenseHash, jti) {
-            const perLic = sessions.get(licenseHash);
-            if (!perLic)
-                return false;
-            const had = perLic.delete(jti);
-            if (perLic.size === 0)
-                sessions.delete(licenseHash);
-            return had;
-        },
-        reset(licenseHash) {
-            const perLic = sessions.get(licenseHash);
-            if (!perLic)
-                return 0;
-            const n = perLic.size;
-            sessions.delete(licenseHash);
-            return n;
-        },
-        activeCount(licenseHash) {
-            return pruneLicense(licenseHash)?.size ?? 0;
-        },
-        size() {
-            let n = 0;
-            for (const perLic of sessions.values())
-                n += perLic.size;
-            return n;
-        },
-    };
-}
-//# sourceMappingURL=ownership.js.map