zklicensing 0.1.0-beta.0

package/build/licenseRecord.d.ts

@@ -0,0 +1,39 @@
+/**
+ * licenseRecord.ts
+ *
+ * The `LicenseRecord` shape and related pure types/constants. Split out from
+ * licenseStore.ts (which pulls in Node `fs`) so browser-side modules — the
+ * buy client, the stats client, the country-stats computation — can consume
+ * the same type without dragging in filesystem code. licenseStore.ts
+ * re-exports these to keep existing Node imports working.
+ */
+export type LicenseRecord = {
+    zkAppAddress: string;
+    licenseHash: string;
+    expirySlot: number;
+    purchaseSlot: number;
+    purchaseAmount: string;
+    txHash: string;
+    createdAt: string;
+    buyerAddress?: string;
+    buyerCountry?: string;
+    pending?: boolean;
+    provedAtSlot?: number;
+    initialExpirySlot?: number;
+    tier?: 'monthly' | 'yearly' | 'fiveYear';
+    renewedAtLeastOnce?: boolean;
+    refunded?: boolean;
+    released?: boolean;
+    releaseSlot?: number;
+    renewals?: Array<{
+        slot: number;
+        amount: string;
+        newExpiry: number;
+        txHash?: string;
+    }>;
+    refundWaiverAcceptedAt?: string;
+    escrowless?: boolean;
+};
+export declare const PENDING_REAP_SLOTS = 60;
+export type LicenseStatus = 'active' | 'refunded' | 'expired' | 'unknown';
+//# sourceMappingURL=licenseRecord.d.ts.map

package/build/licenseRecord.js

@@ -0,0 +1,6 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// All rights reserved.
+// Reap pending records this many slots after prove time if no event ever lands.
+// 60 slots ≈ 90 minutes — a generous window for tx inclusion under devnet conditions.
+export const PENDING_REAP_SLOTS = 60;
+//# sourceMappingURL=licenseRecord.js.map

package/build/licenseStore.d.ts

@@ -0,0 +1,49 @@
+import { MerkleMap, MerkleMapWitness } from 'o1js';
+import { type LicenseRecord as _LicenseRecord, type LicenseStatus as _LicenseStatus } from './licenseRecord.js';
+export type LicenseRecord = _LicenseRecord;
+export type LicenseStatus = _LicenseStatus;
+export declare const PENDING_REAP_SLOTS = 60;
+export declare function licenseStorePath(): string;
+export declare function readRecords(): Promise<LicenseRecord[]>;
+export declare function buildMap(records: LicenseRecord[], zkAppAddress: string): MerkleMap;
+export declare function buildEscrowMap(records: LicenseRecord[], zkAppAddress: string): MerkleMap;
+export declare function serializeWitness(witness: MerkleMapWitness): {
+    isLefts: boolean[];
+    siblings: string[];
+};
+export declare function deserializeWitness(json: {
+    isLefts: boolean[];
+    siblings: string[];
+}): MerkleMapWitness;
+export declare function getWitness(zkAppAddress: string, licenseHash: string): Promise<{
+    root: string;
+    currentValue: string;
+    witness: MerkleMapWitness;
+    serialized: ReturnType<typeof serializeWitness>;
+}>;
+export declare function getLicense(zkAppAddress: string, licenseHash: string): Promise<LicenseRecord | null>;
+export declare function licenseStatus(record: LicenseRecord | null, currentSlot: number): LicenseStatus;
+export declare function upsertLicense(record: LicenseRecord): Promise<void>;
+export declare function updateExpiry(zkAppAddress: string, licenseHash: string, expirySlot: number, opts?: {
+    markRenewed?: boolean;
+    renewal?: {
+        slot: number;
+        amount: string;
+        newExpiry: number;
+        txHash?: string;
+    };
+}): Promise<boolean>;
+export declare function recordRefund(zkAppAddress: string, licenseHash: string): Promise<boolean>;
+export declare function recordRelease(zkAppAddress: string, licenseHash: string, releaseSlot?: number): Promise<boolean>;
+export declare function confirmRecord(zkAppAddress: string, licenseHash: string): Promise<boolean>;
+export declare function applyLicenseIssued(zkAppAddress: string, licenseHash: string, fields: {
+    expirySlot: number;
+    purchaseSlot: number;
+    purchaseAmount: string;
+    tier?: 'monthly' | 'yearly' | 'fiveYear';
+    escrowless?: boolean;
+}): Promise<void>;
+export declare function deleteRecord(zkAppAddress: string, licenseHash: string): Promise<boolean>;
+export declare function getStalePendingRecords(currentSlot: number, maxAgeSlots?: number): Promise<LicenseRecord[]>;
+export declare function getReleasableRecords(currentSlot: number): Promise<LicenseRecord[]>;
+//# sourceMappingURL=licenseStore.d.ts.map

