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

package/build/permitProof.js

@@ -0,0 +1,202 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+/**
+ * permitProof.ts — `zklicensing/permits/proof`
+ *
+ * Zero-knowledge proof that the prover holds an active permit in a registry
+ * (PERMITS_PLAN.md §7.2), without revealing which permit or which key:
+ *
+ *   public:  registry, root, slot, requiredScope, context
+ *   output:  nullifier = Poseidon(holder secret, context)
+ *   private: the permit leaf, its Merkle witness, the holder secret, and the
+ *            holder's signature over (registry, root, context)
+ *
+ * The verifier checks the proof, that `root` is a recent root of the
+ * registry (from a Mina node, or the keeper's /roots), that `slot` is close
+ * to now, and — if it wants one use per holder per context — that the
+ * nullifier is new. Proving runs on the holder's device: it needs the
+ * holder's signature and secret, which never leave it.
+ *
+ * The holder secret: permit subjects are public (each permit is published
+ * with its subject), so a nullifier computed from the subject could be
+ * recomputed by anyone for every permit and matched. The nullifier is
+ * computed from a secret only the holder's wallet can produce instead: the
+ * hash of its text signature over (registry, network, a counter), which is
+ * deterministic, so the same wallet re-derives it anywhere from the chain
+ * alone (holderSecret.ts). The permit's
+ * salt is the hash of that secret, so the keeper and the authority, who see
+ * the salt, still cannot compute nullifiers; and one secret per permit keeps
+ * one nullifier per permit and context.
+ */
+import { Field, MerkleMapWitness, Poseidon, PublicKey, Signature, Struct, UInt32, ZkProgram } from 'o1js';
+import { PermitLeaf, permitLeafHash, permitSubject, PERMIT_STATUS_ACTIVE, } from './permitMessages.js';
+import { saltFromHolderSecret } from './holderSecret.js';
+/** Tag for the holder's proof signature (distinct from every registry message). */
+export const PERMIT_PROOF_TAG = Field([...'zkPermits/v1/proof'].reduce((v, ch) => (v << 8n) | BigInt(ch.charCodeAt(0)), 0n));
+export const PermitProofInput = Struct({
+    registry: PublicKey,
+    root: Field,
+    slot: UInt32,
+    requiredScope: Field,
+    context: Field,
+});
+/** The message the holder signs to prove control of the permit's key. */
+export function holderProofMessage(registry, root, context) {
+    return [PERMIT_PROOF_TAG, ...registry.toFields(), root, context];
+}
+/** Nullifier: stable per (permit, context), unlinkable across contexts; needs the holder secret. */
+export function permitNullifier(holderSecret, context) {
+    return Poseidon.hash([PERMIT_PROOF_TAG, holderSecret, context]);
+}
+// ── Holder secret ─── (holderSecret.ts; re-exported here)
+export { HOLDER_SECRET_TAG, HOLDER_SALT_TAG, holderSecretText, holderSecretFromSignature, saltFromHolderSecret, deriveHolderSecret, findHolderSecret, holderSecretMatches, MAX_HOLDER_SECRETS, } from './holderSecret.js';
+// ── Verifier-bound challenges ───────────────────────────────────────────────
+//
+// The proof's `context` is a public input the verifier chooses, and the
+// nullifier is Poseidon(tag, subject, context). If two verifiers handed out
+// the same raw context, the same holder would give both the same nullifier,
+// and comparing lists would link the two uses. So the context is derived
+// from the verifier's identity and its nonce: verifiers with different
+// identities always get different contexts, whatever nonces they pick. The
+// holder derives it from the identity it actually talks to (a site's
+// origin, a service's address), never from a context the verifier supplies.
+/** Tag for verifier-bound contexts (distinct from PERMIT_PROOF_TAG). */
+export const VERIFIER_CONTEXT_TAG = Field([...'zkPermits/v1/verifier'].reduce((v, ch) => (v << 8n) | BigInt(ch.charCodeAt(0)), 0n));
+/**
+ * The canonical form of a verifier identity: a URL becomes its origin
+ * (scheme, lower-case host, non-default port; path and query dropped), so
+ * `https://Shop.Example/verify?x=1` and `https://shop.example` are the same
+ * verifier. Anything else is a service name, trimmed and lower-cased with
+ * runs of whitespace collapsed.
+ */
+export function normalizeVerifier(verifier) {
+    const raw = String(verifier ?? '').trim();
+    let id;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) {
+        let origin;
+        try {
+            origin = new URL(raw).origin;
+        }
+        catch {
+            throw new Error(`verifier is not a valid URL: ${raw}`);
+        }
+        if (!origin || origin === 'null')
+            throw new Error(`verifier URL has no origin: ${raw}`);
+        id = origin;
+    }
+    else {
+        id = raw.toLowerCase().replace(/\s+/g, ' ');
+    }
+    if (!id)
+        throw new Error('verifier identity is empty');
+    if (id.length > 256)
+        throw new Error('verifier identity is longer than 256 characters');
+    if (/[\u0000-\u001f\u007f]/.test(id))
+        throw new Error('verifier identity contains control characters');
+    return id;
+}
+/** A fresh 128-bit nonce for a verifier to hand to a holder. */
+export function randomNonce() {
+    const b = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(b);
+    return b.reduce((v, x) => (v << 8n) | BigInt(x), 0n);
+}
+function parseNonce(nonce) {
+    const n = typeof nonce === 'bigint' ? nonce : /^\d{1,80}$/.test(String(nonce).trim()) ? BigInt(String(nonce).trim()) : -1n;
+    if (n < 0n || n >= 1n << 253n)
+        throw new Error('nonce must be a decimal integer below 2^253');
+    return n;
+}
+/**
+ * The proof context for `verifier` (see normalizeVerifier) and its `nonce`:
+ * Poseidon(VERIFIER_CONTEXT_TAG, byteLength, identity in 31-byte chunks, nonce).
+ * Holder and verifier compute it the same way.
+ */
+export function verifierContext(verifier, nonce) {
+    const bytes = new TextEncoder().encode(normalizeVerifier(verifier));
+    const chunks = [];
+    for (let i = 0; i < bytes.length; i += 31) {
+        chunks.push(Field(bytes.slice(i, i + 31).reduce((v, x) => (v << 8n) | BigInt(x), 0n)));
+    }
+    return Poseidon.hash([VERIFIER_CONTEXT_TAG, Field(bytes.length), ...chunks, Field(parseNonce(nonce))]).toBigInt();
+}
+/** In-circuit: every bit set in `required` is set in `scope` (254-bit masks). */
+function assertScopeCovers(scope, required) {
+    const s = scope.toBits(254);
+    const r = required.toBits(254);
+    for (let i = 0; i < 254; i++)
+        r[i].not().or(s[i]).assertTrue();
+}
+export const PermitProof = ZkProgram({
+    name: 'zkPermits-holder-proof',
+    publicInput: PermitProofInput,
+    publicOutput: Field,
+    methods: {
+        prove: {
+            privateInputs: [PermitLeaf, MerkleMapWitness, Field, Signature],
+            async method(input, leaf, witness, holderSecret, holderSig) {
+                const [root, key] = witness.computeRootAndKey(permitLeafHash(leaf));
+                root.assertEquals(input.root);
+                key.assertEquals(leaf.subject);
+                permitSubject(leaf.holderKey, saltFromHolderSecret(holderSecret)).assertEquals(leaf.subject);
+                holderSig.verify(leaf.holderKey, holderProofMessage(input.registry, input.root, input.context)).assertTrue();
+                leaf.status.assertEquals(PERMIT_STATUS_ACTIVE);
+                leaf.validFrom.assertLessThanOrEqual(input.slot);
+                input.slot.assertLessThanOrEqual(leaf.expirySlot);
+                assertScopeCovers(leaf.scope, input.requiredScope);
+                return { publicOutput: permitNullifier(holderSecret, input.context) };
+            },
+        },
+    },
+});
+/** Holder side: compiles (once) and proves. Returns the proof as JSON. */
+export async function proveHolder(r) {
+    const { Bool } = await import('o1js');
+    await PermitProof.compile();
+    const input = new PermitProofInput({
+        registry: PublicKey.fromBase58(r.registry),
+        root: Field(r.root),
+        slot: UInt32.from(r.slot),
+        requiredScope: Field(r.requiredScope),
+        context: Field(r.context),
+    });
+    const witness = new MerkleMapWitness(r.witness.isLefts.map(b => Bool(b)), r.witness.siblings.map(s => Field(s)));
+    const { proof } = await PermitProof.prove(input, r.leaf, witness, Field(r.holderSecret), Signature.fromBase58(r.holderSignature));
+    return { proof: proof.toJSON(), nullifier: proof.publicOutput.toString() };
+}
+/** Verifier side: checks the proof and its public inputs. Returns the nullifier. */
+export async function verifyHolderProof(proofJson, check) {
+    const { verificationKey } = await PermitProof.compile();
+    const ProofClass = ZkProgram.Proof(PermitProof);
+    let proof;
+    try {
+        proof = await ProofClass.fromJSON(proofJson);
+    }
+    catch (e) {
+        return { valid: false, nullifier: null, reason: `malformed proof: ${e?.message ?? e}` };
+    }
+    const pub = proof.publicInput;
+    const fail = (reason) => ({ valid: false, nullifier: null, reason });
+    if (pub.registry.toBase58() !== check.registry)
+        return fail('proof is for another registry');
+    if (!check.acceptedRoots.includes(pub.root.toString()))
+        return fail('root is not a current root of the registry');
+    if (Math.abs(Number(pub.slot.toString()) - check.currentSlot) > (check.maxSlotSkew ?? 10))
+        return fail('slot is too far from now');
+    if (pub.requiredScope.toBigInt() !== (check.requiredScope ?? 0n))
+        return fail('proof is for other scope bits');
+    let expected;
+    try {
+        expected = check.verifier !== undefined ? verifierContext(check.verifier, check.nonce) : check.context;
+    }
+    catch (e) {
+        return fail(e?.message ?? String(e));
+    }
+    if (pub.context.toBigInt() !== expected)
+        return fail('proof is for another context');
+    const { verify } = await import('o1js');
+    if (!(await verify(proof, verificationKey)))
+        return fail('proof does not verify');
+    return { valid: true, nullifier: proof.publicOutput.toString(), reason: null };
+}
+//# sourceMappingURL=permitProof.js.map

