zklicensing 0.1.0-beta.0

package/build/freezeClient.d.ts

@@ -0,0 +1,44 @@
+/**
+ * freezeClient.ts
+ *
+ * Client-side view of the keeper's sales-freeze schedule. A freeze is set
+ * ahead of a hardfork so every open escrow window can drain (refund or
+ * release) before v1 → v2 migration. Once past the freeze slot the keeper
+ * refuses new buys and renewals; refunds and verify remain open.
+ *
+ * Resolution order for buy/renew clients that want to know the current
+ * freeze state:
+ *   1. Caller-supplied `freezeAfterSlot` (explicit override — build-time
+ *      constant, or pulled from the vendor's own env at boot).
+ *   2. `process.env.FREEZE_AFTER_SLOT` when running under Node (server-side
+ *      integrators / CLIs).
+ *   3. Keeper's own `/health` payload — the authoritative source of truth.
+ *
+ * A `freezeAfterSlot` of 0 / null / undefined means "no freeze scheduled".
+ */
+export type KeeperHealth = {
+    status: string;
+    network: string;
+    slot: number;
+    salesFrozen: boolean;
+    freezeAfterSlot: number | null;
+};
+export type FreezeState = {
+    salesFrozen: boolean;
+    freezeAfterSlot: number | null;
+    currentSlot: number | null;
+};
+export type GetKeeperHealthOptions = {
+    keeperUrl: string;
+    fetcher?: typeof fetch;
+    signal?: AbortSignal;
+};
+export declare function getKeeperHealth(opts: GetKeeperHealthOptions): Promise<KeeperHealth>;
+export type ResolveFreezeStateOptions = {
+    keeperUrl: string;
+    freezeAfterSlot?: number | null;
+    fetcher?: typeof fetch;
+    signal?: AbortSignal;
+};
+export declare function resolveFreezeState(opts: ResolveFreezeStateOptions): Promise<FreezeState>;
+//# sourceMappingURL=freezeClient.d.ts.map

package/build/freezeClient.js