package/build/licenseStore.js

@@ -0,0 +1,303 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// All rights reserved.
+/**
+ * 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 } from './licenseRecord.js';
+export const PENDING_REAP_SLOTS = _PENDING_REAP_SLOTS;
+export function licenseStorePath() {
+    return process.env.LICENSE_STORE_PATH ?? 'licenses.json';
+}
+export async function readRecords() {
+    let raw;
+    try {
+        raw = JSON.parse(await fs.readFile(licenseStorePath(), 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(raw))
+        return [];
+    const records = raw;
+    // 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) {
+    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.resolve();
+function withWriteLock(fn) {
+    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, zkAppAddress) {
+    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, zkAppAddress) {
+    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, zkAppAddress) {
+    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) {
+    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) {
+    return new MerkleMapWitness(json.isLefts.map((b) => Bool(b)), json.siblings.map((s) => Field(s)));
+}
+// Returns the witness for a licenseHash key in the given zkApp's map.
+export async function getWitness(zkAppAddress, licenseHash) {
+    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, licenseHash) {
+    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, currentSlot) {
+    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) {
+    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, licenseHash, expirySlot, opts = {}) {
+    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, licenseHash) {
+    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, licenseHash, releaseSlot) {
+    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;
+        await writeRecords(records);
+        return true;
+    });
+}
+// Clear the pending flag on a record after a chain event confirms it landed.
+export async function confirmRecord(zkAppAddress, licenseHash) {
+    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, licenseHash, fields) {
+    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, licenseHash) {
+    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, maxAgeSlots = PENDING_REAP_SLOTS) {
+    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) {
+    const records = await readRecords();
+    return records.filter((r) => !r.released &&
+        !r.refunded &&
+        r.purchaseSlot > 0 &&
+        r.zkAppAddress &&
+        currentSlot > r.purchaseSlot + REFUND_WINDOW_N);
+}
+//# sourceMappingURL=licenseStore.js.map

package/build/manifestVerify.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ */
+export declare function canonicalize(value: unknown): string;
+/**
+ * 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 declare function verifyManifestSignature(payload: unknown, signatureBase64: string, pinnedPublicKeysBase64: readonly string[]): Promise<boolean>;
+//# sourceMappingURL=manifestVerify.d.ts.map

package/build/manifestVerify.js

@@ -0,0 +1,95 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// All rights reserved.
+/**
+ * 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) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(canonicalize).join(',') + ']';
+    const keys = Object.keys(value).sort();
+    return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalize(value[k])).join(',') + '}';
+}
+function base64ToBytes(b64) {
+    // 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) {
+    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) {
+    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, signatureBase64, pinnedPublicKeysBase64) {
+    if (!pinnedPublicKeysBase64.length)
+        return false;
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle)
+        return false;
+    const messageBytes = utf8Bytes(canonicalize(payload));
+    let signatureBytes;
+    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, { name: 'Ed25519' }, false, ['verify']);
+            const ok = await subtle.verify({ name: 'Ed25519' }, key, signatureBytes, messageBytes);
+            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;
+}
+//# sourceMappingURL=manifestVerify.js.map

package/build/migrateClient.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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

@@ -0,0 +1,47 @@
+// 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

@@ -0,0 +1,34 @@
+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