zklicensing 0.1.0-beta.0

package/README.md

@@ -0,0 +1,603 @@
+# zklicensing
+
+Client SDK for verifying [zkLicensing](https://zklicensing.com) software licenses.
+
+`verifyLicense` calls the verifier's `GET /verify` endpoint during the on-chain refund window (~14 days), then writes a one-shot anchor to local storage and verifies fully offline from that point on. Works in browsers (via `localStorage`) and in Node (with an injected storage adapter). Zero runtime dependencies.
+
+## Install
+
+```bash
+npm install zklicensing
+```
+
+## Usage
+
+```ts
+import { verifyLicense } from 'zklicensing';
+
+// `proof` is the JSON the buyer downloaded after purchase
+const result = await verifyLicense({
+  licenseHash:    proof.licenseHash,
+  zkAppAddress:   proof.zkAppAddress,                    // your deployed zkApp address (B62q…)
+  expirySlot:     proof.expirySlot,
+  purchaseSlot:   proof.purchaseSlot,
+  verifierUrl:    'https://zklicensing.com/api/verify',  // hosted verify service
+});
+
+if (result.valid) {
+  unlockFeatures();
+}
+```
+
+`result.source` is `'chain'` while the SDK is still calling the verifier, and `'offline'` after the anchor has graduated.
+
+## How it works
+
+```
+purchase ─────► verifier (every call) ─────► anchor written ─────► offline only
+   │                                    │
+   │◄── ~14 days, refund window ───────►│
+```
+
+For the first ~14 days the licence can still be refunded on-chain, so the SDK calls the verifier on every check to catch refunds. Once the verifier itself reports the refund window has closed (`currentSlot > purchaseSlot + 13 440 slots`, ≈ 14 days at one slot every 90 s post-Mesa), the SDK writes an anchor into local storage and never touches the network again for that licence.
+
+> **Note:** "Offline" here refers to the validity/expiry check performed by `verifyLicense`. If the vendor set a concurrent-device cap (`maxConcurrentDevices > 0`) on their app, the *separate* activation-token flow (`/challenge` → `/respond` → session token) still round-trips the verifier on every session — that's stateful by design and cannot be anchored locally. Apps with `maxConcurrentDevices = 0` (unlimited, the default) are fully offline post-refund.
+
+The anchor stores `{ anchoredSlot, anchoredAtMs, expirySlot, ownership }`. In the offline branch the current slot is estimated as `anchoredSlot + (now − anchoredAtMs) / 90 000 ms`, and the same 7-day grace window (`6 720 slots`) is applied either side.
+
+A renewal advances the proof's `expirySlot`; that mismatch invalidates the anchor and the SDK falls back to one more verifier call before re-anchoring with the new expiry.
+
+### Clock-warp safety
+
+Only the verifier's reported `currentSlot` can graduate the anchor — a buyer who winds their local clock forward cannot force the offline branch prematurely.
+
+## API
+
+```ts
+type ProofInput = {
+  licenseHash:    string;   // Poseidon hash identifying the licence on-chain
+  zkAppAddress:   string;   // Your deployed zkApp's Mina address (B62q…)
+  expirySlot:     number;   // From the proof; invalidates stale anchors on renewal
+  purchaseSlot:   number;   // From the proof; decides when the refund window has closed
+  verifierUrl?:   string;
+};
+
+type VerifyOptions = {
+  verifierUrl?: string;
+  storage?:   Storage | null;   // default: globalThis.localStorage; null disables anchoring
+  fetcher?:   typeof fetch;     // default: globalThis.fetch
+  now?:       () => number;     // default: Date.now
+};
+
+type VerifyResult = {
+  valid:         boolean;
+  expirySlot:    number;
+  inGracePeriod: boolean;
+  reason:        string | null;
+  source:        'chain' | 'offline';
+};
+
+function verifyLicense(proof: ProofInput, options?: VerifyOptions): Promise<VerifyResult>;
+```
+
+The package also re-exports the three constants the SDK uses internally:
+
+```ts
+import { REFUND_WINDOW_N, GRACE_PERIOD_N, MS_PER_SLOT } from 'zklicensing';
+// 13_440, 6_720, 90_000
+```
+
+## Node storage adapter
+
+In the browser the SDK uses `localStorage` automatically. In Node, supply your own — otherwise the offline branch will never activate and every call will hit the verifier:
+
+```ts
+import fs from 'node:fs';
+import { verifyLicense } from 'zklicensing';
+
+const ANCHOR_FILE = '/var/lib/myapp/anchor.json';
+const storage = {
+  getItem: (k: string) => {
+    try { return JSON.parse(fs.readFileSync(ANCHOR_FILE, 'utf8'))[k] ?? null; }
+    catch { return null; }
+  },
+  setItem: (k: string, v: string) => {
+    const s = (() => { try { return JSON.parse(fs.readFileSync(ANCHOR_FILE, 'utf8')); } catch { return {}; } })();
+    s[k] = v;
+    fs.writeFileSync(ANCHOR_FILE, JSON.stringify(s));
+  },
+};
+
+await verifyLicense(proof, { storage });
+```
+
+Pass `storage: null` to disable the offline path entirely (every call hits the verifier).
+
+## Verifier response contract
+
+If you self-host the verification endpoint, it must return:
+
+```ts
+{
+  valid:         boolean,
+  expirySlot:    number,
+  inGracePeriod: boolean,
+  reason:        string | null,
+  currentSlot:   number,    // ← SDK reads this to decide when to anchor
+  purchaseSlot:  number,
+}
+```
+
+`currentSlot` and `purchaseSlot` are the keys to the anchor logic — they must be present for the offline branch to activate.
+
+For non-JavaScript clients (Android, iOS, Python, …) call the verifier's `GET /verify` directly and replicate the same anchor logic in idiomatic platform storage.
+
+## Platform examples
+
+Two variants matter per platform:
+
+- **Unlimited** — the vendor set `maxConcurrentDevices = 0`. Just call `GET /verify`; there is no ownership token.
+- **JTI-capped** — the vendor set `maxConcurrentDevices > 0`. Obtain a session token once via a small backend helper that runs `LicenseProof.compile()`, drives `POST /verify/challenge` + `/respond`, and returns the HMAC-JTI token to cache client-side (o1js can't run on-device). Pass `&token=` on every `GET /verify`. Renew silently against `POST /verify/refresh`; release the seat on logout with `POST /verify/releaseSeat`.
+
+### Android (Kotlin)
+
+```kotlin
+// Unlimited — no token
+val licenseHash = prefs.getString("licenseHash", "") ?: ""
+val zkApp       = "B62q…"
+val url = "https://zklicensing.com/api/verify" +
+          "?licenseHash=$licenseHash&zkAppAddress=$zkApp"
+val body = OkHttpClient().newCall(Request.Builder().url(url).build())
+                        .execute().body?.string() ?: "{}"
+val r = JSONObject(body)
+if (r.getBoolean("valid")) unlockFeatures()
+
+// JTI-capped — append &token, refreshed off the backend helper
+val token = prefs.getString("ownershipToken", null)
+val capped = url + (token?.let { "&token=$it" } ?: "")
+// … same fetch + parse; on 429 { activeSessions, deviceLimit } prompt "log out other device"
+```
+
+### iOS (Swift)
+
+```swift
+// Unlimited — no token
+let zkApp = "B62q…"
+var c = URLComponents(string: "https://zklicensing.com/api/verify")!
+c.queryItems = [
+  URLQueryItem(name: "licenseHash",  value: licenseHash),
+  URLQueryItem(name: "zkAppAddress", value: zkApp),
+]
+let (data, _) = try await URLSession.shared.data(from: c.url!)
+let r = try JSONDecoder().decode(VerifyResult.self, from: data)
+if r.valid { unlockFeatures() }
+
+// JTI-capped — append &token; refresh via POST /verify/refresh
+if let token = UserDefaults.standard.string(forKey: "ownershipToken") {
+  c.queryItems! += [URLQueryItem(name: "token", value: token)]
+}
+```
+
+### Browser / PWA
+
+Unlimited licenses are just the top-of-file `verifyLicense` example — no `secretHash`, no `prover`. For JTI-capped apps, load `zklicensing/prove` + `o1js` lazily on first verify only, then let the SDK's stored `secretHash` renew silently:
+
+```ts
+import { verifyLicense } from 'zklicensing';
+
+// `promptPassphraseOnce` is your helper — check localStorage yourself and
+// skip the modal when an activation already exists. On the first successful
+// /challenge + /respond the SDK persists { token, expiresAt, secretHash }
+// to `options.storage` (defaults to localStorage in browsers), and from
+// then on renews silently using the stored secretHash.
+const rawSecret  = await promptPassphraseOnce();
+const [o1js, prove] = await Promise.all([import('o1js'), import('zklicensing/prove')]);
+const secretHash = o1js.Poseidon.hash(o1js.Encoding.stringToFields(rawSecret)).toString();
+await prove.LicenseProof.compile();
+
+const r = await verifyLicense(proof, {
+  secretHash,
+  prover: async ({ licenseHash, nonce, secretHash }) => {
+    const pub = new prove.OwnershipChallenge({
+      licenseHash: o1js.Field(licenseHash), nonce: o1js.Field(nonce),
+    });
+    return (await prove.LicenseProof.prove(pub, o1js.Field(secretHash))).proof.toJSON();
+  },
+});
+if (r.valid && r.ownership === 'verified') unlockFeatures();
+```
+
+## Quick Start: Building a vendor site
+
+Three drop-in pages, one SDK. Fork them, restyle, ship.
+
+- **`examples/buy.html`** — passphrase → wallet sign → licence file.
+- **`examples/renew.html`** — one click, one wallet prompt.
+- **`examples/refund.html`** — 14-day window, handled.
+
+Each page is a self-contained HTML + TS pair calling one SDK subpath.
+
+**Run them:**
+
+```bash
+# 1. Register your app and download apps.json
+open https://zklicensing.com/register.html   # click "Download apps.json"
+
+# 2. Drop apps.json into the examples/ directory
+mv ~/Downloads/apps.json packages/sdk/examples/
+
+# 3. Install + dev
+cd packages/sdk/examples
+npm install
+npm run dev
+```
+
+Vite serves `index.html`, `buy.html`, `renew.html`, and `refund.html` at
+`http://localhost:5173`. The pages `fetch('/apps.json')` for their config —
+no `.env` file needed. Ship them as static assets with `npm run build`.
+
+Wallet support: Auro browser extension out of the box; add a
+[Reown](https://dashboard.reown.com) (formerly WalletConnect Cloud) project ID
+via `VITE_WALLETCONNECT_PROJECT_ID` to enable the mobile QR fallback.
+
+## Subpaths
+
+The main entry point (`zklicensing`) covers licence verification. Additional entry points are shipped alongside for integrators building a buy page, a vendor dashboard, or tax-report tooling — all browser-safe, no `fs`.
+
+### `zklicensing/deploy` — deploy flow client
+
+Wraps the backend's `/prove/deploy` endpoint. The backend generates a throwaway zkApp keypair, bundles `deploy() + initialize()` as a single atomic tx, proves it, signs the zkApp AccountUpdate with the throwaway key, and returns the provenTxJson — the vendor's wallet only adds the fee-payer signature.
+
+```ts
+import { proveDeploy, pollDeployStatus } from 'zklicensing/deploy';
+
+const { provenTxJson, zkAppAddress, verificationKeyHash } = await proveDeploy({
+  keeperUrl:         'https://zklicensing.com/api/keeper',
+  senderPublicKey:   'B62q…',   // vendor's fee-payer wallet
+  vendorAddress:     'B62q…',
+  priceMonthlyMina:  1,
+  priceYearlyMina:   10,
+  priceFiveYearMina: 40,
+});
+
+// Send `provenTxJson` to the wallet for signing, obtain txHash, register the
+// app via /register/app, then optionally watch inclusion:
+const status = await pollDeployStatus({ keeperUrl, zkAppAddress });
+```
+
+The SDK does not expose a raw `initialize()` helper. `initialize()` sets `vendor` on-chain and is guarded only by a `vendor.requireEquals(PublicKey.empty())` precondition — no in-circuit signature check (adding one collides with the proof-based `editState` permission that `deploy()` installs). Front-running is prevented operationally instead: the backend puts `deploy()` and `initialize()` in the same `Mina.transaction`, and the throwaway zkApp keypair is generated inside the handler and dropped at return, so the target address is not observable to an attacker until the initialize AU is already signed and locked to `(vendor, prices)`. Drivers bypassing `proveDeploy` are responsible for the same discipline.
+
+#### Post-hardfork redeploy
+
+After a Mina hardfork relaxes `impossibleDuringCurrentVersion` back to `signature()`, every existing zkApp becomes uneditable in place (deploy keys are already discarded). The platform migrates each app to a fresh v2 address via admin endpoints, guarded by `KEEPER_ADMIN_TOKEN`:
+
+```ts
+import { redeployApp, redeployAll } from 'zklicensing/deploy';
+
+// Migrate one app.
+const { zkAppAddress, txHash, verificationKeyHash, onChainVersion } = await redeployApp({
+  keeperUrl:  'https://zklicensing.example.com',
+  appId:      'acme-editor',
+  adminToken: process.env.KEEPER_ADMIN_TOKEN!,
+});
+
+// Batch — top-level `ok` is always true unless the whole request errored;
+// per-app failures surface as { ok: false, error } inside `results`.
+const batch = await redeployAll({ keeperUrl, adminToken });
+for (const r of batch.results) {
+  if (!r.ok) console.warn(`${r.appId}: ${r.error}`);
+}
+```
+
+The backend reads authoritative `vendor` + prices from the old v1 contract (no vendor RPC), mints a fresh throwaway zkApp keypair, and broadcasts a merged-sign atomic redeploy. Guards (HTTP 409): sales frozen, refund window closed, `escrowRoot === EMPTY_ROOT`, on-chain version still in `SUPPORTED_LICENSING_APP_VERSIONS`. Both endpoints are idempotent — already-migrated apps surface as `{ ok: false, error: "already outside supported range" }`, so reruns after a partial batch are safe.
+
+Pass `force: true` on either helper to bypass the `escrowRoot === EMPTY_ROOT` guard when the platform accepts responsibility for the unrefunded balance. Other guards remain strict. Successful responses that used the override return `forcedEscrowNonEmpty: true` alongside the usual fields; unrefunded buyers keep their independent refund path against the retired v1 address (its on-chain state persists), so pointing them at `deploymentHistory[]` addresses out-of-band remains the mitigation.
+
+Confirmation polling is not baked in — reuse `pollDeployStatus({ keeperUrl, zkAppAddress })` against the returned address.
+
+#### Vendor-triggered redeploy
+
+Vendors don't have to wait for the platform to migrate their app — they can trigger the redeploy themselves through the SDK. Authentication is a Mina signature against the on-chain vendor of the target app (no `KEEPER_ADMIN_TOKEN` required), and the vendor pays gas via their own fee-payer AU. Three-step flow, mirroring the first-time deploy:
+
+```ts
+import {
+  getVendorRedeployChallenge,
+  proveVendorRedeploy,
+  registerVendorRedeploy,
+  pollDeployStatus,
+} from 'zklicensing/deploy';
+
+// 1. Ask the backend for a single-use signing challenge.
+const { nonce } = await getVendorRedeployChallenge({ keeperUrl, appId });
+
+// 2. Vendor's wallet signs the nonce (Auro / Mina wallet's mina_signMessage
+//    or the equivalent that returns a Signature.toObject() form).
+const signature = await wallet.signMessage(nonce); // { field, scalar }
+
+// 3. Backend verifies signature against on-chain vendor, runs all redeploy
+//    guards, generates a throwaway zkApp keypair, and returns the proven tx
+//    for the wallet to sign + broadcast.
+const { provenTxJson, zkAppAddress, redeployId } = await proveVendorRedeploy({
+  keeperUrl, appId,
+  nonce,
+  signature,
+  senderPublicKey: vendorAddress, // fee payer
+  // force: true,                  // optional — bypass escrow-empty guard
+});
+
+// 4. Wallet adds the fee-payer signature and broadcasts (same as proveDeploy).
+const { hash: txHash } = await wallet.sendTransaction({ transaction: provenTxJson });
+
+// 5. Register the pending redeploy so the backend arms its deploy-watcher.
+//    On landing, the backend promotes the new deployment onto the AppRecord
+//    (push old to deploymentHistory[], overwrite live fields, clear sync cursors).
+await registerVendorRedeploy({ keeperUrl, appId, redeployId, txHash });
+
+// 6. Poll for landing.
+await pollDeployStatus({ keeperUrl, zkAppAddress });
+```
+
+Guards are identical to the admin path: freeze slot configured, refund window closed past `FREEZE_AFTER_SLOT + REFUND_WINDOW`, app status `active`, on-chain version in `SUPPORTED_LICENSING_APP_VERSIONS`. The nonce expires 60 seconds after `getVendorRedeployChallenge` returns; consumed on `proveVendorRedeploy`.
+
+`force: true` is available to vendors too, with the same semantics as the admin path — useful when the freeze is scheduled late enough that a straggling refund is still in flight. Unrefunded buyers retain the refund path against the retired v1 address; its on-chain state persists indefinitely, and the retired address stays in `AppRecord.deploymentHistory[]` for out-of-band buyer notification.
+
+> **Buy links auto-update — vendor-embedded links do not.** `proveVendorRedeploy` returns a fresh `zkAppAddress`. The platform marketplace stores your `buyUrl`/`renewUrl`/`refundUrl` as **base URLs** and appends `?app=<zkAppAddress>&network=<net>` at render time, so the "Get" button on the `/apps` listing routes buyers to the new v2 address automatically the moment `finalizeRedeploy` promotes it onto the AppRecord — no vendor action required. Only surfaces where you have hand-embedded the raw `zkAppAddress` yourself (landing pages, docs, emails, screenshots) need manual updating. Existing licenses on the retired v1 address remain independently verifiable.
+
+#### Per-buyer generation list
+
+`GET /apps/:appId` returns the full deployment lineage of an app — every retired zkApp address plus the currently live one, each tagged with a monotonic `gen` and a captured `frozenRoot` (the license Merkle root at retirement). Response shape:
+
+```ts
+{
+  appId: string,
+  current: number,                              // gen of the live deployment
+  generations: Array<{
+    gen: number,                                // 1-indexed
+    zkAppAddress: string,
+    status: 'retired' | 'live',
+    frozenRoot?: string,                        // captured at retirement — absent on live
+    deployedAt?: string,
+    retiredAt?: string,
+  }>
+}
+```
+
+The buy/renew receipts include a `generation: number` field baked into `ProofFile`, so a licence bought against gen 2 can be told apart from one bought against gen 5 without a second network call.
+
+On renew, `renew.ts` fetches this endpoint and, if the licence's `zkAppAddress` is retired, presents a **blocking** "Migrate & Renew" flow (the keeper 409s `/prove/renew` and `/prove/buy*` on retired addresses — buyer-held renewals against a retired tree would silently strand). Migration is a single call — no hop-walking — and copies the current expiry verbatim into the live map; see `zklicensing/migrate` below.
+
+**Signed generation-list, pin-verified.** The response body carries a `publicKey` + `signature` over the canonical `{ appId, current, generations, issuedAt }` payload, signed with the platform manifest Ed25519 key (the same key material that signs the freeze manifest). The SDK verifies against a caller-supplied pin list (`fetchGenerationInfo({ pinnedPublicKeysBase64 })`, see `zklicensing/generation` below) and fails closed — `verified: false` with `current: null` and `generations: []` — when the signature doesn't match. The keeper is not the trust anchor; the pin list is.
+
+Snapshot atomicity: `finalizeRedeploy` gates a retiring generation from all `/prove/*` handlers **before** draining the tolerance window, capturing `frozenRoot`, and persisting — so any buyer-held `provenTxJson` proven against the retiring tree becomes unlandable inside the drain window rather than accidentally landing after the ancestor root is composed.
+
+Never trusts `current` blindly: renew always continues against the licence's own stored `zkAppAddress` unless the buyer explicitly opts into the migrate flow. This means a compromised or misreporting keeper cannot redirect a renew to an address the buyer didn't already receive at purchase time. A verified signature is required to even enable the "Migrate & Renew" button.
+
+### `zklicensing/buy` — buy flow client
+
+Wraps the backend's three-step buy roundtrip so a custom marketplace or CLI can drive it without re-deriving the crypto. Peer dep: `o1js` (for the `secretHash` Poseidon derivation).
+
+```ts
+import { deriveBuyIdentity, proveBuy, confirmBuy, pollBuyStatus } from 'zklicensing/buy';
+
+// 1. Derive the identity from the buyer's passphrase (deterministic).
+const { secretHash, licenseHash } = deriveBuyIdentity(passphrase);
+
+// 2. Ask the backend to compile + prove the buy tx.
+const { provenTxJson, expirySlot, purchaseAmount, verificationKeyHash } = await proveBuy({
+  keeperUrl:    'https://zklicensing.com/api/keeper',
+  secretHash,
+  buyerAddress: 'B62q…',
+  zkAppAddress: 'B62q…',
+  duration:     0,           // 0 = Monthly, 1 = Yearly, 2 = 5 Years
+  buyerCountry: 'FI',        // ISO 3166-1 alpha-2, required
+  // Required only when a sales freeze is scheduled — see `zklicensing/freeze`
+  // below. Ignored (safe to pass anyway) when no freeze is announced.
+  refundWaiverAccepted: true,
+});
+
+// 3. Send `provenTxJson` to the buyer's wallet for signing, obtain txHash.
+
+// 4. Persist the pending record — the caller drives this only after the wallet returned.
+await confirmBuy({ keeperUrl, zkAppAddress, licenseHash, txHash });
+
+// Optional: watch for on-chain inclusion.
+const status = await pollBuyStatus({ keeperUrl, licenseHash });
+```
+
+The SDK never touches a wallet — the caller drives the sign step between `proveBuy` and `confirmBuy` — so this client works for any wallet integration (Auro, WalletConnect, mobile, CLI).
+
+`proveBuy` also refuses locally when the backend's sales freeze is in effect (fetched from `GET /health`) — the request would 423 anyway, so surfacing the message before the round-trip saves a wasted call. See `zklicensing/freeze` below.
+
+**No-escrow routing.** When the buyer's advertised 14-day refund window would land past `FREEZE_AFTER_SLOT` (checked as `currentSlot + REFUND_WINDOW_N + TOLERANCE_WINDOW_N > FREEZE_AFTER_SLOT`), `proveBuy` transparently switches to `POST /prove/buy-no-escrow` — the backend endpoint for a distinct circuit method (`buyLicenseNoEscrow`) that pays vendor + platform directly at buy time (98 / 2, same as `renewLicense`) and never writes an escrow entry. This is the mechanism that makes the pre-hardfork waiver materially real: with no escrow entry there is nothing for the freeze-window migration guard to strand, and no refund path exists at all (a refund would fail the `escrowCommitment` check by construction). Passing `refundWaiverAccepted: true` is mandatory on those routed calls; the backend refuses the endpoint without it. When the backend hasn't yet been redeployed with a build that offers `/prove/buy-no-escrow`, the client throws an actionable message rather than silently falling back to an escrow-backed buy that would strand funds — vendors on old backend builds must complete their §12.13 redeploy before the overlap-window sales resume.
+
+### `zklicensing/renew` — renew flow client
+
+Same shape as `zklicensing/buy`. `proveRenew` takes an explicit `waiverAccepted` flag and refuses locally when it's not `true` — that's the EU/UK CRD Article 16(m) waiver (consent to immediate delivery + acknowledgment of loss of the 14-day withdrawal right) which must be an express affirmative act from the buyer. Integrators wiring a renewal UI from a different surface than `renew.html` must expose the same unticked-by-default checkbox and pass its state through.
+
+```ts
+import { proveRenew, confirmRenew } from 'zklicensing/renew';
+
+const { provenTxJson, newExpirySlot, renewAmount } = await proveRenew({
+  keeperUrl:      'https://zklicensing.com/api/keeper',
+  licenseHash:    '…',
+  buyerAddress:   'B62q…',
+  zkAppAddress:   'B62q…',
+  duration:       0,           // 0 = Monthly, 1 = Yearly, 2 = 5 Years
+  waiverAccepted: true,        // required — throws before the network call if false
+});
+
+// Send `provenTxJson` to the wallet, obtain txHash, then:
+await confirmRenew({ keeperUrl, zkAppAddress, licenseHash, txHash });
+```
+
+`proveRenew` also refuses locally when the backend's sales freeze is in effect (fetched from `GET /health`), for the same reason as `proveBuy`.
+
+### `zklicensing/migrate` — cross-generation migrate client
+
+Wraps `POST /prove/migrate`. The keeper locates the buyer's licence in the freshest ancestor generation where it still exists, assembles the three witnesses (ancestor / predecessor / current-live-empty), and returns a signable transaction that copies the expiry verbatim into the current live map at zero payment.
+
+**Full "Migrate & Renew" sequence** (two txs, one wallet sign each):
+
+1. `fetchGenerationInfo` (see `zklicensing/generation`) — pin-verified signed lineage. If the licence's `zkAppAddress` is retired, present the buyer with a blocking "Migrate & Renew" step.
+2. `proveMigrate` → wallet signs `provenTxJson` → broadcast → poll landing on the current `zkAppAddress`.
+3. `proveRenew` (see `zklicensing/renew`) against the current `zkAppAddress` → wallet signs → broadcast → poll → rewrite `ProofFile` with the new `{ generation, zkAppAddress, expirySlot }`.
+
+The keeper 409s `/prove/renew` and `/prove/buy*` for any retired `zkAppAddress`, so skipping step 2 is not an option.
+
+```ts
+import { proveMigrate, ProveMigrateError } from 'zklicensing/migrate';
+
+try {
+  const { provenTxJson, ancestorGen, expirySlot, zkAppAddress } = await proveMigrate({
+    keeperUrl:    'https://zklicensing.com/api/keeper',
+    licenseHash:  '…',
+    appId:        'app_…',
+    buyerAddress: 'B62q…',   // fee payer (buyer-signed mode)
+  });
+  // Wallet signs provenTxJson → broadcast → poll landing → resume with renew.
+} catch (e) {
+  if (e instanceof ProveMigrateError && e.status === 409 && e.retryAfterMs) {
+    // "migration in flight" — another caller is proving right now.
+    // Wait retryAfterMs before retrying rather than opening a second wallet prompt.
+  }
+  throw e;
+}
+```
+
+Single-flight is enforced keeper-side via a per-`licenseHash` in-flight marker: the second concurrent caller receives a 409 with `retryAfterMs` (surfaced on `ProveMigrateError`) before any wallet prompt, so the buyer never signs a transaction for a live-map that another proof is about to change.
+
+Terminal 4xx surfaces: 404 "license refunded or unknown" (no leaf in any generation — stop), 409 "already migrated" (leaf already in the current live map — refresh the record).
+
+### `zklicensing/generation` — signed generation-list client
+
+Wraps `GET /apps/:appId` — every past `zkAppAddress` plus the currently live one, with the response's Ed25519 signature verified against a caller-supplied pin list of platform manifest public keys.
+
+```ts
+import { fetchGenerationInfo } from 'zklicensing/generation';
+
+const info = await fetchGenerationInfo({
+  keeperUrl:              'https://zklicensing.com/api/keeper',
+  appId:                  'app_…',
+  pinnedPublicKeysBase64: [/* platform manifest pubkeys, base64 Ed25519 */],
+});
+
+if (info.verified) {
+  // info.current is the live generation index; info.generations lists all with
+  // { gen, zkAppAddress, status: 'retired' | 'live', frozenRoot?, deployedAt?, retiredAt? }
+}
+```
+
+Trust model: the keeper is not the trust anchor for this data — it can be re-hosted, mirrored, cached, or (worst case) impersonated. The pin list is. On any failure — missing signature, wrong pubkey, tampered payload, empty pin list — the client returns `{ current: null, generations: [], verified: false }` so callers cannot accidentally route a wallet prompt to an unverified address.
+
+Rotation-friendly: the pin list is a set. Multiple pins can be listed during a key rotation window; verification succeeds on the first pin that matches.
+
+Optional out-of-band corroboration: an operator that publishes `https://<vendor-host>/.well-known/zklicensing/<appId>.json` under vendor TLS (with the same keeper-signed payload) can be cross-checked from the on-chain `zkappUri`. Per-app filename because a vendor may host several apps at one origin; the cross-check is opt-in per app — absence of the file (404) is not a failure signal, just "no corroboration published for this app." That's the caller's job, not this module's; the platform signature is the trust anchor.
+
+### `zklicensing/refund` — refund flow client
+
+Same shape. The backend enforces the 14-day refund window and returns HTTP 409 when it has closed — the error surfaces through the thrown `Error` message, so the SDK doesn't second-guess it locally. Refunds stay open during a sales freeze (that's the whole point of freezing).
+
+```ts
+import { proveRefund, confirmRefund } from 'zklicensing/refund';
+
+const { provenTxJson } = await proveRefund({
+  keeperUrl:    'https://zklicensing.com/api/keeper',
+  licenseHash:  '…',
+  buyerAddress: 'B62q…',
+  zkAppAddress: 'B62q…',
+});
+
+// Send `provenTxJson` to the wallet, obtain txHash, then:
+await confirmRefund({ keeperUrl, zkAppAddress, licenseHash, txHash });
+```
+
+### `zklicensing/freeze` — sales-freeze state
+
+Read helpers for the backend's sales-freeze schedule. A platform operator sets `FREEZE_AFTER_SLOT` on the backend ahead of a hardfork migration; from that slot on the backend refuses new buys and renewals so open escrow can drain. Refunds, releases, and verify stay open throughout.
+
+```ts
+import { getKeeperHealth, resolveFreezeState } from 'zklicensing/freeze';
+
+// Raw /health payload — status, network, current slot, plus freeze state.
+const h = await getKeeperHealth({ keeperUrl });
+
+// Effective freeze state for the caller. Resolves in this precedence:
+//   1. `freezeAfterSlot` override arg (if > 0)
+//   2. `process.env.FREEZE_AFTER_SLOT` (Node only)
+//   3. GET /health (authoritative fallback — always fetched fresh)
+const { salesFrozen, freezeAfterSlot } = await resolveFreezeState({ keeperUrl });
+```
+
+`salesFrozen` computed vs. an authoritative slot is only available on the `/health` path — the override / env paths return `salesFrozen: false` and let the backend reject if the freeze has fired. This is fine because `proveBuy` / `proveRenew` also fall back on the backend's own 423 response.
+
+The buy client requires an express **`refundWaiverAccepted`** boolean whenever the buyer's advertised refund window would overlap `freezeAfterSlot` — the scheduled hardfork can truncate that window, so their express acknowledgment is a legal precondition. UIs must expose this as an unticked-by-default checkbox, matching the Article 16(m) renewal waiver. Under the hood the SDK routes waivered overlap-buys to `POST /prove/buy-no-escrow` (the `buyLicenseNoEscrow` circuit method), which pays vendor + platform directly at buy time so no funds sit in escrow across the freeze; buys whose window ends before the freeze proceed through the standard escrow-backed `POST /prove/buy` and no waiver is required.
+
+No SDK restart or user intervention is required to pick up freeze changes — `resolveFreezeState` re-reads env and re-fetches `/health` on every call.
+
+### `zklicensing/stats` — vendor dashboard client
+
+Fetch helpers for the backend's vendor-facing analytics endpoints. Types mirror the backend's response shape so a dashboard implementation doesn't have to re-derive them.
+
+```ts
+import { fetchVendorStats, fetchTransactions, fetchVendorApps } from 'zklicensing/stats';
+
+const stats = await fetchVendorStats({ keeperUrl, vendorAddress });
+// stats.totalRevenueMina, .activeLicenses, .monthlyRevenueMina[], .licensesByTier, .countryBreakdown
+const txs   = await fetchTransactions({ keeperUrl, vendorAddress, days: 30 });
+const apps  = await fetchVendorApps({ keeperUrl, vendorAddress });
+```
+
+Each helper returns `null` on non-OK response so a degraded backend doesn't tear the dashboard down.
+
+### `zklicensing/country-stats` — buyer-country breakdown
+
+Pure computation over `LicenseRecord[]`, bucketed by UTC calendar year and structured for tax reporting (one row per `year × appId × countryCode`). Used by both the backend (for `/stats.countryBreakdown`) and any downstream dashboard, so numbers can never drift between them.
+
+```ts
+import { computeCountryBreakdown } from 'zklicensing/country-stats';
+
+const breakdown = computeCountryBreakdown(apps, records, currentSlot, nowMs);
+// { years: [2026, 2025, …], byYear: { 2026: { aggregate: { FI: { count, revenueMina }, … }, byApp: { … } }, … } }
+```
+
+Purchase revenue attributes to `createdAt` (falling back to slot-derived time for legacy records). Renewals attribute to the renewal slot. Refunded purchases contribute zero revenue but still count as licences.
+
+### `zklicensing/record` — `LicenseRecord` type
+
+The off-chain record shape written by the backend. Import if you're building tooling that consumes the raw store (Node) or that consumes it via the analytics endpoints.
+
+```ts
+import type { LicenseRecord, LicenseStatus } from 'zklicensing/record';
+```
+
+### `zklicensing/prove` — ownership `ZkProgram`
+
+`LicenseOwnershipProgram` — the challenge/response proof used by verifiers to bind a proof to a fresh nonce. Loaded on demand by clients that produce ownership proofs (verify itself never imports it).
+
+### Verify service — ownership tokens & concurrent-device cap
+
+The verify service issues an HMAC-SHA256 bearer **token** through a challenge/response flow: `GET /challenge?licenseHash=…` returns a fresh nonce, the client produces a `LicenseProof` binding `(licenseHash, nonce)`, `POST /respond` verifies the proof and returns `{ token, expiresAt, jti, activeSessions, deviceLimit }`. Token TTL is 7 days; the client renews in the background via `POST /refresh` while the app is running so the user only redoes the passphrase-gated `/respond` after a full week of inactivity or an explicit logout. Passing `token` on subsequent `GET /?licenseHash=…&zkAppAddress=…&token=…` calls upgrades the response from "on-chain state" to "verified caller owns this license." Tokens carry a random `jti` (JWT-style unique id) that ties them to an in-memory session-store row so revocation and concurrency caps are enforceable on top of the stateless HMAC.
+
+The AppRecord field `maxConcurrentDevices` (register-time or dashboard-editable, `0` = unlimited, capped at 10,000) is the per-license active-device cap. `POST /respond` reserves a session slot for the newly minted `jti` before signing; when the cap is reached and no expired session is available, it returns `429` with `{ activeSessions, deviceLimit }`. The store also prunes on TTL, so the cap is self-recovering.
+
+Three lifecycle endpoints back the cap:
+
+- **`POST /refresh`** — body `{ token }`. Verifies HMAC + `jti` still active, reissues a token with the same `jti` and a fresh expiry. No LicenseProof needed. Used by running apps to keep sessions warm across the 7-day TTL. If the seat was released in the meantime, returns `401 Seat released`.
+- **`POST /releaseSeat`** — body `{ token }`. Releases the seat identified by the token's `jti`. Idempotent. Same threat model as any bearer token: possession is authorization. Enables an in-app "Log this device out" button.
+- **`POST /reset-sessions`** — body `{ zkAppAddress, proof }`. Drops **all** sessions for the license proved by the `LicenseProof`. Requires the same passphrase-gated challenge/response as `/respond`, so only the license owner can invoke it. Intended as a self-service recovery for owners who hit the cap after an app reinstall or a lost device didn't `POST /releaseSeat` on the way out. The caller runs a fresh `/respond` afterwards to re-provision under a zero active count.
+
+Sessions are in-memory by design — a service restart drops every session, forcing devices to re-prove. That is intentional: persisted sessions would let a stolen token bypass the cap across restarts with no signal to the license owner.
+
+## Documentation
+
+- Integration walkthrough — [zklicensing.com/docs](https://zklicensing.com/docs)
+- FAQ — [zklicensing.com/faq](https://zklicensing.com/faq)
+- Register an app — [zklicensing.com/register](https://zklicensing.com/register)
+
+## Licence
+
+Business Source License 1.1 (BUSL-1.1). See [LICENSE](./LICENSE) for the full text.
+
+The Additional Use Grant permits production use of the SDK to build, distribute, and operate applications and services that consume, verify, purchase, renew, refund, or migrate licences issued via the zkLicensing backend protocol. It does not permit operating a competing licensing backend for third parties.
+
+On **2030-07-11** (or four years after this version's first distribution, whichever comes first) the licence automatically converts to Apache License 2.0.

package/build/archiveBootstrap.d.ts

@@ -0,0 +1,60 @@
+export declare const SYNC_CHUNK_SLOTS = 10000;
+export declare const MAX_LOOKBACK_SLOTS = 525600;
+export type Tier = 'monthly' | 'yearly' | 'fiveYear';
+export type NormalizedEvent = {
+    kind: 'licenseIssued';
+    slot: number;
+    licenseHash: string;
+    amount: bigint;
+    issuedSlot: number;
+    expirySlot: number;
+} | {
+    kind: 'licenseIssuedNoEscrow';
+    slot: number;
+    licenseHash: string;
+    amount: bigint;
+    issuedSlot: number;
+    expirySlot: number;
+} | {
+    kind: 'licenseRenewed';
+    slot: number;
+    licenseHash: string;
+    newExpiry: number;
+} | {
+    kind: 'licenseMigrated';
+    slot: number;
+    licenseHash: string;
+    expirySlot: number;
+    ancestorGen: number;
+} | {
+    kind: 'refundIssued';
+    slot: number;
+    licenseHash: string;
+} | {
+    kind: 'fundsReleased';
+    slot: number;
+    licenseHash: string;
+} | {
+    kind: 'priceUpdated';
+    slot: number;
+    priceMonthly: bigint;
+    priceYearly: bigint;
+    priceFiveYear: bigint;
+};
+export declare function tierFromExpiryDelta(slots: number): Tier | null;
+export type FetchRange = {
+    from?: number;
+    to?: number;
+};
+export type BootstrapResult = {
+    maxSeenSlot: number;
+    events: NormalizedEvent[];
+};
+export declare function bootstrapFromArchive(zkAppAddress: string, range?: FetchRange): Promise<BootstrapResult>;
+export declare function applyEventsToStore(zkAppAddress: string, events: NormalizedEvent[]): Promise<{
+    count: number;
+    warnings: string[];
+}>;
+export declare function discoverAppCreatedSlot(zkAppAddress: string, nowSlot: number, lookbackSlots?: number): Promise<number | null>;
+export declare function lazyBootstrap(zkAppAddress: string): Promise<void>;
+//# sourceMappingURL=archiveBootstrap.d.ts.map