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

package/src/bindClient.ts

@@ -0,0 +1,297 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * bindClient.ts
+ *
+ * Browser-safe client for the non-custodial device-binding flow.
+ * Mirrors `buyClient.ts` in shape: the caller drives the wallet step
+ * between `proveBind` and `confirmBind`, so the SDK stays
+ * wallet-agnostic.
+ *
+ * Binding is a root-mutating tx on the same per-app in-flight slot
+ * that buy / renew / refund use — a concurrent request
+ * against the same app returns 409 `ProveQueueBusyError`, which the
+ * caller must catch and retry (see the retry loop in
+ * examples/src/bind.ts).
+ *
+ * The signature scheme is Pallas Schnorr and is re-verified INSIDE
+ * the on-chain circuit via `Signature.verify()` — a compromised
+ * backend cannot forge a bind because it can't produce a signature
+ * that satisfies the in-circuit check.
+ */
+
+import { Field, PrivateKey, PublicKey, Signature } from 'o1js';
+import { readErrorBody, tryQueueBusyFromBody, keeperError } from './proveErrors.js';
+import { encodePublicKey, encodeSignature, signBinding, slotStateOf } from './ownershipSignature.js';
+
+// The bind message shape reuses `bindingMessageFields` from
+// ownershipSignature.ts, which prefixes every preimage with
+// TAG_BINDING so a captured bind signature can't be replayed as an
+// unbind (or any other flow) even at identical field values.
+
+export type ProveBindRequest = {
+  keeperUrl:        string;
+  // Mina network the vendor's zkApp is deployed to. Must match the
+  // network the buy was proved against.
+  network:          'devnet' | 'mainnet';
+  // Address of the vendor's LicensingApp — combined with `licenseHash`
+  // to route to the right on-chain state.
+  zkAppAddress:     string;
+  // Poseidon([ownerPub.x, ownerPub.isOdd.toField()]) — the same value
+  // computed at buy time via `licenseHashFromPubkey`. The circuit
+  // asserts `Poseidon([pk.x, pk.isOdd.toField()]) === leaf.licenseHash`,
+  // which is the on-chain owner-pubkey commitment.
+  licenseHash:      string;
+  // Passphrase-derived Pallas Schnorr private key. The pubkey is
+  // derived from it locally and both are sent on the wire — the
+  // backend cross-checks the pubkey against the leaf.
+  ownerPrivateKey:  PrivateKey;
+  // Poseidon([devicePub.x, devicePub.isOdd.toField()]) — get this
+  // from `getOrCreateDeviceIdentity(storageKey).deviceCommitment`.
+  // The raw device pubkey never crosses the wire; only its
+  // commitment does.
+  deviceCommitment: string;
+  // Which slot (0..cap-1) to write into.
+  slotIndex:        number;
+  // Buyer's Mina wallet address — pays fees + signs the tx.
+  buyerAddress:     string;
+  // Optional nonce override. When omitted the SDK samples a fresh
+  // 128-bit random nonce per call. Callers that need a deterministic
+  // nonce for tests can pass one explicitly. Pass as a decimal Field
+  // string.
+  nonce?:           string;
+  // Optional overrides for the on-chain state the signature commits to: the
+  // target slot's packed (boundAt, freedAt) (see slotStateOf) and the
+  // license's expirySlot. When either is omitted the SDK reads both from
+  // GET /license/:zkApp/:hash. A stale value only makes the keeper refuse
+  // the bind (409); it can't authorize anything other than the transition
+  // from that exact state.
+  slotState?:       string;
+  expirySlot?:      number;
+  fetcher?:         typeof fetch;
+  signal?:          AbortSignal;
+};
+
+export type ProveBindResponse = {
+  provenTxJson: string;
+  licenseHash:  string;
+  slotIndex:    number;
+};
+
+export type ConfirmBindRequest = {
+  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}`;
+}
+
+// Sample a fresh replay-defense nonce. WebCrypto is required for
+// `crypto.getRandomValues` — same runtime floor as the rest of the
+// signing surface (Node ≥ 20, modern browsers).
+function freshNonce(): string {
+  const crypto = (globalThis as any).crypto as Crypto | undefined;
+  if (!crypto?.getRandomValues) {
+    throw new Error(
+      'crypto.getRandomValues unavailable — bindClient requires Node ≥ 20 or a modern browser',
+    );
+  }
+  const bytes = new Uint8Array(16); // 128 bits
+  crypto.getRandomValues(bytes);
+  let n = 0n;
+  for (const b of bytes) n = (n << 8n) | BigInt(b);
+  // Field(n) is safe: 128 bits << the Pallas base field size, so no
+  // modular reduction ever fires here.
+  return Field(n).toString();
+}
+
+// Read the target slot's current packed state and the license's expiry from
+// the keeper's license mirror. Shared with unbindClient.
+export async function fetchBindingState(opts: {
+  keeperUrl:    string;
+  network:      'devnet' | 'mainnet';
+  zkAppAddress: string;
+  licenseHash:  string;
+  slotIndex:    number;
+  fetcher?:     typeof fetch;
+  signal?:      AbortSignal;
+}): Promise<{ slotState: string; expirySlot: number }> {
+  const fetcher = opts.fetcher ?? fetch;
+  const url = `${baseUrl(opts.keeperUrl)}/license/${encodeURIComponent(opts.zkAppAddress)}/`
+    + `${encodeURIComponent(opts.licenseHash)}?network=${encodeURIComponent(opts.network)}`;
+  const resp = await fetcher(url, { signal: opts.signal });
+  if (!resp.ok) throw new Error(`License lookup failed: ${await readJsonError(resp)}`);
+  const body = await resp.json() as {
+    found?: boolean;
+    expirySlot?: number;
+    devices?: Array<{ boundAtSlot: number; freedAtSlot: number } | null>;
+  };
+  if (!body.found || !body.expirySlot) throw new Error('License not found on the keeper.');
+  return {
+    slotState:  slotStateOf((body.devices ?? [])[opts.slotIndex]),
+    expirySlot: body.expirySlot,
+  };
+}
+
+// POST /prove/bind — backend compiles + proves the bind tx.
+//
+// Retry contract:
+//   - 409 `proving queue busy` → `ProveQueueBusyError`; caller catches
+//     and retries with `retryAfterMs` cadence (see examples/src/bind.ts).
+//   - Any other non-2xx surfaces the body's `error` field verbatim.
+export async function proveBind(req: ProveBindRequest): Promise<ProveBindResponse> {
+  const fetcher = req.fetcher ?? fetch;
+  const nonce = req.nonce ?? freshNonce();
+  const { slotState, expirySlot } = (req.slotState !== undefined && req.expirySlot !== undefined)
+    ? { slotState: req.slotState, expirySlot: req.expirySlot }
+    : await fetchBindingState({ ...req, fetcher });
+
+  const ownerPubKey: PublicKey = req.ownerPrivateKey.toPublicKey();
+  const ownerSig: Signature = signBinding(req.ownerPrivateKey, {
+    licenseHash:      req.licenseHash,
+    deviceCommitment: req.deviceCommitment,
+    slotIndex:        req.slotIndex,
+    nonce,
+    slotState,
+    expirySlot,
+    zkAppAddress:     req.zkAppAddress,
+  });
+
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/prove/bind`, {
+    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,
+      ownerPubKey:      encodePublicKey(ownerPubKey),
+      ownerSig:         encodeSignature(ownerSig),
+      deviceCommitment: req.deviceCommitment,
+      slotIndex:        req.slotIndex,
+      nonce,
+    }),
+  });
+  if (!resp.ok) {
+    const parsed = await readErrorBody(resp);
+    const queueBusy = tryQueueBusyFromBody(parsed);
+    if (queueBusy) throw queueBusy;
+    throw keeperError(parsed);
+  }
+  return await resp.json() as ProveBindResponse;
+}
+
+// POST /confirm/bind — pass-through no-op that clears the staged
+// intent on the backend. Call this only after the wallet has returned
+// a real txHash; a cancelled or dropped signature leaves the intent
+// to expire on its own.
+export async function confirmBind(req: ConfirmBindRequest): Promise<{ ok: true }> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/confirm/bind`, {
+    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 BindStatus = {
+  // 'confirmed' once eventSync has observed the DeviceBound event on-chain
+  // and the license record's devices[slotIndex] reflects the new commitment.
+  // 'pending' while the tx is in flight. 'unknown' if the license record
+  // hasn't been persisted yet.
+  status: 'confirmed' | 'pending' | 'unknown';
+  slotIndex?:        number;
+  deviceCommitment?: string;
+  elapsedMs?:        number;
+};
+
+export type PollBindStatusOptions = {
+  keeperUrl:        string;
+  network:          'devnet' | 'mainnet';
+  zkAppAddress:     string;
+  licenseHash:      string;
+  slotIndex:        number;
+  // The commitment the slot should carry once the tx has landed —
+  // typically `device.deviceCommitment` from ProveBindResponse or the
+  // value fed into proveBind. Confirmation requires the on-chain record
+  // to reflect exactly this value at `slotIndex`.
+  deviceCommitment: string;
+  fetcher?:         typeof fetch;
+  // Mina slots are ~90 s and a tx usually lands within a few slots, so
+  // 10 s ticks keep the UI live without hammering the backend.
+  intervalMs?:      number;  // default 10 000
+  timeoutMs?:       number;  // default 20 min
+  signal?:          AbortSignal;
+  onTick?:          (status: BindStatus) => void;
+};
+
+// Polls GET /license/:zkAppAddress/:licenseHash until the bind has
+// landed on-chain (the target slot's commitment matches the expected
+// value) or the timeout fires. Mirrors pollRenewStatus in shape.
+export async function pollBindStatus(opts: PollBindStatusOptions): Promise<BindStatus> {
+  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('pollBindStatus aborted');
+    let status: BindStatus = { 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;
+          devices?: Array<{ slotIndex: number; deviceCommitment: string }>;
+        };
+        if (body.found) {
+          const slot = (body.devices ?? []).find(d => d.slotIndex === opts.slotIndex);
+          const commitment = slot?.deviceCommitment ?? '0';
+          if (commitment === opts.deviceCommitment) {
+            status = {
+              status: 'confirmed',
+              slotIndex: opts.slotIndex,
+              deviceCommitment: commitment,
+              elapsedMs: Date.now() - startedAt,
+            };
+          } else {
+            status = {
+              status: 'pending',
+              slotIndex: opts.slotIndex,
+              deviceCommitment: commitment,
+              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/buyClient.ts

@@ -0,0 +1,344 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * buyClient.ts
+ *
+ * Browser-safe client for the buy flow. Exposes the three backend roundtrips
+ * (derive identity → prove → confirm) as small, individually testable
+ * functions plus a `pollBuyStatus` helper. Deliberately does NOT talk to a
+ * wallet — the caller drives the wallet step between `proveBuy` and
+ * `confirmBuy`, so the SDK stays wallet-agnostic and can be reused by CLI
+ * tools, alternate UIs, and third-party integrators.
+ *
+ * Peer dep: o1js (for Poseidon + Pallas PrivateKey/PublicKey/Signature).
+ * The ownership-signing surface (ownershipSignature.ts) uses Mina-native
+ * Schnorr so the passphrase-derived keypair also authorizes /prove/bind
+ * and /prove/unbind — verified IN-CIRCUIT there via Signature.verify(),
+ * which requires o1js. Every buy-flow consumer already ships o1js for the
+ * buy-witness path, so this is not new cost.
+ */
+
+import { resolveFreezeState } from './freezeClient.js';
+import type { PurchaseReceipt } from './receipt.js';
+import { REFUND_WINDOW_N, TOLERANCE_WINDOW_N } from './contractInterface.js';
+import { readErrorBody, tryQueueBusyFromBody, keeperError } from './proveErrors.js';
+import { deriveOwnershipKeypair } from './ownershipSignature.js';
+import { licenseHashFromPubkey } from './ownershipLicenseHash.js';
+import type { PrivateKey, PublicKey } from 'o1js';
+
+export type BuyIdentity = {
+  // Pallas Schnorr pubkey. The buyer keeps it locally; on-chain the leaf's
+  // `licenseHash` IS `Poseidon([pk.x, pk.isOdd.toField()])` (the circuit
+  // asserts this at buy time), so no separate owner-pubkey commitment is
+  // needed — the pubkey is re-derived from the passphrase whenever a
+  // bind/unbind signature is needed.
+  publicKey:       PublicKey;
+  // Mina canonical base58 encoding of publicKey. Convenience field for
+  // callers that need to persist or transmit the pubkey shape.
+  publicKeyBase58: string;
+  // Passphrase-derived Pallas private key. Callers should scope this to
+  // the activation call and let it be GC'd rather than persisting it —
+  // the passphrase is the real secret, and the keypair is re-derivable
+  // from it deterministically at any point.
+  privateKey:      PrivateKey;
+  // Poseidon([pk.x, pk.isOdd.toField()]) as a decimal Field string.
+  // Sent to /prove/buy exactly like the old Poseidon(Poseidon(passphrase))
+  // licenseHash was. On-chain LicensingApp treats licenseHash as opaque,
+  // so no contract change is needed for the preimage swap.
+  licenseHash:     string;
+};
+
+// Derive the ownership keypair + licenseHash the buy flow keys off.
+// Deterministic in (passphrase, zkAppAddress) — same inputs always map
+// to the same keypair (via HKDF-SHA256) and therefore the same
+// licenseHash on every device, so a buyer can re-derive their license
+// identity anywhere from the passphrase and the app address. Binding
+// the derivation to the app address means a leaked passphrase for app A
+// cannot be replayed as a valid activation for app B.
+//
+// HKDF still needs WebCrypto (Node ≥20, Chromium 137+, Safari 17+,
+// Firefox 130+); the scalar reduction and Pallas group operations are
+// pure JS through o1js. Async because subtle.deriveBits is async.
+export async function deriveBuyIdentity(
+  passphrase:   string,
+  zkAppAddress: string,
+): Promise<BuyIdentity> {
+  const { privateKey, publicKey, publicKeyBase58 } = await deriveOwnershipKeypair(passphrase, zkAppAddress);
+  const licenseHash = licenseHashFromPubkey(publicKey);
+  return { publicKey, publicKeyBase58, privateKey, licenseHash };
+}
+
+export type ProveBuyRequest = {
+  // Standing consent (zklicensing/agent/actions) when an AI agent gives the
+  // withdrawal waiver for its owner; only sent with the waiver.
+  agentConsent?:  unknown;
+  keeperUrl:      string;
+  // Poseidon([pallasPubkey.x, pallasPubkey.isOdd.toField()]) as a decimal
+  // Field string — computed client-side via deriveBuyIdentity(). This IS
+  // the on-chain owner-pubkey commitment (the circuit asserts equality at
+  // buy time), so anyone with the passphrase (and hence the pubkey) can
+  // prove ownership at bind / unbind time without the passphrase ever
+  // leaving the device.
+  licenseHash:    string;
+  buyerAddress:   string;
+  zkAppAddress:   string;
+  // Base58-encoded Pallas Schnorr pubkey derived from the passphrase — use
+  // `deriveBuyIdentity(passphrase, zkAppAddress).publicKeyBase58`. Bind /
+  // unbind proofs Signature.verify() against this key without the passphrase
+  // ever leaving the buyer's device. Circuit-side the licensing service
+  // asserts `licenseHash === Poseidon([pk.x, pk.isOdd.toField()])`, so a
+  // mismatch is rejected front-door.
+  ownerPubKey:    string;
+  // Mina network this buy targets. Must match the network the vendor deployed
+  // the zkApp on — the licensing service uses this to pick the matching
+  // GraphQL endpoint and signer. Persist in your ProofFile so renew/refund
+  // can pass the same value.
+  network:        'devnet' | 'mainnet';
+  duration:       0 | 1 | 2 | 3; // 0 = Monthly, 1 = Yearly, 2 = 5 Years, 3 = Perpetual
+  buyerCountry:   string;    // ISO 3166-1 alpha-2
+  // Buyer's postal code — MANDATORY when buyerCountry === 'US' (state-level
+  // sales-tax attribution). Ignored server-side for non-US buyers. Format is
+  // enforced by the backend: 5 digits or ZIP+4 ("12345" or "12345-6789").
+  buyerZip?:      string;
+  // Off by default. Mandatory only when this buy's 14-day refund window
+  // would overlap the scheduled hardfork — i.e. currentSlot + REFUND_WINDOW_N
+  // > freezeAfterSlot. Buyers whose full window ends before the freeze get
+  // no warning (nothing to warn about). When the current slot cannot be
+  // resolved client-side (caller-supplied freezeAfterSlot or env override),
+  // the SDK falls back to requiring the waiver as a safe default; the
+  // backend's own guard runs the same overlap check against its authoritative
+  // slot. Persisted on the LicenseRecord as `refundWaiverAcceptedAt`.
+  refundWaiverAccepted?: 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 ProveBuyResponse = {
+  provenTxJson:        string;
+  expirySlot:          number;
+  licenseHash:         string;
+  verificationKeyHash: string;
+  purchaseSlot:        number;
+  purchaseAmount:      string; // nanomina
+  duration:            number;
+  durationLabel:       string;
+  // Deployment generation this buy is proved against. Threaded through into
+  // ProofFile so a later `renew.ts` can detect generation drift against
+  // GET /apps/:appId and renew on the current deployment.
+  generation:          number;
+  // Key the backend stored the per-app in-flight slot under. Callers pass
+  // this back to POST /tx-broadcast after the wallet returns a hash so the
+  // slot is extended from signing-TTL to landing-TTL. For registered apps
+  // this is the appId; for direct-paste buys it falls back to zkAppAddress.
+  appKey:              string;
+};
+
+export type ConfirmBuyRequest = {
+  keeperUrl:    string;
+  zkAppAddress: string;
+  licenseHash:  string;
+  txHash:       string;
+  fetcher?:     typeof fetch;
+  signal?:      AbortSignal;
+};
+
+export type BuyStatus = {
+  // Mirrors the backend's txLandWatch machine (kind: 'buy'):
+  //   'pending' → 'landed' (tx included on-chain, terminal, success)
+  //             → 'timeout' (watch deadline hit without inclusion, terminal, failure)
+  //             → 'failed' (included but failed on chain, e.g. the wallet could
+  //               pay the fee but not the price: no license, only the network
+  //               fee was paid; `failureReason` says why; terminal)
+  //   'unknown' if the backend has no watch record for this licenseHash yet —
+  //     e.g. confirmBuy hasn't run, or the watch's retention window expired.
+  status:              'unknown' | 'pending' | 'landed' | 'timeout' | 'failed';
+  failureReason?:      string;
+  txHash?:             string;
+  landedAtBlockHeight?: number;
+  landedAtSlot?:       number;
+  elapsedMs?:          number;
+};
+
+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/buy — backend compiles + proves the buy tx.
+// The buyer's wallet then signs the returned provenTxJson.
+//
+// Pre-network guards:
+//   - salesFrozen === true → refuse immediately (backend would 423 anyway).
+//   - freezeAfterSlot announced AND this buy's 14-day refund window would
+//     extend past the freeze slot AND refundWaiverAccepted !== true →
+//     refuse (buyer must explicitly accept that the scheduled hardfork
+//     can truncate their refund window). Buys whose full window ends
+//     before the freeze proceed without a waiver.
+//
+// Endpoint routing:
+//   - refundWaiverAccepted === true → POST /prove/buy-no-escrow. The no-escrow
+//     circuit method pays vendor+platform directly (98/2 split, no escrow
+//     tree write). This is chosen either voluntarily by the buyer (opting out
+//     of the 14-day statutory right of withdrawal in exchange for immediate
+//     delivery) or forced by a freeze overlap.
+//   - refundWaiverAccepted !== true → POST /prove/buy (standard escrow path
+//     with a 14-day refund window).
+/**
+ * The buyer's country guessed from their IP address (keeper `GET /geo/country`),
+ * to pre-fill the country field. Null when the keeper has no geolocation
+ * database, the address has no country, or the keeper is unreachable. The
+ * buyer's own choice is what `proveBuy` sends; the keeper separately records
+ * the country it sees as VAT evidence, and never the address.
+ */
+export async function detectBuyerCountry(keeperUrl: string, fetcher: typeof fetch = fetch): Promise<string | null> {
+  try {
+    const res = await fetcher(`${keeperUrl.replace(/\/$/, '')}/geo/country`, { cache: 'no-store' });
+    if (!res.ok) return null;
+    const body = await res.json() as { country?: unknown };
+    return typeof body.country === 'string' && /^[A-Z]{2}$/.test(body.country) ? body.country : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function proveBuy(req: ProveBuyRequest): Promise<ProveBuyResponse> {
+  const fetcher = req.fetcher ?? fetch;
+  const freeze = await resolveFreezeState({
+    keeperUrl:       req.keeperUrl,
+    network:         req.network,
+    freezeAfterSlot: req.freezeAfterSlot,
+    fetcher,
+    signal:          req.signal,
+  });
+  if (freeze.salesFrozen) {
+    throw new Error('Sales frozen — new buys refused ahead of a scheduled hardfork');
+  }
+  let windowOverlapsFreeze = false;
+  if (freeze.freezeAfterSlot !== null) {
+    // Waiver required when the refund window would overlap the freeze, or
+    // when the current slot is unknown client-side (safe default). The
+    // +TOLERANCE_WINDOW_N margin accounts for slot-precondition slop
+    // between prove and inclusion: the real inclusion slot can be up to
+    // TOLERANCE_WINDOW_N slots past `currentSlot`, so we include that in
+    // the overlap comparison rather than let a late inclusion silently
+    // push the refund deadline past the freeze without a waiver.
+    windowOverlapsFreeze =
+      freeze.currentSlot === null ||
+      freeze.currentSlot + REFUND_WINDOW_N + TOLERANCE_WINDOW_N > freeze.freezeAfterSlot;
+    if (windowOverlapsFreeze && req.refundWaiverAccepted !== true) {
+      throw new Error(
+        `refundWaiverAccepted must be true — the scheduled hardfork at slot ${freeze.freezeAfterSlot} can truncate the 14-day refund window`,
+      );
+    }
+  }
+  const useNoEscrow = req.refundWaiverAccepted === true;
+  const endpoint = useNoEscrow ? '/prove/buy-no-escrow' : '/prove/buy';
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}${endpoint}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    signal: req.signal,
+    body: JSON.stringify({
+      licenseHash:  req.licenseHash,
+      buyerAddress: req.buyerAddress,
+      zkAppAddress: req.zkAppAddress,
+      ownerPubKey:  req.ownerPubKey,
+      network:      req.network,
+      duration:     req.duration,
+      buyerCountry: req.buyerCountry,
+      ...(req.buyerZip ? { buyerZip: req.buyerZip } : {}),
+      ...(req.refundWaiverAccepted === true ? { refundWaiverAccepted: true } : {}),
+      ...(req.refundWaiverAccepted === true && req.agentConsent ? { agentConsent: req.agentConsent } : {}),
+    }),
+  });
+  if (!resp.ok) {
+    // Distinct guidance for the no-escrow path: a 404 here means the
+    // vendor's zkApp was deployed before the no-escrow method existed. Fix
+    // is a redeploy (§12.13); until
+    // then the escrowless (waiver) path is unavailable on this vendor.
+    if (useNoEscrow && resp.status === 404) {
+      throw new Error(
+        'Backend does not offer /prove/buy-no-escrow — this vendor\'s zkApp does not support the escrowless (waiver) path; vendor must redeploy',
+      );
+    }
+    const parsed = await readErrorBody(resp);
+    const queueBusy = tryQueueBusyFromBody(parsed);
+    if (queueBusy) throw queueBusy;
+    throw keeperError(parsed);
+  }
+  return await resp.json() as ProveBuyResponse;
+}
+
+// POST /confirm/buy — promotes the in-memory intent staged by /prove/buy
+// into a persisted (pending: true) LicenseRecord. Call this only after the
+// wallet has actually returned a txHash — a cancelled or dropped signature
+// leaves the intent to expire on its own.
+/**
+ * Returns the buyer's receipt (zklicensing/receipt) when the keeper issued
+ * one: put it in the license file as `receipt` (Vendor Terms §7.1).
+ */
+export async function confirmBuy(req: ConfirmBuyRequest): Promise<{ ok: true; receipt?: PurchaseReceipt }> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(`${baseUrl(req.keeperUrl)}/confirm/buy`, {
+    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));
+  const body = await resp.json().catch(() => ({})) as { receipt?: PurchaseReceipt };
+  return { ok: true, ...(body?.receipt ? { receipt: body.receipt } : {}) };
+}
+
+export type PollBuyStatusOptions = {
+  keeperUrl:      string;
+  licenseHash:    string;
+  fetcher?:       typeof fetch;
+  // How often to poll and how long to wait total. Buy-watch flips 'pending'
+  // → 'landed' within seconds of tx inclusion, so a snappy interval keeps
+  // the UI live without hammering the backend.
+  intervalMs?:    number;  // default 3 000
+  timeoutMs?:     number;  // default 10 min
+  signal?:        AbortSignal;
+  onTick?:        (status: BuyStatus) => void;
+};
+
+// Polls GET /buy/status until it returns a terminal state ('landed' — success,
+// tx included on-chain; 'failed' — included but failed on chain; or 'timeout'
+// — watch deadline passed without inclusion)
+// or the local poll timeout fires. 'unknown' just means the backend hasn't seen
+// a watch record yet (confirmBuy still landing, or retention window expired).
+export async function pollBuyStatus(opts: PollBuyStatusOptions): Promise<BuyStatus> {
+  const fetcher = opts.fetcher ?? fetch;
+  const interval = opts.intervalMs ?? 3_000;
+  const timeout = opts.timeoutMs ?? 10 * 60 * 1000;
+  const deadline = Date.now() + timeout;
+  const url = `${baseUrl(opts.keeperUrl)}/buy/status?licenseHash=${encodeURIComponent(opts.licenseHash)}`;
+
+  while (true) {
+    if (opts.signal?.aborted) throw new Error('pollBuyStatus aborted');
+    let status: BuyStatus = { status: 'unknown' };
+    try {
+      const resp = await fetcher(url, { signal: opts.signal });
+      if (resp.ok) status = await resp.json() as BuyStatus;
+    } catch { /* transient network — try again on next tick */ }
+    opts.onTick?.(status);
+    if (status.status === 'landed' || status.status === 'timeout' || status.status === 'failed') return status;
+    if (Date.now() >= deadline) return status;
+    await new Promise<void>((r) => setTimeout(r, interval));
+  }
+}