zklicensing 0.1.0-beta.2 → 0.1.0-beta.3

package/src/licenseStore.ts

@@ -0,0 +1,358 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * licenseStore.ts
+ *
+ * Off-chain MerkleMap state for the licensing system.
+ *
+ * Records are keyed by (zkAppAddress, licenseHash). Each LicensingApp deploys
+ * its own on-chain MerkleMap, so a passphrase used on two different apps
+ * produces the same `licenseHash` but two distinct records. Lookups that omit
+ * `zkAppAddress` would collide across apps — every API here takes it.
+ *
+ * Used by:
+ *   - interact.ts / buyLicense.ts (CLI) — reads/writes directly
+ *   - keeperService.ts              — exposes the same logic over HTTP
+ *   - proofServer.ts                — reads expirySlot for a given licenseHash
+ */
+
+import fs from 'fs/promises';
+import { Bool, Field, MerkleMap, MerkleMapWitness, Poseidon, PublicKey, UInt32, UInt64 } from 'o1js';
+import { GRACE_PERIOD_N, REFUND_WINDOW_N } from './contractInterface.js';
+import { PENDING_REAP_SLOTS as _PENDING_REAP_SLOTS, type LicenseRecord as _LicenseRecord, type LicenseStatus as _LicenseStatus } from './licenseRecord.js';
+
+// The record shape and pure types now live in licenseRecord.ts so browser
+// modules (buyClient, statsClient, countryStats) can consume them without
+// importing Node's `fs`. Re-exported here so existing Node imports of
+// `zklicensing/internal/licenseStore` continue to resolve.
+export type LicenseRecord = _LicenseRecord;
+export type LicenseStatus = _LicenseStatus;
+export const PENDING_REAP_SLOTS = _PENDING_REAP_SLOTS;
+
+export function licenseStorePath(): string {
+  return process.env.LICENSE_STORE_PATH ?? 'licenses.json';
+}
+
+export async function readRecords(): Promise<LicenseRecord[]> {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(await fs.readFile(licenseStorePath(), 'utf8'));
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(raw)) return [];
+  const records = raw as LicenseRecord[];
+  // Records pre-dating composite keying lack `zkAppAddress` and cannot be
+  // safely matched against any specific zkApp. Drop them with a warning so
+  // bootstrap rebuilds them fresh from on-chain events.
+  const filtered = records.filter(r => typeof r.zkAppAddress === 'string' && r.zkAppAddress.length > 0);
+  if (filtered.length < records.length) {
+    console.warn(`[licenseStore] dropped ${records.length - filtered.length} record(s) missing zkAppAddress — re-bootstrap to recover`);
+  }
+  return filtered;
+}
+
+async function writeRecords(records: LicenseRecord[]): Promise<void> {
+  await fs.writeFile(licenseStorePath(), JSON.stringify(records, null, 2));
+}
+
+// Serialize all read-modify-write operations against licenses.json. Each
+// mutating function does (readRecords → mutate → writeRecords); without a lock,
+// two concurrent calls can interleave such that the second one's read predates
+// the first one's write, and the second one's write then clobbers the first.
+// This was visible during archive sync (applyEventsToStore fires many writes
+// back-to-back) racing with /confirm/* writes from buyer flows.
+let writeChain: Promise<void> = Promise.resolve();
+function withWriteLock<T>(fn: () => Promise<T>): Promise<T> {
+  const result = writeChain.then(fn, fn);
+  writeChain = result.then(() => {}, () => {});
+  return result;
+}
+
+// Records belonging to a specific zkApp. Each zkApp owns an independent
+// on-chain MerkleMap, so all map operations must filter first.
+function recordsForApp(records: LicenseRecord[], zkAppAddress: string): LicenseRecord[] {
+  return records.filter(r => r.zkAppAddress === zkAppAddress);
+}
+
+// Rebuild the license MerkleMap for a single zkApp. Only inserts entries
+// with expirySlot > 0.
+export function buildMap(records: LicenseRecord[], zkAppAddress: string): MerkleMap {
+  const map = new MerkleMap();
+  for (const r of recordsForApp(records, zkAppAddress)) {
+    if (r.expirySlot !== 0) {
+      map.set(Field(r.licenseHash), Field(r.expirySlot));
+    }
+  }
+  return map;
+}
+
+// Rebuild the escrow MerkleMap for a single zkApp:
+// licenseHash → escrowCommitment(amount, slot, buyerKey). Only includes
+// entries with live escrow (not released, not refunded) and a known buyer.
+export function buildEscrowMap(records: LicenseRecord[], zkAppAddress: string): MerkleMap {
+  const map = new MerkleMap();
+  for (const r of recordsForApp(records, zkAppAddress)) {
+    if (!r.released && !r.refunded && r.purchaseSlot > 0 && r.buyerAddress) {
+      const buyerKey = PublicKey.fromBase58(r.buyerAddress);
+      const commitment = Poseidon.hash([
+        UInt64.from(BigInt(r.purchaseAmount)).value,
+        UInt32.from(r.purchaseSlot).value,
+        buyerKey.x,
+        buyerKey.isOdd.toField(),
+      ]);
+      map.set(Field(r.licenseHash), commitment);
+    }
+  }
+  return map;
+}
+
+// Serialize a MerkleMapWitness to plain JSON (safe to send over HTTP).
+export function serializeWitness(witness: MerkleMapWitness): {
+  isLefts: boolean[];
+  siblings: string[];
+} {
+  return {
+    isLefts: witness.isLefts.map((b) => b.toBoolean()),
+    siblings: witness.siblings.map((f) => f.toString()),
+  };
+}
+
+// Reconstruct a MerkleMapWitness from serialized JSON.
+export function deserializeWitness(json: {
+  isLefts: boolean[];
+  siblings: string[];
+}): MerkleMapWitness {
+  return new MerkleMapWitness(
+    json.isLefts.map((b: boolean) => Bool(b)),
+    json.siblings.map((s: string) => Field(s))
+  );
+}
+
+// Returns the witness for a licenseHash key in the given zkApp's map.
+export async function getWitness(zkAppAddress: string, licenseHash: string): Promise<{
+  root: string;
+  currentValue: string;
+  witness: MerkleMapWitness;
+  serialized: ReturnType<typeof serializeWitness>;
+}> {
+  const records = await readRecords();
+  const map = buildMap(records, zkAppAddress);
+  const key = Field(licenseHash);
+  const witness = map.getWitness(key);
+  return {
+    root: map.getRoot().toString(),
+    currentValue: map.get(key).toString(),
+    witness,
+    serialized: serializeWitness(witness),
+  };
+}
+
+// Look up a single license record by its composite key.
+export async function getLicense(zkAppAddress: string, licenseHash: string): Promise<LicenseRecord | null> {
+  const records = await readRecords();
+  return records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash) ?? null;
+}
+
+// Determine the status of a license. A license in the 7-day grace window is
+// still considered 'active' so renewal is not urgently forced.
+export function licenseStatus(record: LicenseRecord | null, currentSlot: number): LicenseStatus {
+  if (!record) return 'unknown';
+  if (record.expirySlot === 0) return 'refunded';
+  if (record.expirySlot + GRACE_PERIOD_N < currentSlot) return 'expired';
+  return 'active';
+}
+
+// Add or update a license record (upsert by composite key).
+export async function upsertLicense(record: LicenseRecord): Promise<void> {
+  if (!record.zkAppAddress) {
+    throw new Error('upsertLicense: record.zkAppAddress is required');
+  }
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const idx = records.findIndex(r => r.zkAppAddress === record.zkAppAddress && r.licenseHash === record.licenseHash);
+    if (idx >= 0) {
+      records[idx] = record;
+    } else {
+      records.push(record);
+    }
+    await writeRecords(records);
+  });
+}
+
+// Update the expirySlot for an existing record (used by renew).
+// `opts.markRenewed` flips renewedAtLeastOnce so stats can detect first-renewal
+// without re-walking events. `opts.renewal` appends to the renewals[] log so
+// stats can compute renewal revenue from the store alone.
+export async function updateExpiry(
+  zkAppAddress: string,
+  licenseHash: string,
+  expirySlot: number,
+  opts: { markRenewed?: boolean; renewal?: { slot: number; amount: string; newExpiry: number; txHash?: string } } = {},
+): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (!record) return false;
+    record.expirySlot = expirySlot;
+    if (opts.markRenewed) record.renewedAtLeastOnce = true;
+    if (opts.renewal) {
+      const renewals = (record.renewals ??= []);
+      // Dedup by newExpiry — confirm-time and event-sync may both try to log
+      // the same renewal, but each renewal advances expiry by a unique tier
+      // amount, so newExpiry is a stable identifier.
+      if (!renewals.some(r => r.newExpiry === opts.renewal!.newExpiry)) {
+        renewals.push(opts.renewal);
+      }
+    }
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// Clear license and escrow data after a confirmed refund. Also flips `refunded`.
+export async function recordRefund(zkAppAddress: string, licenseHash: string): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (!record) return false;
+    record.expirySlot = 0;
+    record.purchaseSlot = 0;
+    record.purchaseAmount = '0';
+    record.refunded = true;
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// Mark escrow as released. Preserves purchaseAmount/purchaseSlot so stats can
+// compute released revenue. The `released` flag is the truth signal —
+// buildEscrowMap and getReleasableRecords filter on it directly.
+export async function recordRelease(
+  zkAppAddress: string,
+  licenseHash: string,
+  releaseSlot?: number,
+  txHash?: string,
+): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (!record) return false;
+    record.released = true;
+    if (releaseSlot !== undefined) record.releaseSlot = releaseSlot;
+    if (txHash !== undefined) record.releaseTxHash = txHash;
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// Clear the pending flag on a record after a chain event confirms it landed.
+export async function confirmRecord(zkAppAddress: string, licenseHash: string): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (!record) return false;
+    if (!record.pending) return false;
+    delete record.pending;
+    delete record.provedAtSlot;
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// Apply a licenseIssued event atomically: confirm any pending /confirm/buy
+// write, backfill initialExpirySlot/tier if missing, or create a fresh record.
+// Doing the whole read-decide-write inside a single lock acquisition avoids the
+// stale-snapshot hazard that would arise if archiveBootstrap called
+// getLicense + confirmRecord + upsertLicense as three separate locked steps —
+// a concurrent write between them could be clobbered by the upsert's
+// pre-confirm snapshot.
+export async function applyLicenseIssued(
+  zkAppAddress: string,
+  licenseHash: string,
+  fields: {
+    expirySlot: number;
+    purchaseSlot: number;
+    purchaseAmount: string;
+    tier?: 'monthly' | 'yearly' | 'fiveYear';
+    // True for licenses minted through buyLicenseNoEscrow: funds went straight
+    // to vendor + platform, no escrow entry. Refund CTA must be suppressed.
+    escrowless?: boolean;
+  },
+): Promise<void> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    let dirty = false;
+    if (record) {
+      if (record.pending) {
+        delete record.pending;
+        delete record.provedAtSlot;
+        dirty = true;
+      }
+      if (record.initialExpirySlot === undefined) {
+        record.initialExpirySlot = fields.expirySlot;
+        dirty = true;
+      }
+      if (!record.tier && fields.tier) {
+        record.tier = fields.tier;
+        dirty = true;
+      }
+      if (fields.escrowless === true && record.escrowless !== true) {
+        record.escrowless = true;
+        dirty = true;
+      }
+    } else {
+      records.push({
+        zkAppAddress,
+        licenseHash,
+        expirySlot:        fields.expirySlot,
+        purchaseSlot:      fields.purchaseSlot,
+        purchaseAmount:    fields.purchaseAmount,
+        txHash:            '',
+        createdAt:         new Date().toISOString(),
+        initialExpirySlot: fields.expirySlot,
+        ...(fields.tier ? { tier: fields.tier } : {}),
+        ...(fields.escrowless === true ? { escrowless: true } : {}),
+      });
+      dirty = true;
+    }
+    if (dirty) await writeRecords(records);
+  });
+}
+
+// Delete a record entirely (used to reap stale pending entries the buyer never submitted).
+export async function deleteRecord(zkAppAddress: string, licenseHash: string): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const idx = records.findIndex(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (idx < 0) return false;
+    records.splice(idx, 1);
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// List pending records whose prove slot is older than `currentSlot - maxAgeSlots`.
+// Used by the reaper to drop records the buyer never actually signed/submitted.
+export async function getStalePendingRecords(currentSlot: number, maxAgeSlots = PENDING_REAP_SLOTS): Promise<LicenseRecord[]> {
+  const records = await readRecords();
+  return records.filter(
+    (r) => r.pending && typeof r.provedAtSlot === 'number' && currentSlot - r.provedAtSlot > maxAgeSlots,
+  );
+}
+
+// Return all records where the refund window has passed and escrow is still live.
+// Filters on the released/refunded flags so we don't re-release or release after refund.
+export async function getReleasableRecords(currentSlot: number): Promise<LicenseRecord[]> {
+  const records = await readRecords();
+  return records.filter(
+    (r) =>
+      !r.released &&
+      !r.refunded &&
+      r.purchaseSlot > 0 &&
+      r.zkAppAddress &&
+      currentSlot > r.purchaseSlot + REFUND_WINDOW_N,
+  );
+}

package/src/manifestVerify.ts

@@ -0,0 +1,106 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * manifestVerify.ts
+ *
+ * Browser + Node Ed25519 signature verification for platform-signed manifests
+ * (currently: the generation-list served at GET /apps/:appId, next: the
+ * sales-freeze manifest). The keeper signs with the platform manifest key
+ * loaded via PLATFORM_MANIFEST_KEY_FILE; the SDK pins the public key against
+ * a caller-supplied allow-list and verifies before trusting anything.
+ *
+ * Runtime: browsers and Node ≥ 20 expose `globalThis.crypto.subtle`. The
+ * SDK's `engines.node` is `>=20` for this reason — Node 18 child workers
+ * (spawned by `node --test`) do not populate `globalThis.crypto`.
+ *
+ * Canonicalization must match `src/manifestSign.ts` byte-for-byte:
+ *   - sorted object keys
+ *   - no whitespace
+ *   - arrays preserved in order
+ * Any divergence silently breaks verification, so keep the algorithm dead
+ * simple and mirrored.
+ */
+
+// Canonical JSON: sorted keys, no whitespace, arrays preserved in order.
+// Mirror of src/manifestSign.ts:canonicalize. Divergence here silently
+// breaks verification.
+export function canonicalize(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(canonicalize).join(',') + ']';
+  const keys = Object.keys(value as Record<string, unknown>).sort();
+  return '{' + keys.map(k =>
+    JSON.stringify(k) + ':' + canonicalize((value as Record<string, unknown>)[k])
+  ).join(',') + '}';
+}
+
+function base64ToBytes(b64: string): Uint8Array {
+  // atob is present in every modern JS runtime we target (browser + Node ≥ 16).
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function utf8Bytes(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+// SPKI DER wrapper around a raw 32-byte Ed25519 public key.
+// Same prefix used by src/manifestSign.ts:verifyPayload — WebCrypto needs
+// SPKI to import; the wire format is raw base64 for space.
+const ED25519_SPKI_PREFIX = new Uint8Array([
+  0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x03, 0x21, 0x00,
+]);
+
+function rawEd25519ToSpki(raw: Uint8Array): Uint8Array {
+  if (raw.length !== 32) throw new Error(`Ed25519 pubkey must be 32 bytes, got ${raw.length}`);
+  const out = new Uint8Array(ED25519_SPKI_PREFIX.length + raw.length);
+  out.set(ED25519_SPKI_PREFIX, 0);
+  out.set(raw, ED25519_SPKI_PREFIX.length);
+  return out;
+}
+
+/**
+ * Verify a base64 Ed25519 signature over a canonicalized payload against
+ * one of the pinned base64 public keys. Returns true iff at least one
+ * pinned key verifies. Fails closed on any error (unknown key format,
+ * WebCrypto rejection, missing subtle) — callers must interpret `false`
+ * as "do not trust."
+ */
+export async function verifyManifestSignature(
+  payload: unknown,
+  signatureBase64: string,
+  pinnedPublicKeysBase64: readonly string[],
+): Promise<boolean> {
+  if (!pinnedPublicKeysBase64.length) return false;
+  const subtle = (globalThis.crypto as Crypto | undefined)?.subtle;
+  if (!subtle) return false;
+  const messageBytes = utf8Bytes(canonicalize(payload));
+  let signatureBytes: Uint8Array;
+  try { signatureBytes = base64ToBytes(signatureBase64); }
+  catch { return false; }
+  for (const pinB64 of pinnedPublicKeysBase64) {
+    try {
+      const spki = rawEd25519ToSpki(base64ToBytes(pinB64));
+      const key = await subtle.importKey(
+        'spki',
+        spki as unknown as ArrayBuffer,
+        { name: 'Ed25519' },
+        false,
+        ['verify'],
+      );
+      const ok = await subtle.verify(
+        { name: 'Ed25519' },
+        key,
+        signatureBytes as unknown as ArrayBuffer,
+        messageBytes as unknown as ArrayBuffer,
+      );
+      if (ok) return true;
+    } catch {
+      // Try the next pin — one bad entry in the pin list must not mask
+      // a valid signature under a different pin.
+    }
+  }
+  return false;
+}

package/src/migrateClient.ts

@@ -0,0 +1,82 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * 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 "proving queue busy": another root-mutating request (buy, renew,
+ *     migrate) is holding this app's in-flight slot. Thrown as the shared
+ *     ProveQueueBusyError so callers can wait+retry uniformly across the
+ *     three endpoints.
+ */
+
+import { readErrorBody, tryQueueBusyFromBody } from './proveErrors.js';
+
+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;
+  // Key the keeper stored the per-app in-flight slot under. Passed back to
+  // POST /tx-broadcast after the wallet returns a hash. See ProveBuyResponse.
+  appKey:       string;
+}
+
+/**
+ * Terminal migrate failures (404 refunded/unknown, 409 already migrated).
+ * The queue-busy 409 is surfaced separately as ProveQueueBusyError so
+ * callers can share one retry helper across buy/renew/migrate.
+ */
+export class ProveMigrateError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = 'ProveMigrateError';
+    this.status = status;
+  }
+}
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+export async function proveMigrate(req: ProveMigrateRequest): Promise<ProveMigrateResponse> {
+  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) {
+    const parsed = await readErrorBody(resp);
+    const queueBusy = tryQueueBusyFromBody(parsed);
+    if (queueBusy) throw queueBusy;
+    throw new ProveMigrateError(parsed.message, resp.status);
+  }
+  return await resp.json() as ProveMigrateResponse;
+}