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

package/src/index.ts

@@ -0,0 +1,392 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * verifyLicense — client SDK.
+ *
+ * Calls the keeper's GET /verify until the on-chain refund window for the
+ * license has closed; from that point on returns from a local anchor and
+ * never touches the network again. The refund-window decision is server-
+ * side: the keeper returns `refundWindowClosed: boolean` on its /verify
+ * response, computed from its own record of `purchaseSlot + REFUND_WINDOW_N`
+ * against the on-chain `currentSlot`. The SDK gates anchor writes on that
+ * boolean and never trusts a `purchaseSlot` supplied by the local proof
+ * file, so a user who forges their proof metadata cannot force the offline
+ * branch prematurely.
+ *
+ * Anchor purity: every field persisted in the Anchor derives from the
+ * keeper's /verify response — `anchoredSlot`, `expirySlot`, `ownership`.
+ * The only client-supplied input to the offline branch is
+ * `proof.expirySlot`, used solely as the loadAnchor binding key. A
+ * tampered proof file therefore never gets a wrong answer; it gets no
+ * offline branch at all and falls through to the keeper on every call.
+ */
+
+import {
+  REFUND_WINDOW_N,
+  GRACE_PERIOD_N,
+  MS_PER_SLOT_N,
+  SLOTS_PER_DAY_N,
+} from './contractInterface.js';
+
+const MS_PER_SLOT = MS_PER_SLOT_N;
+const SLOTS_PER_DAY = SLOTS_PER_DAY_N;
+
+const ANCHOR_KEY_PREFIX = 'zklic_anchor_';
+const ACTIVATION_KEY_PREFIX = 'zklic_activation_';
+
+export interface Storage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+export interface ActivationRecord {
+  token: string;
+  expiresAt: number;
+  // Optional: kept so the SDK can refresh the token without prompting again.
+  // Treated as a bearer credential — same trust level as a session cookie.
+  secretHash?: string;
+}
+
+function activationKey(zkAppAddress: string, licenseHash: string): string {
+  return `${ACTIVATION_KEY_PREFIX}${zkAppAddress}_${licenseHash}`;
+}
+
+export function loadActivation(
+  storage: Storage,
+  zkAppAddress: string,
+  licenseHash: string,
+  nowMs: number = Date.now()
+): ActivationRecord | null {
+  try {
+    const raw = storage.getItem(activationKey(zkAppAddress, licenseHash));
+    if (!raw) return null;
+    const rec = JSON.parse(raw) as ActivationRecord;
+    if (nowMs > rec.expiresAt) return null;
+    return rec;
+  } catch {
+    return null;
+  }
+}
+
+export function saveActivation(
+  storage: Storage,
+  zkAppAddress: string,
+  licenseHash: string,
+  rec: ActivationRecord
+): void {
+  try {
+    storage.setItem(activationKey(zkAppAddress, licenseHash), JSON.stringify(rec));
+  } catch {
+    /* quota / read-only — non-fatal */
+  }
+}
+
+export interface ProofInput {
+  licenseHash: string;
+  zkAppAddress: string;
+  expirySlot: number;
+  verifierUrl?: string;
+}
+
+/**
+ * Callback that proves an OwnershipChallenge using a stored secretHash.
+ * Callers wire this up with their own o1js + LicenseProof imports so the SDK
+ * stays dependency-free for the verify-only path. Return value is the
+ * `proof.toJSON()` payload the verifier's POST /respond expects.
+ */
+export type TokenProver = (input: {
+  licenseHash: string;
+  nonce: string;
+  secretHash: string;
+}) => Promise<unknown>;
+
+export interface VerifyOptions {
+  verifierUrl?: string;
+  storage?: Storage | null;
+  fetcher?: typeof fetch;
+  now?: () => number;
+  // When supplied with `secretHash`, the SDK runs activation on the first
+  // verify after install. From then on it silently re-runs the challenge-
+  // response flow using the stored secretHash whenever the token is missing
+  // or within ~1 day of expiry — the user is never prompted again.
+  prover?: TokenProver;
+  // First-verify-after-install bootstrap. Caller obtains this from the user
+  // (e.g., passphrase prompt → Poseidon.hash) and passes it once; the SDK
+  // persists it as part of the activation record so subsequent verifies
+  // renew silently. Ignored when an activation already exists in storage.
+  secretHash?: string;
+}
+
+export interface VerifyResult {
+  valid: boolean;
+  expirySlot: number;
+  // ISO-8601 timestamp of estimated expiry. `null` when the license is
+  // unknown / refunded / unreachable. In the offline branch this is
+  // estimated from the anchor + local clock.
+  expiresAt: string | null;
+  // Estimated current Mina slot. From the keeper in the chain branch;
+  // estimated from the anchor + elapsed local time in the offline branch.
+  currentSlot: number;
+  inGracePeriod: boolean;
+  // Whole days until expiry. Negative while in the grace period (down to ~-7)
+  // and below that once fully expired. 0 when expirySlot is unknown.
+  remainingDays: number;
+  reason: string | null;
+  source: 'offline' | 'chain';
+  // 'verified' when the keeper accepted a valid ownership token on this
+  // request; 'unverified' otherwise (no token, expired token, or offline
+  // branch replaying a chain result that itself was unverified).
+  ownership: 'verified' | 'unverified';
+}
+
+interface Anchor {
+  anchoredSlot: number;
+  anchoredAtMs: number;
+  expirySlot: number;
+  // Captured from the keeper's /verify response at anchor time — offline
+  // checks return this stored value verbatim rather than fabricating one.
+  ownership: 'verified' | 'unverified';
+}
+
+function defaultStorage(): Storage | null {
+  if (typeof globalThis !== 'undefined' && (globalThis as any).localStorage) {
+    return (globalThis as any).localStorage as Storage;
+  }
+  return null;
+}
+
+function loadAnchor(storage: Storage, licenseHash: string, expirySlot: number): Anchor | null {
+  try {
+    const raw = storage.getItem(ANCHOR_KEY_PREFIX + licenseHash);
+    if (!raw) return null;
+    const a = JSON.parse(raw) as Anchor;
+    // `a.expirySlot` is the KEEPER's value captured at anchor time; the
+    // `expirySlot` argument is the LOCAL proof file's value. Match ⇒ local
+    // file agrees with chain truth as of anchoring ⇒ offline is safe.
+    // Mismatch has two honest meanings:
+    //   - renewal: chain moved, local file updated ⇒ re-anchor via chain check
+    //   - forgery: local file edited ⇒ every call falls through to the keeper,
+    //     which reports truth. The forger gets no offline branch at all.
+    if (a.expirySlot !== expirySlot) return null;
+    return a;
+  } catch {
+    return null;
+  }
+}
+
+function saveAnchor(storage: Storage, licenseHash: string, anchor: Anchor): void {
+  try {
+    storage.setItem(ANCHOR_KEY_PREFIX + licenseHash, JSON.stringify(anchor));
+  } catch {
+    // Storage may be full or read-only; the offline path simply won't activate.
+  }
+}
+
+function computeRemainingDays(expirySlot: number, currentSlot: number): number {
+  if (expirySlot === 0) return 0;
+  return Math.floor((expirySlot - currentSlot) / SLOTS_PER_DAY);
+}
+
+// Renew the activation token when within this window of expiry. Picked so
+// that a daily verify call has many chances to refresh before the token dies.
+const TOKEN_RENEW_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+
+async function tryActivate(
+  storage: Storage,
+  zkAppAddress: string,
+  licenseHash: string,
+  current: ActivationRecord | null,
+  bootstrapSecretHash: string | undefined,
+  prover: TokenProver,
+  verifierUrl: string,
+  fetcher: typeof fetch,
+  nowMs: number
+): Promise<ActivationRecord | null> {
+  const secretHash = current?.secretHash ?? bootstrapSecretHash;
+  if (!secretHash) return current;
+  // Existing token still fresh — nothing to do.
+  if (current?.token && current.expiresAt - nowMs > TOKEN_RENEW_THRESHOLD_MS) return current;
+  try {
+    const base = verifierUrl.replace(/\/+$/, '');
+    const challengeResp = await fetcher(
+      `${base}/challenge?licenseHash=${encodeURIComponent(licenseHash)}`
+    );
+    if (!challengeResp.ok) return current;
+    const { nonce } = (await challengeResp.json()) as { nonce: string };
+    const proofJson = await prover({ licenseHash, nonce, secretHash });
+    const respondResp = await fetcher(`${base}/respond`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ zkAppAddress, proof: proofJson }),
+    });
+    if (!respondResp.ok) return current;
+    const { token, expiresAt } = (await respondResp.json()) as {
+      token: string;
+      expiresAt: number;
+    };
+    const next: ActivationRecord = { token, expiresAt, secretHash };
+    saveActivation(storage, zkAppAddress, licenseHash, next);
+    return next;
+  } catch {
+    return current;
+  }
+}
+
+function offlineCheck(anchor: Anchor, nowMs: number): VerifyResult {
+  const elapsedSlots = Math.max(0, Math.floor((nowMs - anchor.anchoredAtMs) / MS_PER_SLOT));
+  const estCurrentSlot = anchor.anchoredSlot + elapsedSlots;
+  const expired = estCurrentSlot > anchor.expirySlot + GRACE_PERIOD_N;
+  const inGracePeriod = !expired && estCurrentSlot > anchor.expirySlot;
+  const expiresAt = new Date(nowMs + (anchor.expirySlot - estCurrentSlot) * MS_PER_SLOT).toISOString();
+  return {
+    valid: !expired,
+    expirySlot: anchor.expirySlot,
+    expiresAt,
+    currentSlot: estCurrentSlot,
+    inGracePeriod,
+    remainingDays: computeRemainingDays(anchor.expirySlot, estCurrentSlot),
+    reason: expired
+      ? 'License has expired'
+      : inGracePeriod
+      ? 'License is in grace period — renew to avoid interruption'
+      : null,
+    source: 'offline',
+    ownership: anchor.ownership,
+  };
+}
+
+export async function verifyLicense(
+  proof: ProofInput,
+  options: VerifyOptions = {}
+): Promise<VerifyResult> {
+  const storage = options.storage === null ? null : options.storage ?? defaultStorage();
+  const fetcher = options.fetcher ?? (typeof fetch !== 'undefined' ? fetch : undefined);
+  const nowFn = options.now ?? (() => Date.now());
+  const verifierUrl = options.verifierUrl ?? proof.verifierUrl;
+
+  if (storage) {
+    const anchor = loadAnchor(storage, proof.licenseHash, proof.expirySlot);
+    if (anchor) return offlineCheck(anchor, nowFn());
+  }
+
+  if (!verifierUrl || !fetcher) {
+    return {
+      valid: false,
+      expirySlot: proof.expirySlot,
+      expiresAt: null,
+      currentSlot: 0,
+      inGracePeriod: false,
+      remainingDays: 0,
+      reason: 'No verifier URL or fetcher available; cannot verify',
+      source: 'chain',
+      ownership: 'unverified',
+    };
+  }
+
+  let activation = storage
+    ? loadActivation(storage, proof.zkAppAddress, proof.licenseHash, nowFn())
+    : null;
+  if (storage && options.prover && (activation || options.secretHash)) {
+    activation = await tryActivate(
+      storage,
+      proof.zkAppAddress,
+      proof.licenseHash,
+      activation,
+      options.secretHash,
+      options.prover,
+      verifierUrl,
+      fetcher,
+      nowFn()
+    );
+  }
+
+  const tokenParam = activation?.token
+    ? `&token=${encodeURIComponent(activation.token)}`
+    : '';
+  const url =
+    `${verifierUrl.replace(/\/+$/, '')}` +
+    `?licenseHash=${encodeURIComponent(proof.licenseHash)}` +
+    `&zkAppAddress=${encodeURIComponent(proof.zkAppAddress)}` +
+    tokenParam;
+
+  let data: any;
+  try {
+    const resp = await fetcher(url);
+    if (!resp.ok) {
+      return {
+        valid: false,
+        expirySlot: proof.expirySlot,
+        expiresAt: null,
+        currentSlot: 0,
+        inGracePeriod: false,
+        remainingDays: 0,
+        reason: `Verification request failed (HTTP ${resp.status})`,
+        source: 'chain',
+        ownership: 'unverified',
+      };
+    }
+    data = await resp.json();
+  } catch (err: any) {
+    return {
+      valid: false,
+      expirySlot: proof.expirySlot,
+      expiresAt: null,
+      currentSlot: 0,
+      inGracePeriod: false,
+      remainingDays: 0,
+      reason: err?.message ?? 'Verification request errored',
+      source: 'chain',
+      ownership: 'unverified',
+    };
+  }
+
+  // Keeper's authoritative expiry, or null if the response omits it. Only
+  // the null-safe form may be written into the anchor; the chain-result
+  // display value below falls back to the local proof file for user-facing
+  // fields, which is safe (display only).
+  const respExpirySlotStrict: number | null =
+    typeof data.expirySlot === 'number' ? data.expirySlot : null;
+  const respExpirySlot: number = respExpirySlotStrict ?? proof.expirySlot;
+  const respCurrentSlot: number = typeof data.currentSlot === 'number' ? data.currentSlot : 0;
+  const result: VerifyResult = {
+    valid: !!data.valid,
+    expirySlot: respExpirySlot,
+    expiresAt: typeof data.expiresAt === 'string' ? data.expiresAt : null,
+    currentSlot: respCurrentSlot,
+    inGracePeriod: !!data.inGracePeriod,
+    remainingDays: typeof data.remainingDays === 'number'
+      ? data.remainingDays
+      : computeRemainingDays(respExpirySlot, respCurrentSlot),
+    reason: data.reason ?? null,
+    source: 'chain',
+    ownership: data.ownership === 'verified' ? 'verified' : 'unverified',
+  };
+
+  // Anchor gate uses the keeper's own refund-window decision. The keeper
+  // knows the true purchaseSlot (stored in its LicenseRecord) and the true
+  // currentSlot; the SDK never trusts a purchaseSlot or expirySlot supplied
+  // by the local proof file, since that file is client-writable and could
+  // be forged. If the keeper omits `expirySlot`, we fail-closed on the
+  // offline path — no anchor written, subsequent calls stay online.
+  if (
+    storage &&
+    result.valid &&
+    data.refundWindowClosed === true &&
+    typeof data.currentSlot === 'number' &&
+    respExpirySlotStrict !== null
+  ) {
+    saveAnchor(storage, proof.licenseHash, {
+      anchoredSlot: data.currentSlot,
+      anchoredAtMs: nowFn(),
+      expirySlot: respExpirySlotStrict,
+      ownership: result.ownership,
+    });
+  }
+
+  return result;
+}
+
+// Re-exported so tests and downstream tooling can reference the same values
+// the SDK uses internally without re-deriving them.
+export { REFUND_WINDOW_N, GRACE_PERIOD_N, MS_PER_SLOT };

