zklicensing 0.1.0-beta.2 → 0.1.0-beta.3

package/src/ownership.ts

@@ -0,0 +1,198 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * ownership.ts
+ *
+ * Ownership-token helpers and a small in-memory nonce store for the
+ * challenge-response /verify flow.
+ *
+ * Replay-resistance: the LicenseProof's public input binds (licenseHash,
+ * nonce). The keeper hands out a nonce, the client proves against it, the
+ * keeper consumes the nonce on the way through. Tokens are HMAC-SHA256 of
+ * the (zkAppAddress, licenseHash, exp, jti?) tuple so signature validation
+ * is purely cryptographic — no server-side lookup, restart-safe as long as
+ * the HMAC key persists.
+ *
+ * Session tracking: the optional `jti` field lets the caller run a
+ * revocation / concurrency layer on top of the stateless HMAC — the token
+ * is still validated cryptographically, but the caller can also check that
+ * the jti is present in a per-license active-session set. Absent jti keeps
+ * old callers working unchanged (there is no session tracking to begin with,
+ * so nothing needs to migrate).
+ */
+
+import { createHmac, randomBytes, timingSafeEqual } from 'crypto';
+import { Field } from 'o1js';
+
+export const OWNERSHIP_CHALLENGE_TTL_MS = 600_000;
+// A device that stays active refreshes via a fresh /challenge + /respond;
+// a lost/uninstalled device burns its slot for at most this long before
+// the server prunes it (see verifyService session store). 7 days keeps
+// re-prove pressure low on daily-use apps while still bounding the recovery
+// window for owners hitting the concurrent-device cap.
+export const OWNERSHIP_TOKEN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+export type OwnershipTokenPayload = {
+  z:    string;
+  l:    string;
+  e:    number;
+  // Random device-session id. Optional so pre-jti callers still round-trip.
+  // When present, the server-side session store gates verify-time access:
+  // an HMAC-valid token whose jti was released (or evicted by the concurrent-
+  // device cap) is refused.
+  jti?: string;
+};
+
+// Generate a 128-bit random jti. base64url so it drops into token payloads
+// and query strings without escaping.
+export function newJti(): string {
+  return randomBytes(16).toString('base64url');
+}
+
+// --- challenge store ---------------------------------------------------------
+
+export type ChallengeStore = {
+  issue(licenseHash: string): { nonce: string; ttl: number };
+  consume(licenseHash: string, nonce: string): 'ok' | 'unknown' | 'expired';
+  size(): number;
+};
+
+export function createChallengeStore(ttlMs: number = OWNERSHIP_CHALLENGE_TTL_MS): ChallengeStore {
+  const issued = new Map<string, number>(); // `${lh}:${nonce}` → expiresAt
+  return {
+    issue(licenseHash: string) {
+      const nonce = Field.random().toString();
+      issued.set(`${licenseHash}:${nonce}`, Date.now() + ttlMs);
+      return { nonce, ttl: ttlMs };
+    },
+    consume(licenseHash: string, nonce: string) {
+      const key = `${licenseHash}:${nonce}`;
+      const expiresAt = issued.get(key);
+      if (expiresAt === undefined) return 'unknown';
+      issued.delete(key);
+      if (Date.now() > expiresAt) return 'expired';
+      return 'ok';
+    },
+    size: () => issued.size,
+  };
+}
+
+// --- token signing -----------------------------------------------------------
+
+export function signOwnershipToken(key: Buffer, payload: OwnershipTokenPayload): string {
+  const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const mac = createHmac('sha256', key).update(body).digest('base64url');
+  return `${body}.${mac}`;
+}
+
+export function verifyOwnershipToken(key: Buffer, token: string): OwnershipTokenPayload | null {
+  const dot = token.indexOf('.');
+  if (dot < 0) return null;
+  const body = token.slice(0, dot);
+  const mac = token.slice(dot + 1);
+  const expected = createHmac('sha256', key).update(body).digest('base64url');
+  const a = Buffer.from(mac);
+  const b = Buffer.from(expected);
+  if (a.length !== b.length || !timingSafeEqual(a, b)) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as OwnershipTokenPayload;
+    if (Date.now() > payload.e) return null;
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+export function newOwnershipKey(): Buffer {
+  return randomBytes(32);
+}
+
+// --- session store -----------------------------------------------------------
+//
+// Tracks active device-sessions per license, enforced by the caller (see
+// verifyService /respond, /releaseSeat, /reset-sessions). The store is a plain
+// in-memory Map — restart-safe by design: a keeper restart drops all sessions,
+// requiring devices to re-prove ownership. That is intentional; the alternative
+// (persisted sessions) would let a stolen /respond bypass concurrency caps
+// across restarts without any signal to the license owner.
+//
+// Cap semantics:
+//   - cap == 0 (or undefined): no limit — insert always succeeds.
+//   - cap  > 0: prune expired first; if remaining active count >= cap, refuse
+//     the insert. The caller decides how to surface that (429 in verifyService).
+//
+// Explicit release (POST /releaseSeat by a caller holding the token) and full
+// reset (POST /reset-sessions after re-proving ownership) both flow through
+// this same store.
+
+export type SessionStore = {
+  // Insert a new session. Prunes expired first. Returns:
+  //   'ok'      → session inserted; `active` includes this one.
+  //   'at-cap'  → cap reached; caller should surface 429.
+  insert(licenseHash: string, jti: string, exp: number, cap: number): { state: 'ok' | 'at-cap'; active: number };
+  // Membership check for verify-time. Prunes expired opportunistically so a
+  // token whose jti expired isn't kept alive by verify calls hitting a stale
+  // slot in the map.
+  has(licenseHash: string, jti: string): boolean;
+  // Release a single seat. Idempotent — returns whether the jti was present.
+  releaseSeat(licenseHash: string, jti: string): boolean;
+  // Drop all sessions for a license. Used by /reset-sessions after a fresh
+  // ownership proof. Returns the count of sessions dropped (0 if none).
+  reset(licenseHash: string): number;
+  // Live counts per license, for admin / support tooling. Prunes expired
+  // entries before counting.
+  activeCount(licenseHash: string): number;
+  // Total sessions across all licenses — for /health telemetry.
+  size(): number;
+};
+
+export function createSessionStore(): SessionStore {
+  // licenseHash → jti → expiresAt
+  const sessions = new Map<string, Map<string, number>>();
+  const pruneLicense = (licenseHash: string): Map<string, number> | undefined => {
+    const perLic = sessions.get(licenseHash);
+    if (!perLic) return undefined;
+    const now = Date.now();
+    for (const [jti, exp] of perLic) if (exp <= now) perLic.delete(jti);
+    if (perLic.size === 0) { sessions.delete(licenseHash); return undefined; }
+    return perLic;
+  };
+  return {
+    insert(licenseHash, jti, exp, cap) {
+      const perLic = pruneLicense(licenseHash) ?? new Map<string, number>();
+      if (cap > 0 && perLic.size >= cap && !perLic.has(jti)) {
+        return { state: 'at-cap', active: perLic.size };
+      }
+      perLic.set(jti, exp);
+      sessions.set(licenseHash, perLic);
+      return { state: 'ok', active: perLic.size };
+    },
+    has(licenseHash, jti) {
+      const perLic = pruneLicense(licenseHash);
+      return perLic?.has(jti) ?? false;
+    },
+    releaseSeat(licenseHash, jti) {
+      const perLic = sessions.get(licenseHash);
+      if (!perLic) return false;
+      const had = perLic.delete(jti);
+      if (perLic.size === 0) sessions.delete(licenseHash);
+      return had;
+    },
+    reset(licenseHash) {
+      const perLic = sessions.get(licenseHash);
+      if (!perLic) return 0;
+      const n = perLic.size;
+      sessions.delete(licenseHash);
+      return n;
+    },
+    activeCount(licenseHash) {
+      return pruneLicense(licenseHash)?.size ?? 0;
+    },
+    size() {
+      let n = 0;
+      for (const perLic of sessions.values()) n += perLic.size;
+      return n;
+    },
+  };
+}

package/src/proveErrors.ts

@@ -0,0 +1,70 @@
+// 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/migrate. The
+ * keeper serializes all four 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 keeper.
+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 };
+}
+
+// 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/refundClient.ts

