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

package/src/proveErrors.ts

@@ -0,0 +1,98 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * proveErrors.ts
+ *
+ * Shared typed error for the "proving queue busy" 409 surface returned by
+ * /prove/buy, /prove/buy-no-escrow, /prove/renew, and
+ * /prove/refund. The backend serializes all five endpoints on a per-app
+ * in-flight slot: while a proof is out with a buyer waiting to be signed
+ * (or a signed tx is waiting to land), further requests against the same
+ * app get an immediate 409 with a `retryAfterMs` hint. Callers should catch
+ * this and wait+retry rather than surfacing the failure — the wallet popup
+ * never opens for a proof with no live chance of landing.
+ *
+ * `queueDepth` is 1 in v1 (single slot per app); the field exists so that a
+ * future Tier-1 optimistic-chaining pass can widen it without breaking
+ * clients written today.
+ */
+
+export class ProveQueueBusyError extends Error {
+  readonly status = 409;
+  readonly retryAfterMs: number;
+  readonly queueDepth:   number;
+  constructor(message: string, retryAfterMs: number, queueDepth: number) {
+    super(message);
+    this.name = 'ProveQueueBusyError';
+    this.retryAfterMs = retryAfterMs;
+    this.queueDepth = queueDepth;
+  }
+}
+
+// Shared 409-body shape used by all four prove endpoints. Matches backend.
+export type ProveQueueBusyBody = {
+  error:        'proving queue busy';
+  retryAfterMs: number;
+  queueDepth?:  number;
+};
+
+// Reads the response body as JSON exactly once and returns a normalized
+// view. Callers use this in the non-2xx branch to decide the specific
+// error surface (queue-busy, endpoint-specific, or generic).
+export type ParsedErrorBody = {
+  status: number;
+  body:   Record<string, unknown>;
+  // Convenience: extracted `body.error` when it's a string, else the HTTP fallback.
+  message: string;
+};
+
+export async function readErrorBody(resp: Response): Promise<ParsedErrorBody> {
+  let body: Record<string, unknown> = {};
+  try {
+    body = await resp.json() as Record<string, unknown>;
+  } catch { /* body wasn't JSON */ }
+  const message = typeof body.error === 'string' ? body.error : `HTTP ${resp.status}`;
+  return { status: resp.status, body, message };
+}
+
+/**
+ * A keeper error with its stable `code` and `retryable` (e.g.
+ * FEE_PAYER_MISSING, REFUND_WINDOW_CLOSED), so callers and the MCP server can
+ * act on the code rather than the wording.
+ */
+export class KeeperError extends Error {
+  readonly code: string;
+  readonly retryable: boolean;
+  readonly status: number;
+  /** How long to wait before retrying, when the keeper says. */
+  readonly retryAfterMs?: number;
+  constructor(message: string, code: string, retryable: boolean, status: number, retryAfterMs?: number) {
+    super(message);
+    this.name = 'KeeperError';
+    this.code = code;
+    this.retryable = retryable;
+    this.status = status;
+    if (retryAfterMs !== undefined) this.retryAfterMs = retryAfterMs;
+  }
+}
+
+/** The error a failed keeper response stands for. */
+export function keeperError(parsed: ParsedErrorBody): KeeperError {
+  const { body } = parsed;
+  const code = typeof body.code === 'string' && body.code ? body.code : parsed.status >= 500 ? 'INTERNAL' : 'INVALID_REQUEST';
+  return new KeeperError(parsed.message, code, body.retryable === true, parsed.status, typeof body.retryAfterMs === 'number' ? body.retryAfterMs : undefined);
+}
+
+// Returns a ProveQueueBusyError if the parsed body matches the queue-busy
+// shape; otherwise null. Cheap to call — no I/O.
+export function tryQueueBusyFromBody(parsed: ParsedErrorBody): ProveQueueBusyError | null {
+  if (parsed.status !== 409) return null;
+  const { body } = parsed;
+  if (body.error !== 'proving queue busy' || typeof body.retryAfterMs !== 'number') return null;
+  return new ProveQueueBusyError(
+    body.error,
+    body.retryAfterMs,
+    typeof body.queueDepth === 'number' ? body.queueDepth : 1,
+  );
+}

package/src/receipt.ts

