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

package/src/ownershipSignature.ts

@@ -0,0 +1,421 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * ownershipSignature.ts
+ *
+ * Schnorr-over-Pallas signing primitive for the two on-chain flows that
+ * need the passphrase-derived owner key:
+ *
+ *  1. The /prove/bind and /prove/unbind flows — the passphrase-derived
+ *     keypair authorizes device slot mutations, and the signature is
+ *     re-verified INSIDE the circuit by `Signature.verify()` so even a
+ *     compromised licensing service cannot forge a bind.
+ *  2. The retained `ActivationMessage` shape (see below) — kept so external
+ *     tooling can still sign an "I hold the passphrase for this license"
+ *     assertion off-band. The platform no longer runs a challenge/respond
+ *     endpoint; the shape is purely an SDK primitive now.
+ *
+ * Deterministic HKDF-SHA256 derivation of a seed from the passphrase,
+ * reduced to a Pallas scalar → o1js `PrivateKey`. The buyer can
+ * re-derive the same keypair anywhere from just the passphrase.
+ *
+ * o1js-dependent by design: the whole point of switching from Ed25519 to
+ * Pallas Schnorr is native in-circuit verification. Any client that
+ * signs an activation or binding challenge already ships o1js for the
+ * downstream buy/verify surface, so the "keep this module o1js-free"
+ * constraint that motivated the Ed25519 version no longer applies.
+ *
+ * HKDF still needs WebCrypto (Node ≥ 20, Chromium 137+, Safari 17+,
+ * Firefox 130+). The module throws at derive time if
+ * `globalThis.crypto.subtle` is unavailable — callers cannot silently
+ * fall back to a weaker path.
+ */
+
+import { Field, PrivateKey, PublicKey, Signature, UInt32 } from 'o1js';
+import { packSlotTimes } from './licenseLeaf.js';
+import { licenseHashFromPubkey } from './ownershipLicenseHash.js';
+
+// HKDF info binds the derivation to a specific zkApp address, so the
+// same passphrase yields different keypairs for different apps. This
+// makes credentials per-app: a leaked passphrase for app A cannot be
+// replayed as an activation for app B. RFC 5869 designates `info` as
+// the domain-separation channel (salt is for randomness, which we don't
+// have here — the passphrase IS the secret input).
+//
+// The `v1` prefix reserves room to rotate the KDF or the target key type
+// later without a silent collision — a future scheme bumps to `v2` and
+// derives an unrelated key from the same passphrase.
+const HKDF_INFO_PREFIX = 'zkLicensing/v1/ownership|';
+const HKDF_SALT = new Uint8Array(0);
+
+// Domain-separation tags baked into every signed message. Prevents a
+// signature captured on one flow (activation) from being replayed on
+// another (binding) — the first Field the signer hashes is the flow ID,
+// so the two signatures live in disjoint spaces even at identical
+// (licenseHash, nonce).
+//
+// Exported so `LicensingApp.bind()` / `unbind()` can rebuild the exact
+// same Field[] preimage inside the circuit for `Signature.verify()`.
+// Bumping these values is a hardfork — every off-chain signer and every
+// deployed circuit would need to agree.
+export const TAG_ACTIVATION = 1n;
+export const TAG_BINDING    = 2n;
+export const TAG_UNBINDING  = 3n;
+
+function buildHkdfInfo(zkAppAddress: string): Uint8Array {
+  return new TextEncoder().encode(HKDF_INFO_PREFIX + zkAppAddress);
+}
+
+function utf8Bytes(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let s = '';
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s);
+}
+
+function base64ToBytes(b64: string): Uint8Array {
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function subtle(): SubtleCrypto {
+  const s = (globalThis.crypto as Crypto | undefined)?.subtle;
+  if (!s) {
+    throw new Error(
+      'WebCrypto unavailable — ownershipSignature requires Node ≥ 20 or a modern browser (Chromium 137+, Safari 17+, Firefox 130+).',
+    );
+  }
+  return s;
+}
+
+function bytesToBigInt(bytes: Uint8Array): bigint {
+  let n = 0n;
+  for (const b of bytes) n = (n << 8n) | BigInt(b);
+  return n;
+}
+
+/**
+ * HKDF-SHA256 with empty salt and a per-app domain-separation info
+ * string (`zkLicensing/v1/ownership|<zkAppAddress>`). Deterministic:
+ * same (passphrase, zkAppAddress) → same 32-byte seed. Different
+ * zkAppAddress → cryptographically unrelated seed even with the same
+ * passphrase.
+ */
+export async function deriveSeed(
+  passphrase:   string,
+  zkAppAddress: string,
+): Promise<Uint8Array> {
+  const baseKey = await subtle().importKey(
+    'raw',
+    utf8Bytes(passphrase) as unknown as ArrayBuffer,
+    'HKDF',
+    false,
+    ['deriveBits'],
+  );
+  const info = buildHkdfInfo(zkAppAddress);
+  const bits = await subtle().deriveBits(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: HKDF_SALT as unknown as ArrayBuffer,
+      info: info as unknown as ArrayBuffer,
+    },
+    baseKey,
+    256,
+  );
+  return new Uint8Array(bits);
+}
+
+export type OwnershipKeypair = {
+  privateKey:      PrivateKey;
+  publicKey:       PublicKey;
+  publicKeyBase58: string;
+};
+
+/**
+ * Derive a Pallas Schnorr keypair deterministically from (passphrase,
+ * zkAppAddress). The keypair is bound to the specific app: the same
+ * passphrase used against a different app yields a different keypair,
+ * so a leaked passphrase cannot be replayed as an activation for any
+ * other app.
+ *
+ * The 32-byte HKDF output is interpreted as a big-endian integer and
+ * passed to `PrivateKey.fromBigInt`, which reduces it modulo the Pallas
+ * scalar field order internally. All 2^256 possible HKDF outputs map to
+ * valid private keys with (256 - log2(Fq_order))-bit modular bias — the
+ * scalar field is ~254 bits, so bias is <2^-253 and lies well below any
+ * practical distinguisher.
+ */
+export async function deriveOwnershipKeypair(
+  passphrase:   string,
+  zkAppAddress: string,
+): Promise<OwnershipKeypair> {
+  const seed = await deriveSeed(passphrase, zkAppAddress);
+  const privateKey = PrivateKey.fromBigInt(bytesToBigInt(seed));
+  const publicKey = privateKey.toPublicKey();
+  return { privateKey, publicKey, publicKeyBase58: publicKey.toBase58() };
+}
+
+/**
+ * The ownership keypair of license `licenseHash`, trying each candidate app
+ * address in turn. The key is derived from the address the license was
+ * issued on; after a redeploy the license carries over to the successor
+ * unchanged, so its key is the earlier generation's. Pass the app's
+ * generation addresses (any order; the live one first is cheapest for new
+ * licenses). A wrong address only gives a key that doesn't match, so the
+ * list needn't be authenticated. Null when none matches (another passphrase).
+ */
+export async function findOwnershipKeypair(
+  passphrase: string,
+  licenseHash: string,
+  candidateAddresses: readonly string[],
+): Promise<(OwnershipKeypair & { zkAppAddress: string }) | null> {
+  for (const zkAppAddress of [...new Set(candidateAddresses)]) {
+    const kp = await deriveOwnershipKeypair(passphrase, zkAppAddress);
+    if (licenseHashFromPubkey(kp.publicKey) === licenseHash) return { ...kp, zkAppAddress };
+  }
+  return null;
+}
+
+/**
+ * The addresses of every generation of the app at `zkAppAddress` (any of
+ * them), live first, from the keeper's generation list; just
+ * `zkAppAddress` when the keeper doesn't know it. For findOwnershipKeypair.
+ */
+export async function ownershipCandidateAddresses(keeperUrl: string, zkAppAddress: string, fetcher: typeof fetch = fetch): Promise<string[]> {
+  try {
+    const r = await fetcher(`${keeperUrl.replace(/\/+$/, '')}/apps/by-address/${encodeURIComponent(zkAppAddress)}`);
+    if (!r.ok) return [zkAppAddress];
+    const body = await r.json() as { generations?: Array<{ gen: number; zkAppAddress: string }> };
+    const gens = Array.isArray(body.generations) ? [...body.generations].sort((a, b) => b.gen - a.gen).map(g => g.zkAppAddress) : [];
+    return [...new Set([zkAppAddress, ...gens])];
+  } catch {
+    return [zkAppAddress];
+  }
+}
+
+// ── Message shapes ────────────────────────────────────────────────
+
+/**
+ * Activation assertion shape. Proves the caller holds the passphrase
+ * that derived the license's ownerPubKey. Retained as an SDK primitive
+ * so external tooling can still request / verify an off-band "I own
+ * this license" signature — the on-chain flows themselves do not use
+ * it.
+ */
+export type ActivationMessage = {
+  licenseHash:  string;   // Field as decimal string
+  nonce:        string;   // Field as decimal string — replay defense
+  zkAppAddress: string;   // base58
+};
+
+/**
+ * Binding / unbinding message — the /prove/bind and /prove/unbind
+ * flows. Authorizes a specific device commitment being placed into or
+ * cleared from a specific slot on a specific license.
+ */
+export type BindingMessage = {
+  licenseHash:      string;   // Field as decimal string
+  deviceCommitment: string;   // Field as decimal string (Poseidon(devicePubKeyHash))
+  slotIndex:        number;   // 0..cap-1
+  nonce:            string;   // Field as decimal string
+  // Target slot's current packed (boundAt, freedAt) — see slotStateOf().
+  // Every bind/unbind changes it, so a signature authorizes exactly one
+  // transition and cannot be replayed once the slot has moved on.
+  slotState:        string;   // Field as decimal string
+  // The license leaf's current expirySlot. A refund + re-buy with the same
+  // passphrase resets every slot to pristine; the new leaf's expiry differs,
+  // so signatures from the earlier purchase stay dead.
+  expirySlot:       number;
+  zkAppAddress:     string;   // base58 — stops cross-deployment replay
+};
+
+/**
+ * Packed (boundAt, freedAt) of one slot as the circuit sees it — the
+ * `slotState` a BindingMessage must commit to. Takes the slot entry from a
+ * LicenseRecord's `devices[]` (as served by GET /license/:zkApp/:hash);
+ * an absent entry is a pristine slot (0).
+ */
+export function slotStateOf(
+  device?: { boundAtSlot: number; freedAtSlot: number } | null,
+): string {
+  if (!device) return '0';
+  return packSlotTimes(UInt32.from(device.boundAtSlot), UInt32.from(device.freedAtSlot)).toString();
+}
+
+// Retained for back-compat with callers that imported ChallengeMessage
+// from this module before the v2 rename. New code should use
+// ActivationMessage directly.
+export type ChallengeMessage = ActivationMessage;
+
+/**
+ * Canonicalize the activation message into the Field[] that
+ * `Signature.create` / `Signature.verify` hash. The domain-separation
+ * tag prefix means no captured activation signature can be replayed as
+ * a binding signature, even if all other fields collide.
+ */
+export function activationMessageFields(msg: ActivationMessage): Field[] {
+  const addr = PublicKey.fromBase58(msg.zkAppAddress);
+  return [
+    Field(TAG_ACTIVATION),
+    Field(msg.licenseHash),
+    Field(msg.nonce),
+    addr.x,
+    addr.isOdd.toField(),
+  ];
+}
+
+/**
+ * Canonicalize a binding or unbinding message. The `tag` argument
+ * distinguishes bind (TAG_BINDING) from unbind (TAG_UNBINDING) so a
+ * bind signature captured off-chain cannot be replayed as an unbind
+ * even at identical (licenseHash, deviceCommitment, slotIndex, nonce).
+ */
+function bindingLikeFields(tag: bigint, msg: BindingMessage): Field[] {
+  const addr = PublicKey.fromBase58(msg.zkAppAddress);
+  return [
+    Field(tag),
+    Field(msg.licenseHash),
+    Field(msg.deviceCommitment),
+    Field(msg.slotIndex),
+    Field(msg.nonce),
+    Field(msg.slotState),
+    Field(msg.expirySlot),
+    addr.x,
+    addr.isOdd.toField(),
+  ];
+}
+
+export function bindingMessageFields(msg: BindingMessage): Field[] {
+  return bindingLikeFields(TAG_BINDING, msg);
+}
+
+export function unbindingMessageFields(msg: BindingMessage): Field[] {
+  return bindingLikeFields(TAG_UNBINDING, msg);
+}
+
+// ── Signing ───────────────────────────────────────────────────────
+
+export function signActivation(
+  privateKey: PrivateKey,
+  msg: ActivationMessage,
+): Signature {
+  return Signature.create(privateKey, activationMessageFields(msg));
+}
+
+export function signBinding(
+  privateKey: PrivateKey,
+  msg: BindingMessage,
+): Signature {
+  return Signature.create(privateKey, bindingMessageFields(msg));
+}
+
+export function signUnbinding(
+  privateKey: PrivateKey,
+  msg: BindingMessage,
+): Signature {
+  return Signature.create(privateKey, unbindingMessageFields(msg));
+}
+
+// Retained for back-compat with the Ed25519-era name. New code should
+// call signActivation directly.
+export function signChallenge(
+  privateKey: PrivateKey,
+  msg: ChallengeMessage,
+): Signature {
+  return signActivation(privateKey, msg);
+}
+
+// ── Verification ──────────────────────────────────────────────────
+
+/**
+ * Verify an activation signature. Returns false (never throws) for any
+ * failure — malformed pubkey, malformed signature, actual signature
+ * mismatch. Callers get a single go/no-go decision without having to
+ * distinguish "invalid" from "unparseable."
+ */
+export function verifyActivation(
+  publicKey: PublicKey,
+  msg: ActivationMessage,
+  signature: Signature,
+): boolean {
+  try {
+    return signature.verify(publicKey, activationMessageFields(msg)).toBoolean();
+  } catch {
+    return false;
+  }
+}
+
+export function verifyBinding(
+  publicKey: PublicKey,
+  msg: BindingMessage,
+  signature: Signature,
+): boolean {
+  try {
+    return signature.verify(publicKey, bindingMessageFields(msg)).toBoolean();
+  } catch {
+    return false;
+  }
+}
+
+export function verifyUnbinding(
+  publicKey: PublicKey,
+  msg: BindingMessage,
+  signature: Signature,
+): boolean {
+  try {
+    return signature.verify(publicKey, unbindingMessageFields(msg)).toBoolean();
+  } catch {
+    return false;
+  }
+}
+
+// Back-compat alias, see signChallenge.
+export function verifyChallenge(
+  publicKey: PublicKey,
+  msg: ChallengeMessage,
+  signature: Signature,
+): boolean {
+  return verifyActivation(publicKey, msg, signature);
+}
+
+// ── Wire encoding helpers ─────────────────────────────────────────
+
+/**
+ * Encode a signature for the wire (POST body, ProofFile JSON, etc).
+ * Base58 matches Mina's canonical serialization for both PublicKey and
+ * Signature, keeping the same encoding shape across everything the
+ * buyer's SDK produces.
+ */
+export function encodeSignature(sig: Signature): string {
+  return sig.toBase58();
+}
+
+export function decodeSignature(base58: string): Signature {
+  return Signature.fromBase58(base58);
+}
+
+export function encodePublicKey(pk: PublicKey): string {
+  return pk.toBase58();
+}
+
+export function decodePublicKey(base58: string): PublicKey {
+  return PublicKey.fromBase58(base58);
+}
+
+// Retained so callers that already do `encodeBase64(seed)` for logging
+// or persistence keep working — this module no longer produces raw byte
+// pubkeys or signatures, only o1js objects with .toBase58().
+export function encodeBase64(bytes: Uint8Array): string {
+  return bytesToBase64(bytes);
+}
+
+export function decodeBase64(b64: string): Uint8Array {
+  return base64ToBytes(b64);
+}