package/src/licenseProof.d.ts

@@ -0,0 +1,26 @@
+// Hand-written declarations for licenseProof.ts.
+// tsc can't emit these automatically because the inferred return types of
+// Struct() and ZkProgram() reference internal o1js paths outside this
+// package's rootDir, triggering TS2742. Callers get full typing on the
+// methods they actually invoke by importing the corresponding o1js types
+// directly (Field, Proof, etc.) in their own code.
+
+export const OwnershipChallenge: any;
+export type OwnershipChallenge = any;
+
+export const LicenseProof: any;
+
+export class LicenseProofProof {
+  static publicInputType: any;
+  static publicOutputType: any;
+  static fromJSON(json: any): Promise<LicenseProofProof>;
+  static dummy(...args: any[]): Promise<LicenseProofProof>;
+  publicInput: any;
+  publicOutput: any;
+  proof: any;
+  maxProofsVerified: 0 | 1 | 2;
+  shouldVerify: any;
+  verify(): void;
+  verifyIf(condition: any): void;
+  toJSON(): { publicInput: string[]; publicOutput: string[]; maxProofsVerified: 0 | 1 | 2; proof: string };
+}

package/src/licenseProof.ts

@@ -0,0 +1,48 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * licenseProof.ts — ZkProgram for ownership challenge-response.
+ *
+ * Loaded only when the caller needs to *produce* an ownership proof on the
+ * client (the verify path never imports this file). Lives in a dedicated
+ * subpath (`zklicensing/prove`) so the verify-only entry stays free of o1js.
+ *
+ * Proves: Poseidon.hash([secretHash]) === licenseHash
+ * where  secretHash = Poseidon.hash(Encoding.stringToFields(rawSecret)).
+ *
+ * The nonce sits in the public input. Its sole purpose is replay-resistance:
+ * a proof generated for nonce A is mathematically distinct from one for nonce
+ * B, so a verifier that issued nonce A will reject any proof not produced for
+ * exactly that challenge.
+ */
+
+import { ZkProgram, Field, Poseidon, Struct } from 'o1js';
+
+// Struct() / ZkProgram / ZkProgram.Proof() return types reference o1js
+// internal paths outside this package's rootDir, triggering TS2742 on
+// declaration emit. Annotating each export as `any` suppresses the inference;
+// consumers get real types via the hand-written licenseProof.d.ts shim.
+// See contractInterface.ts for the longer rationale on why this workaround.
+
+export const OwnershipChallenge: any = Struct({
+  licenseHash: Field,
+  nonce: Field,
+});
+export type OwnershipChallenge = any;
+
+export const LicenseProof: any = ZkProgram({
+  name: 'license-proof',
+  publicInput: OwnershipChallenge,
+  methods: {
+    prove: {
+      privateInputs: [Field], // secretHash — never sent anywhere
+      async method(pub: OwnershipChallenge, secretHash: Field) {
+        Poseidon.hash([secretHash]).assertEquals(pub.licenseHash);
+      },
+    },
+  },
+});
+
+export const LicenseProofProof: any = ZkProgram.Proof(LicenseProof);
+export type LicenseProofProof = any;

