@zanii/certify 0.0.0-stage → 0.5.0

package/dist/issuer-resolution.js

@@ -0,0 +1,89 @@
+import { publicKeyFromDid } from "@zanii/core";
+import { isObj } from "./shared.js";
+const failure = (error) => {
+    const e = error;
+    const code = e?.cause?.code ?? e?.code ?? "";
+    return { ok: false, code: e?.name === "TimeoutError" || e?.name === "AbortError" || code === "ETIMEDOUT" || code.endsWith("_TIMEOUT") ? "timeout"
+            : ["ENOTFOUND", "EAI_AGAIN", "ENODATA"].includes(code) ? "dns" : /^(?:ERR_TLS|ERR_SSL|CERT_|DEPTH_|SELF_SIGNED|UNABLE_TO_VERIFY|UNABLE_TO_GET_ISSUER_CERT)/.test(code) ? "tls" : "network" };
+};
+/** A single deadline covers headers and body, including injected transports that ignore AbortSignal. */
+export async function fetchJsonBounded(url, opts = {}) {
+    const timeout = opts.timeoutMs ?? 10_000, limit = opts.maxBytes ?? 1_048_576;
+    if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 10_000 || !Number.isSafeInteger(limit) || limit < 1 || limit > 8_388_608)
+        return { ok: false, code: "invalid_input" };
+    try {
+        const u = new URL(url);
+        if (!["http:", "https:"].includes(u.protocol) || u.username || u.password || u.hash)
+            return { ok: false, code: "invalid_input" };
+    }
+    catch {
+        return { ok: false, code: "invalid_input" };
+    }
+    const controller = new AbortController();
+    let timer;
+    const task = async () => {
+        const response = await (opts.fetch ?? fetch)(url, { redirect: "error", signal: controller.signal });
+        if (response.status !== 200) {
+            await response.body?.cancel();
+            return { ok: false, code: "http", status: response.status };
+        }
+        if (Number(response.headers.get("content-length")) > limit) {
+            await response.body?.cancel();
+            return { ok: false, code: "too_large" };
+        }
+        const reader = response.body?.getReader();
+        const chunks = [];
+        let size = 0;
+        if (reader)
+            try {
+                for (;;) {
+                    const read = await reader.read();
+                    if (read.done)
+                        break;
+                    size += read.value.length;
+                    if (size > limit) {
+                        void reader.cancel().catch(() => { });
+                        return { ok: false, code: "too_large" };
+                    }
+                    chunks.push(read.value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        try {
+            return { ok: true, document: JSON.parse(new TextDecoder("utf8", { fatal: true }).decode(Buffer.concat(chunks))) };
+        }
+        catch {
+            return { ok: false, code: "document" };
+        }
+    };
+    try {
+        return await Promise.race([task(), new Promise((resolve) => { timer = setTimeout(() => { controller.abort(); resolve({ ok: false, code: "timeout" }); }, timeout); })]);
+    }
+    catch (error) {
+        return failure(error);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        controller.abort();
+    }
+}
+/** Unlike the legacy null resolver, distinguishes a failed fetch from a document that omits the key. */
+export async function resolveIssuerDetailed(did, domain, opts = {}) {
+    if (typeof did !== "string" || did.length > 69 || !publicKeyFromDid(did) || typeof domain !== "string" || domain.length > 253
+        || !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(domain.toLowerCase()) || domain.trim() !== domain)
+        return { ok: false, code: "invalid_input" };
+    const host = domain.toLowerCase();
+    const result = await fetchJsonBounded(`https://${host}/.well-known/zanii-issuer.json`, opts);
+    if (!result.ok)
+        return result;
+    const doc = result.document;
+    if (!isObj(doc) || doc.v !== 1 || typeof doc.domain !== "string" || doc.domain.toLowerCase() !== host || typeof doc.name !== "string"
+        || doc.name.length > 200 || !Array.isArray(doc.dids) || doc.dids.length > 64 || !doc.dids.every((d) => typeof d === "string" && d.length <= 69 && publicKeyFromDid(d)))
+        return { ok: false, code: "document" };
+    if (!doc.dids.includes(did))
+        return { ok: false, code: "key_missing" };
+    return { ok: true, issuer: { did, name: doc.name, domain: host }, document: doc };
+}

package/dist/licence-owner-entry.d.ts

@@ -0,0 +1,20 @@
+import { type LicenceState } from "./licence.ts";
+export interface LicenceOwnerEntryContext {
+    root: string;
+    currentOwner: string;
+    size: number;
+    hash: string | null;
+    at: string | null;
+    prefixRoot: string;
+    /** Lookups expose only the already authenticated prefix. */
+    knownOwner: (did: string) => boolean;
+    licenceState: (hash: string) => LicenceState;
+}
+export interface LicenceOwnerEntryCheck {
+    ok: boolean;
+    reasons: string[];
+    currentOwner: string | null;
+    at?: string;
+    licenceState?: LicenceState;
+}
+export declare function verifyLicenceOwnerEntry(doc: unknown, c: LicenceOwnerEntryContext): LicenceOwnerEntryCheck;

package/dist/licence-owner-entry.js

@@ -0,0 +1,33 @@
+// One extension of a trusted mixed owner-history prefix; the caller commits metadata atomically.
+import { publicKeyFromDid, verifySignedObject, verifySTH } from "@zanii/core";
+import { signersOf } from "./board.js";
+import { licenceStatusFieldError } from "./licence.js";
+import { isLicenceOwnerCheckpoint, isLicenceOwnerRotation } from "./licence-owner.js";
+import { isInt, isIso, isObj, isSha, ms } from "./shared.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+const did = (v) => typeof v === "string" && v.length <= 69 && publicKeyFromDid(v) !== null;
+export function verifyLicenceOwnerEntry(doc, c) {
+    const denied = (reason) => ({ ok: false, reasons: [reason], currentOwner: null });
+    if (!withinVerificationBudget(doc, { maxBytes: 1_048_576, maxNodes: 100_000 }) || !withinVerificationBudget({ root: c?.root, currentOwner: c?.currentOwner, size: c?.size, hash: c?.hash, at: c?.at, prefixRoot: c?.prefixRoot }, { maxBytes: 4096, maxNodes: 100 })
+        || !did(c?.root) || !did(c?.currentOwner) || !isInt(c?.size, 0, 9999) || !(c.size === 0 ? c.hash === null && c.at === null && c.currentOwner === c.root : isSha(c.hash) && isIso(c.at)) || !isSha(c?.prefixRoot) || typeof c?.knownOwner !== "function" || typeof c?.licenceState !== "function")
+        return denied("a bounded authenticated licence-owner prefix is required");
+    if (!isObj(doc) || doc.seq !== c.size || doc.prev !== c.hash || !isIso(doc.at) || (c.at !== null && ms(doc.at) < ms(c.at)))
+        return denied("owner history entry has an invalid position or time");
+    if (doc.type === "certify.licence-owner-rotation") {
+        if (!isLicenceOwnerRotation(doc) || doc.from !== c.currentOwner || c.knownOwner(doc.to) || (c.at !== null && ms(doc.at) <= ms(c.at)))
+            return denied("owner rotation has an invalid signer, cutover or reused key");
+        const cp = doc.checkpoint;
+        if (!isLicenceOwnerCheckpoint(cp) || cp.log_id !== c.currentOwner || cp.size !== c.size || cp.root !== c.prefixRoot || !verifySTH(cp) || ms(cp.ts) > ms(doc.at) || (c.at !== null && ms(cp.ts) < ms(c.at)))
+            return denied("owner rotation does not bind the preceding history checkpoint");
+        const signed = signersOf(doc, [c.currentOwner, doc.to]);
+        if (!signed.wellFormed || signed.signers.length !== 2)
+            return denied("owner rotation needs the retiring and successor signatures");
+        return { ok: true, reasons: [], currentOwner: doc.to, at: doc.at };
+    }
+    if (doc.v !== 1 || doc.type !== "certify.licence-status" || Object.keys(doc).length !== ("for_cause" in doc || "effective_at" in doc ? 12 : 10) || doc.signer !== c.currentOwner || licenceStatusFieldError(doc) || !verifySignedObject(doc))
+        return denied("owner history entry is not a status entry signed by the current owner");
+    const was = c.licenceState(doc.licence);
+    if (!["active", "suspended", "withdrawn"].includes(was) || (doc.action === "suspend" && was !== "active") || (doc.action === "reinstate" && was !== "suspended") || (doc.action === "withdraw" && was === "withdrawn"))
+        return denied("owner history entry has an invalid licence state transition");
+    return { ok: true, reasons: [], currentOwner: c.currentOwner, at: doc.at, licenceState: doc.action === "suspend" ? "suspended" : doc.action === "reinstate" ? "active" : "withdrawn" };
+}

package/dist/licence-owner.d.ts

@@ -0,0 +1,67 @@
+import { type SignedTreeHead } from "@zanii/core";
+import { type BodySignature } from "./board.ts";
+import { type Licence } from "./licence.ts";
+import { type Signer } from "./signer.ts";
+export interface LicenceOwnerRotation {
+    v: 1;
+    type: "certify.licence-owner-rotation";
+    seq: number;
+    prev: string | null;
+    from: string;
+    to: string;
+    at: string;
+    checkpoint: SignedTreeHead;
+    licences: {
+        size: number;
+        root: string;
+    };
+    signatures: BodySignature[];
+}
+export interface OwnerLicenceProof {
+    rotation: string;
+    licence: string;
+    index: number;
+    size: number;
+    path: string[];
+}
+export interface LicenceOwnerHistoryPolicy {
+    log: readonly unknown[];
+    checkpoint: SignedTreeHead;
+    licenceProofs: readonly OwnerLicenceProof[];
+}
+export interface LicenceOwnerHistoryCheck {
+    ok: boolean;
+    reasons: string[];
+    currentOwner: string | null;
+    owners: {
+        did: string;
+        from: string | null;
+    }[];
+    rotations: LicenceOwnerRotation[];
+}
+declare const checkpointShape: (v: unknown) => v is SignedTreeHead;
+declare const rotationShape: (v: unknown) => v is LicenceOwnerRotation;
+export declare const isLicenceOwnerRotation: typeof rotationShape;
+export declare const isLicenceOwnerCheckpoint: typeof checkpointShape;
+export declare function verifyLicenceOwnerHistory(log: readonly unknown[], opts: {
+    root: string;
+    checkpoint: SignedTreeHead;
+}): LicenceOwnerHistoryCheck;
+export declare function licenceOwnerCheckpoint(log: readonly unknown[], at: string, signer: Signer, opts: {
+    root: string;
+}): Promise<SignedTreeHead>;
+export declare function buildLicenceOwnerRotation(input: {
+    history: readonly unknown[];
+    root: string;
+    licences: readonly Licence[];
+    at: string;
+}, retiring: Signer, successor: Signer): Promise<LicenceOwnerRotation>;
+export declare function licenceOwnerProofs(rotation: LicenceOwnerRotation, licences: readonly Licence[], hashes: readonly string[]): OwnerLicenceProof[];
+export declare const licenceOwnerProof: (rotation: LicenceOwnerRotation, licences: readonly Licence[], hash: string) => OwnerLicenceProof;
+export declare function verifyLicenceWithOwnerHistory(licence: unknown, opts: LicenceOwnerHistoryPolicy & {
+    root: string;
+}): {
+    ok: boolean;
+    reasons: string[];
+};
+export {};

package/dist/licence-owner.js

@@ -0,0 +1,180 @@
+// Versioned owner succession keeps status state and commits retired-owner issuance before cutover.
+import { canonicalBytes, createSTHAsync, jcsHash, leafHash, merkleRoot, publicKeyFromDid, verifyInclusion, verifySTH } from "@zanii/core";
+import { bodySignature, signersOf, withSignatures } from "./board.js";
+import { licenceStatusFieldError, verifyLicence } from "./licence.js";
+import { isInt, isIso, isObj, isSha, ms } from "./shared.js";
+import { signatureOk, signerDid } from "./signer.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+const did = (v) => typeof v === "string" && v.length <= 69 && publicKeyFromDid(v) !== null;
+const digest = (v) => isSha(v) && v.length === 71;
+const signature = (v) => typeof v === "string" && v.length === 136 && /^ed25519:[0-9a-f]{128}$/.test(v);
+const checkpointShape = (v) => isObj(v) && Object.keys(v).length === 6 && v.v === 1 && did(v.log_id) && digest(v.root) && isInt(v.size, 0, 10_000) && isIso(v.ts) && signature(v.sig);
+const rotationShape = (v) => isObj(v) && Object.keys(v).length === 10 && v.v === 1 && v.type === "certify.licence-owner-rotation"
+    && isInt(v.seq, 0, 10_000) && (v.seq === 0 ? v.prev === null : digest(v.prev)) && did(v.from) && did(v.to) && v.from !== v.to && isIso(v.at)
+    && checkpointShape(v.checkpoint) && isObj(v.licences) && Object.keys(v.licences).length === 2 && isInt(v.licences.size, 0, 50_000) && digest(v.licences.root)
+    && Array.isArray(v.signatures) && v.signatures.length === 2 && Array.from(v.signatures).every((s) => isObj(s) && Object.keys(s).length === 2 && did(s.signer) && signature(s.sig));
+const proofShape = (v) => isObj(v) && Object.keys(v).length === 5 && digest(v.rotation) && digest(v.licence) && isInt(v.size, 1, 50_000) && isInt(v.index, 0, v.size - 1)
+    && Array.isArray(v.path) && v.path.length <= 32 && Array.from(v.path).every((p) => typeof p === "string" && p.length === 64 && /^[0-9a-f]{64}$/.test(p));
+export const isLicenceOwnerRotation = rotationShape;
+export const isLicenceOwnerCheckpoint = checkpointShape;
+const hashHex = (b) => `sha256:${Buffer.from(b).toString("hex")}`;
+function frontier() {
+    const levels = [];
+    let size = 0;
+    return {
+        append(value) {
+            let node = leafHash(canonicalBytes(value)), n = size++, level = 0;
+            while (n % 2) {
+                node = merkleRoot([levels[level], node]);
+                levels[level] = undefined;
+                n = Math.floor(n / 2);
+                level++;
+            }
+            levels[level] = node;
+        },
+        root() {
+            let root;
+            for (const node of levels)
+                if (node)
+                    root = root ? merkleRoot([node, root]) : node;
+            return hashHex(root ?? merkleRoot([]));
+        },
+    };
+}
+function historyCheck(log, root, checkpoint, building = false) {
+    const denied = (reason) => ({ ok: false, reasons: [reason], currentOwner: null, owners: [], rotations: [] });
+    if (!did(root) || (!building && !checkpointShape(checkpoint)))
+        return denied("trusted owner root and independently pinned checkpoint are required");
+    if (!Array.isArray(log) || log.length > 10_000 || (!building && !log.length) || !withinVerificationBudget({ log, root, ...(checkpoint ? { checkpoint } : {}) }))
+        return denied("owner history exceeds bounds or is empty");
+    let current = root, previous = null;
+    const owners = [{ did: root, from: null }], rotations = [], state = new Map(), tree = frontier();
+    for (let i = 0; i < log.length; i++) {
+        const row = log[i];
+        if (!isObj(row) || row.seq !== i || row.prev !== (i ? jcsHash(previous) : null) || !isIso(row.at) || (previous && ms(row.at) < ms(previous.at)))
+            return denied(`owner history entry ${i} has an invalid position or time`);
+        if (row.type === "certify.licence-owner-rotation") {
+            if (!rotationShape(row) || row.from !== current || owners.some((o) => o.did === row.to) || (previous && ms(row.at) <= ms(previous.at)))
+                return denied(`owner rotation ${i} has an invalid signer, cutover or reused key`);
+            const cp = row.checkpoint;
+            if (cp.log_id !== current || cp.size !== i || cp.root !== tree.root() || !verifySTH(cp) || ms(cp.ts) > ms(row.at) || (previous && ms(cp.ts) < ms(previous.at)))
+                return denied(`owner rotation ${i} does not bind the preceding history checkpoint`);
+            const signed = signersOf(row, [current, row.to]);
+            if (!signed.wellFormed || signed.signers.length !== 2)
+                return denied(`owner rotation ${i} needs the retiring and successor signatures`);
+            current = row.to;
+            owners.push({ did: current, from: row.at });
+            rotations.push(row);
+        }
+        else {
+            if (row.v !== 1 || row.type !== "certify.licence-status" || Object.keys(row).length !== ("for_cause" in row || "effective_at" in row ? 12 : 10)
+                || row.signer !== current || !signature(row.sig) || !signatureOk(Object.fromEntries(Object.entries(row).filter(([key]) => key !== "sig")), row.sig, current)
+                || licenceStatusFieldError(row) || !digest(row.licence))
+                return denied(`owner history entry ${i} is not a status entry signed by the current owner`);
+            const was = state.get(row.licence) ?? "active";
+            const action = row.action;
+            if ((action === "suspend" && was !== "active") || (action === "reinstate" && was !== "suspended") || (action === "withdraw" && was === "withdrawn"))
+                return denied(`owner history entry ${i} has an invalid licence state transition`);
+            state.set(row.licence, action === "suspend" ? "suspended" : action === "reinstate" ? "active" : "withdrawn");
+        }
+        tree.append(row);
+        previous = row;
+    }
+    if (!building && (!checkpoint || checkpoint.log_id !== current || checkpoint.size !== log.length || checkpoint.root !== tree.root() || !verifySTH(checkpoint) || (previous && ms(checkpoint.ts) < ms(previous.at))))
+        return denied("pinned owner checkpoint does not cover this complete history");
+    return { ok: true, reasons: [], currentOwner: current, owners, rotations };
+}
+export function verifyLicenceOwnerHistory(log, opts) {
+    return historyCheck(log, opts?.root, opts?.checkpoint);
+}
+export async function licenceOwnerCheckpoint(log, at, signer, opts) {
+    const checked = historyCheck(log, opts?.root, undefined, true), last = log?.at(-1);
+    if (!checked.ok || checked.currentOwner !== signerDid(signer) || !isIso(at) || (last && ms(at) < ms(last.at)))
+        throw new Error("invalid owner checkpoint signer, history or time");
+    const tree = frontier();
+    for (const row of log)
+        tree.append(row);
+    return createSTHAsync({ logId: signerDid(signer), size: log.length, root: tree.root(), ts: at }, signer.sign);
+}
+const licenceLeaf = (hash) => leafHash(canonicalBytes({ v: 1, type: "certify.owner-licence-leaf", licence: hash }));
+function licenceSnapshot(licences, owner, at) {
+    if (!Array.isArray(licences) || licences.length > 50_000 || !withinVerificationBudget(licences))
+        throw new Error("owner issuance snapshot exceeds bounds");
+    const hashes = licences.map((licence) => {
+        if (!verifyLicence(licence, { owner }).ok || ms(licence.issued_at) > ms(at))
+            throw new Error("invalid retiring-owner licence snapshot");
+        return jcsHash(licence);
+    }).sort();
+    if (new Set(hashes).size !== hashes.length)
+        throw new Error("duplicate retiring-owner licence");
+    const levels = [hashes.map(licenceLeaf)];
+    while (levels.at(-1).length > 1) {
+        const level = levels.at(-1);
+        const next = [];
+        for (let i = 0; i < level.length; i += 2)
+            next.push(i + 1 < level.length ? merkleRoot([level[i], level[i + 1]]) : level[i]);
+        levels.push(next);
+    }
+    return { hashes, levels, root: hashHex(levels.at(-1)[0] ?? merkleRoot([])) };
+}
+export async function buildLicenceOwnerRotation(input, retiring, successor) {
+    if (!withinVerificationBudget(input) || !isIso(input.at) || !Array.isArray(input.history) || input.history.length >= 10_000)
+        throw new Error("invalid owner rotation input");
+    const checked = historyCheck(input.history, input.root, undefined, true), from = signerDid(retiring), to = signerDid(successor);
+    const prior = input.history.at(-1);
+    if (!checked.ok || checked.currentOwner !== from || checked.owners.some((o) => o.did === to) || (prior && ms(input.at) <= ms(prior.at)))
+        throw new Error("invalid retiring/successor owner or cutover history");
+    const issued = licenceSnapshot(input.licences, from, input.at), tree = frontier();
+    for (const entry of input.history)
+        tree.append(entry);
+    const seq = input.history.length, prev = seq ? jcsHash(prior) : null, at = input.at;
+    const cp = await createSTHAsync({ logId: from, size: seq, root: tree.root(), ts: at }, retiring.sign);
+    const body = { v: 1, type: "certify.licence-owner-rotation", seq, prev, from, to, at, checkpoint: cp, licences: { size: issued.hashes.length, root: issued.root } };
+    return withSignatures(body, await Promise.all([bodySignature(body, retiring), bodySignature(body, successor)]));
+}
+export function licenceOwnerProofs(rotation, licences, hashes) {
+    if (!rotationShape(rotation) || !Array.isArray(hashes) || hashes.length < 1 || hashes.length > 100 || !Array.from(hashes).every(digest) || !withinVerificationBudget({ rotation, licences, hashes }))
+        throw new Error("invalid owner licence proof request");
+    const snapshot = licenceSnapshot(licences, rotation.from, rotation.at);
+    if (snapshot.root !== rotation.licences.root || snapshot.hashes.length !== rotation.licences.size)
+        throw new Error("licences do not match the committed cutover snapshot");
+    const positions = new Map(snapshot.hashes.map((hash, i) => [hash, i]));
+    return hashes.map((hash) => {
+        const index = positions.get(hash);
+        if (index === undefined)
+            throw new Error("licence is not in the cutover snapshot");
+        const path = [];
+        let at = index;
+        for (const level of snapshot.levels.slice(0, -1)) {
+            const sibling = at % 2 ? at - 1 : at + 1;
+            if (sibling < level.length)
+                path.push(Buffer.from(level[sibling]).toString("hex"));
+            at = Math.floor(at / 2);
+        }
+        return { rotation: jcsHash(rotation), licence: hash, index, size: snapshot.hashes.length, path };
+    });
+}
+export const licenceOwnerProof = (rotation, licences, hash) => licenceOwnerProofs(rotation, licences, [hash])[0];
+export function verifyLicenceWithOwnerHistory(licence, opts) {
+    const denied = (reason) => ({ ok: false, reasons: [reason] });
+    if (!isObj(opts) || Object.keys(opts).length !== 4 || !Array.isArray(opts.licenceProofs) || opts.licenceProofs.length > 1000 || !Array.from(opts.licenceProofs).every(proofShape)
+        || !withinVerificationBudget({ licence, opts }))
+        return denied("rotated-owner policy or proofs exceed bounds");
+    const checked = verifyLicenceOwnerHistory(opts.log, opts);
+    if (!checked.ok)
+        return { ok: false, reasons: checked.reasons };
+    if (!isObj(licence) || !did(licence.signer) || !isIso(licence.issued_at))
+        return denied("invalid licence owner or issuance time");
+    const owner = checked.owners.find((o) => o.did === licence.signer), outgoing = checked.rotations.find((r) => r.from === licence.signer);
+    if (!owner || (owner.from && ms(licence.issued_at) < ms(owner.from)) || (outgoing && ms(licence.issued_at) > ms(outgoing.at)))
+        return denied("licence was not signed by an owner in force at issuance");
+    const reasons = verifyLicence(licence, { owner: licence.signer }).reasons;
+    if (outgoing) {
+        const hash = jcsHash(licence), rotation = jcsHash(outgoing), proof = opts.licenceProofs.find((p) => p.licence === hash && p.rotation === rotation);
+        if (!proof)
+            reasons.push("retired-owner licence needs its cutover issuance inclusion proof");
+        else if (proof.size !== outgoing.licences.size || !verifyInclusion(licenceLeaf(hash), proof.index, proof.size, proof.path.map((p) => Buffer.from(p, "hex")), Buffer.from(outgoing.licences.root.slice(7), "hex")))
+            reasons.push("retired-owner licence is not in the cutover issuance snapshot");
+    }
+    return { ok: reasons.length === 0, reasons };
+}

package/dist/licence.d.ts

@@ -0,0 +1,174 @@
+import type { Credential } from "@zanii/credentials";
+import { type BodySignature } from "./board.ts";
+import { type Signer } from "./signer.ts";
+import { type LicenceOwnerHistoryPolicy } from "./licence-owner.ts";
+/** Section 1: the largest royalty per certificate, and section 4 the most certificates in one statement (their product stays a safe integer). */
+export declare const MAX_ROYALTY_MINOR = 1000000000;
+export declare const MAX_STATEMENT_CERTIFICATES = 1000000;
+export interface LicenceScope {
+    profile: string;
+    levels: number[];
+}
+export interface Licence {
+    v: 1;
+    type: "certify.licence";
+    licensee: string;
+    legal_name: string;
+    countries: string[];
+    scope: LicenceScope[];
+    valid_from: string;
+    valid_until: string;
+    royalty: {
+        per_certificate_minor: number;
+        currency: string;
+    };
+    issued_at: string;
+    signer: string;
+    sig: string;
+}
+export interface LicenceInput {
+    licensee: string;
+    legalName: string;
+    countries: readonly string[];
+    scope: readonly {
+        profile: string;
+        levels: readonly number[];
+    }[];
+    validFrom: string;
+    validUntil: string;
+    royalty: {
+        per_certificate_minor: number;
+        currency: string;
+    };
+    issuedAt: string;
+}
+export interface LicenceCheck {
+    ok: boolean;
+    reasons: string[];
+}
+/** A scope list (licences, the body register): 1 to 256 `{profile, levels}`, sorted by profile, each once. */
+export declare function scopeError(s: unknown): string | null;
+/** Sorted by profile, each profile's levels sorted and distinct (the shape `scopeError` accepts). */
+export declare const normaliseScope: (scope: readonly {
+    profile: string;
+    levels: readonly number[];
+}[]) => LicenceScope[];
+/** Section 1: a licence, signed by the scheme owner (`signer`). */
+export declare function buildLicence(f: LicenceInput, signer: Signer): Promise<Licence>;
+/** Section 1: signed, well formed and (with `owner`) signed by the scheme owner. */
+export declare function verifyLicence(doc: unknown, opts?: {
+    owner?: string;
+}): LicenceCheck;
+/** Section 3: is `issuer` the licensee, or a key the licensee's key was succeeded by in `lineage` (oldest first)? */
+export declare const licensedKey: (licensee: unknown, issuer: unknown, lineage?: readonly string[]) => boolean;
+/**
+ * Section 3: what a licence must cover for a certificate: its issuer (the licensee, or a later key
+ * of the licensee's verified `lineage`), profile, level, country and issue time.
+ */
+export declare function licenceCoverage(licence: Record<string, unknown>, cert: Credential, lineage?: readonly string[]): string[];
+export declare const LICENCE_ACTIONS: readonly ["suspend", "reinstate", "withdraw"];
+export type LicenceAction = (typeof LICENCE_ACTIONS)[number];
+export declare const LICENCE_REASONS: readonly ["ROYALTY_UNPAID", "SCOPE_BREACH", "MARK_MISUSE", "AUDIT_FINDING", "ACCREDITATION_LOST", "LICENSEE_REQUEST", "OTHER"];
+export type LicenceReason = (typeof LICENCE_REASONS)[number];
+export type LicenceState = "active" | "suspended" | "withdrawn";
+export interface LicenceStatus {
+    v: 1;
+    type: "certify.licence-status";
+    seq: number;
+    prev: string | null;
+    licence: string;
+    action: LicenceAction;
+    reason: LicenceReason | null;
+    at: string;
+    /** Section 2a: a suspension or withdrawal for cause; certificates issued from `effective_at` are refused. */
+    for_cause?: true;
+    effective_at?: string;
+    signer: string;
+    sig: string;
+}
+declare function statusError(s: Record<string, unknown>): string | null;
+export { statusError as licenceStatusFieldError };
+/**
+ * Section 2: one licence status change, signed by the scheme owner. With `effectiveAt` (section 2a)
+ * a suspension or withdrawal is for cause from that time.
+ */
+export declare function buildLicenceStatus(f: {
+    seq: number;
+    prev: string | null;
+    licence: string;
+    action: LicenceAction;
+    reason: LicenceReason | null;
+    at: string;
+    effectiveAt?: string;
+}, signer: Signer): Promise<LicenceStatus>;
+/**
+ * Section 2: one log, signed by one key (with `owner`, the scheme owner), at seq i naming entry
+ * i - 1, `at` never going back, and every change allowed from the licence's state (withdrawal is final).
+ */
+export declare function verifyLicenceLog(log: readonly unknown[], opts?: {
+    owner?: string;
+}): LicenceCheck;
+/** Section 2: a licence's state at `at` from a verified log (changes at or before `at` apply). */
+export declare function licenceStateAt(log: readonly LicenceStatus[], licence: string, at: string): LicenceState;
+/** `verifyCertificate`'s `licences` option (section 3). */
+export interface LicenceOptions {
+    /** The scheme owner's did:key: licences and the licence status log must be signed by it. */
+    owner: string;
+    /** Candidate licences; the one whose jcsHash is `claim.licence` is checked. */
+    licences: readonly unknown[];
+    /** The scheme owner's licence status log; without it suspension and withdrawal are not checked. */
+    log?: readonly unknown[];
+    /** Issuer DIDs of the scheme owner's own labs, which certify without a licence. */
+    ownIssuers?: readonly string[];
+    /** The certificate issuer's verified key lineage, oldest first (`issuerLineage`): a licence naming an earlier key covers a later one. */
+    lineage?: readonly string[];
+    /** Strict rotated-owner history and independently pinned checkpoint (licensing.md section 6). */
+    ownerHistory?: LicenceOwnerHistoryPolicy;
+}
+/** Section 3: the reasons a certificate is not covered by a licence that was valid when it was issued. */
+export declare function licenceReasons(cert: Credential, opts: LicenceOptions): string[];
+export interface RoyaltyStatementInput {
+    licence: Licence;
+    period: {
+        from: string;
+        until: string;
+    };
+    /** The hashes of the certificates issued under the licence in the period. */
+    certificates: readonly string[];
+    issuedAt: string;
+}
+export type RoyaltyStatementBody = {
+    v: 1;
+    type: "certify.royalty-statement";
+    licence: string;
+    licensee: string;
+    period: {
+        from: string;
+        until: string;
+    };
+    certificates: number;
+    certificates_sha256: string;
+    amount_minor: number;
+    currency: string;
+    issued_at: string;
+};
+export type RoyaltyStatement = RoyaltyStatementBody & {
+    signatures: BodySignature[];
+};
+/** Section 4: `jcsHash({items})` of the sorted, distinct certificate hashes. */
+export declare const certificateListHash: (certificates: readonly string[]) => string;
+/** Section 4: the statement signed by the licensee (`signer`, the licence's licensee key). */
+export declare function buildRoyaltyStatement(f: RoyaltyStatementInput, signer: Signer): Promise<RoyaltyStatement>;
+/** Section 4: the scheme owner's countersignature, added beside the licensee's. */
+export declare function countersignRoyaltyStatement(statement: RoyaltyStatement, signer: Signer): Promise<RoyaltyStatement>;
+/**
+ * Section 4: signed by its licensee, countersigned by `owner`, and (with `licence`) the amount is
+ * the certificate count times the licence royalty in its currency; with `certificates`, the count
+ * and list hash are those of the supplied hashes.
+ */
+export declare function verifyRoyaltyStatement(doc: unknown, opts?: {
+    owner?: string;
+    licence?: unknown;
+    certificates?: readonly string[];
+    ownerHistory?: LicenceOwnerHistoryPolicy;
+}): LicenceCheck;