package/src/permitCheckFlow.ts

@@ -0,0 +1,227 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * permitCheckFlow.ts — `zklicensing/permits/check`
+ *
+ * Anonymous permit checks through the keeper's relay (verify.html's
+ * Anonymous mode and prove.html use this; so can any checker or holder app).
+ *
+ *   checker:  openCheck (or createCheckEvent + openCheck in it) → show the
+ *             check's link → verifyCheck once the holder has proved
+ *   holder:   proveForCheck(checkId, permit file, wallet)
+ *
+ * The challenge is bound to the site both sides are on: context =
+ * verifierContext(origin, check nonce). The holder builds its Merkle witness
+ * from a compact copy of the whole registry (zklicensing/permits/tree), so
+ * the keeper never learns which permit is being proved; the proof itself
+ * reveals nothing about it. The checker verifies the proof itself, against roots from the keeper or, with
+ * `trustless`, from a Mina node.
+ */
+
+import { Field, MerkleMap, PublicKey } from 'o1js';
+import { permitLeafHash } from './permitMessages.js';
+import { recordToLeaf, permitStatusAt, type PermitRecord } from './permitRegistryRebuild.js';
+import { syncRegistryTree, witnessFromCompactTree, type TreeCache } from './permitTree.js';
+import type { PermitMessageDescription } from './permitDescribe.js';
+
+export type Network = 'devnet' | 'mainnet';
+
+export type CheckView = {
+  id: string; network: Network; registry: string; requiredScope: string; label: string; nonce: string;
+  createdAt: string; expiresAt: string; status: 'waiting' | 'proved' | 'expired';
+  event?: { id: string; label: string; expiresAt: string };
+};
+export type CheckEventView = { id: string; network: Network; registry: string; requiredScope: string; label: string; createdAt: string; expiresAt: string };
+
+/**
+ * The holder's permit file (from the apply page): no secret in it. `registry`
+ * is where it was issued; `lineage`, that registry's first generation's
+ * address (what its secret is derived against; `registry` when absent).
+ */
+export type PermitFileRef = { registry: string; subject: string; holderKey: string; network?: string; lineage?: string };
+
+export class CheckError extends Error {
+  constructor(message: string, readonly code: string, readonly status = 0) { super(message); this.name = 'CheckError'; }
+}
+
+/** The keeper's check relay. */
+export function createCheckRelay(keeperUrl: string, fetcher: typeof fetch = fetch) {
+  const base = keeperUrl.replace(/\/+$/, '');
+  async function call<T>(method: string, path: string, body?: unknown, headers: Record<string, string> = {}): Promise<T> {
+    const r = await fetcher(base + path, {
+      method, cache: 'no-store',
+      headers: { Accept: 'application/json', ...(body === undefined ? {} : { 'Content-Type': 'application/json' }), ...headers },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const j: any = await r.json().catch(() => null);
+    if (!r.ok) throw new CheckError(j?.error ?? `HTTP ${r.status}`, j?.code ?? 'HTTP_ERROR', r.status);
+    return j as T;
+  }
+  return {
+    /** A single check: its own nonce, so its nullifier never repeats. */
+    openCheck: (a: { registry: string; network?: Network; requiredScope?: string; label?: string }) =>
+      call<{ check: CheckView }>('POST', '/permits/checks', a).then(r => r.check),
+    /** A check in an event (the event's nonce), opened with the event key. */
+    openEventCheck: (eventId: string, eventKey: string) =>
+      call<{ check: CheckView }>('POST', '/permits/checks', { eventId }, { 'X-Event-Key': eventKey }).then(r => r.check),
+    getCheck: (id: string) => call<{ check: CheckView; proof?: unknown; provedAt?: string }>('GET', `/permits/checks/${encodeURIComponent(id)}`),
+    submitProof: (id: string, proof: unknown) => call<{ ok: true }>('POST', `/permits/checks/${encodeURIComponent(id)}/proof`, { proof }),
+    createEvent: (a: { registry: string; network?: Network; requiredScope?: string; label: string; days?: number }) =>
+      call<{ event: CheckEventView; eventKey: string }>('POST', '/permits/check-events', a),
+    getEvent: (id: string) => call<{ event: CheckEventView }>('GET', `/permits/check-events/${encodeURIComponent(id)}`).then(r => r.event),
+    /** Records a verified nullifier at the event: first use there, or when it was first seen. */
+    markSeen: (eventId: string, eventKey: string, nullifier: string) =>
+      call<{ firstUse: boolean; firstSeenAt: string; count: number }>('POST', `/permits/check-events/${encodeURIComponent(eventId)}/seen`, { nullifier }, { 'X-Event-Key': eventKey }),
+    seenCount: (eventId: string, eventKey: string) =>
+      call<{ count: number }>('GET', `/permits/check-events/${encodeURIComponent(eventId)}/seen`, undefined, { 'X-Event-Key': eventKey }).then(r => r.count),
+    /** The registry's compact tree (zklicensing/permits/tree), or with `since` the changes since that root. */
+    getTree: (registry: string, since?: string) =>
+      call<any>('GET', `/permits/registries/${encodeURIComponent(registry)}/tree${since ? `?since=${encodeURIComponent(since)}` : ''}`),
+    getRoots: (registry: string) => call<{ roots: Array<{ root: string; slot: number }>; current: string; slot: number }>('GET', `/permits/registries/${encodeURIComponent(registry)}/roots`),
+  };
+}
+
+/** The Merkle witness for `subject`, built locally from all of a registry's permits. */
+export function witnessFromPermits(permits: PermitRecord[], subject: string): { root: string; witness: { isLefts: boolean[]; siblings: string[] } } {
+  const map = new MerkleMap();
+  for (const p of permits) map.set(Field(p.subject), permitLeafHash(recordToLeaf(p)));
+  const w = map.getWitness(Field(subject));
+  return { root: map.getRoot().toString(), witness: { isLefts: w.isLefts.map(b => b.toBoolean()), siblings: w.siblings.map(s => s.toString()) } };
+}
+
+export type ProveStep = 'check' | 'registry' | 'sign-secret' | 'sign-proof' | 'compile-prove' | 'send';
+
+/**
+ * Holder: proves to a check that this wallet holds an active permit covering
+ * the check's activities, and sends the proof. `origin` is the site the
+ * holder is on (the check's verifier). Two wallet signatures: one re-derives
+ * the permit's secret, one authorises the proof.
+ */
+export async function proveForCheck(opts: {
+  keeperUrl: string;
+  network: Network;
+  checkId: string;
+  permit: PermitFileRef;
+  wallet: { address: string; signFields(fields: string[]): Promise<string>; signMessage(message: string): Promise<{ field: string; scalar: string }> };
+  origin: string;
+  graphqlUrl?: string;
+  fetcher?: typeof fetch;
+  /** Where to keep registry copies between checks (IndexedDB in a browser); without one, each check downloads the registry. */
+  treeCache?: TreeCache;
+  onStep?: (step: ProveStep) => void;
+  /** Shown before the proof's field signature (as PermitsClientOptions.confirmSignature); false cancels. */
+  confirmSignature?: (d: PermitMessageDescription) => Promise<boolean | void> | boolean | void;
+}): Promise<{ nullifier: string }> {
+  const step = opts.onStep ?? (() => {});
+  const relay = createCheckRelay(opts.keeperUrl, opts.fetcher);
+  step('check');
+  const { check } = await relay.getCheck(opts.checkId);
+  if (check.status !== 'waiting') throw new CheckError(check.status === 'proved' ? 'This check already has a proof.' : 'This check has expired; ask for a new one.', 'CHECK_CLOSED');
+  if (check.network !== opts.network) throw new CheckError(`This check is on ${check.network}.`, 'WRONG_NETWORK');
+  const p = opts.permit;
+  if (p.network && p.network !== opts.network) throw new CheckError(`Your permit is on ${p.network}; this check is on ${opts.network}.`, 'WRONG_NETWORK');
+  if (opts.wallet.address !== p.holderKey) throw new CheckError(`Connect the permit's holder key ${p.holderKey}.`, 'WRONG_KEY');
+  if (p.registry !== check.registry) {
+    // Issued by an earlier generation: fine when, on chain, its successors lead to the registry checked.
+    const [{ currentOnChain, PERMIT_LINEAGE }, { CANONICAL_PERMIT_VK_HASHES }, { DEFAULT_MINA_GRAPHQL_URLS }] = await Promise.all([
+      import('./successorChain.js'), import('./permitInterface.js'), import('./onChainRoot.js'),
+    ]);
+    const current = await currentOnChain({
+      start: p.registry, layout: PERMIT_LINEAGE, canonicalVks: Object.values(CANONICAL_PERMIT_VK_HASHES),
+      graphqlUrl: opts.graphqlUrl ?? DEFAULT_MINA_GRAPHQL_URLS[opts.network], fetcher: opts.fetcher,
+    }).then(r => r.address, () => null);
+    if (current !== check.registry) throw new CheckError('Your permit is from another registry than the one this check asks for.', 'WRONG_REGISTRY');
+  }
+
+  step('registry');
+  // The whole registry (a compact copy, kept between checks), so the keeper
+  // can't tell which permit is proved; the root and slot from a Mina node,
+  // so the proof is for the chain's current state.
+  const { readChainHead } = await import('./chainHead.js');
+  const [tree, head] = await Promise.all([
+    syncRegistryTree({ registry: check.registry, fetchTree: since => relay.getTree(check.registry, since), cache: opts.treeCache }),
+    readChainHead({ address: check.registry, network: opts.network, graphqlUrl: opts.graphqlUrl, fetcher: opts.fetcher }),
+  ]);
+  if (tree.root !== head.root) throw new CheckError('zkLicensing\'s copy of the registry is behind the blockchain; try again in a minute.', 'ROOT_BEHIND');
+  let found;
+  try { found = witnessFromCompactTree(tree, p.subject); }
+  catch (e: any) { throw new CheckError(e?.message ?? String(e), /no such permit/.test(e?.message) ? 'NOT_FOUND' : 'ROOT_MISMATCH'); }
+  const { witness, permit: rec } = found;
+  const status = permitStatusAt(rec, head.slot);
+  if (status !== 'active') throw new CheckError(`Your permit is ${status}.`, 'NOT_ACTIVE');
+  const required = BigInt(check.requiredScope);
+  if ((BigInt(rec.scope) & required) !== required) throw new CheckError('Your permit doesn\'t cover the activities this check asks for.', 'SCOPE');
+
+  step('sign-secret');
+  // Re-derived with the wallet against the permit's lineage: nothing from the keeper.
+  const { findHolderSecret } = await import('./holderSecret.js');
+  let secret: string;
+  try { ({ secret } = await findHolderSecret(opts.wallet, { lineage: p.lineage ?? p.registry, network: opts.network, subject: p.subject })); }
+  catch (e: any) { throw new CheckError(e?.message ?? String(e), 'WRONG_SECRET'); }
+
+  step('sign-proof');
+  const { holderProofMessage, verifierContext, proveHolder } = await import('./permitProof.js');
+  const context = verifierContext(opts.origin, check.nonce);
+  const msg = holderProofMessage(PublicKey.fromBase58(check.registry), Field(head.root), Field(context));
+  const fields = msg.map(f => f.toString());
+  if (opts.confirmSignature) {
+    const { fingerprint } = await import('./permitDescribe.js');
+    const d: PermitMessageDescription = {
+      kind: 'holderProof', title: `Prove to ${new URL(opts.origin).host} that you hold an active permit, without saying which`,
+      facts: [['Checker', opts.origin], ['Registry', check.registry], ['Network', opts.network], ['Check', check.label || check.id]],
+      network: opts.network, registry: check.registry, verified: true, fingerprint: fingerprint(fields),
+    };
+    if ((await opts.confirmSignature(d)) === false) throw new CheckError('Cancelled', 'CANCELLED');
+  }
+  const holderSignature = await opts.wallet.signFields(fields);
+
+  step('compile-prove');
+  const { proof, nullifier } = await proveHolder({
+    registry: check.registry, root: head.root, witness, leaf: recordToLeaf(rec), holderSecret: secret,
+    slot: head.slot, requiredScope: required, context, holderSignature,
+  });
+
+  step('send');
+  await relay.submitProof(check.id, proof);
+  return { nullifier };
+}
+
+/**
+ * Checker: verifies the proof sent to a check, in this process. Roots from
+ * the keeper's recent roots, or with `trustless` only the registry's current
+ * root read from a Mina node. `origin` is the site the check was opened on.
+ */
+export async function verifyCheck(opts: {
+  keeperUrl: string;
+  network: Network;
+  checkId: string;
+  origin: string;
+  trustless?: boolean;
+  maxSlotSkew?: number;
+  graphqlUrl?: string;
+  fetcher?: typeof fetch;
+}): Promise<{ status: CheckView['status']; check: CheckView; valid: boolean; nullifier: string | null; reason: string | null }> {
+  const relay = createCheckRelay(opts.keeperUrl, opts.fetcher);
+  const { check, proof } = await relay.getCheck(opts.checkId);
+  if (!proof) return { status: check.status, check, valid: false, nullifier: null, reason: null };
+  let acceptedRoots: string[];
+  let currentSlot: number;
+  if (opts.trustless) {
+    const { readChainHead } = await import('./chainHead.js');
+    const head = await readChainHead({ address: check.registry, network: opts.network, graphqlUrl: opts.graphqlUrl, fetcher: opts.fetcher });
+    acceptedRoots = [head.root];
+    currentSlot = head.slot;
+  } else {
+    const r = await relay.getRoots(check.registry);
+    const { freshRoots } = await import('./agent.js');
+    acceptedRoots = freshRoots(r.roots, r.current, r.slot, opts.maxSlotSkew ?? 10);
+    currentSlot = r.slot;
+  }
+  const { verifyHolderProof } = await import('./permitProof.js');
+  const res = await verifyHolderProof(proof, {
+    registry: check.registry, acceptedRoots, currentSlot, maxSlotSkew: opts.maxSlotSkew,
+    requiredScope: BigInt(check.requiredScope), verifier: opts.origin, nonce: check.nonce,
+  });
+  return { status: 'proved', check, ...res };
+}