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

package/src/deviceIdentity.ts

@@ -0,0 +1,249 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * deviceIdentity.ts
+ *
+ * Per-install Pallas Schnorr keypair used to identify a device to the
+ * non-custodial binding flow. `getOrCreateDeviceIdentity(storageKey)`
+ * returns a stable keypair for the caller's storage key: created on
+ * first call, loaded verbatim on every subsequent call.
+ *
+ * The `deviceCommitment` this module exposes matches the on-chain
+ * `occupied[i]` field shape written by `LicensingApp.bind()` — it's
+ * `Poseidon([pk.x, pk.isOdd.toField()])` over the device's Pallas
+ * pubkey (see `ownerPubKeyHash` in ./licenseLeaf.ts for the identical
+ * shape applied to the ownership pubkey). Callers pass the commitment
+ * to `proveBind` and to the ownership signature; the raw device pubkey
+ * itself never crosses the wire.
+ *
+ * Storage tradeoffs (documented up front — the plan's original
+ * assumption was WebCrypto extractable=false, which only applies to
+ * WebCrypto-native primitives):
+ *
+ *   Browser path — IndexedDB.
+ *     Pallas is not a WebCrypto primitive, so we cannot store the
+ *     private key as a non-extractable CryptoKey. The private key is
+ *     persisted as its Mina canonical base58 encoding. An adversary
+ *     with access to the browser profile (malware running as the user,
+ *     evil browser extension) can read it. This matches the trust
+ *     model of every other browser-persisted secret today (bearer
+ *     cookies, IndexedDB tokens); binding to a fresh device after
+ *     compromise is a keypair regen + one on-chain bind — no funds
+ *     at risk, only slot churn. Users who want stronger storage can
+ *     wipe the storageKey between sessions and re-bind on demand.
+ *
+ *   Node / Electron path — keytar (OS keychain).
+ *     `keytar` is loaded lazily and marked as an optional peer
+ *     dependency in package.json so the browser bundle isn't dragged
+ *     into installing native bindings it can't use. If keytar is
+ *     unavailable at runtime, the SDK throws with a clear message
+ *     rather than falling back to plaintext-on-disk.
+ *
+ * The keypair is Pallas-scalar-random, NOT passphrase-derived — the
+ * device identity is meant to survive a passphrase reset (the user
+ * can re-derive their ownership key from the passphrase, then unbind
+ * / rebind existing device slots without re-installing the app).
+ */
+
+import { PrivateKey, PublicKey, Poseidon } from 'o1js';
+
+// ── Storage key namespacing ───────────────────────────────────────
+
+// All device identities live under this shared prefix in whatever
+// backing store is chosen. Callers pass a per-app / per-installation
+// suffix (e.g. the app's short name) so a single browser profile can
+// hold distinct device identities for distinct vendors' apps.
+const STORAGE_PREFIX = 'zklic_device_';
+
+function namespaced(storageKey: string): string {
+  return `${STORAGE_PREFIX}${storageKey}`;
+}
+
+// ── The identity shape callers get back ──────────────────────────
+
+export type DeviceIdentity = {
+  devicePrivateKey: PrivateKey;
+  devicePubKey:     PublicKey;
+  // Poseidon([pk.x, pk.isOdd.toField()]) as a decimal Field string.
+  // Same shape the on-chain `occupied[i]` slot stores, and the value
+  // /prove/bind expects in its request body. Callers pass this
+  // string directly — no further hashing at the call site.
+  deviceCommitment: string;
+};
+
+/**
+ * Compute the on-chain-shaped device commitment from a Pallas pubkey.
+ * Exported so tests and downstream tooling can re-derive it without
+ * re-instantiating the whole DeviceIdentity.
+ */
+export function computeDeviceCommitment(devicePubKey: PublicKey): string {
+  return Poseidon.hash([devicePubKey.x, devicePubKey.isOdd.toField()]).toString();
+}
+
+function buildIdentity(privateKey: PrivateKey): DeviceIdentity {
+  const devicePubKey = privateKey.toPublicKey();
+  return {
+    devicePrivateKey: privateKey,
+    devicePubKey,
+    deviceCommitment: computeDeviceCommitment(devicePubKey),
+  };
+}
+
+// ── Environment detection ─────────────────────────────────────────
+
+function hasIndexedDB(): boolean {
+  return typeof globalThis !== 'undefined'
+    && typeof (globalThis as any).indexedDB !== 'undefined';
+}
+
+function isNodeLike(): boolean {
+  // Node exposes `process.versions.node`; Deno/Bun don't (their
+  // process shims omit this key). Browsers have no `process` global
+  // unless something's polyfilled it, but the indexedDB branch runs
+  // first so that ordering is fine.
+  return typeof (globalThis as any).process !== 'undefined'
+    && typeof (globalThis as any).process?.versions?.node === 'string';
+}
+
+// ── IndexedDB backing store (browser) ─────────────────────────────
+
+// Small promisified wrapper — no third-party idb library, to keep the
+// SDK dependency surface minimal. Single key/value store; the whole
+// database is one object store with `storageKey` as the key.
+const IDB_DB_NAME = 'zklicensing';
+const IDB_STORE_NAME = 'device_identities';
+const IDB_VERSION = 1;
+
+function openIdb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = (globalThis as any).indexedDB.open(IDB_DB_NAME, IDB_VERSION);
+    req.onupgradeneeded = () => {
+      const db = req.result as IDBDatabase;
+      if (!db.objectStoreNames.contains(IDB_STORE_NAME)) {
+        db.createObjectStore(IDB_STORE_NAME);
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error ?? new Error('IndexedDB open failed'));
+  });
+}
+
+async function idbGet(key: string): Promise<string | null> {
+  const db = await openIdb();
+  try {
+    return await new Promise<string | null>((resolve, reject) => {
+      const tx = db.transaction(IDB_STORE_NAME, 'readonly');
+      const store = tx.objectStore(IDB_STORE_NAME);
+      const req = store.get(key);
+      req.onsuccess = () => resolve((req.result as string | undefined) ?? null);
+      req.onerror = () => reject(req.error ?? new Error('IndexedDB get failed'));
+    });
+  } finally {
+    db.close();
+  }
+}
+
+async function idbPut(key: string, value: string): Promise<void> {
+  const db = await openIdb();
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(IDB_STORE_NAME, 'readwrite');
+      const store = tx.objectStore(IDB_STORE_NAME);
+      const req = store.put(value, key);
+      req.onsuccess = () => resolve();
+      req.onerror = () => reject(req.error ?? new Error('IndexedDB put failed'));
+    });
+  } finally {
+    db.close();
+  }
+}
+
+// ── keytar backing store (Node / Electron) ────────────────────────
+
+// Loaded via dynamic import so a browser bundler doesn't try to
+// resolve the native module. If keytar isn't installed we throw with
+// a message that tells the caller which optional peer dep to add,
+// rather than silently persisting to plaintext.
+async function loadKeytar(): Promise<any> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return await (Function('return import("keytar")')() as Promise<any>);
+  } catch {
+    throw new Error(
+      'deviceIdentity requires the optional peer dependency `keytar` in Node/Electron. ' +
+      'Install it with `npm i keytar` alongside the zklicensing SDK.',
+    );
+  }
+}
+
+// keytar's shape: getPassword(service, account) / setPassword(service, account, value).
+// We use a single service name and let `storageKey` be the account, so
+// multiple apps under the same node install can coexist under distinct
+// storage keys without stomping each other.
+const KEYTAR_SERVICE = 'zklicensing-device-identity';
+
+async function keytarGet(key: string): Promise<string | null> {
+  const keytar = await loadKeytar();
+  const mod = (keytar.default ?? keytar) as { getPassword: (s: string, a: string) => Promise<string | null> };
+  return mod.getPassword(KEYTAR_SERVICE, key);
+}
+
+async function keytarPut(key: string, value: string): Promise<void> {
+  const keytar = await loadKeytar();
+  const mod = (keytar.default ?? keytar) as { setPassword: (s: string, a: string, p: string) => Promise<void> };
+  await mod.setPassword(KEYTAR_SERVICE, key, value);
+}
+
+// ── Backend selection ────────────────────────────────────────────
+
+type Backend = {
+  get: (key: string) => Promise<string | null>;
+  put: (key: string, value: string) => Promise<void>;
+};
+
+function pickBackend(): Backend {
+  if (hasIndexedDB()) return { get: idbGet, put: idbPut };
+  if (isNodeLike())    return { get: keytarGet, put: keytarPut };
+  throw new Error(
+    'deviceIdentity: no suitable storage backend detected. ' +
+    'Expected IndexedDB in the browser or a Node/Electron runtime with `keytar` installed.',
+  );
+}
+
+// ── Public API ────────────────────────────────────────────────────
+
+/**
+ * Load an existing device keypair for `storageKey`, or create + persist
+ * a fresh one on first call. Idempotent across every subsequent call
+ * for the same key on the same install.
+ *
+ * The `storageKey` should be per-app (e.g. the vendor's app short
+ * name or its `appId`), so a single browser profile / OS user account
+ * can hold distinct device identities for distinct vendors without
+ * cross-contamination.
+ */
+export async function getOrCreateDeviceIdentity(storageKey: string): Promise<DeviceIdentity> {
+  if (!storageKey || typeof storageKey !== 'string') {
+    throw new Error('getOrCreateDeviceIdentity: storageKey must be a non-empty string');
+  }
+  const backend = pickBackend();
+  const key = namespaced(storageKey);
+
+  const existing = await backend.get(key);
+  if (existing) {
+    try {
+      const privateKey = PrivateKey.fromBase58(existing);
+      return buildIdentity(privateKey);
+    } catch {
+      // Corrupt persisted value — fall through and mint a fresh key,
+      // overwriting the bad blob. Losing a device identity here is
+      // recoverable: the caller re-binds the new keypair and unbinds
+      // the old slot from any other device that still has the
+      // ownership key.
+    }
+  }
+  const privateKey = PrivateKey.random();
+  await backend.put(key, privateKey.toBase58());
+  return buildIdentity(privateKey);
+}