@@ -0,0 +1,144 @@
+// 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 on the keeper side (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.
+ */
+
+export type ProveRefundRequest = {
+  keeperUrl:    string;
+  licenseHash:  string;
+  buyerAddress: string;
+  zkAppAddress: string;
+  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(/\/+$/, '');
+}
+
+async function readJsonError(resp: Response): Promise<string> {
+  try {
+    const body = await resp.json() as Record<string, unknown>;
+    if (typeof body.error === 'string') return body.error;
+  } catch { /* body wasn't JSON */ }
+  return `HTTP ${resp.status}`;
+}
+
+// POST /prove/refund — keeper compiles + proves the refund tx.
+// The keeper 409s when the 14-day window has closed; that error surfaces
+// through the thrown `Error` message.
+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,
+    }),
+  });
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  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.
+export async function confirmRefund(req: ConfirmRefundRequest): Promise<{ ok: true }> {
+  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) throw new Error(await readJsonError(resp));
+  return { ok: true };
+}
+
+export type RefundStatus = {
+  // 'confirmed' once the eventSync sweep has observed the refundIssued event
+  // on-chain (record.status flips to 'refunded'). 'pending' while the tx is
+  // in flight. 'unknown' if no record has been persisted yet.
+  status: 'confirmed' | 'pending' | 'unknown';
+  txHash?:    string | null;
+  elapsedMs?: number;
+};
+
+export type PollRefundStatusOptions = {
+  keeperUrl:    string;
+  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)}`;
+
+  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'; txHash?: string | null;
+        };
+        if (!body.found) {
+          status = { status: 'unknown', elapsedMs: Date.now() - startedAt };
+        } else if (body.status === 'refunded') {
+          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 */ }
+    opts.onTick?.(status);
+    if (status.status === 'confirmed') return status;
+    if (Date.now() >= deadline) return status;
+    await new Promise<void>((r) => setTimeout(r, interval));
+  }
+}

package/src/renewClient.ts

@@ -0,0 +1,209 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * renewClient.ts
+ *
+ * Browser-safe client for the renew flow. Mirrors `buyClient.ts` in shape:
+ * the caller drives the wallet step between `proveRenew` and `confirmRenew`
+ * so the SDK stays wallet-agnostic.
+ *
+ * Unlike buy, renew carries a legally load-bearing `waiverAccepted` flag —
+ * EU/UK CRD Article 16(m) extinguishes the 14-day right of withdrawal only
+ * on the buyer's express affirmative act (consent to immediate delivery +
+ * acknowledgment of loss of withdrawal). We refuse the /prove/renew call
+ * when the flag is false to keep third-party integrators from silently
+ * shipping a UI that omits the waiver gate.
+ *
+ * Also refused pre-network when the keeper's sales-freeze schedule has
+ * fired (salesFrozen === true) — the keeper would 423 the request anyway,
+ * so surfacing the specific message client-side avoids a wasted round-trip.
+ */
+
+import { resolveFreezeState } from './freezeClient.js';
+import { readErrorBody, tryQueueBusyFromBody } from './proveErrors.js';
+
+export type ProveRenewRequest = {
+  keeperUrl:       string;
+  licenseHash:     string;
+  buyerAddress:    string;
+  zkAppAddress:    string;
+  duration:        0 | 1 | 2; // 0 = Monthly, 1 = Yearly, 2 = 5 Years
+  // Set from the UI's Article 16(m) consent gate. Missing/false raises
+  // before the network call — the SDK never proves a renew without it.
+  waiverAccepted:  boolean;
+  // Optional freeze-slot override. When omitted the SDK reads
+  // `process.env.FREEZE_AFTER_SLOT` (Node only), else GET /health.
+  freezeAfterSlot?: number | null;
+  fetcher?:        typeof fetch;
+  signal?:         AbortSignal;
+};
+
+export type ProveRenewResponse = {
+  provenTxJson:  string;
+  newExpirySlot: number;
+  licenseHash:   string;
+  renewAmount:   string; // nanomina
+  // Deployment generation the keeper proved against. If the buyer's stored
+  // ProofFile.generation is smaller, renew.ts walks ancestors and calls
+  // migrateLicense on each hop before submitting the renew.
+  generation:    number;
+  // Key the keeper stored the per-app in-flight slot under. Passed back to
+  // POST /tx-broadcast after the wallet returns a hash. See ProveBuyResponse.
+  appKey:        string;
+};
+
+export type ConfirmRenewRequest = {
+  keeperUrl:    string;
+  zkAppAddress: string;
+  licenseHash:  string;
+  txHash:       string;
+  fetcher?:     typeof fetch;
+  signal?:      AbortSignal;
+};
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+async function readJsonError(resp: Response): Promise<string> {
+  try {
+    const body = await resp.json() as Record<string, unknown>;
+    if (typeof body.error === 'string') return body.error;
+  } catch { /* body wasn't JSON */ }
+  return `HTTP ${resp.status}`;
+}
+
+// POST /prove/renew — keeper compiles + proves the renew tx.
+// Rejects locally when `waiverAccepted` is false; a network call in that
+// state would be wasted work and would give the caller no signal that the
+// legal precondition was missing. Also rejects when the keeper's freeze
+// has fired — same reasoning.
+export async function proveRenew(req: ProveRenewRequest): Promise<ProveRenewResponse> {
+  if (req.waiverAccepted !== true) {
+    throw new Error('waiverAccepted must be true — Article 16(m) waiver required to renew');
+  }
+  const fetcher = req.fetcher ?? fetch;
+  const freeze = await resolveFreezeState({
+    keeperUrl:       req.keeperUrl,
+    freezeAfterSlot: req.freezeAfterSlot,
+    fetcher,
+    signal:          req.signal,
+  });
+  if (freeze.salesFrozen) {
+    throw new Error('Sales frozen — new renewals refused ahead of scheduled hardfork migration');
+  }
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/prove/renew`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    signal: req.signal,
+    body: JSON.stringify({
+      licenseHash:  req.licenseHash,
+      buyerAddress: req.buyerAddress,
+      zkAppAddress: req.zkAppAddress,
+      duration:     req.duration,
+    }),
+  });
+  if (!resp.ok) {
+    const parsed = await readErrorBody(resp);
+    const queueBusy = tryQueueBusyFromBody(parsed);
+    if (queueBusy) throw queueBusy;
+    throw new Error(parsed.message);
+  }
+  return await resp.json() as ProveRenewResponse;
+}
+
+// POST /confirm/renew — promotes the in-memory renew intent to a pending
+// LicenseRecord. Call this only after the wallet returns a txHash.
+export async function confirmRenew(req: ConfirmRenewRequest): Promise<{ ok: true }> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/confirm/renew`, {
+    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) throw new Error(await readJsonError(resp));
+  return { ok: true };
+}
+
+export type RenewStatus = {
+  // 'confirmed' once the eventSync sweep has observed the licenseRenewed event
+  // on-chain and cleared the pending flag with the new expiry in place.
+  // 'pending' while the tx is in flight. 'unknown' if the license record
+  // hasn't been persisted yet (confirmRenew hasn't run or the intent expired).
+  status: 'confirmed' | 'pending' | 'unknown';
+  expirySlot?: number;
+  txHash?:     string | null;
+  elapsedMs?:  number;
+};
+
+export type PollRenewStatusOptions = {
+  keeperUrl:     string;
+  zkAppAddress:  string;
+  licenseHash:   string;
+  // The expected new expiry (from ProveRenewResponse). Confirmation requires
+  // BOTH pending=false AND the on-chain record's expirySlot matching or
+  // exceeding this — the pending flag alone flips before the sweep, so
+  // matching against the expected slot avoids reporting confirmed on the
+  // stale pre-renew record.
+  newExpirySlot: number;
+  fetcher?:      typeof fetch;
+  // Mina slots are ~90 s and a tx usually lands within a few slots, so a
+  // 10 s tick keeps the UI live without hammering the keeper.
+  intervalMs?:   number;  // default 10 000
+  timeoutMs?:    number;  // default 20 min
+  signal?:       AbortSignal;
+  onTick?:       (status: RenewStatus) => void;
+};
+
+// Polls GET /license/:zkAppAddress/:licenseHash until the renew has landed
+// on-chain (pending flipped and new expiry recorded) or the timeout fires.
+// Mirrors pollBuyStatus, except the terminal condition is Mina-side rather
+// than keeper-side buy-watch — renew has no dedicated watch map.
+export async function pollRenewStatus(opts: PollRenewStatusOptions): Promise<RenewStatus> {
+  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)}`;
+
+  while (true) {
+    if (opts.signal?.aborted) throw new Error('pollRenewStatus aborted');
+    let status: RenewStatus = { 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; expirySlot?: number; pending?: boolean; txHash?: string | null;
+        };
+        if (!body.found) {
+          status = { status: 'unknown', elapsedMs: Date.now() - startedAt };
+        } else if (body.pending === false && (body.expirySlot ?? 0) >= opts.newExpirySlot) {
+          status = {
+            status: 'confirmed',
+            expirySlot: body.expirySlot,
+            txHash: body.txHash ?? null,
+            elapsedMs: Date.now() - startedAt,
+          };
+        } else {
+          status = {
+            status: 'pending',
+            expirySlot: body.expirySlot,
+            txHash: body.txHash ?? null,
+            elapsedMs: Date.now() - startedAt,
+          };
+        }
+      }
+    } catch { /* transient network — try again on next tick */ }
+    opts.onTick?.(status);
+    if (status.status === 'confirmed') return status;
+    if (Date.now() >= deadline) return status;
+    await new Promise<void>((r) => setTimeout(r, interval));
+  }
+}