zklicensing 0.1.0-beta.3 → 0.1.0-beta.6

package/README.md

@@ -1,6 +1,6 @@
 # zklicensing
 
-Client SDK for verifying [zkLicensing](https://zklicensing.com) software licenses.
+Client SDK for verifying [zkLicensing](https://dev.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.
 
@@ -18,10 +18,8 @@ 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…)
+  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) {
@@ -41,9 +39,7 @@ purchase ─────► verifier (every call) ─────► anchor writ
 
 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.
+The anchor stores `{ anchoredSlot, anchoredAtMs, expirySlot }`. 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.
 
@@ -58,12 +54,9 @@ 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
@@ -72,7 +65,10 @@ type VerifyOptions = {
 type VerifyResult = {
   valid:         boolean;
   expirySlot:    number;
+  expiresAt:     string | null;         // ISO-8601; estimated in the offline branch
+  currentSlot:   number;                // from the verifier, or estimated offline
   inGracePeriod: boolean;
+  remainingDays: number;                // negative through grace and beyond
   reason:        string | null;
   source:        'chain' | 'offline';
 };
@@ -80,6 +76,8 @@ type VerifyResult = {
 function verifyLicense(proof: ProofInput, options?: VerifyOptions): Promise<VerifyResult>;
 ```
 
+The refund-window decision is server-side: the verifier returns `refundWindowClosed: boolean` on its `/verify` response, computed from its own `purchaseSlot` record against the on-chain `currentSlot`. The SDK gates anchor writes on that boolean and never trusts a `purchaseSlot` supplied by the local proof file, so a user who forges their proof metadata cannot force the offline branch prematurely.
+
 The package also re-exports the three constants the SDK uses internally:
 
 ```ts
@@ -87,6 +85,62 @@ import { REFUND_WINDOW_N, GRACE_PERIOD_N, MS_PER_SLOT } from 'zklicensing';
 // 13_440, 6_720, 90_000
 ```
 
+### Non-custodial device binding
+
+For apps with a per-license device cap (`deviceCap > 0`), the SDK ships a bind/unbind client that writes device slots directly to the on-chain `LicenseLeaf`. There is no session server: the leaf carries a fixed-width slot array (`DEVICE_SLOT_CAP_N = 5`), the on-chain `bind()` / `unbind()` methods re-verify the buyer's Pallas Schnorr ownership signature IN-CIRCUIT via `Signature.verify()`, and offline verification checks the device's local commitment against the cached leaf.
+
+```ts
+import {
+  proveBind,
+  confirmBind,
+  proveUnbind,
+  confirmUnbind,
+  getOrCreateDeviceIdentity,
+  deriveOwnershipKeypair,
+} from 'zklicensing';
+
+// Fresh device: generate (or load) a Pallas keypair kept in OS secure
+// storage. Only its Poseidon commitment ever crosses the wire.
+const { deviceCommitment } = await getOrCreateDeviceIdentity('myapp/license/device');
+
+// Owner key — derived from the buyer's passphrase + the app's zkApp
+// address. Same keypair `licenseHash` was derived from at buy time.
+const { privateKey: ownerPrivateKey } = await deriveOwnershipKeypair(
+  passphrase,
+  zkAppAddress,
+);
+
+// Bind — the on-chain circuit re-verifies this signature, so a
+// compromised backend cannot forge a bind.
+const { provenTxJson, slotIndex } = await proveBind({
+  keeperUrl:     'https://dev.zklicensing.com/api/keeper',
+  network:       'mainnet',
+  zkAppAddress,
+  licenseHash,
+  ownerPrivateKey,
+  deviceCommitment,
+  slotIndex:     0,               // 0..deviceCap-1
+  buyerAddress:  wallet.address,
+});
+
+const txHash = await wallet.sendTransaction(provenTxJson);
+await confirmBind({ keeperUrl, zkAppAddress, licenseHash, txHash });
+```
+
+**Remote log-off.** `proveUnbind` needs only the ownership key — not physical possession of the target device. Any device with the passphrase-derived key can unbind any slot on the license, including one bound to a lost or stolen device.
+
+**Slot behaviour.**
+
+- Binding into an empty slot succeeds immediately.
+- Unbinding stamps `freedAt = currentSlot`; the slot cannot be re-bound until `COOLDOWN_SLOTS_N = 6_720` slots (≈ 7 days at 90 s/slot) have elapsed. The cooldown is a flat one-week wait for every tier (monthly, yearly, five-year), independent of `deviceCap` — one number to reason about, not a per-tier formula.
+- `deviceCap = 0` disables binding entirely — `bind()` rejects with "bindings disabled" and no slot state is written to the leaf.
+- Cap is committed to the leaf at buy time and immutable for the life of the license. A vendor cannot tighten enforcement retroactively.
+- Bindings survive cross-generation migration: `migrateLicense` copies the ancestor leaf verbatim (including the device slot array) into the successor tree.
+
+**Offline verification.** After bind, the SDK caches the leaf's slot array locally. `verifyOffline` compares the device's local Poseidon commitment against `occupiedSlot[]`; a stolen laptop's commitment vanishing from the slot array denies access on the next launch without any network call.
+
+Non-custodial guarantees preserved: the keeper cannot bind or unbind (no signature to sign with), the vendor cannot revoke a bound device (no admin unbind path in the circuit), and the platform cannot revoke either. The only party who can add or remove a device commitment is whoever holds the passphrase-derived ownership private key.
+
 ## 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:
@@ -115,7 +169,7 @@ Pass `storage: null` to disable the offline path entirely (every call hits the v
 
 ## Verifier response contract
 
-If you self-host the verification endpoint, it must return:
+The verifier returns:
 
 ```ts
 {
@@ -134,36 +188,26 @@ For non-JavaScript clients (Android, iOS, Python, …) call the verifier's `GET
 
 ## 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`.
+Device-cap enforcement is fully on-chain via [Non-custodial device binding](#non-custodial-device-binding) — the verifier never mints session tokens, so every platform reduces to the same `GET /verify` call. If the vendor set `deviceCap > 0` at registration, the SDK's bind/unbind clients drive on-chain slot writes; the verifier is stateless and passphrase-free.
 
 ### Android (Kotlin)
 
 ```kotlin
-// Unlimited — no token
 val licenseHash = prefs.getString("licenseHash", "") ?: ""
 val zkApp       = "B62q…"
-val url = "https://zklicensing.com/api/verify" +
+val url = "https://dev.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")!
+var c = URLComponents(string: "https://dev.zklicensing.com/api/verify")!
 c.queryItems = [
   URLQueryItem(name: "licenseHash",  value: licenseHash),
   URLQueryItem(name: "zkAppAddress", value: zkApp),
@@ -171,41 +215,11 @@ c.queryItems = [
 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();
-```
+`verifyLicense` is the top-of-file example — no `signer`, no passphrase round-trip. If your app also needs to bind/unbind devices, see [Non-custodial device binding](#non-custodial-device-binding) below for the `proveBind` / `proveUnbind` flow that uses the buyer's passphrase-derived Pallas Schnorr ownership key to authorize on-chain slot writes.
 
 ## Quick Start: Building a vendor site
 
@@ -214,6 +228,8 @@ 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.
+- **`examples/bind.html`** / **`examples/unbind.html`** — device-slot writes for `deviceCap > 0` apps.
+- **`examples/verify.html`** — non-custodial verify: paste proof.json → witness + record from the service, root from Mina, folded locally.
 
 Each page is a self-contained HTML + TS pair calling one SDK subpath.
 
@@ -221,7 +237,7 @@ Each page is a self-contained HTML + TS pair calling one SDK subpath.
 
 ```bash
 # 1. Register your app and download apps.json
-open https://zklicensing.com/register.html   # click "Download apps.json"
+open https://dev.zklicensing.com/register.html   # click "Download apps.json"
 
 # 2. Drop apps.json into the examples/ directory
 mv ~/Downloads/apps.json packages/sdk/examples/
@@ -232,7 +248,7 @@ npm install
 npm run dev
 ```
 
-Vite serves `index.html`, `buy.html`, `renew.html`, and `refund.html` at
+Vite serves `index.html`, `buy.html`, `renew.html`, `refund.html`, `bind.html`, `unbind.html`, and `verify.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`.
 
@@ -246,9 +262,9 @@ The main entry point (`zklicensing`) covers licence verification. Additional ent
 
 ### Per-app in-flight proving guard
 
-`/prove/buy`, `/prove/buy-no-escrow`, `/prove/renew`, and `/prove/migrate` all mutate the same on-chain `licensesRoot` precondition. Two proofs assembled against the same pre-state root within one landing window are mutually exclusive — the chain admits whichever lands first, the second's precondition fails and the tx is dropped. Left unguarded, the second buyer pays the wallet-popup + fee for a doomed tx.
+`/prove/buy`, `/prove/buy-no-escrow`, `/prove/renew`, `/prove/migrate`, and `/prove/refund` all mutate the same on-chain `licensesRoot` (and, for buy/refund, `escrowRoot`) preconditions. Two proofs assembled against the same pre-state root within one landing window are mutually exclusive — the chain admits whichever lands first, the second's precondition fails and the tx is dropped. Left unguarded, the second buyer pays the wallet-popup + fee for a doomed tx.
 
-The keeper defends against this with a **per-app in-flight slot** shared across all four endpoints. While the slot is held, a second concurrent request for the same app receives an immediate `409 { error: "proving queue busy", retryAfterMs, queueDepth }` — before any circuit work or wallet prompt. The SDK surfaces this as a shared `ProveQueueBusyError` (from `zklicensing/prove-errors`) thrown by `proveBuy`, `proveRenew`, and `proveMigrate`. Callers wait `retryAfterMs`, then retry — no popup, no fee, no signed-tx-doomed-to-fail.
+The keeper defends against this with a **per-app in-flight slot** shared across all five endpoints. While the slot is held, a second concurrent request for the same app receives an immediate `409 { error: "proving queue busy", retryAfterMs, queueDepth }` — before any circuit work or wallet prompt. The SDK surfaces this as a shared `ProveQueueBusyError` (from `zklicensing/prove-errors`) thrown by `proveBuy`, `proveRenew`, `proveMigrate`, and `proveRefund`. Callers wait `retryAfterMs`, then retry — no popup, no fee, no signed-tx-doomed-to-fail.
 
 Each prove response carries an `appKey` field — the same value the keeper uses to key the slot. After the wallet returns a tx hash, the SDK client calls `notifyBroadcast({ keeperUrl, appId: appKey, txHash })` (from `zklicensing/tx-broadcast`, fire-and-forget) to extend the slot's TTL from signing-TTL to landing-TTL, giving the honest broadcast room to land before another prove goes through.
 
@@ -262,12 +278,13 @@ Wraps the backend's `/prove/deploy` endpoint. The backend generates a throwaway
 import { proveDeploy, pollDeployStatus } from 'zklicensing/deploy';
 
 const { provenTxJson, zkAppAddress, verificationKeyHash } = await proveDeploy({
-  keeperUrl:         'https://zklicensing.com/api/keeper',
+  keeperUrl:         'https://dev.zklicensing.com/api/keeper',
   senderPublicKey:   'B62q…',   // vendor's fee-payer wallet
   vendorAddress:     'B62q…',
-  priceMonthlyMina:  1,
-  priceYearlyMina:   10,
-  priceFiveYearMina: 40,
+  priceMonthlyMina:   1,
+  priceYearlyMina:    10,
+  priceFiveYearMina:  40,
+  pricePerpetualMina: 10000,
 });
 
 // Send `provenTxJson` to the wallet for signing, obtain txHash, register the
@@ -374,6 +391,22 @@ Guards are identical to the admin path: freeze slot configured, refund window cl
 
 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.
 
+**Resolving by `zkAppAddress` instead of `appId`.** The keeper also exposes `GET /apps/by-address/:zkAppAddress`, which resolves any registered address — current or historical — to the same signed generation-list body **plus** an `app: AppRecord` field:
+
+```ts
+{
+  ...signedGenerationList,   // same shape as GET /apps/:appId
+  app: AppRecord             // full record; usable for name / prices / vendor legal
+}
+```
+
+Two properties matter for integrators:
+
+1. It accepts *any* generation's address (live or retired) and always returns the current lineage — so a buyer holding a link with a retired `?app=<addr>` still reaches the correct app.
+2. It does **not** filter by marketplace status. `pending`, `active`, `inactive`, and `rejected` apps all resolve. Contrast with `GET /apps`, which is `status: 'active'`-only for the storefront listing.
+
+This is what `buy.html` and `renew.html` on zklicensing.com call — an inactive-listing app can still be bought and renewed against so long as its on-chain LicensingApp is live. Use this endpoint when starting from a `zkAppAddress` (URL param, wallet paste); use `GET /apps/:appId` when you already know the stable app ID and only need the lineage.
+
 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.
@@ -384,15 +417,19 @@ Never trusts `current` blindly: renew always continues against the licence's own
 
 ### `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).
+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 `licenseHash` binding to the buyer's derived ownership pubkey).
 
 ```ts
 import { deriveBuyIdentity, proveBuy, confirmBuy, pollBuyStatus } from 'zklicensing/buy';
 import { ProveQueueBusyError } from 'zklicensing/prove-errors';
 import { notifyBroadcast }     from 'zklicensing/tx-broadcast';
 
-// 1. Derive the identity from the buyer's passphrase (deterministic).
-const { secretHash, licenseHash } = deriveBuyIdentity(passphrase);
+// 1. Derive the identity from the buyer's passphrase and the app's zkApp
+//    address (deterministic — the resulting ownership pubkey is hashed into
+//    the on-chain licenseHash). Binding to zkAppAddress means the same
+//    passphrase yields different keypairs across apps, so a leaked
+//    passphrase for one app cannot be replayed against any other.
+const { licenseHash } = await deriveBuyIdentity(passphrase, zkAppAddress);
 
 // 2. Ask the backend to compile + prove the buy tx. Retry on shared per-app
 //    queue-busy — server drives cadence via `retryAfterMs`, which caps at
@@ -404,11 +441,12 @@ async function proveBuyWithRetry(): Promise<Awaited<ReturnType<typeof proveBuy>>
   for (let n = 1; n <= MAX_ATTEMPTS; n++) {
     try {
       return await proveBuy({
-        keeperUrl:    'https://zklicensing.com/api/keeper',
-        secretHash,
+        keeperUrl:    'https://dev.zklicensing.com/api/keeper',
+        licenseHash,
         buyerAddress: 'B62q…',
         zkAppAddress: 'B62q…',
-        duration:     0,           // 0 = Monthly, 1 = Yearly, 2 = 5 Years
+        network:      'mainnet',   // 'devnet' or 'mainnet' — must match your ProofFile
+        duration:     0,           // 0 = Monthly, 1 = Yearly, 2 = 5 Years, 3 = Perpetual
         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.
@@ -455,11 +493,12 @@ import { ProveQueueBusyError }      from 'zklicensing/prove-errors';
 import { notifyBroadcast }          from 'zklicensing/tx-broadcast';
 
 const proveArgs = {
-  keeperUrl:      'https://zklicensing.com/api/keeper',
+  keeperUrl:      'https://dev.zklicensing.com/api/keeper',
   licenseHash:    '…',
   buyerAddress:   'B62q…',
   zkAppAddress:   'B62q…',
-  duration:       0 as 0 | 1 | 2,   // 0 = Monthly, 1 = Yearly, 2 = 5 Years
+  network:        'mainnet' as 'devnet' | 'mainnet',   // must match your ProofFile
+  duration:       0 as 0 | 1 | 2 | 3,   // 0 = Monthly, 1 = Yearly, 2 = 5 Years, 3 = Perpetual
   waiverAccepted: true,             // required — throws before the network call if false
 };
 
@@ -502,7 +541,7 @@ import { ProveQueueBusyError } from 'zklicensing/prove-errors';
 
 try {
   const { provenTxJson, ancestorGen, expirySlot, zkAppAddress, appKey } = await proveMigrate({
-    keeperUrl:    'https://zklicensing.com/api/keeper',
+    keeperUrl:    'https://dev.zklicensing.com/api/keeper',
     licenseHash:  '…',
     appId:        'app_…',
     buyerAddress: 'B62q…',   // fee payer (buyer-signed mode)
@@ -532,7 +571,7 @@ Wraps `GET /apps/:appId` — every past `zkAppAddress` plus the currently live o
 import { fetchGenerationInfo } from 'zklicensing/generation';
 
 const info = await fetchGenerationInfo({
-  keeperUrl:              'https://zklicensing.com/api/keeper',
+  keeperUrl:              'https://dev.zklicensing.com/api/keeper',
   appId:                  'app_…',
   pinnedPublicKeysBase64: [/* platform manifest pubkeys, base64 Ed25519 */],
 });
@@ -547,31 +586,69 @@ Trust model: the keeper is not the trust anchor for this data — it can be re-h
 
 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.
+Optional out-of-band corroboration: an operator that publishes `https://<vendor-host>/.well-known/zklicensing/<zkAppAddress>.json` under vendor TLS (with the same keeper-signed payload) can be cross-checked from the on-chain `zkappUri`. Per-address filename because a buyer's wallet shows the zkApp address, not the platform appId — keying by address lets any buyer verify from just the address they were prompted to sign, including addresses for retired generations they may still hold licenses under. The cross-check is opt-in per app — absence of the file (404) is not a failure signal, just "no corroboration published for this address." That's the caller's job, not this module's; the platform signature is the trust anchor.
 
 #### Publishing the manifest (vendor side)
 
 Vendors who want to enable the corroboration path host the same signed payload the keeper returns for their app. The vendor console exposes this as a one-click flow:
 
-1. Open the vendor dashboard, find the app card, and click **Download manifest**. This downloads the exact bytes served by `GET /apps/:appId` as `<appId>.json` — Ed25519 signature intact.
-2. Serve that file, unchanged, at `https://<vendor-host>/.well-known/zklicensing/<appId>.json` under the vendor's TLS certificate. Any static host works; no dynamic logic needed.
-3. Make sure the app's on-chain `zkappUri` points at `https://<vendor-host>` (the origin — the `.well-known` path is fixed). Callers derive the corroboration URL from that origin plus the appId they already have.
+1. Open the vendor dashboard, find the app card, and click **Download manifest**. This downloads the exact bytes served by `GET /apps/:appId` — one `<zkAppAddress>.json` file per generation address (current live + every retired address), all byte-identical, Ed25519 signature intact.
+2. Serve each downloaded file, unchanged, at `https://<vendor-host>/.well-known/zklicensing/<zkAppAddress>.json` under the vendor's TLS certificate. Any static host works; no dynamic logic needed.
+3. Make sure the app's on-chain `zkappUri` points at `https://<vendor-host>` (the origin — the `.well-known` path is fixed). Callers derive the corroboration URL from that origin plus the address their wallet already showed them.
+
+Re-download and re-publish after each retirement or redeploy: the `current` index changes, the `generations[]` list grows by one, and the payload's `issuedAt` timestamp rolls forward — every address file must be replaced with the new signed bytes. Serving a stale copy is not a security failure (the signature still verifies), but callers that compare `current` against the keeper's response will treat the vendor copy as behind.
 
-Re-download and re-publish after each retirement or redeploy: the `current` index changes, and the payload's `issuedAt` timestamp rolls forward. Serving a stale copy is not a security failure (the signature still verifies), but callers that compare `current` against the keeper's response will treat the vendor copy as behind.
+#### `zklicensing-verify-trust` — trust-anchor CLI
+
+Ships as a `bin` in this package. Runs the full trust-anchor pipeline for a single zkApp address end-to-end: fetches `.well-known/zklicensing/<zkAppAddress>.json` from the vendor origin, verifies the platform signature against caller-provided pins, asserts the address appears in the signed `generations[]`, then reads the on-chain zkApp and checks that its `zkappUri` binds back to the same origin, that its verification-key hash equals the pinned canonical value for that generation, and that the six-line permission matrix from `LicensingApp.init()` is intact (URI freeze, meta-freeze, VK lock, `send`/`editState` proof-only). Structured findings — no boolean collapse — so vendor CI can pin the exact check that regressed.
+
+```sh
+zklicensing-verify-trust \
+  --origin https://store.example.com \
+  --address B62q… \
+  --pinned-key O5BBGskSzE+BOxgf3rukMiV2e4t0I1oTwi0ERtvbUfA= \
+  --mina-graphql https://api.minascan.io/node/mainnet/v1/graphql \
+  --cross-check \
+  --json
+```
+
+`--cross-check` adds a `manifest_matches_backend` finding: fetches `https://dev.zklicensing.com/apps/by-address/<address>`, verifies its signature against the same `--pinned-key` values (never trusts the backend response blind), and byte-compares the canonicalized payload against the vendor's `.well-known` copy. Catches a vendor serving a stale or rolled-back manifest even when its signature is still valid. Opt-in — adds one extra network fetch and couples the verifier to zklicensing.com being reachable.
+
+`--address` is the zkApp address the buyer's wallet displays — the same address they'd see in a purchase or renewal signature prompt. The platform appId is not an input; the CLI reads it out of the signed payload after the signature verifies. Buyers with only a wallet-shown address (including addresses for retired-generation licenses) can self-verify with nothing else. Exit 0 on all-ok, 1 on any check failure, 2 on bad args. Default output is a human summary; `--json` emits the `TrustAnchorReport` for CI. Add `--skip-chain-checks` for offline manifest-only audits (no o1js peer dep required in that mode).
+
+> **Badge policy.** Per Vendor Terms §7.7, the zkLicensing trust-anchor badge (and any equivalent "trust anchor by zkLicensing" mark) may be displayed on vendor pages **only while this CLI returns all-`ok`** against your live `origin` and vendor `--address`, with `--pinned-key` sourced from the attestation table at <https://dev.zklicensing.com/trustanchor.html>. If a chain-side or manifest-side check starts failing, remove the badge until compliance is restored. Wiring this CLI into CI (fail the build on non-zero exit) is the simplest way to keep the two in sync.
+
+**Where `--pinned-key` comes from.** Read the current platform manifest pubkey(s) off the published trust-anchor page — <https://dev.zklicensing.com/trustanchor.html> lists them alongside each generation's verification-key hash. The same data is served as JSON for CI: <https://dev.zklicensing.com/trustanchor/manifest-pubkeys.json> (and VK hashes at <https://dev.zklicensing.com/trustanchor/vk-hashes.json>). Copy that base64 value into your build config and pass it as `--pinned-key`. **Do not** rely on the pubkey embedded inside the `.well-known` manifest itself — it is the signer's self-declaration and is not trusted; only the caller-pinned list is. Repeat `--pinned-key <b64>` once per key during a rotation window.
 
 ### `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).
+Same shape as buy/renew. 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). Refund shares the per-app in-flight guard with buy/renew/migrate, so `proveRefund` throws `ProveQueueBusyError` on concurrent-prove collisions.
 
 ```ts
 import { proveRefund, confirmRefund } from 'zklicensing/refund';
+import { ProveQueueBusyError }        from 'zklicensing/prove-errors';
 
-const { provenTxJson } = await proveRefund({
-  keeperUrl:    'https://zklicensing.com/api/keeper',
+const proveArgs = {
+  keeperUrl:    'https://dev.zklicensing.com/api/keeper',
   licenseHash:  '…',
   buyerAddress: 'B62q…',
   zkAppAddress: 'B62q…',
-});
+  network:      'mainnet' as 'devnet' | 'mainnet',   // must match your ProofFile
+};
+
+const MAX_ATTEMPTS = 10;   // ~15 min slot-by-slot coverage at Mesa/0.4
+let proved;
+for (let n = 1; n <= MAX_ATTEMPTS; n++) {
+  try { proved = await proveRefund(proveArgs); break; }
+  catch (err) {
+    if (err instanceof ProveQueueBusyError && n < MAX_ATTEMPTS) {
+      await new Promise(r => setTimeout(r, err.retryAfterMs));
+      continue;
+    }
+    throw err;
+  }
+}
+const { provenTxJson } = proved!;
 
 // Send `provenTxJson` to the wallet, obtain txHash, then:
 await confirmRefund({ keeperUrl, zkAppAddress, licenseHash, txHash });
@@ -630,7 +707,7 @@ Purchase revenue attributes to `createdAt` (falling back to slot-derived time fo
 
 ### `zklicensing/prove-errors` — shared typed errors
 
-Typed error surface for the per-app in-flight guard shared across `proveBuy`, `proveRenew`, and `proveMigrate`. See [Per-app in-flight proving guard](#per-app-in-flight-proving-guard) for the wire contract.
+Typed error surface for the per-app in-flight guard shared across `proveBuy`, `proveRenew`, `proveMigrate`, and `proveRefund`. See [Per-app in-flight proving guard](#per-app-in-flight-proving-guard) for the wire contract.
 
 ```ts
 import { ProveQueueBusyError } from 'zklicensing/prove-errors';
@@ -679,29 +756,81 @@ The off-chain record shape written by the backend. Import if you're building too
 import type { LicenseRecord, LicenseStatus } from 'zklicensing/record';
 ```
 
-### `zklicensing/prove` — ownership `ZkProgram`
+### `zklicensing/internal/ownershipSignature` — ownership challenge signer
+
+`deriveOwnershipKeypair(passphrase, zkAppAddress)` + `signBinding(privateKey, { licenseHash, deviceCommitment, slotIndex, nonce })` — the Pallas Schnorr signer used by the bind/unbind clients to authorize on-chain slot writes. Derivation is bound to the app's zkApp address, so a leaked passphrase for one app cannot bind against any other. Signatures are re-verified IN-CIRCUIT by `Signature.verify()`, so a compromised backend cannot forge a bind or unbind. Runs via `o1js` — the same primitive `licenseHash` was derived from at buy time.
 
-`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).
+### `zklicensing/verify-offline` — non-custodial offline verify
+
+Pure fold verifier. Given a `licensesRoot` you have anchored to, a serialized `MerkleMapWitness`, and the `LicenseLeaf` field set, `verifyOffline` reconstructs the leaf hash, walks the witness back to the root, cross-checks against the anchor, and (when `deviceCap > 0`) folds the device slot array and confirms the caller's device commitment appears in an occupied slot. No network, no service round-trip — the trust question reduces entirely to "where did `licensesRoot` come from?".
+
+```ts
+import { verifyOffline } from 'zklicensing/verify-offline';
+
+const result = verifyOffline({
+  licensesRoot,          // see below — trust anchor
+  currentSlot,           // Mina slot to check expiry against
+  licenseHash,
+  expirySlot,
+  deviceCap,
+  devices,               // DeviceSlotSnapshot[]
+  witness,               // { root, isLefts[], siblings[] } — from GET /witness
+  devicePubKey,          // optional; required when deviceCap > 0
+});
+
+if (!result.valid) throw new Error(result.reason ?? 'invalid');
+```
+
+### `zklicensing/on-chain-root` — non-custodial trust anchor
+
+Reads `licensesRoot` (`zkapp.appState[0]`) directly from Mina via `fetchAccount`. Pair it with `verify-offline` to remove the licensing service from the trust boundary — the service supplies the witness and license record, Mina supplies the root, and the two are cross-checked before any leaf is trusted. `o1js` is a peer dep and imported dynamically so this only costs the o1js payload for callers that actually use it.
+
+```ts
+import { fetchOnChainLicensesRoot } from 'zklicensing/on-chain-root';
+import { verifyOffline }             from 'zklicensing/verify-offline';
+
+// 1. Fetch witness + license record from the licensing service.
+const [w, rec] = await Promise.all([
+  fetch(`${service}/witness/${zkApp}/${licenseHash}`).then(r => r.json()),
+  fetch(`${service}/license/${zkApp}/${licenseHash}?network=mainnet`).then(r => r.json()),
+]);
+
+// 2. Fetch the on-chain root INDEPENDENTLY.
+const onChainRoot = await fetchOnChainLicensesRoot({ zkAppAddress: zkApp, network: 'mainnet' });
+
+// 3. Cross-check. If they disagree the service is stale/wrong; bail.
+if (w.root !== onChainRoot) throw new Error('service root disagrees with chain');
+
+// 4. Fold-verify.
+const res = verifyOffline({
+  licensesRoot: onChainRoot,
+  currentSlot,
+  licenseHash,
+  expirySlot:   rec.expirySlot,
+  deviceCap:    rec.deviceCap ?? 0,
+  devices:      rec.devices  ?? [],
+  witness:      w,
+});
+```
 
-### Verify service — ownership tokens & concurrent-device cap
+A worked end-to-end example — proof.json paste box, three-way fetch, cross-check, verdict — lives at `packages/sdk/examples/verify.html` alongside the buy / renew / refund / bind / unbind pages.
 
-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.
+Two sourcing modes for `licensesRoot`:
 
-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.
+- **Non-custodial (recommended).** Fetch it via `fetchOnChainLicensesRoot`. The service never gets to say "trust me, this leaf is real" — a service serving a stale or forged witness fails the cross-check and the leaf is refused.
+- **Custodial (trusted-service).** Reuse the `root` field the service returned on its `/verify` or `/witness` response. Faster (no o1js + Mina RPC round-trip) but relies on the service to report the true chain state. Fine for callers that already trust the service; not the recommended default.
 
-Three lifecycle endpoints back the cap:
+Default public Mina GraphQL endpoints are wired in (`DEFAULT_MINA_GRAPHQL_URLS.mainnet` / `.devnet`); pass `graphqlUrl` to point at your own node.
 
-- **`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.
+### Verify service — on-chain state only
 
-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.
+The verify service is a stateless mirror of on-chain license state. `GET /verify?licenseHash=…&zkAppAddress=…` returns `{ valid, expirySlot, inGracePeriod, reason, currentSlot, purchaseSlot }`. No session tokens, no HMAC-signed bearer state, no challenge/response — the verifier reads the archive and reports. Device-cap enforcement lives entirely on-chain via the [Non-custodial device binding](#non-custodial-device-binding) flow: the buyer's `bind()` / `unbind()` transactions write into the `LicenseLeaf`'s slot array, and offline verification checks the local device commitment against the cached leaf. There is no server-side seat concept the verifier or keeper can revoke; the only party who can add or remove a device commitment is whoever holds the passphrase-derived ownership private key.
 
 ## 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)
+- Integration walkthrough — [dev.zklicensing.com/docs.html](https://dev.zklicensing.com/docs.html)
+- FAQ — [dev.zklicensing.com/faq.html](https://dev.zklicensing.com/faq.html)
+- Register an app — [dev.zklicensing.com/register.html](https://dev.zklicensing.com/register.html)
 
 ## Licence
 

package/build/appsLookup.d.ts

@@ -0,0 +1,14 @@
+export type LookupableDeployment = {
+    zkAppAddress: string;
+    deploymentHistory?: Array<{
+        zkAppAddress: string;
+    }>;
+};
+export type LookupableApp = {
+    deployments: {
+        devnet?: LookupableDeployment;
+        mainnet?: LookupableDeployment;
+    };
+};
+export declare function findAppByAnyAddress<T extends LookupableApp>(apps: readonly T[], zkAppAddress: string): T | undefined;
+//# sourceMappingURL=appsLookup.d.ts.map

package/build/appsLookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appsLookup.d.ts","sourceRoot":"","sources":["../src/appsLookup.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,oBAAoB,GAAG;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,KAAK,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD,CAAC;AAKF,MAAM,MAAM,aAAa,GAAG;IAC1B,WAAW,EAAE;QACX,MAAM,CAAC,EAAG,oBAAoB,CAAC;QAC/B,OAAO,CAAC,EAAE,oBAAoB,CAAC;KAChC,CAAC;CACH,CAAC;AAMF,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,aAAa,EACzD,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,YAAY,EAAE,MAAM,GACnB,CAAC,GAAG,SAAS,CAOf"}

package/build/appsLookup.js

@@ -0,0 +1,12 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+// Return the first app whose devnet OR mainnet deployment matches (current
+// live address or any retired generation in deploymentHistory). Under the
+// keeper-routing design a buyer who pinned an original devnet address stays
+// resolvable across N mainnet promotions and any number of retired gens.
+export function findAppByAnyAddress(apps, zkAppAddress) {
+    const matches = (d) => !!d && (d.zkAppAddress === zkAppAddress ||
+        (d.deploymentHistory ?? []).some(h => h.zkAppAddress === zkAppAddress));
+    return apps.find(a => matches(a.deployments.devnet) || matches(a.deployments.mainnet));
+}
+//# sourceMappingURL=appsLookup.js.map

package/build/appsLookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appsLookup.js","sourceRoot":"","sources":["../src/appsLookup.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,oCAAoC;AAgCpC,2EAA2E;AAC3E,0EAA0E;AAC1E,4EAA4E;AAC5E,yEAAyE;AACzE,MAAM,UAAU,mBAAmB,CACjC,IAAkB,EAClB,YAAoB;IAEpB,MAAM,OAAO,GAAG,CAAC,CAAwB,EAAW,EAAE,CACpD,CAAC,CAAC,CAAC,IAAI,CACL,CAAC,CAAC,YAAY,KAAK,YAAY;QAC/B,CAAC,CAAC,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,YAAY,CAAC,CACvE,CAAC;IACJ,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;AACzF,CAAC"}