package/src/licenseRecord.ts

@@ -0,0 +1,91 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * licenseRecord.ts
+ *
+ * The `LicenseRecord` shape and related pure types/constants. Split out from
+ * licenseStore.ts (which pulls in Node `fs`) so browser-side modules — the
+ * buy client, the stats client, the country-stats computation — can consume
+ * the same type without dragging in filesystem code. licenseStore.ts
+ * re-exports these to keep existing Node imports working.
+ */
+
+// MINA→fiat rate snapshot captured at the moment a business event happens
+// (registration, purchase, renewal). Immutable — the value at time of event
+// is what tax authorities want, so the keeper snapshots against the same
+// 5-minute CoinGecko cache used by receipts and never re-fetches. Records
+// created before the very first successful CoinGecko response get no
+// snapshot; dashboards render fiat as `—` for those.
+export type FiatRateSnapshot = {
+  minaEurRate:   number;
+  minaUsdRate:   number;
+  minaGbpRate:   number;
+  recordedAt:    string;
+};
+
+export type LicenseRecord = {
+  zkAppAddress:   string;  // REQUIRED — composite key with licenseHash
+  licenseHash:    string;  // Poseidon.hash([secretHash]).toString()
+  expirySlot:     number;  // 0 = refunded / empty
+  purchaseSlot:   number;  // block slot when purchased (0 after escrow released/refunded)
+  purchaseAmount: string;  // nanomina paid (as string to avoid BigInt serialisation issues)
+  txHash:         string;
+  createdAt:      string;
+  buyerAddress?:  string;  // buyer's public key (B62q...) — required for escrow commitment
+  buyerCountry?:  string;  // ISO 3166-1 alpha-2 self-declared buyer jurisdiction (required at buy time; optional here for backward-compat with pre-existing records)
+  buyerZip?:      string;  // Buyer-declared postal code — required at buy time only when buyerCountry === 'US' (state-level sales-tax attribution). Optional here for backward-compat and non-US buyers.
+  pending?:       boolean; // true if staged at prove-time but not yet confirmed by chain events
+  provedAtSlot?:  number;  // slot at which prove succeeded — used by reaper to drop unsubmitted records
+  // Captured at licenseIssued and never mutated by renewal. Lets stats decide
+  // who's past their first paid period without re-walking events.
+  initialExpirySlot?: number;
+  // Back-derived from (initialExpirySlot - purchaseSlot) at issue time. Lets
+  // licensesByTier roll up active counts without keeping the issued slot.
+  tier?: 'monthly' | 'yearly' | 'fiveYear';
+  // True after a licenseRenewed event has been observed. Lets the stats
+  // accumulator detect the FIRST renewal per license without re-counting.
+  renewedAtLeastOnce?: boolean;
+  // True after a refundIssued event. Distinct from expirySlot=0 for legacy
+  // records that lacked refund tracking.
+  refunded?: boolean;
+  // True after a fundsReleased event. Distinct from purchaseAmount=0 so stats
+  // can compute released revenue without re-walking events.
+  released?: boolean;
+  releaseSlot?: number;
+  // Tx hash of the fundsReleased broadcast. Persisted so the vendor's
+  // transaction feed can link the release row to the explorer. Optional for
+  // backward-compat: pre-tracking records and archive-replayed events
+  // (which don't carry the tx hash) simply omit it.
+  releaseTxHash?: string;
+  // Each renewal pushes { slot, amount, newExpiry, txHash?, fiatSnapshot? }
+  // where amount is the nanomina paid. newExpiry is the resulting expiry —
+  // used as a dedup key so confirm-time entries don't double up when archive
+  // sync later replays the same renewedEvent. fiatSnapshot captures the
+  // MINA→fiat rates at renewal confirm time (missing on archive-replayed
+  // renewals, which have no live keeper context).
+  renewals?: Array<{ slot: number; amount: string; newExpiry: number; txHash?: string; fiatSnapshot?: FiatRateSnapshot }>;
+  // MINA→fiat rates captured at buy confirm time. Immutable — the rate at
+  // time of purchase is what tax authorities want. Missing on records created
+  // before the first successful CoinGecko response and on archive-replayed
+  // purchases (dashboards render fiat as `—`).
+  fiatSnapshot?: FiatRateSnapshot;
+  // ISO timestamp of the buyer's express waiver of the 14-day refund window,
+  // captured at buy time when a FREEZE_AFTER_SLOT was scheduled on the
+  // keeper. Absent for normal (non-freeze-window) buys. Kept for audit /
+  // dispute purposes — the waiver is the buyer's acknowledgment that the
+  // scheduled hardfork can truncate their refund window.
+  refundWaiverAcceptedAt?: string;
+  // True when the buy was minted through the no-escrow circuit method
+  // (buyLicenseNoEscrow). Funds went straight to vendor + platform (98/2)
+  // rather than into the contract's escrow tree, so there is nothing to
+  // refund. The buyer accepted this at purchase (see refundWaiverAcceptedAt).
+  // The UI uses this flag to hide the "Refund" CTA on the licenses page.
+  escrowless?: boolean;
+};
+
+// Reap pending records this many slots after prove time if no event ever lands.
+// 60 slots ≈ 90 minutes — a generous window for tx inclusion under devnet conditions.
+export const PENDING_REAP_SLOTS = 60;
+
+export type LicenseStatus = 'active' | 'refunded' | 'expired' | 'unknown';