@@ -0,0 +1,59 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// All rights reserved.
+function baseUrl(url) {
+    return url.replace(/\/+$/, '');
+}
+function envFreezeSlot() {
+    // Runs both in Node (process.env) and browser (no `process`). The typeof
+    // guard keeps bundlers from choking on the reference.
+    if (typeof process === 'undefined' || !process.env)
+        return null;
+    const raw = process.env.FREEZE_AFTER_SLOT;
+    if (!raw)
+        return null;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+// GET /health — raw payload. Callers that only need the freeze state
+// should use resolveFreezeState() instead; this is exposed for UIs that
+// surface slot / network info alongside freeze.
+export async function getKeeperHealth(opts) {
+    const fetcher = opts.fetcher ?? fetch;
+    const resp = await fetcher(`${baseUrl(opts.keeperUrl)}/health`, { signal: opts.signal });
+    if (!resp.ok)
+        throw new Error(`HTTP ${resp.status}`);
+    return await resp.json();
+}
+// Resolves the effective freeze state for the caller. When the source is
+// the caller override or process.env, the current slot is not known
+// client-side, so salesFrozen is filled from /health only — the override
+// path returns { freezeAfterSlot: N, salesFrozen: false, currentSlot: null }
+// and lets the keeper reject the actual prove call if the freeze has fired.
+export async function resolveFreezeState(opts) {
+    if (typeof opts.freezeAfterSlot === 'number' && opts.freezeAfterSlot > 0) {
+        return { salesFrozen: false, freezeAfterSlot: opts.freezeAfterSlot, currentSlot: null };
+    }
+    const envSlot = envFreezeSlot();
+    if (envSlot !== null) {
+        return { salesFrozen: false, freezeAfterSlot: envSlot, currentSlot: null };
+    }
+    try {
+        const health = await getKeeperHealth({
+            keeperUrl: opts.keeperUrl,
+            fetcher: opts.fetcher,
+            signal: opts.signal,
+        });
+        return {
+            salesFrozen: health.salesFrozen === true,
+            freezeAfterSlot: typeof health.freezeAfterSlot === 'number' ? health.freezeAfterSlot : null,
+            currentSlot: typeof health.slot === 'number' ? health.slot : null,
+        };
+    }
+    catch {
+        // /health unreachable — treat as no freeze so we don't block buys on a
+        // transient network hiccup. The keeper's own guard is still the last
+        // line of defense.
+        return { salesFrozen: false, freezeAfterSlot: null, currentSlot: null };
+    }
+}
+//# sourceMappingURL=freezeClient.js.map

package/build/generationClient.d.ts

@@ -0,0 +1,54 @@
+export interface GenerationEntry {
+    gen: number;
+    zkAppAddress: string;
+    status: 'retired' | 'live';
+    frozenRoot?: string;
+    deployedAt?: string;
+    retiredAt?: string;
+}
+export interface GenerationInfo {
+    /** Live-generation index (matches the entry with status: 'live'). Null when unverified or missing. */
+    current: number | null;
+    generations: GenerationEntry[];
+    /** True iff signature verified against one of the pinned pubkeys. */
+    verified: boolean;
+}
+export interface FetchGenerationRequest {
+    keeperUrl: string;
+    appId: string;
+    /** Base64-encoded Ed25519 public keys pinned by the caller. Empty ⇒ verified:false. */
+    pinnedPublicKeysBase64: readonly string[];
+    fetcher?: typeof fetch;
+    signal?: AbortSignal;
+}
+export interface FetchGenerationByAddressRequest {
+    keeperUrl: string;
+    /** Any zkApp address in the app's generation chain — current live or any retired. */
+    zkAppAddress: string;
+    /** Base64-encoded Ed25519 public keys pinned by the caller. Empty ⇒ verified:false. */
+    pinnedPublicKeysBase64: readonly string[];
+    fetcher?: typeof fetch;
+    signal?: AbortSignal;
+}
+/**
+ * GET /apps/:appId — returns { appId, current, generations, issuedAt, publicKey, signature }.
+ * We reconstruct the canonical payload (everything except `publicKey` +
+ * `signature`) and verify against the pin list. `publicKey` in the response
+ * is advisory only — it's the key the keeper claims to have signed with;
+ * the SDK never trusts it in place of a pin.
+ */
+export declare function fetchGenerationInfo(req: FetchGenerationRequest): Promise<GenerationInfo>;
+/**
+ * GET /apps/by-address/:zkAppAddress — same signed payload as fetchGenerationInfo,
+ * but keyed by an address the caller already has (direct-paste buys, renew on a
+ * since-retired address). Buyers arriving without an appId would otherwise have
+ * to trust the keeper's unsigned `/apps` list to bind their address to an appId
+ * first — defeating the pin.
+ *
+ * Extra assertion beyond the appId flow: the queried address MUST appear in the
+ * returned `generations[]`. Without this, a malicious keeper could return a
+ * validly-signed payload for a DIFFERENT app in response to the query, and the
+ * signature check alone wouldn't catch it.
+ */
+export declare function fetchGenerationInfoByAddress(req: FetchGenerationByAddressRequest): Promise<GenerationInfo>;
+//# sourceMappingURL=generationClient.d.ts.map

package/build/generationClient.js

@@ -0,0 +1,113 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// All rights reserved.
+/**
+ * generationClient.ts
+ *
+ * Browser-safe fetcher for the keeper's signed generation-list. Returns the
+ * app's deployment history — every past address plus the current live one —
+ * verified against a caller-supplied pin list of platform manifest public
+ * keys.
+ *
+ * Trust model: the keeper is not the trust anchor for this data — it can
+ * be re-hosted, mirrored, cached, or (worst case) impersonated. The pin
+ * list is. Any response that fails signature verification is surfaced as
+ * `verified: false` with `generations: []` so callers cannot accidentally
+ * route a wallet prompt to an unverified address.
+ *
+ * Optional corroboration channel: an operator that publishes
+ *   https://<vendor-host>/.well-known/zklicensing/<appId>.json
+ * (using the same keeper-signed payload) can be cross-checked from the
+ * on-chain zkappUri. Per-app filename because a vendor may host several
+ * apps at one origin. The cross-check is opt-in per-app — a 404 at that
+ * URL is not a failure signal, just "no corroboration published for this
+ * app." That's the caller's job, not this module's.
+ */
+import { verifyManifestSignature } from './manifestVerify.js';
+function baseUrl(url) {
+    return url.replace(/\/+$/, '');
+}
+function parseGenerationBody(body) {
+    const gensRaw = body.generations;
+    return {
+        current: typeof body.current === 'number' ? body.current : null,
+        generations: Array.isArray(gensRaw) ? gensRaw : [],
+        signature: typeof body.signature === 'string' ? body.signature : null,
+        issuedAt: typeof body.issuedAt === 'string' ? body.issuedAt : null,
+        appId: typeof body.appId === 'string' ? body.appId : null,
+    };
+}
+async function verifyAndProject(parsed, pinnedPublicKeysBase64) {
+    const { current, generations, signature, issuedAt, appId } = parsed;
+    if (!signature || !issuedAt || !appId || current === null) {
+        return { current, generations, verified: false };
+    }
+    // Reconstruct the canonical payload — must match keeperService's
+    // signPayload input exactly.
+    const canonical = { appId, current, generations, issuedAt };
+    const verified = await verifyManifestSignature(canonical, signature, pinnedPublicKeysBase64);
+    if (!verified) {
+        // Never surface unverified `current`/`generations` — a caller must not
+        // accidentally route a wallet prompt to an address we couldn't authenticate.
+        return { current: null, generations: [], verified: false };
+    }
+    return { current, generations, verified: true };
+}
+/**
+ * GET /apps/:appId — returns { appId, current, generations, issuedAt, publicKey, signature }.
+ * We reconstruct the canonical payload (everything except `publicKey` +
+ * `signature`) and verify against the pin list. `publicKey` in the response
+ * is advisory only — it's the key the keeper claims to have signed with;
+ * the SDK never trusts it in place of a pin.
+ */
+export async function fetchGenerationInfo(req) {
+    const fetcher = req.fetcher ?? fetch;
+    const resp = await fetcher(`${baseUrl(req.keeperUrl)}/apps/${encodeURIComponent(req.appId)}`, {
+        method: 'GET',
+        signal: req.signal,
+    });
+    if (!resp.ok) {
+        return { current: null, generations: [], verified: false };
+    }
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch {
+        return { current: null, generations: [], verified: false };
+    }
+    return verifyAndProject(parseGenerationBody(body), req.pinnedPublicKeysBase64);
+}
+/**
+ * GET /apps/by-address/:zkAppAddress — same signed payload as fetchGenerationInfo,
+ * but keyed by an address the caller already has (direct-paste buys, renew on a
+ * since-retired address). Buyers arriving without an appId would otherwise have
+ * to trust the keeper's unsigned `/apps` list to bind their address to an appId
+ * first — defeating the pin.
+ *
+ * Extra assertion beyond the appId flow: the queried address MUST appear in the
+ * returned `generations[]`. Without this, a malicious keeper could return a
+ * validly-signed payload for a DIFFERENT app in response to the query, and the
+ * signature check alone wouldn't catch it.
+ */
+export async function fetchGenerationInfoByAddress(req) {
+    const fetcher = req.fetcher ?? fetch;
+    const resp = await fetcher(`${baseUrl(req.keeperUrl)}/apps/by-address/${encodeURIComponent(req.zkAppAddress)}`, { method: 'GET', signal: req.signal });
+    if (!resp.ok) {
+        return { current: null, generations: [], verified: false };
+    }
+    let body;
+    try {
+        body = await resp.json();
+    }
+    catch {
+        return { current: null, generations: [], verified: false };
+    }
+    const projected = await verifyAndProject(parseGenerationBody(body), req.pinnedPublicKeysBase64);
+    if (!projected.verified)
+        return projected;
+    if (!projected.generations.some(g => g.zkAppAddress === req.zkAppAddress)) {
+        return { current: null, generations: [], verified: false };
+    }
+    return projected;
+}
+//# sourceMappingURL=generationClient.js.map

package/build/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 } from './contractInterface.js';
+declare const MS_PER_SLOT = 90000;
+export interface Storage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export interface ActivationRecord {
+    token: string;
+    expiresAt: number;
+    secretHash?: string;
+}
+export declare function loadActivation(storage: Storage, zkAppAddress: string, licenseHash: string, nowMs?: number): ActivationRecord | null;
+export declare function saveActivation(storage: Storage, zkAppAddress: string, licenseHash: string, rec: ActivationRecord): void;
+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;
+    prover?: TokenProver;
+    secretHash?: string;
+}
+export interface VerifyResult {
+    valid: boolean;
+    expirySlot: number;
+    expiresAt: string | null;
+    currentSlot: number;
+    inGracePeriod: boolean;
+    remainingDays: number;
+    reason: string | null;
+    source: 'offline' | 'chain';
+    ownership: 'verified' | 'unverified';
+}
+export declare function verifyLicense(proof: ProofInput, options?: VerifyOptions): Promise<VerifyResult>;
+export { REFUND_WINDOW_N, GRACE_PERIOD_N, MS_PER_SLOT };
+//# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -0,0 +1,258 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// All rights reserved.
+/**
+ * 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_';
+function activationKey(zkAppAddress, licenseHash) {
+    return `${ACTIVATION_KEY_PREFIX}${zkAppAddress}_${licenseHash}`;
+}
+export function loadActivation(storage, zkAppAddress, licenseHash, nowMs = Date.now()) {
+    try {
+        const raw = storage.getItem(activationKey(zkAppAddress, licenseHash));
+        if (!raw)
+            return null;
+        const rec = JSON.parse(raw);
+        if (nowMs > rec.expiresAt)
+            return null;
+        return rec;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveActivation(storage, zkAppAddress, licenseHash, rec) {
+    try {
+        storage.setItem(activationKey(zkAppAddress, licenseHash), JSON.stringify(rec));
+    }
+    catch {
+        /* quota / read-only — non-fatal */
+    }
+}
+function defaultStorage() {
+    if (typeof globalThis !== 'undefined' && globalThis.localStorage) {
+        return globalThis.localStorage;
+    }
+    return null;
+}
+function loadAnchor(storage, licenseHash, expirySlot) {
+    try {
+        const raw = storage.getItem(ANCHOR_KEY_PREFIX + licenseHash);
+        if (!raw)
+            return null;
+        const a = JSON.parse(raw);
+        // `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, licenseHash, anchor) {
+    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, currentSlot) {
+    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, zkAppAddress, licenseHash, current, bootstrapSecretHash, prover, verifierUrl, fetcher, nowMs) {
+    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());
+        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());
+        const next = { token, expiresAt, secretHash };
+        saveActivation(storage, zkAppAddress, licenseHash, next);
+        return next;
+    }
+    catch {
+        return current;
+    }
+}
+function offlineCheck(anchor, nowMs) {
+    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, options = {}) {
+    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;
+    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) {
+        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 = typeof data.expirySlot === 'number' ? data.expirySlot : null;
+    const respExpirySlot = respExpirySlotStrict ?? proof.expirySlot;
+    const respCurrentSlot = typeof data.currentSlot === 'number' ? data.currentSlot : 0;
+    const result = {
+        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 };
+//# sourceMappingURL=index.js.map

package/build/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/build/licenseProof.js

@@ -0,0 +1,41 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// All rights reserved.
+/**
+ * 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 = Struct({
+    licenseHash: Field,
+    nonce: Field,
+});
+export const LicenseProof = ZkProgram({
+    name: 'license-proof',
+    publicInput: OwnershipChallenge,
+    methods: {
+        prove: {
+            privateInputs: [Field], // secretHash — never sent anywhere
+            async method(pub, secretHash) {
+                Poseidon.hash([secretHash]).assertEquals(pub.licenseHash);
+            },
+        },
+    },
+});
+export const LicenseProofProof = ZkProgram.Proof(LicenseProof);
+//# sourceMappingURL=licenseProof.js.map