package/build/permitProof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permitProof.js","sourceRoot":"","sources":["../src/permitProof.ts"],"names":[],"mappings":"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"}

package/build/permitRegistryRebuild.d.ts

@@ -0,0 +1,166 @@
+/**
+ * permitRegistryRebuild.ts — `zklicensing/permits/rebuild`
+ *
+ * Rebuilds a PermitRegistry's permits tree from its events alone. Every
+ * event that changes a permit carries the full new leaf, so the tree is
+ * recoverable from the chain without the Keeper (PERMITS_PLAN.md §8.2).
+ * The Keeper's indexer uses this same code. Open applications (fees in
+ * escrow) are rebuilt the same way: filed minus settled.
+ */
+import { PublicKey, UInt32 } from 'o1js';
+import { CompactMerkleMap } from './compactMerkleMap.js';
+import { Application, PermitLeaf, unpackFees, unpackPolicy } from './permitMessages.js';
+/** A decoded event, as returned by `fetchEvents` (fields we use). */
+export type RegistryEvent = {
+    type: string;
+    event: {
+        data: any;
+    };
+    blockHeight?: UInt32 | {
+        toString(): string;
+    };
+    globalSlot?: UInt32 | {
+        toString(): string;
+    };
+};
+export type PermitRecord = {
+    subject: string;
+    holderKey: string;
+    scope: string;
+    validFrom: number;
+    expirySlot: number;
+    status: number;
+    seq: number;
+    docHash: string;
+};
+/** An application with its fee in escrow, as JSON (amounts in nanomina, slots as numbers). */
+export type ApplicationRecord = {
+    subject: string;
+    holderKey: string;
+    payer: string;
+    baseSeq: number;
+    scope: string;
+    validFrom: number;
+    expirySlot: number;
+    docHash: string;
+    fee: string;
+    processingFee: string;
+    deadline: number;
+    /** The registry's filing number. */
+    filing: number;
+};
+/** How an application ended (APPLICATION_OUTCOME), amounts in nanomina. */
+export type Settlement = {
+    subject: string;
+    outcome: number;
+    kept: string;
+    refunded: string;
+};
+export type RegistryView = {
+    /** The permits tree (a MerkleMap drop-in that can be saved and loaded without re-hashing). */
+    tree: CompactMerkleMap;
+    root: string;
+    permits: Map<string, PermitRecord>;
+    keysHash: string | null;
+    epoch: number;
+    feesPacked: string | null;
+    /** The escrow tree (subject → applicationHash of the open application) and its root. */
+    escrow: CompactMerkleMap;
+    escrowRoot: string;
+    /** Open applications by subject. */
+    applications: Map<string, ApplicationRecord>;
+    /** Settled applications by application hash: how each ended. */
+    settlements: Map<string, Settlement>;
+    eventsApplied: number;
+    /** Set once the registry was retired (redeployed): its frozen permits root. */
+    retiredRoot?: string;
+    /** Whether the platform key retired it (retireByPlatform) rather than the authority. */
+    retiredByPlatform?: boolean;
+    /** Whether it was retired with application fees in escrow (they stay on it). */
+    retiredForced?: boolean;
+    /**
+     * A redeployed registry starts with its predecessor's permits
+     * (seededRegistryView): the tree it started with, and each carried-over
+     * permit's seq then, so its next change is seq + 1.
+     */
+    start?: {
+        root: string;
+        seqs: Map<string, number>;
+    };
+};
+export declare function leafToRecord(leaf: PermitLeaf): PermitRecord;
+export declare function applicationToRecord(app: Application): ApplicationRecord;
+export declare function recordToApplication(r: ApplicationRecord): Application;
+export declare function recordToLeaf(r: PermitRecord): PermitLeaf;
+/**
+ * The view a redeployed registry starts with: a copy of its retired
+ * predecessor's permits and tree (the initialPermitsRoot its keys signed).
+ * Its own events then apply on top; `registryCreated` checks the root.
+ */
+export declare function seededRegistryView(predecessor: RegistryView): RegistryView;
+/**
+ * The retired registry a registry continues, from its `registryCreated`
+ * event (base58), or null for a first generation. With it a registry's
+ * lineage can be walked back on chain events alone; the successor's start
+ * was checked against the predecessor's retired root when it was deployed.
+ */
+export declare function registryPredecessor(events: RegistryEvent[]): string | null;
+export declare function emptyRegistryView(): RegistryView;
+/**
+ * Applies events in any order. Archive nodes, local chains and paginated
+ * fetches don't agree on ordering, so none is assumed: each subject's leaves
+ * are ordered by `seq` (the contract advances it by exactly one per change),
+ * key rotations by `epoch` and fee changes by `actionNonce`. A gap in a
+ * subject's sequence means events are missing, and throws rather than build
+ * a wrong tree. Applying to a non-empty view continues from its state.
+ */
+export declare function applyRegistryEvents(view: RegistryView, events: RegistryEvent[]): RegistryView;
+/**
+ * Brings `view` up to date with a registry's full event list, re-hashing only
+ * the permits whose latest leaf changed: a full rebuild costs a 256-level tree
+ * path per permit, a refresh one per changed permit. Returns the subjects
+ * that changed (added or updated).
+ */
+export declare function refreshRegistryView(view: RegistryView, events: RegistryEvent[]): string[];
+/** Fetches a registry's events (active Mina instance) and rebuilds its tree. */
+export declare function rebuildRegistry(address: PublicKey | string): Promise<RegistryView>;
+/** 'moved': the holder moved it to a new key (a new permit, under a new subject); this one is closed. */
+export type PermitStatusName = 'active' | 'suspended' | 'revoked' | 'moved' | 'expired' | 'not-yet-valid' | 'in-grace' | 'unknown';
+/**
+ * Effective status of a permit at `slot`: revoked and suspended win, then the
+ * dates. `gracePeriod` comes from the registry policy.
+ */
+/**
+ * A permit's status at `slot`. With the registry's `forkActivationSlot`
+ * (a successor deployed after a Mina hard fork): a permit that lapsed
+ * shortly before the fork, while its registry was retired and couldn't
+ * renew it, counts as expiring at the fork slot, so its grace runs from the
+ * fork (as licensing's effectiveExpirySlot). Anonymous holder proofs check
+ * the expiry as granted.
+ */
+export declare function permitStatusAt(rec: PermitRecord | undefined, slot: number, gracePeriod?: number, forkActivationSlot?: number): PermitStatusName;
+export { unpackFees, unpackPolicy };
+/** A registry view saved without its tree's hashes recomputed (see CompactMerkleMap). */
+export type StoredRegistryView = {
+    root: string;
+    permits: PermitRecord[];
+    tree: {
+        indices: string;
+        leaves: string;
+        splits: string;
+    };
+    /** Open applications (absent in views saved before escrow). */
+    applications?: ApplicationRecord[];
+    /** A redeployed registry's start (RegistryView.start): its root and the carried-over seqs. */
+    start?: {
+        root: string;
+        seqs: Array<[string, number]>;
+    };
+};
+export declare function registryViewToStored(view: RegistryView): StoredRegistryView;
+/**
+ * Loads a saved view without re-hashing; its keys, epoch and fees come back
+ * with the next refreshRegistryView. Throws if the copy is inconsistent.
+ */
+export declare function registryViewFromStored(s: StoredRegistryView): RegistryView;
+//# sourceMappingURL=permitRegistryRebuild.d.ts.map

package/build/permitRegistryRebuild.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permitRegistryRebuild.d.ts","sourceRoot":"","sources":["../src/permitRegistryRebuild.ts"],"names":[],"mappings":"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"}