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

package/src/trustAnchorVerify.ts

@@ -0,0 +1,550 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * trustAnchorVerify.ts
+ *
+ * End-to-end trust-anchor verification for a single zkLicensing app.
+ *
+ * Given a vendor origin + a zkApp address + one or more pinned platform
+ * manifest public keys, this module performs the full "does this vendor
+ * page point at a real zkLicensing deployment for this vendor?" pipeline
+ * that the trust-anchor page walks a human buyer through — mechanically,
+ * with structured findings suitable for CI, monitoring, or a
+ * wallet/extension consumer.
+ *
+ * The verifier is address-keyed: buyers see zkApp addresses in their
+ * wallet popup, not opaque platform appIds, so the primary lookup is by
+ * address. The signed manifest served at
+ * `<origin>/.well-known/zklicensing/<zkAppAddress>.json` carries the
+ * appId inside its signed payload, so callers never need to know the
+ * appId out-of-band.
+ *
+ * Pipeline (each step yields a discrete Finding — no boolean collapse):
+ *
+ *   1.  manifest_fetch                    — GET https://<origin>/.well-known/zklicensing/<address>.json
+ *   2.  manifest_signature                — Ed25519 verify against caller-provided pinned keys
+ *                                            (any of the manifest's signatures: during a platform
+ *                                            key rotation it carries the old and the new key's)
+ *   2b. manifest_network                  — signed for the network being checked (minaNetworkId)
+ *   3.  manifest_address_in_generations   — opts.address appears in the signed generations[]
+ *   3b. manifest_matches_backend          — (opt-in, opts.crossCheck) vendor payload equals
+ *                                            zklicensing.com/apps/by-address/<address> after
+ *                                            independent signature-verify against same pins
+ *   4.  chain_account_exists              — fetchAccount succeeds at the address
+ *   5.  chain_zkapp_uri_match             — on-chain zkappUri equals opts.origin
+ *   6.  chain_vk_hash_pinned              — on-chain verification-key hash equals CANONICAL_VK_HASHES[generation]
+ *   7.  chain_set_zkapp_uri_impossible    — permissions.setZkappUri === Permissions.impossible()
+ *   8.  chain_set_permissions_impossible  — permissions.setPermissions === Permissions.impossible() (meta-freeze)
+ *   9.  chain_set_verification_key_locked — permissions.setVerificationKey.auth === Permissions.impossible()
+ *   10. chain_send_proof_only             — permissions.send === Permissions.proof()
+ *   11. chain_edit_state_proof_only       — permissions.editState === Permissions.proof()
+ *
+ * Steps 5 + 7 close the URI-binding loop: (5) proves the contract claims
+ * this origin, (7) proves nobody can rewrite that claim. Steps 8–11 verify
+ * the rest of LicensingApp.init()'s permission matrix — catching the case
+ * where a deployer used the correct VK but skipped/altered init(), leaving
+ * default `signature()` permissions that would still let the deploy key
+ * drain escrow, rewrite state, or swap the circuit.
+ *
+ * Chain reads go to the Mina node's GraphQL API directly (chainHead.ts):
+ * no o1js is needed, and o1js's global Mina instance is never switched, so
+ * long-lived services can run the check concurrently.
+ *
+ * The pinned pubkey list is caller-supplied — the SDK ships NO baked-in
+ * pin. Source it from https://zklicensing.com/trustanchor.html (published
+ * next to each generation's VK hash). See the SDK README for details.
+ */
+
+import { canonicalize, manifestSignaturesOf, signedManifestOf, verifyManifestSignature } from './manifestVerify.js';
+
+export type Finding = {
+  /** Machine-readable check identifier, stable across releases. */
+  name: string;
+  /** True iff the check passed. */
+  ok: boolean;
+  /** Human-readable one-line summary or reason. */
+  detail: string;
+};
+
+export type TrustAnchorReport = {
+  /** True iff every finding is ok. */
+  ok: boolean;
+  origin: string;
+  /** Address that was checked. Echoed from opts.address. */
+  address: string;
+  /** appId as declared in the signed manifest payload. Undefined if the fetch/signature failed. */
+  appId?: string;
+  /** Generation index the address maps to in the signed manifest (1-based). */
+  generation?: number;
+  findings: Finding[];
+};
+
+export interface VerifyTrustAnchorOpts {
+  /** Vendor origin, e.g. `https://store.example.com`. HTTPS required. */
+  origin: string;
+  /** zkApp address (base58 PublicKey) — the manifest lives at `/.well-known/zklicensing/<address>.json`. */
+  address: string;
+  /** Platform manifest Ed25519 public keys (base64). Comma-list from `VITE_MANIFEST_PUBKEYS`. */
+  pinnedPublicKeysBase64: readonly string[];
+  /** Mina GraphQL endpoint for on-chain reads. Ignored when `skipChainChecks` is true. */
+  minaGraphqlUrl?: string;
+  /** Optional Mina networkId — 'mainnet' or 'testnet'. Defaults to 'mainnet'. */
+  minaNetworkId?: 'mainnet' | 'testnet' | 'devnet';
+  /** Fetch timeout in ms for the manifest fetch. Default 15000. */
+  fetchTimeoutMs?: number;
+  /** When true, skips all `chain_*` checks. Useful for manifest-only audits. */
+  skipChainChecks?: boolean;
+  /**
+   * When true, runs an extra `manifest_matches_backend` finding: fetch the
+   * same signed payload from `https://zklicensing.com/apps/by-address/{address}`,
+   * verify it against the same pinned keys, then byte-compare canonicalized
+   * payloads (minus `signature`, `publicKey`, `issuedAt`, `app`). Catches a
+   * vendor serving a stale/rolled-back manifest even when its own signature
+   * is still valid. Not on by default — adds a second network fetch and
+   * couples the verifier to zklicensing.com being reachable.
+   */
+  crossCheck?: boolean;
+}
+
+// The zkLicensing backend is mounted under /api/keeper on zklicensing.com —
+// the bare /apps/... paths return 404 (they're not the app route, they're an
+// unrelated marketing route). This is the concrete URL prefix, not just an
+// origin. The `/api/keeper` path is a stable public route and must not be
+// renamed here.
+const BACKEND_URL_PREFIX = 'https://zklicensing.com/api/keeper';
+
+const DEFAULT_FETCH_TIMEOUT_MS = 15000;
+
+function normalizeOrigin(origin: string): string {
+  return origin.replace(/\/+$/, '');
+}
+
+// Strip trailing slash / path from a URL so we can compare against zkappUri,
+// which vendors typically set to their bare origin.
+function urlOrigin(url: string): string | null {
+  try {
+    const u = new URL(url);
+    return `${u.protocol}//${u.host}`;
+  } catch {
+    return null;
+  }
+}
+
+type Generation = {
+  gen: number;
+  zkAppAddress: string;
+  status: 'retired' | 'live';
+  frozenRoot?: string;
+  deployedAt?: string;
+  retiredAt?: string;
+  // On-chain permissions.setVerificationKey.txnVersion recorded by the backend
+  // at manifest-assembly time. Optional for backwards compatibility with
+  // older manifests written before the field existed.
+  deployTxnVersion?: number;
+};
+
+type ManifestPayload = {
+  appId: string;
+  network: 'devnet' | 'mainnet';
+  current: number;
+  generations: Generation[];
+  issuedAt: string;
+};
+
+async function fetchManifest(
+  origin: string,
+  address: string,
+  timeoutMs: number,
+): Promise<Finding & { body?: unknown }> {
+  const originOk = origin.startsWith('https://');
+  if (!originOk) {
+    return { name: 'manifest_fetch', ok: false, detail: 'origin must be https://' };
+  }
+  let manifestUrl: string;
+  try {
+    manifestUrl = new URL(`/.well-known/zklicensing/${encodeURIComponent(address)}.json`, origin).href;
+  } catch {
+    return { name: 'manifest_fetch', ok: false, detail: 'origin is not a valid URL' };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const resp = await fetch(manifestUrl, { signal: controller.signal, redirect: 'follow' });
+    if (!resp.ok) {
+      return { name: 'manifest_fetch', ok: false, detail: `HTTP ${resp.status} from ${manifestUrl}` };
+    }
+    const text = await resp.text();
+    let parsed: unknown;
+    try { parsed = JSON.parse(text); }
+    catch { return { name: 'manifest_fetch', ok: false, detail: 'response is not valid JSON' }; }
+    return { name: 'manifest_fetch', ok: true, detail: `fetched ${manifestUrl}`, body: parsed };
+  } catch (err: any) {
+    return { name: 'manifest_fetch', ok: false, detail: `fetch failed: ${err?.message ?? String(err)}` };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Split a raw manifest JSON into { signature, payload }. The backend writes the
+// payload fields at the top level plus { signature, publicKey } — we ignore
+// publicKey (never trust the payload's self-declared key; only the
+// caller-pinned list is authoritative). The same signed bytes are served at
+// every /.well-known/zklicensing/<address>.json — one file per generation
+// address, all carrying the same appId in the payload.
+//
+// We whitelist the signed fields (appId, current, generations, issuedAt)
+// rather than blacklist non-signed ones. The backend appends advisory
+// fields (e.g. `forkActivationSlot`) to the response AFTER signing, so a
+// blacklist misses them and canonicalize() then hashes bytes the signer
+// never saw — the signature never verifies.
+function splitManifest(raw: unknown): { signatures: string[]; payload: ManifestPayload | null } {
+  const payload = signedManifestOf(raw) as ManifestPayload | null;
+  return { signatures: manifestSignaturesOf(raw), payload };
+}
+
+/** True when one of `signatures` verifies over `payload` against a pinned key. */
+async function anySignatureVerifies(payload: unknown, signatures: readonly string[], pinned: readonly string[]): Promise<boolean> {
+  for (const sig of signatures) if (await verifyManifestSignature(payload, sig, pinned)) return true;
+  return false;
+}
+
+// Optional cross-check against the zkLicensing backend's own copy of the
+// signed generation list. Fetches `https://zklicensing.com/apps/by-address/
+// {address}`, verifies its signature against the same caller-pinned keys (so
+// a compromised backend URL cannot lie), strips signature/publicKey/issuedAt/
+// app/network, and byte-compares canonicalized payloads against the vendor's
+// `.well-known` copy. `issuedAt` is stripped because the backend re-stamps on
+// every call; `app` and `network` are stripped because they are unsigned
+// envelope fields the by-address endpoint tacks on.
+async function checkBackendMatch(args: {
+  address: string;
+  vendorPayload: ManifestPayload;
+  pinnedPublicKeysBase64: readonly string[];
+  timeoutMs: number;
+}): Promise<Finding> {
+  const name = 'manifest_matches_backend';
+  const url = `${BACKEND_URL_PREFIX}/apps/by-address/${encodeURIComponent(args.address)}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), args.timeoutMs);
+  let body: any;
+  try {
+    const resp = await fetch(url, { signal: controller.signal, redirect: 'follow' });
+    if (!resp.ok) return { name, ok: false, detail: `backend HTTP ${resp.status} from ${url}` };
+    body = await resp.json();
+  } catch (err: any) {
+    return { name, ok: false, detail: `backend fetch failed: ${err?.message ?? String(err)}` };
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!body || typeof body !== 'object') {
+    return { name, ok: false, detail: 'backend response is not a JSON object' };
+  }
+  // Only the signed fields (same reason as splitManifest above): the backend
+  // appends envelope fields (publicKey, app, forkActivationSlot) after signing.
+  const backendSignatures = manifestSignaturesOf(body);
+  if (!backendSignatures.length) {
+    return { name, ok: false, detail: 'backend response missing signature' };
+  }
+  const backendPayload = signedManifestOf(body);
+  if (!backendPayload) {
+    return { name, ok: false, detail: 'backend response missing signed fields' };
+  }
+  if (!await anySignatureVerifies(backendPayload, backendSignatures, args.pinnedPublicKeysBase64)) {
+    return { name, ok: false, detail: 'backend response signature does not verify against pinned keys' };
+  }
+  const { issuedAt: _kIA, ...kRest } = backendPayload as Record<string, unknown>;
+  const { issuedAt: _vIA, ...vRest } = args.vendorPayload as unknown as Record<string, unknown>;
+  if (canonicalize(kRest) !== canonicalize(vRest)) {
+    return { name, ok: false, detail: 'vendor manifest content diverges from backend record (stale or drifted)' };
+  }
+  return { name, ok: true, detail: `vendor payload matches backend /apps/by-address/${args.address}` };
+}
+
+type ChainState = {
+  zkappUri?: string;
+  vkHash?: string;
+  // Each flag mirrors one line of LicensingApp.init()'s permissions matrix.
+  // undefined means the field could not be read from chain.
+  setZkappUriIsImpossible?: boolean;
+  setPermissionsIsImpossible?: boolean;
+  // setVerificationKey uses VerificationKey.impossibleDuringCurrentVersion(),
+  // which stores {auth: Impossible, txnVersion: currentChainTxnVersion} on the
+  // account. After a Mina hardfork the chain's current txnVersion advances
+  // past the stored value and the effective enforcement falls back to
+  // signature() by design — but the deploy key was discarded at deploy time
+  // (see LicensingApp.ts:546-547), so no one can sign the fallback update.
+  //
+  // We read both the stored auth string AND the stored txnVersion so the
+  // verifier can bind on-chain state to the manifest-recorded deployTxnVersion.
+  setVerificationKeyAuth?: string;
+  setVerificationKeyTxnVersion?: number;
+  sendIsProof?: boolean;
+  editStateIsProof?: boolean;
+  accountFound: boolean;
+  fetchError?: string;
+};
+
+// Converts an o1js-decoded Permission (three booleans) back to its canonical
+// enum string. Mirrors the switch inside o1js's own AuthRequired.toJSON — kept
+// inline because o1js doesn't publicly export it.
+export function permToString(p: any): string | undefined {
+  const b = (v: any) => (typeof v?.toBoolean === 'function' ? v.toBoolean() : Boolean(v)) ? 1 : 0;
+  const key = `${b(p?.constant)}${b(p?.signatureNecessary)}${b(p?.signatureSufficient)}`;
+  switch (key) {
+    case '110': return 'Impossible';
+    case '101': return 'None';
+    case '000': return 'Proof';
+    case '011': return 'Signature';
+    case '001': return 'Either';
+    default:    return undefined;
+  }
+}
+
+// Reads the on-chain facts needed to close the trust loop for a single
+// zkApp address, over the node's GraphQL API (no o1js, and no switch of
+// o1js's global Mina instance, so long-lived hosts can call it safely).
+async function readChainState(
+  address: string,
+  minaGraphqlUrl: string,
+  _minaNetworkId: 'mainnet' | 'testnet' | 'devnet',
+  fetcher?: typeof fetch,
+): Promise<ChainState> {
+  try {
+    const { readZkappAccount } = await import('./chainHead.js');
+    const a = await readZkappAccount({ address, graphqlUrl: minaGraphqlUrl, fetcher });
+    if (!a.found) return { accountFound: false, fetchError: `no account at ${address} via ${minaGraphqlUrl}` };
+    const p = a.permissions ?? {};
+    return {
+      accountFound: true,
+      zkappUri: a.zkappUri,
+      vkHash: a.vkHash,
+      setZkappUriIsImpossible:      p.setZkappUri === 'Impossible',
+      setPermissionsIsImpossible:   p.setPermissions === 'Impossible',
+      setVerificationKeyAuth:       p.setVerificationKey?.auth,
+      setVerificationKeyTxnVersion: p.setVerificationKey?.txnVersion,
+      sendIsProof:                  p.send === 'Proof',
+      editStateIsProof:             p.editState === 'Proof',
+    };
+  } catch (err: any) {
+    return { accountFound: false, fetchError: err?.message ?? String(err) };
+  }
+}
+
+async function loadCanonicalVkHashes(): Promise<Readonly<Record<number, string>> | null> {
+  try {
+    const m = await import('./contractInterface.js');
+    return m.CANONICAL_VK_HASHES ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export async function verifyTrustAnchor(opts: VerifyTrustAnchorOpts): Promise<TrustAnchorReport> {
+  const origin = normalizeOrigin(opts.origin);
+  const address = opts.address;
+  const findings: Finding[] = [];
+  const timeoutMs = opts.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+
+  // 1. manifest_fetch
+  const fetchResult = await fetchManifest(origin, address, timeoutMs);
+  findings.push({ name: fetchResult.name, ok: fetchResult.ok, detail: fetchResult.detail });
+  if (!fetchResult.ok) {
+    return { ok: false, origin, address, findings };
+  }
+  const { signatures, payload } = splitManifest(fetchResult.body);
+
+  // 2. manifest_signature
+  if (!signatures.length || !payload) {
+    findings.push({ name: 'manifest_signature', ok: false, detail: 'manifest missing signature or payload fields (appId, network, current, generations, issuedAt)' });
+    return { ok: false, origin, address, findings };
+  }
+  const sigOk = await anySignatureVerifies(payload, signatures, opts.pinnedPublicKeysBase64);
+  findings.push({
+    name: 'manifest_signature',
+    ok: sigOk,
+    detail: sigOk
+      ? `Ed25519 verified against pinned key (1 of ${opts.pinnedPublicKeysBase64.length})`
+      : 'signature does not verify against any pinned key',
+  });
+  if (!sigOk) {
+    return { ok: false, origin, address, findings };
+  }
+
+  // appId is trusted only after signature verifies — it comes from the signed
+  // payload, not the caller.
+  const appId = payload.appId;
+
+  // 2b. manifest_network: signed for the network being checked (a devnet
+  // manifest never vouches for a mainnet contract, nor the other way round).
+  const expectedNetwork = (opts.minaNetworkId ?? 'mainnet') === 'mainnet' ? 'mainnet' : 'devnet';
+  findings.push({
+    name: 'manifest_network',
+    ok: payload.network === expectedNetwork,
+    detail: payload.network === expectedNetwork ? `signed for ${payload.network}` : `signed for ${payload.network}, checking ${expectedNetwork}`,
+  });
+  if (payload.network !== expectedNetwork) {
+    return { ok: false, origin, address, findings };
+  }
+
+  // 3. manifest_address_in_generations
+  const entry = payload.generations.find((g) => g.zkAppAddress === address);
+  findings.push({
+    name: 'manifest_address_in_generations',
+    ok: !!entry,
+    detail: entry
+      ? `address maps to gen ${entry.gen} (${entry.status})`
+      : `address ${address} not in manifest generations for app "${appId}"`,
+  });
+  const generation = entry?.gen;
+
+  // 3b. manifest_matches_backend (opt-in)
+  if (opts.crossCheck) {
+    findings.push(await checkBackendMatch({
+      address,
+      vendorPayload: payload,
+      pinnedPublicKeysBase64: opts.pinnedPublicKeysBase64,
+      timeoutMs,
+    }));
+  }
+
+  if (opts.skipChainChecks) {
+    const allOk = findings.every((f) => f.ok);
+    return { ok: allOk, origin, appId, address, generation, findings };
+  }
+
+  if (!opts.minaGraphqlUrl) {
+    findings.push({ name: 'chain_account_exists', ok: false, detail: 'minaGraphqlUrl is required for chain checks' });
+    return { ok: false, origin, appId, address, generation, findings };
+  }
+
+  // 4-11: chain reads
+  const state = await readChainState(address, opts.minaGraphqlUrl, opts.minaNetworkId ?? 'mainnet');
+  findings.push({
+    name: 'chain_account_exists',
+    ok: state.accountFound,
+    detail: state.accountFound ? `account ${address.slice(0, 12)}… found` : (state.fetchError ?? 'account not found'),
+  });
+  if (!state.accountFound) {
+    return { ok: false, origin, appId, address, generation, findings };
+  }
+
+  const onChainOrigin = state.zkappUri ? urlOrigin(state.zkappUri) : null;
+  const originClean = urlOrigin(origin);
+  const uriOk = !!state.zkappUri && !!onChainOrigin && !!originClean && onChainOrigin === originClean;
+  findings.push({
+    name: 'chain_zkapp_uri_match',
+    ok: uriOk,
+    detail: state.zkappUri
+      ? (uriOk ? `zkappUri "${state.zkappUri}" origin matches` : `zkappUri "${state.zkappUri}" origin ≠ "${originClean ?? origin}"`)
+      : 'zkappUri is empty on chain',
+  });
+
+  // Pinned by circuit: the on-chain VK must be one of the published circuit
+  // hashes. The manifest's `gen` counts this app's redeploys, which is not
+  // the circuit generation (a redeploy can keep the circuit, and an app
+  // deployed after a circuit bump starts at gen 1 on the newer circuit).
+  const canonicalVks = await loadCanonicalVkHashes();
+  const matchedCircuit = state.vkHash && canonicalVks
+    ? Object.entries(canonicalVks).find(([, h]) => h === state.vkHash)?.[0]
+    : undefined;
+  const vkOk = matchedCircuit !== undefined;
+  findings.push({
+    name: 'chain_vk_hash_pinned',
+    ok: vkOk,
+    detail: vkOk
+      ? `on-chain vkHash matches CANONICAL_VK_HASHES[${matchedCircuit}] (app gen ${generation ?? '?'})`
+      : !canonicalVks
+        ? 'CANONICAL_VK_HASHES unavailable'
+        : `on-chain vkHash "${state.vkHash?.slice(0, 16) ?? 'missing'}…" is not a published circuit hash`,
+  });
+
+  findings.push({
+    name: 'chain_set_zkapp_uri_impossible',
+    ok: !!state.setZkappUriIsImpossible,
+    detail: state.setZkappUriIsImpossible
+      ? 'permissions.setZkappUri = impossible (zkappUri is frozen)'
+      : 'permissions.setZkappUri ≠ impossible — vendor could rewrite the URI',
+  });
+
+  // The meta-freeze: without this, every other permission lock below is
+  // reversible with a single signature. Priority #1 among the extras.
+  findings.push({
+    name: 'chain_set_permissions_impossible',
+    ok: !!state.setPermissionsIsImpossible,
+    detail: state.setPermissionsIsImpossible
+      ? 'permissions.setPermissions = impossible (permission matrix is meta-frozen)'
+      : 'permissions.setPermissions ≠ impossible — every other lock could be relaxed later',
+  });
+
+  // setVerificationKey lock, with hardfork-aware softening.
+  //
+  // The contract deploys with VerificationKey.impossibleDuringCurrentVersion(),
+  // which stores {auth: Impossible, txnVersion: <chain's txnVersion at deploy
+  // time>}. After a Mina hardfork the chain's current txnVersion advances
+  // past the stored value and the effective enforcement falls back to
+  // signature() — but the deploy key was discarded (LicensingApp.ts:546-547),
+  // so no one can sign the fallback update.
+  //
+  // The backend records the deploy-time txnVersion in the signed manifest as
+  // deployTxnVersion. We accept two states as OK, provided the on-chain
+  // stored txnVersion still matches the manifest-recorded value (which proves
+  // no one has re-set the permission since deploy):
+  //
+  //   - auth = Impossible  → normal, pre-hardfork state
+  //   - auth = Signature   → post-hardfork fallback (see above)
+  //
+  // Any mismatch — different txnVersion, or auth is some other string, or
+  // deployTxnVersion missing from an old manifest — falls back to the strict
+  // rule (auth === 'Impossible').
+  const onChainAuth = state.setVerificationKeyAuth;
+  const onChainTxnVersion = state.setVerificationKeyTxnVersion;
+  const manifestDeployTxnVersion = entry?.deployTxnVersion;
+  let vkLockOk = false;
+  let vkLockDetail: string;
+  if (manifestDeployTxnVersion !== undefined && onChainTxnVersion !== undefined && onChainTxnVersion === manifestDeployTxnVersion) {
+    if (onChainAuth === 'Impossible') {
+      vkLockOk = true;
+      vkLockDetail = `permissions.setVerificationKey.auth = impossible (circuit cannot be swapped; txnVersion ${onChainTxnVersion} matches deploy)`;
+    } else if (onChainAuth === 'Signature') {
+      vkLockOk = true;
+      vkLockDetail = `permissions.setVerificationKey.auth = signature (post-hardfork fallback; deploy key was destroyed at deploy time; txnVersion ${onChainTxnVersion} matches deploy)`;
+    } else {
+      vkLockDetail = `permissions.setVerificationKey.auth = "${onChainAuth ?? '?'}" — expected impossible or signature`;
+    }
+  } else if (manifestDeployTxnVersion === undefined) {
+    // Older manifest without deployTxnVersion — fall back to strict.
+    vkLockOk = onChainAuth === 'Impossible';
+    vkLockDetail = vkLockOk
+      ? 'permissions.setVerificationKey.auth = impossible (circuit cannot be swapped; manifest omits deployTxnVersion — strict rule applied)'
+      : `permissions.setVerificationKey.auth = "${onChainAuth ?? '?'}" ≠ impossible — vendor could swap the circuit (manifest omits deployTxnVersion — strict rule applied)`;
+  } else {
+    vkLockDetail = `on-chain setVerificationKey.txnVersion (${onChainTxnVersion ?? 'unknown'}) ≠ manifest deployTxnVersion (${manifestDeployTxnVersion}) — permission may have been re-set since deploy`;
+  }
+  findings.push({
+    name: 'chain_set_verification_key_locked',
+    ok: vkLockOk,
+    detail: vkLockDetail,
+  });
+
+  // send + editState must be proof() (not signature()): withdrawals and Merkle
+  // root advances only happen via a valid LicensingApp proof.
+  findings.push({
+    name: 'chain_send_proof_only',
+    ok: !!state.sendIsProof,
+    detail: state.sendIsProof
+      ? 'permissions.send = proof() (escrow only leaves via a refund proof)'
+      : 'permissions.send ≠ proof() — vendor could drain escrow with a signature',
+  });
+
+  findings.push({
+    name: 'chain_edit_state_proof_only',
+    ok: !!state.editStateIsProof,
+    detail: state.editStateIsProof
+      ? 'permissions.editState = proof() (Merkle root advances only via a proof)'
+      : 'permissions.editState ≠ proof() — vendor could rewrite the license root',
+  });
+
+  const allOk = findings.every((f) => f.ok);
+  return { ok: allOk, origin, appId, address, generation, findings };
+}