@@ -0,0 +1,156 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * receipt.ts — `zklicensing/receipt`
+ *
+ * The purchase receipt: the durable confirmation a buyer keeps (Vendor Terms
+ * §7.1). The keeper issues it when a purchase, renewal or permit payment is
+ * confirmed, with a number in the seller's own series; a refund gets a
+ * credit note (kind 'license-refund', negative amounts, `creditFor` naming
+ * the receipt it cancels) in the seller's credit-note series. It is a
+ * document of its own, next to the license or permit file:
+ * `receiptHtml` renders it as a self-contained page the buyer downloads
+ * (receiptFileName), prints or saves as PDF.
+ */
+
+import { fiatCurrencies, formatFiatList } from './units.js';
+
+export type ReceiptKind = 'license-purchase' | 'license-renewal' | 'permit-grant' | 'permit-renewal' | 'permit-processing' | 'license-refund';
+
+export type PurchaseReceipt = {
+  type: 'zklicensing-receipt';
+  version: 1;
+  /** The seller's series: <SERIES>-<YYYY>-<NNNNNN>, sequential per seller and year. */
+  number: string;
+  issuedAt: string;
+  network: 'devnet' | 'mainnet';
+  kind: ReceiptKind;
+  /** The seller of record: the vendor (licenses) or the permit authority. */
+  seller: {
+    legalName: string;
+    address: string;
+    country: string;
+    /** VAT number; empty when the seller has none on record. */
+    vatId: string;
+    /** Organisation number (permit authorities). */
+    registrationNumber?: string;
+    website?: string;
+    wallet: string;
+  };
+  /** Who issued the document for the seller. */
+  issuedBy: { name: string; site: string };
+  buyer: { wallet: string; country?: string };
+  item: {
+    description: string;
+    /** License: the app; permit: the registry. */
+    productId: string;
+    productName: string;
+    /** License tier or permit term, in words. */
+    term?: string;
+    /** License hash or permit subject: what the payment bought. */
+    reference: string;
+  };
+  amount: {
+    /** 'tMINA' on devnet (test MINA, no value); receipts from before carry 'MINA'. */
+    currency: 'MINA' | 'tMINA';
+    total: string;
+    /** null: VAT not itemised (see `vatNote`). */
+    vatRatePct: number | null;
+    vat: string | null;
+    net: string | null;
+    vatCountry?: string;
+    vatNote?: string;
+    /** For reference: MINA→EUR on the day, and (mainnet only) the total in euros. */
+    eurRate?: number;
+    totalEur?: string;
+    /**
+     * The total in euros, dollars and pounds at the day's MINA rates (and the
+     * rates). On devnet (`basis: 'mainnet-reference'`) it is what the same
+     * amount of mainnet MINA would have been worth: tMINA has no value.
+     */
+    fiat?: {
+      basis: 'paid' | 'mainnet-reference';
+      rates: { eur: number; usd: number; gbp: number };
+      totals: { eur: string; usd: string; gbp: string };
+    };
+  };
+  payment: { txHash: string; method: 'Mina blockchain' };
+  /** Set when the transaction failed on chain or never landed: nothing was paid, and the document is void. */
+  voided?: { at: string; reason: string };
+  /** Withdrawal waiver, refund window and similar terms that apply to this purchase. */
+  terms: string[];
+  /** Credit notes: the receipt this one cancels. */
+  creditFor?: { number: string; txHash: string };
+};
+
+export const isCreditNote = (r: PurchaseReceipt) => r.kind === 'license-refund';
+
+/** The download name for one receipt or credit note (or several: `receipts-<first number>.html`). */
+export function receiptFileName(receipts: PurchaseReceipt | PurchaseReceipt[]): string {
+  const list = Array.isArray(receipts) ? receipts : [receipts];
+  const safe = (s: string) => s.replace(/[^A-Za-z0-9-]+/g, '-');
+  if (list.length === 1) return `${isCreditNote(list[0]) ? 'credit-note' : 'receipt'}-${safe(list[0].number)}.html`;
+  return `receipts-${safe(list[0]?.number ?? 'none')}.html`;
+}
+
+const esc = (s: unknown) => String(s ?? '').replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!));
+
+/** A self-contained printable page (no scripts) for one or more receipts. */
+export function receiptHtml(receipts: PurchaseReceipt | PurchaseReceipt[]): string {
+  const list = Array.isArray(receipts) ? receipts : [receipts];
+  const one = (r: PurchaseReceipt) => {
+    const a = r.amount;
+    // Devnet: test MINA (tMINA), whatever an older receipt's currency says.
+    const unit = r.network === 'mainnet' ? a.currency : 'tMINA';
+    const test = r.network !== 'mainnet' ? `<div class="banner">TEST (${esc(r.network)}): amounts in tMINA, test MINA with no value; not a tax document</div>` : '';
+    const rows = [
+      ['Net', a.net !== null ? `${esc(a.net)} ${unit}` : '—'],
+      [a.vatRatePct !== null ? `VAT ${esc(a.vatCountry ?? '')} ${esc(a.vatRatePct)}%` : 'VAT', a.vat !== null ? `${esc(a.vat)} ${unit}` : esc(a.vatNote ?? 'not itemised')],
+    ];
+    // Money in the buyer's currencies: euros in the EU, pounds and euros in
+    // the UK, dollars in the US, euros and dollars elsewhere (fiatCurrencies).
+    const f = a.fiat;
+    const cur = fiatCurrencies(r.buyer.country);
+    const money = esc(f ? formatFiatList(f.totals, cur) : '');
+    const rates = f ? esc(`1 MINA = ${formatFiatList(f.rates, cur, 4)}`) : '';
+    const paidWord = isCreditNote(r) ? 'refunded' : 'paid';
+    const eur = unit === 'tMINA'
+      ? (f
+        ? `In real MINA this would be ≈ ${money} (${rates} on mainnet that day). tMINA has no value: nothing was ${paidWord} in money.`
+        : a.eurRate ? `tMINA has no value. For reference, 1 MINA on mainnet ≈ €${esc(a.eurRate)}.` : '')
+      : (f
+        ? `≈ ${money} at the day's rate${cur.length > 1 ? 's' : ''} (${rates}).`
+        : a.totalEur ? `≈ €${esc(a.totalEur)} at ${esc(a.eurRate)} €/MINA.` : '');
+    return `<section class="receipt">${test}
+<h1>${isCreditNote(r) ? 'Credit note' : 'Receipt'} ${esc(r.number)}</h1>
+<div class="dim">${esc(r.issuedAt.slice(0, 10))} · ${esc(r.kind.replace('-', ' '))} · ${esc(r.network)}</div>
+${r.voided ? `<p><strong>VOID</strong>: ${esc(r.voided.reason)} Nothing was paid.</p>` : ''}
+${r.creditFor ? `<p>Cancels receipt <strong>${esc(r.creditFor.number)}</strong> (transaction <span class="mono">${esc(r.creditFor.txHash)}</span>).</p>` : ''}
+<div class="cols">
+  <div><strong>Seller</strong><br>${esc(r.seller.legalName)}<br>${esc(r.seller.address)}<br>${r.seller.vatId ? `VAT ${esc(r.seller.vatId)}` : 'Not VAT-registered'}${r.seller.registrationNumber ? `<br>Organisation number ${esc(r.seller.registrationNumber)}` : ''}${r.seller.website ? `<br>${esc(r.seller.website)}` : ''}<br><span class="dim">wallet ${esc(r.seller.wallet)}</span></div>
+  <div><strong>Buyer</strong><br><span class="dim">wallet</span> ${esc(r.buyer.wallet)}${r.buyer.country ? `<br>Country ${esc(r.buyer.country)}` : ''}</div>
+</div>
+<table>
+  <tr><th>Item</th><th class="r">Total</th></tr>
+  <tr><td>${esc(r.item.description)}<br><span class="dim">${esc(r.item.productName)} (${esc(r.item.productId)})${r.item.term ? ` · ${esc(r.item.term)}` : ''}<br>ref ${esc(r.item.reference)}</span></td><td class="r">${esc(a.total)} ${unit}</td></tr>
+  ${rows.map(([k, v]) => `<tr class="sub"><td>${k}</td><td class="r">${v}</td></tr>`).join('')}
+  <tr class="tot"><td>${isCreditNote(r) ? 'Total refunded' : 'Total paid'}</td><td class="r">${esc(a.total)} ${unit}</td></tr>
+</table>
+${eur ? `<p class="dim fiat">${eur}</p>` : ''}
+<p>${isCreditNote(r) ? 'Refunded' : 'Paid'} on the ${esc(r.payment.method)}, transaction <span class="mono">${esc(r.payment.txHash)}</span>.</p>
+${r.terms.length ? `<ul>${r.terms.map(t => `<li>${esc(t)}</li>`).join('')}</ul>` : ''}
+<p class="dim">Issued by ${esc(r.issuedBy.name)} (${esc(r.issuedBy.site)}) on behalf of the seller.</p>
+</section>`;
+  };
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${esc(list.length === 1 ? `${isCreditNote(list[0]) ? 'Credit note' : 'Receipt'} ${list[0].number}` : 'Receipts')}</title>
+<style>
+  body { font: 13px/1.45 system-ui, sans-serif; color: #111; margin: 32px; max-width: 760px; }
+  h1 { font-size: 20px; margin: 0 0 4px; } .dim { color: #666; font-size: 11px; } .mono { font-family: ui-monospace, monospace; font-size: 11px; word-break: break-all; }
+  .cols { display: flex; gap: 48px; margin: 20px 0; } .cols div { flex: 1; word-break: break-word; }
+  table { width: 100%; border-collapse: collapse; margin-top: 12px; } th, td { padding: 6px 8px; border-bottom: 1px solid #ddd; vertical-align: top; text-align: left; }
+  th { font-size: 11px; color: #555; } .r { text-align: right; white-space: nowrap; } .sub td { color: #444; } .tot td { font-weight: 700; border-top: 2px solid #111; }
+  .banner { padding: 8px 12px; background: #fff3cd; border: 1px solid #e0c060; margin-bottom: 16px; }
+  .receipt + .receipt { page-break-before: always; margin-top: 48px; }
+</style></head><body>${list.map(one).join('\n')}</body></html>`;
+}

package/src/refundClient.ts

@@ -0,0 +1,177 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * refundClient.ts
+ *
+ * Browser-safe client for the refund flow. Mirrors `buyClient.ts` in shape:
+ * the caller drives the wallet step between `proveRefund` and
+ * `confirmRefund` so the SDK stays wallet-agnostic.
+ *
+ * The 14-day refund window is enforced by the backend (returns HTTP 409
+ * when closed) and cross-checked in the circuit; the SDK doesn't second-guess
+ * it locally so a single source of truth stays authoritative.
+ *
+ * `/prove/refund` shares the per-app in-flight slot with buy/renew:
+ * a concurrent request for the same app receives 409 { error: "proving queue
+ * busy", retryAfterMs, queueDepth }, which this client classifies into a
+ * `ProveQueueBusyError` so callers can wait+retry without opening a wallet.
+ */
+
+import { readErrorBody, tryQueueBusyFromBody, keeperError } from './proveErrors.js';
+import type { PurchaseReceipt } from './receipt.js';
+
+export type ProveRefundRequest = {
+  keeperUrl:    string;
+  licenseHash:  string;
+  buyerAddress: string;
+  zkAppAddress: string;
+  // Mina network this refund targets. Pull from your persisted ProofFile
+  // so it always matches the network the original buy was proved against.
+  network:      'devnet' | 'mainnet';
+  fetcher?:     typeof fetch;
+  signal?:      AbortSignal;
+};
+
+export type ProveRefundResponse = {
+  provenTxJson: string;
+  licenseHash:  string;
+};
+
+export type ConfirmRefundRequest = {
+  keeperUrl:    string;
+  zkAppAddress: string;
+  licenseHash:  string;
+  txHash:       string;
+  fetcher?:     typeof fetch;
+  signal?:      AbortSignal;
+};
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+// POST /prove/refund — backend compiles + proves the refund tx.
+// The backend 409s when the 14-day window has closed (surfaces through the
+// thrown `Error` message) and also when the shared per-app in-flight slot
+// is held by a concurrent buy/renew/refund (surfaces as a typed
+// `ProveQueueBusyError` — caller waits `retryAfterMs` and retries).
+export async function proveRefund(req: ProveRefundRequest): Promise<ProveRefundResponse> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/prove/refund`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    signal: req.signal,
+    body: JSON.stringify({
+      licenseHash:  req.licenseHash,
+      buyerAddress: req.buyerAddress,
+      zkAppAddress: req.zkAppAddress,
+      network:      req.network,
+    }),
+  });
+  if (!resp.ok) {
+    const parsed = await readErrorBody(resp);
+    const queueBusy = tryQueueBusyFromBody(parsed);
+    if (queueBusy) throw queueBusy;
+    throw keeperError(parsed);
+  }
+  return await resp.json() as ProveRefundResponse;
+}
+
+// POST /confirm/refund — promotes the in-memory refund intent to a
+// pending (refunded: true) LicenseRecord. Best-effort: if the caller
+// swallows the failure, eventSyncLoop will still pick up the on-chain
+// refund event.
+/** Returns the credit note cancelling the purchase receipt (zklicensing/receipt), when the keeper issued one: offer it as a download. */
+export async function confirmRefund(req: ConfirmRefundRequest): Promise<{ ok: true; creditNote?: PurchaseReceipt }> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/confirm/refund`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    signal: req.signal,
+    body: JSON.stringify({
+      zkAppAddress: req.zkAppAddress,
+      licenseHash:  req.licenseHash,
+      txHash:       req.txHash,
+    }),
+  });
+  if (!resp.ok) {
+    const parsed = await readErrorBody(resp);
+    throw keeperError(parsed);
+  }
+  const body = await resp.json().catch(() => ({})) as { creditNote?: PurchaseReceipt };
+  return { ok: true, ...(body?.creditNote ? { creditNote: body.creditNote } : {}) };
+}
+
+export type RefundStatus = {
+  // 'confirmed' once the eventSync sweep has observed the refundIssued event
+  // on-chain AND cleared the pending flag. 'pending' while the tx is in
+  // flight (confirmRefund flips record.status to 'refunded' immediately but
+  // leaves pending: true until the on-chain sweep lands, so both signals
+  // are needed to distinguish an intent from an actual on-chain refund).
+  // 'unknown' if no record has been persisted yet. 'failed' if the keeper
+  // saw the transaction included but failed on chain (failureReason says
+  // why): the license is as it was, not refunded; terminal.
+  status: 'confirmed' | 'pending' | 'unknown' | 'failed';
+  failureReason?: string;
+  txHash?:    string | null;
+  elapsedMs?: number;
+};
+
+export type PollRefundStatusOptions = {
+  keeperUrl:    string;
+  network:      'devnet' | 'mainnet';
+  zkAppAddress: string;
+  licenseHash:  string;
+  fetcher?:     typeof fetch;
+  intervalMs?:  number;  // default 10 000
+  timeoutMs?:   number;  // default 20 min
+  signal?:      AbortSignal;
+  onTick?:      (status: RefundStatus) => void;
+};
+
+// Polls GET /license/:zkAppAddress/:licenseHash until the refund has landed
+// on-chain (record.status === 'refunded') or the timeout fires. Mirrors
+// pollBuyStatus / pollRenewStatus.
+export async function pollRefundStatus(opts: PollRefundStatusOptions): Promise<RefundStatus> {
+  const fetcher = opts.fetcher ?? fetch;
+  const interval = opts.intervalMs ?? 10_000;
+  const timeout  = opts.timeoutMs  ?? 20 * 60 * 1000;
+  const startedAt = Date.now();
+  const deadline  = startedAt + timeout;
+  const url = `${baseUrl(opts.keeperUrl)}/license/${encodeURIComponent(opts.zkAppAddress)}/${encodeURIComponent(opts.licenseHash)}?network=${opts.network}`;
+
+  while (true) {
+    if (opts.signal?.aborted) throw new Error('pollRefundStatus aborted');
+    let status: RefundStatus = { status: 'unknown', elapsedMs: Date.now() - startedAt };
+    try {
+      const resp = await fetcher(url, { signal: opts.signal });
+      if (resp.ok) {
+        const body = await resp.json() as {
+          found?: boolean; status?: 'active' | 'refunded' | 'expired' | 'unknown';
+          pending?: boolean; txHash?: string | null;
+        };
+        if (!body.found) {
+          status = { status: 'unknown', elapsedMs: Date.now() - startedAt };
+        } else if (body.status === 'refunded' && body.pending === false) {
+          status = { status: 'confirmed', txHash: body.txHash ?? null, elapsedMs: Date.now() - startedAt };
+        } else {
+          status = { status: 'pending', txHash: body.txHash ?? null, elapsedMs: Date.now() - startedAt };
+        }
+      }
+    } catch { /* transient network — try again on next tick */ }
+    // Not confirmed yet: the keeper's landing watch says whether the
+    // transaction failed on chain (a keeper without the route: 404, ignored).
+    if (status.status !== 'confirmed') {
+      try {
+        const w = await fetcher(`${baseUrl(opts.keeperUrl)}/refund/status?licenseHash=${encodeURIComponent(opts.licenseHash)}`, { signal: opts.signal });
+        const watch = w.ok ? await w.json() as { status?: string; failureReason?: string } : null;
+        if (watch?.status === 'failed') status = { ...status, status: 'failed', ...(watch.failureReason ? { failureReason: watch.failureReason } : {}) };
+      } catch { /* transient — try again on next tick */ }
+    }
+    opts.onTick?.(status);
+    if (status.status === 'confirmed' || status.status === 'failed') return status;
+    if (Date.now() >= deadline) return status;
+    await new Promise<void>((r) => setTimeout(r, interval));
+  }
+}

package/src/registryTrustVerify.ts

@@ -0,0 +1,192 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * registryTrustVerify.ts — `zklicensing/permits/trust`
+ *
+ * Is this address a genuine, unmodifiable zkPermits registry? The permits
+ * counterpart of verifyTrustAnchor, used by `zklicensing-verify-trust
+ * --registry`. Each check is a discrete finding:
+ *
+ *   chain_account_exists              the account exists and is a zkApp
+ *   chain_vk_hash_pinned              its verification key is a published PermitRegistry release
+ *   chain_initialized                 authority keys are set (initialize ran)
+ *   chain_network_bound               the registry is bound to this network
+ *   chain_set_verification_key_locked the circuit can't be replaced
+ *   chain_set_permissions_impossible  permissions are frozen
+ *   chain_send_proof_only             funds move only through the circuit
+ *   chain_edit_state_proof_only       state changes only through the circuit
+ *   chain_set_zkapp_uri_impossible, chain_set_delegate_impossible, chain_set_timing_impossible
+ *   chain_website_bound               the authority's https website is written into zkappUri (set at deploy, frozen)
+ *   website_expected                  (with website) that website is on the host you expected
+ *   website_claims_registry           (with checkWellKnown) the website serves
+ *                                     /.well-known/zkpermits/<address>.json naming this registry and network
+ *   keeper_keys_match                 (with keeperUrl) the keeper's authority keys hash to the on-chain value
+ *   keeper_payout_match               (with keeperUrl) the keeper's payout address is the on-chain one
+ *   keeper_website_match              (with keeperUrl) the keeper lists the same website
+ *
+ * The website pair is the registry's identity: zkappUri says which site the
+ * registry belongs to, and the .well-known file, which only that site's
+ * owner can publish, says the site claims the registry. A copy of a real
+ * authority's registry under another address can't have both.
+ *
+ * Until the circuit is released after its audit, no verification-key hash
+ * is published, and chain_vk_hash_pinned fails by design.
+ */
+
+import type { Finding } from './trustAnchorVerify.js';
+export { permToString } from './trustAnchorVerify.js';
+
+export type RegistryChainFacts = {
+  accountFound: boolean;
+  fetchError?: string;
+  vkHash?: string;
+  /** The website written at deploy. */
+  zkappUri?: string;
+  /** appState as decimal strings. */
+  appState?: string[];
+  /** Permission names as permToString gives them ('Impossible', 'Proof', …). */
+  permissions?: Record<'setVerificationKey' | 'setPermissions' | 'send' | 'editState' | 'setZkappUri' | 'setDelegate' | 'setTiming', string | undefined>;
+};
+
+export type RegistryTrustReport = { ok: boolean; address: string; network: 'devnet' | 'mainnet'; findings: Finding[] };
+
+export type VerifyRegistryTrustOpts = {
+  address: string;
+  network: 'devnet' | 'mainnet';
+  /** Mina node GraphQL; default the public node for the network. */
+  minaGraphqlUrl?: string;
+  /** Also compare the keeper's record with the chain. */
+  keeperUrl?: string;
+  fetcher?: typeof fetch;
+  /** Override the chain read (tests, custom nodes). */
+  readChain?: (address: string) => Promise<RegistryChainFacts>;
+  /** The authority's website you expect (from its letters, signage or your own bookmarks); compared by host. */
+  website?: string;
+  /** Fetch the website's /.well-known/zkpermits/<address>.json and check it claims this registry. */
+  checkWellKnown?: boolean;
+  /** Override the published hashes (tests). */
+  canonicalVkHashes?: Readonly<Record<number, string>>;
+};
+
+/** Where an authority's website claims a registry: one file per registry address. */
+export function wellKnownPath(address: string): string {
+  return `/.well-known/zkpermits/${address}.json`;
+}
+
+/** The file an authority publishes at wellKnownPath(address) on its website. */
+export function wellKnownFile(address: string, network: 'devnet' | 'mainnet', name?: string): { registry: string; network: 'devnet' | 'mainnet'; name?: string } {
+  return { registry: address, network, ...(name ? { name } : {}) };
+}
+
+function httpsUrl(v: string | undefined): URL | null {
+  if (!v) return null;
+  try { const u = new URL(v); return u.protocol === 'https:' && u.hostname && !u.username && !u.password ? u : null; } catch { return null; }
+}
+
+async function readRegistryChain(address: string, graphqlUrl: string, fetcher?: typeof fetch): Promise<RegistryChainFacts> {
+  try {
+    const { readZkappAccount } = await import('./chainHead.js');
+    const a = await readZkappAccount({ address, graphqlUrl, fetcher });
+    if (!a.found) return { accountFound: false, fetchError: 'no account' };
+    const p = a.permissions ?? {};
+    return {
+      accountFound: true,
+      vkHash: a.vkHash,
+      zkappUri: a.zkappUri,
+      appState: a.appState,
+      permissions: {
+        setVerificationKey: p.setVerificationKey?.auth,
+        setPermissions: p.setPermissions,
+        send: p.send,
+        editState: p.editState,
+        setZkappUri: p.setZkappUri,
+        setDelegate: p.setDelegate,
+        setTiming: p.setTiming,
+      },
+    };
+  } catch (e: any) {
+    return { accountFound: false, fetchError: e?.message ?? String(e) };
+  }
+}
+
+export async function verifyRegistryTrust(opts: VerifyRegistryTrustOpts): Promise<RegistryTrustReport> {
+  const { DEFAULT_MINA_GRAPHQL_URLS } = await import('./onChainRoot.js');
+  const { PERMIT_REGISTRY_STATE, CANONICAL_PERMIT_VK_HASHES } = await import('./permitInterface.js');
+  const findings: Finding[] = [];
+  const add = (name: string, ok: boolean, detail: string) => findings.push({ name, ok, detail });
+  const done = (): RegistryTrustReport => ({ ok: findings.every(f => f.ok), address: opts.address, network: opts.network, findings });
+
+  const read = opts.readChain ?? ((a: string) => readRegistryChain(a, opts.minaGraphqlUrl ?? DEFAULT_MINA_GRAPHQL_URLS[opts.network], opts.fetcher));
+  const chain = await read(opts.address);
+  add('chain_account_exists', chain.accountFound && !!chain.vkHash, chain.accountFound ? (chain.vkHash ? 'zkApp account found' : 'account has no verification key (not a zkApp)') : `not found: ${chain.fetchError ?? ''}`);
+  if (!chain.accountFound || !chain.vkHash) return done();
+
+  const pinned = opts.canonicalVkHashes ?? CANONICAL_PERMIT_VK_HASHES;
+  const gen = Object.entries(pinned).find(([, h]) => h === chain.vkHash)?.[0];
+  add('chain_vk_hash_pinned', gen !== undefined,
+    gen !== undefined ? `verification key is PermitRegistry release generation ${gen}`
+      : Object.keys(pinned).length === 0 ? 'no PermitRegistry verification-key hash is published yet (pre-release)'
+        : `verification key ${chain.vkHash} is not a published PermitRegistry release`);
+
+  const st = (k: keyof typeof PERMIT_REGISTRY_STATE) => chain.appState?.[PERMIT_REGISTRY_STATE[k]] ?? '0';
+  add('chain_initialized', st('authorityKeysHash') !== '0', st('authorityKeysHash') !== '0' ? 'authority keys set' : 'authority keys not set: initialize has not run');
+  const { PERMIT_NETWORK } = await import('./permitMessages.js');
+  const want = PERMIT_NETWORK[opts.network].toString();
+  add('chain_network_bound', st('networkId') === want, st('networkId') === want ? `bound to ${opts.network}` : `bound to network id ${st('networkId')}, expected ${want} (${opts.network})`);
+
+  const perm = (name: string, key: keyof NonNullable<RegistryChainFacts['permissions']>, expected: string) => {
+    const got = chain.permissions?.[key];
+    add(name, got === expected, `${key} is ${got ?? 'unknown'}${got === expected ? '' : `, expected ${expected}`}`);
+  };
+  perm('chain_set_verification_key_locked', 'setVerificationKey', 'Impossible');
+  perm('chain_set_permissions_impossible', 'setPermissions', 'Impossible');
+  perm('chain_send_proof_only', 'send', 'Proof');
+  perm('chain_edit_state_proof_only', 'editState', 'Proof');
+  perm('chain_set_zkapp_uri_impossible', 'setZkappUri', 'Impossible');
+  perm('chain_set_delegate_impossible', 'setDelegate', 'Impossible');
+  perm('chain_set_timing_impossible', 'setTiming', 'Impossible');
+
+  const site = httpsUrl(chain.zkappUri);
+  add('chain_website_bound', !!site, site ? `belongs to ${chain.zkappUri}` : chain.zkappUri ? `zkappUri "${chain.zkappUri}" is not an https website` : 'no website written at deploy (zkappUri is empty)');
+  if (opts.website !== undefined) {
+    const want = httpsUrl(opts.website) ?? httpsUrl(`https://${opts.website}`);
+    const same = !!site && !!want && site.hostname.toLowerCase() === want.hostname.toLowerCase();
+    add('website_expected', same, same ? `on ${want!.hostname}, as expected` : `the registry belongs to ${site?.hostname ?? 'no website'}, not ${want?.hostname ?? opts.website}`);
+  }
+  if (opts.checkWellKnown) {
+    const url = site ? new URL(wellKnownPath(opts.address), site.origin).href : null;
+    if (!url) add('website_claims_registry', false, 'no website to ask');
+    else {
+      try {
+        const r = await (opts.fetcher ?? fetch)(url, { redirect: 'error', headers: { Accept: 'application/json' } });
+        if (!r.ok) throw new Error(`HTTP ${r.status}`);
+        const j: any = await r.json();
+        const claims = j?.registry === opts.address && j?.network === opts.network;
+        add('website_claims_registry', claims, claims ? `${url} claims this registry on ${opts.network}`
+          : `${url} names ${j?.registry ?? 'no registry'} on ${j?.network ?? 'no network'}`);
+      } catch (e: any) {
+        add('website_claims_registry', false, `${url}: ${e?.message ?? e}`);
+      }
+    }
+  }
+
+  if (opts.keeperUrl) {
+    try {
+      const r = await (opts.fetcher ?? fetch)(`${opts.keeperUrl.replace(/\/+$/, '')}/permits/registries/${opts.address}`);
+      if (!r.ok) throw new Error(`HTTP ${r.status}`);
+      const { registry } = await r.json() as { registry: { keys: string[]; threshold: number; payout: string; website?: string } };
+      const { PublicKey, Field } = await import('o1js');
+      const { authorityKeys, authorityKeysHash } = await import('./permitMessages.js');
+      const h = authorityKeysHash(authorityKeys(registry.keys.map(k => PublicKey.fromBase58(k)), registry.threshold)).toString();
+      add('keeper_keys_match', h === st('authorityKeysHash'), h === st('authorityKeysHash')
+        ? `keeper lists ${registry.keys.length} keys, threshold ${registry.threshold}, matching the chain` : 'the keeper\'s authority keys do not match the chain (stale or wrong record)');
+      const payout = PublicKey.fromFields([Field(st('payoutX')), Field(st('payoutIsOdd'))]).toBase58();
+      add('keeper_payout_match', payout === registry.payout, payout === registry.payout ? `payout ${payout}` : `chain pays ${payout}, keeper lists ${registry.payout}`);
+      add('keeper_website_match', registry.website === chain.zkappUri, registry.website === chain.zkappUri ? `website ${registry.website}` : `chain says ${chain.zkappUri ?? 'none'}, keeper lists ${registry.website ?? 'none'}`);
+    } catch (e: any) {
+      add('keeper_keys_match', false, `keeper record unavailable: ${e?.message ?? e}`);
+    }
+  }
+  return done();
+}