package/src/freezeClient.ts

@@ -0,0 +1,162 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * freezeClient.ts
+ *
+ * Client-side view of the backend's sales-freeze schedule. A freeze is set
+ * ahead of a hardfork so every open escrow window can drain (refund or
+ * release) before v1 → v2 migration. Once past the freeze slot the backend
+ * refuses new buys and renewals; refunds and verify remain open.
+ *
+ * Resolution order for buy/renew clients that want to know the current
+ * freeze state:
+ *   1. Caller-supplied `freezeAfterSlot` (explicit override — build-time
+ *      constant, or pulled from the vendor's own env at boot).
+ *   2. `process.env.FREEZE_AFTER_SLOT` when running under Node (server-side
+ *      integrators / CLIs).
+ *   3. Backend's own `/health` payload — the authoritative source of truth.
+ *
+ * A `freezeAfterSlot` of 0 / null / undefined means "no freeze scheduled".
+ */
+
+export type NetworkHealth = {
+  graphqlUrl?:     string;
+  archiveUrl?:     string;
+  slot:            number;
+  salesFrozen:     boolean;
+  freezeAfterSlot: number | null;
+};
+
+// GET /health returns one block per configured network:
+//   { status: 'ok', devnet?: NetworkHealth, mainnet?: NetworkHealth }
+// Older keepers returned a single flat block; those fields stay optional here
+// so both shapes typecheck. Use pickNetworkHealth() rather than reading
+// either shape directly.
+export type KeeperHealth = {
+  status:           string;
+  devnet?:          NetworkHealth;
+  mainnet?:         NetworkHealth;
+  /** @deprecated legacy flat shape */
+  network?:         string;
+  /** @deprecated legacy flat shape */
+  slot?:            number;
+  /** @deprecated legacy flat shape */
+  salesFrozen?:     boolean;
+  /** @deprecated legacy flat shape */
+  freezeAfterSlot?: number | null;
+};
+
+/**
+ * The health block for `network`. Without a network: the only configured
+ * one, or null when several are configured (ambiguous). Falls back to the
+ * legacy flat shape.
+ */
+export function pickNetworkHealth(health: KeeperHealth, network?: 'devnet' | 'mainnet'): NetworkHealth | null {
+  const nested = (['devnet', 'mainnet'] as const).filter(n => health[n] && typeof health[n]!.slot === 'number');
+  if (nested.length > 0) {
+    if (network) return health[network] ?? null;
+    return nested.length === 1 ? health[nested[0]]! : null;
+  }
+  if (typeof health.slot === 'number' || typeof health.salesFrozen === 'boolean') {
+    return {
+      slot:            typeof health.slot === 'number' ? health.slot : 0,
+      salesFrozen:     health.salesFrozen === true,
+      freezeAfterSlot: typeof health.freezeAfterSlot === 'number' ? health.freezeAfterSlot : null,
+    };
+  }
+  return null;
+}
+
+export type FreezeState = {
+  // True when the current slot is past freezeAfterSlot — new buys and
+  // renewals are refused backend-side.
+  salesFrozen:     boolean;
+  // Scheduled freeze slot (announced ahead of a hardfork). Null when no
+  // freeze is configured. Buy clients should require an explicit
+  // refund-window waiver only when the buyer's 14-day refund window would
+  // extend past this slot (i.e. currentSlot + REFUND_WINDOW_N > freezeAfterSlot).
+  freezeAfterSlot: number | null;
+  // Chain slot at resolution time. Populated from /health; null on the
+  // caller-override / env paths where the slot is not known client-side.
+  // Callers computing refund-window overlap should treat null
+  // conservatively (require the waiver) — the backend's own guard is still
+  // the last line of defence.
+  currentSlot:     number | null;
+};
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+function envFreezeSlot(): number | null {
+  // Runs both in Node (process.env) and browser (no `process`). The typeof
+  // guard keeps bundlers from choking on the reference.
+  if (typeof process === 'undefined' || !process.env) return null;
+  const raw = process.env.FREEZE_AFTER_SLOT;
+  if (!raw) return null;
+  const n = parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export type GetKeeperHealthOptions = {
+  keeperUrl: string;
+  fetcher?:  typeof fetch;
+  signal?:   AbortSignal;
+};
+
+// GET /health — raw payload. Callers that only need the freeze state
+// should use resolveFreezeState() instead; this is exposed for UIs that
+// surface slot / network info alongside freeze.
+export async function getKeeperHealth(opts: GetKeeperHealthOptions): Promise<KeeperHealth> {
+  const fetcher = opts.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(opts.keeperUrl)}/health`, { signal: opts.signal });
+  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+  return await resp.json() as KeeperHealth;
+}
+
+export type ResolveFreezeStateOptions = {
+  keeperUrl:        string;
+  // Network the action targets. Needed to read the right block of a
+  // multi-network /health response.
+  network?:         'devnet' | 'mainnet';
+  // Explicit override (highest precedence). Null/undefined falls through
+  // to env, then /health.
+  freezeAfterSlot?: number | null;
+  fetcher?:         typeof fetch;
+  signal?:          AbortSignal;
+};
+
+// Resolves the effective freeze state for the caller. When the source is
+// the caller override or process.env, the current slot is not known
+// client-side, so salesFrozen is filled from /health only — the override
+// path returns { freezeAfterSlot: N, salesFrozen: false, currentSlot: null }
+// and lets the backend reject the actual prove call if the freeze has fired.
+export async function resolveFreezeState(opts: ResolveFreezeStateOptions): Promise<FreezeState> {
+  if (typeof opts.freezeAfterSlot === 'number' && opts.freezeAfterSlot > 0) {
+    return { salesFrozen: false, freezeAfterSlot: opts.freezeAfterSlot, currentSlot: null };
+  }
+  const envSlot = envFreezeSlot();
+  if (envSlot !== null) {
+    return { salesFrozen: false, freezeAfterSlot: envSlot, currentSlot: null };
+  }
+  try {
+    const health = await getKeeperHealth({
+      keeperUrl: opts.keeperUrl,
+      fetcher:   opts.fetcher,
+      signal:    opts.signal,
+    });
+    const net = pickNetworkHealth(health, opts.network);
+    if (!net) return { salesFrozen: false, freezeAfterSlot: null, currentSlot: null };
+    return {
+      salesFrozen:     net.salesFrozen === true,
+      freezeAfterSlot: typeof net.freezeAfterSlot === 'number' && net.freezeAfterSlot > 0 ? net.freezeAfterSlot : null,
+      currentSlot:     typeof net.slot === 'number' && net.slot > 0 ? net.slot : null,
+    };
+  } catch {
+    // /health unreachable — treat as no freeze so we don't block buys on a
+    // transient network hiccup. The backend's own guard is still the last
+    // line of defense.
+    return { salesFrozen: false, freezeAfterSlot: null, currentSlot: null };
+  }
+}

package/src/generationClient.ts

@@ -0,0 +1,145 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * generationClient.ts
+ *
+ * Browser-safe fetcher for the backend's signed generation-list. Returns the
+ * app's deployment history — every past address plus the current live one —
+ * verified against a caller-supplied pin list of platform manifest public
+ * keys.
+ *
+ * Trust model: the backend is not the trust anchor for this data — it can
+ * be re-hosted, mirrored, cached, or (worst case) impersonated. The pin
+ * list is. Any response that fails signature verification is surfaced as
+ * `verified: false` with `generations: []` so callers cannot accidentally
+ * route a wallet prompt to an unverified address.
+ *
+ * Optional corroboration channel: an operator that publishes
+ *   https://<vendor-host>/.well-known/zklicensing/<zkAppAddress>.json
+ * (using the same backend-signed payload) can be cross-checked from the
+ * on-chain zkappUri. One file per deployed address (so per generation),
+ * because a vendor may host several apps at one origin. The cross-check is opt-in per-app — a 404 at that
+ * URL is not a failure signal, just "no corroboration published for this
+ * app." That's the caller's job, not this module's.
+ */
+
+import { verifyManifest } from './manifestVerify.js';
+
+export interface GenerationEntry {
+  gen:          number;
+  zkAppAddress: string;
+  status:       'retired' | 'live';
+  frozenRoot?:  string;
+  deployedAt?:  string;
+  retiredAt?:   string;
+}
+
+export interface GenerationInfo {
+  /** Live-generation index (matches the entry with status: 'live'). Null when unverified or missing. */
+  current:     number | null;
+  generations: GenerationEntry[];
+  /** True iff signature verified against one of the pinned pubkeys. */
+  verified:    boolean;
+}
+
+export interface FetchGenerationRequest {
+  keeperUrl: string;
+  network:  'devnet' | 'mainnet';
+  appId:    string;
+  /** Base64-encoded Ed25519 public keys pinned by the caller. Empty ⇒ verified:false. */
+  pinnedPublicKeysBase64: readonly string[];
+  fetcher?: typeof fetch;
+  signal?:  AbortSignal;
+}
+
+export interface FetchGenerationByAddressRequest {
+  keeperUrl: string;
+  /** When given, a list signed for the other network is refused. */
+  network?: 'devnet' | 'mainnet';
+  /** Any zkApp address in the app's generation chain — current live or any retired. */
+  zkAppAddress: string;
+  /** Base64-encoded Ed25519 public keys pinned by the caller. Empty ⇒ verified:false. */
+  pinnedPublicKeysBase64: readonly string[];
+  fetcher?: typeof fetch;
+  signal?:  AbortSignal;
+}
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+/**
+ * The verified generation list in a keeper response: a platform signature
+ * from a pinned key (current or, during a key rotation, the previous one)
+ * over the signed fields, for `network` when given. Unverified data is
+ * never surfaced: a caller must not route a wallet prompt to an address we
+ * couldn't authenticate.
+ */
+async function verifyAndProject(
+  body: unknown,
+  pinnedPublicKeysBase64: readonly string[],
+  network?: 'devnet' | 'mainnet',
+): Promise<GenerationInfo> {
+  const signed = await verifyManifest(body, pinnedPublicKeysBase64, network ? { network } : {});
+  if (!signed) return { current: null, generations: [], verified: false };
+  return { current: signed.current, generations: signed.generations as GenerationEntry[], verified: true };
+}
+
+/**
+ * GET /apps/:appId — returns { appId, current, generations, issuedAt, publicKey, signature }.
+ * We reconstruct the canonical payload (everything except `publicKey` +
+ * `signature`) and verify against the pin list. `publicKey` in the response
+ * is advisory only — it's the key the backend claims to have signed with;
+ * the SDK never trusts it in place of a pin.
+ */
+export async function fetchGenerationInfo(req: FetchGenerationRequest): Promise<GenerationInfo> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/apps/${encodeURIComponent(req.appId)}?network=${req.network}`, {
+    method: 'GET',
+    signal: req.signal,
+  });
+  if (!resp.ok) {
+    return { current: null, generations: [], verified: false };
+  }
+  let body: Record<string, unknown>;
+  try { body = await resp.json() as Record<string, unknown>; }
+  catch { return { current: null, generations: [], verified: false }; }
+
+  return verifyAndProject(body, req.pinnedPublicKeysBase64, req.network);
+}
+
+/**
+ * GET /apps/by-address/:zkAppAddress — same signed payload as fetchGenerationInfo,
+ * but keyed by an address the caller already has (direct-paste buys, renew on a
+ * since-retired address). Buyers arriving without an appId would otherwise have
+ * to trust the backend's unsigned `/apps` list to bind their address to an appId
+ * first — defeating the pin.
+ *
+ * Extra assertion beyond the appId flow: the queried address MUST appear in the
+ * returned `generations[]`. Without this, a malicious backend could return a
+ * validly-signed payload for a DIFFERENT app in response to the query, and the
+ * signature check alone wouldn't catch it.
+ */
+export async function fetchGenerationInfoByAddress(
+  req: FetchGenerationByAddressRequest,
+): Promise<GenerationInfo> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(
+    `${baseUrl(req.keeperUrl)}/apps/by-address/${encodeURIComponent(req.zkAppAddress)}`,
+    { method: 'GET', signal: req.signal },
+  );
+  if (!resp.ok) {
+    return { current: null, generations: [], verified: false };
+  }
+  let body: Record<string, unknown>;
+  try { body = await resp.json() as Record<string, unknown>; }
+  catch { return { current: null, generations: [], verified: false }; }
+
+  const projected = await verifyAndProject(body, req.pinnedPublicKeysBase64, req.network);
+  if (!projected.verified) return projected;
+  if (!projected.generations.some(g => g.zkAppAddress === req.zkAppAddress)) {
+    return { current: null, generations: [], verified: false };
+  }
+  return projected;
+}

package/src/holderSecret.ts

@@ -0,0 +1,91 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * holderSecret.ts — the permit holder's secret for anonymous proofs
+ * (see permitProof.ts). Light: no ZkProgram, so clients can derive it when
+ * applying without loading the proof.
+ */
+
+import { Field, Poseidon, PublicKey } from 'o1js';
+import { networkField, permitSubject, type PermitNetwork } from './permitMessages.js';
+
+/** Tags for the holder secret's signed message and for the salt derived from it. */
+export const HOLDER_SECRET_TAG: Field = Field([...'zkPermits/v1/holder-secret'].reduce((v, ch) => (v << 8n) | BigInt(ch.charCodeAt(0)), 0n));
+export const HOLDER_SALT_TAG: Field = Field([...'zkPermits/v1/holder-salt'].reduce((v, ch) => (v << 8n) | BigInt(ch.charCodeAt(0)), 0n));
+
+/** How many counter values recovery tries: one key rarely holds more permits in one registry. */
+export const MAX_HOLDER_SECRETS = 16;
+
+/**
+ * What the holder's wallet signs (a text signature, signMessage) to derive a
+ * secret: the registry's lineage, its network and a counter: 0 for the
+ * key's first permit in the registry, 1 for the next, and so on. The
+ * lineage is the registry's first generation's address (the keeper's
+ * `registry.lineage`; the address itself for a registry never redeployed),
+ * so a permit's secret stays the same when the registry moves to a new
+ * address. Readable in the wallet, and nothing needs to be kept: the holder
+ * re-derives the secret from the chain and the wallet alone (findHolderSecret).
+ */
+export function holderSecretText(lineage: string, network: PermitNetwork, index: number): string {
+  if (!Number.isSafeInteger(index) || index < 0) throw new Error('holder secret index must be a non-negative integer');
+  PublicKey.fromBase58(lineage);
+  networkField(network);
+  return [
+    'zkPermits: recover my permit secret',
+    `registry: ${lineage}`,
+    `network: ${network}`,
+    `permit number: ${index}`,
+    'Sign this only on zkLicensing pages: it lets the signer recognise this permit\'s anonymous proofs.',
+  ].join('\n');
+}
+
+/** The holder secret from the wallet's (deterministic) text signature over holderSecretText. */
+export function holderSecretFromSignature(sig: { field: string; scalar: string }): Field {
+  const scalar = BigInt(sig.scalar);
+  const low = scalar & ((1n << 128n) - 1n);
+  return Poseidon.hash([HOLDER_SECRET_TAG, Field(BigInt(sig.field)), Field(scalar >> 128n), Field(low)]);
+}
+
+/** The permit's salt: public to the keeper and the authority, and reveals nothing about the secret. */
+export function saltFromHolderSecret(holderSecret: Field): Field {
+  return Poseidon.hash([HOLDER_SALT_TAG, holderSecret]);
+}
+
+type TextWallet = { address: string; signMessage(message: string): Promise<{ field: string; scalar: string }> };
+
+/** Derives the secret, salt and permit subject for counter `index` (one wallet signature). */
+export async function deriveHolderSecret(
+  wallet: TextWallet,
+  args: { lineage: string; network: PermitNetwork; index: number },
+): Promise<{ secret: string; salt: string; subject: string; index: number }> {
+  const signature = await wallet.signMessage(holderSecretText(args.lineage, args.network, args.index));
+  const secret = holderSecretFromSignature(signature);
+  const salt = saltFromHolderSecret(secret);
+  return { secret: secret.toString(), salt: salt.toString(), subject: permitSubject(PublicKey.fromBase58(wallet.address), salt).toString(), index: args.index };
+}
+
+/**
+ * Recovers the secret of the permit `subject` held by this wallet: signs for
+ * counter 0, 1, 2… until one gives that subject (usually the first). Throws
+ * when none does: another wallet, or a permit issued before secrets were
+ * derived this way.
+ */
+export async function findHolderSecret(
+  wallet: TextWallet,
+  args: { lineage: string; network: PermitNetwork; subject: string; maxTries?: number },
+): Promise<{ secret: string; index: number }> {
+  for (let index = 0; index < (args.maxTries ?? MAX_HOLDER_SECRETS); index++) {
+    const d = await deriveHolderSecret(wallet, { lineage: args.lineage, network: args.network, index });
+    if (d.subject === args.subject) return { secret: d.secret, index };
+  }
+  throw new Error('This wallet derives no secret for this permit: is it the wallet the permit was applied for with, on this network?');
+}
+
+/**
+ * True when `holderSecret` belongs to the permit (subject = H(holderKey, salt(secret))).
+ * Check before proving, for a clear error instead of a failed proof.
+ */
+export function holderSecretMatches(holderKey: string, subject: string, holderSecret: string): boolean {
+  return permitSubject(PublicKey.fromBase58(holderKey), saltFromHolderSecret(Field(holderSecret))).toString() === subject;
+}