@zanii/certify 0.0.0-stage → 0.5.0

package/dist/licence.js

@@ -0,0 +1,400 @@
+// spec/licensing.md: scheme licences signed by the scheme owner, the owner's signed licence status
+// log (suspension, reinstatement, withdrawal), the licence check behind `verifyCertificate`'s
+// `licences` option, and royalty statements signed by the licensee and countersigned by the owner.
+import { jcsHash, verifySignedObject } from "@zanii/core";
+import { bodySignature, signersOf, withSignatures } from "./board.js";
+import { isDid, isInt, isIso, isObj, isSha, ms, SLUG, sortedUnique } from "./shared.js";
+import { signerDid, signWith } from "./signer.js";
+import { logPositionOk } from "./status.js";
+import { verifyLicenceOwnerHistory, verifyLicenceWithOwnerHistory } from "./licence-owner.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+const COUNTRY = /^[A-Z]{2}$/;
+const CURRENCY = /^[A-Z]{3}$/;
+const PROFILE_REF = new RegExp(`^${SLUG.source.slice(1, -1)}/[1-9][0-9]*$`);
+/** Section 1: the largest royalty per certificate, and section 4 the most certificates in one statement (their product stays a safe integer). */
+export const MAX_ROYALTY_MINOR = 1_000_000_000;
+export const MAX_STATEMENT_CERTIFICATES = 1_000_000;
+const sortedDistinct = (xs) => sortedUnique(xs).join("\n") === xs.join("\n");
+/** A scope list (licences, the body register): 1 to 256 `{profile, levels}`, sorted by profile, each once. */
+export function scopeError(s) {
+    if (!Array.isArray(s) || s.length < 1 || s.length > 256)
+        return "scope must list 1 to 256 profiles";
+    for (const e of s) {
+        if (!isObj(e) || Object.keys(e).length !== 2 || typeof e.profile !== "string" || !PROFILE_REF.test(e.profile))
+            return "each scope entry is {profile: <slug>/<version>, levels}";
+        const lv = e.levels;
+        if (!Array.isArray(lv) || lv.length < 1 || !lv.every((x) => isInt(x, 1, 3)) || lv.some((x, i) => i > 0 && !(x > lv[i - 1])))
+            return "scope levels must be sorted, distinct levels from 1 to 3";
+    }
+    if (!sortedDistinct(s.map((e) => e.profile)))
+        return "scope must be sorted by profile, each profile once";
+    return null;
+}
+/** Sorted by profile, each profile's levels sorted and distinct (the shape `scopeError` accepts). */
+export const normaliseScope = (scope) => Array.isArray(scope)
+    ? [...scope]
+        .map((e) => ({ profile: e?.profile, levels: Array.isArray(e?.levels) ? [...new Set(e.levels)].sort((a, b) => a - b) : e?.levels }))
+        .sort((a, b) => (a.profile < b.profile ? -1 : a.profile > b.profile ? 1 : 0))
+    : scope;
+function licenceError(l) {
+    if (!isDid(l.licensee))
+        return "licensee must be a did:key";
+    if (typeof l.legal_name !== "string" || l.legal_name.length < 1 || l.legal_name.length > 200)
+        return "legal_name must be 1 to 200 characters";
+    const c = l.countries;
+    if (!Array.isArray(c) || c.length < 1 || c.length > 250 || !c.every((x) => typeof x === "string" && COUNTRY.test(x)) || !sortedDistinct(c))
+        return "countries must be 1 to 250 sorted, distinct ISO 3166-1 alpha-2 codes";
+    const se = scopeError(l.scope);
+    if (se)
+        return se;
+    if (!isIso(l.valid_from) || !isIso(l.valid_until) || !(ms(l.valid_until) > ms(l.valid_from)))
+        return "valid_from and valid_until must be ISO timestamps, valid_until after valid_from";
+    const r = isObj(l.royalty) ? l.royalty : {};
+    if (!isObj(l.royalty) || Object.keys(r).length !== 2 || !isInt(r.per_certificate_minor, 0, MAX_ROYALTY_MINOR) || typeof r.currency !== "string" || !CURRENCY.test(r.currency))
+        return `royalty must be {per_certificate_minor: an integer from 0 to ${MAX_ROYALTY_MINOR}, currency: ISO 4217}`;
+    if (!isIso(l.issued_at))
+        return "issued_at must be an ISO timestamp";
+    return null;
+}
+/** Section 1: a licence, signed by the scheme owner (`signer`). */
+export async function buildLicence(f, signer) {
+    const scope = normaliseScope(f.scope);
+    const unsigned = {
+        v: 1,
+        type: "certify.licence",
+        licensee: f.licensee,
+        legal_name: f.legalName,
+        countries: Array.isArray(f.countries) ? sortedUnique(f.countries) : f.countries,
+        scope,
+        valid_from: f.validFrom,
+        valid_until: f.validUntil,
+        royalty: { per_certificate_minor: f.royalty?.per_certificate_minor, currency: f.royalty?.currency },
+        issued_at: f.issuedAt,
+    };
+    const err = licenceError(unsigned);
+    if (err)
+        throw new Error(err);
+    return signWith(unsigned, signer);
+}
+const isLicence = (l) => isObj(l) && l.v === 1 && l.type === "certify.licence" && Object.keys(l).length === 12;
+/** Section 1: signed, well formed and (with `owner`) signed by the scheme owner. */
+export function verifyLicence(doc, opts = {}) {
+    if (!isLicence(doc))
+        return { ok: false, reasons: ["not a licence (v1)"] };
+    const reasons = [];
+    if (!verifySignedObject(doc))
+        reasons.push("bad licence signature");
+    const err = licenceError(doc);
+    if (err)
+        reasons.push(`licence is malformed: ${err}`);
+    if (opts.owner === undefined)
+        reasons.push("no trusted scheme owner supplied: the licence signer was NOT checked");
+    else if (doc.signer !== opts.owner)
+        reasons.push("licence is not signed by the scheme owner");
+    return { ok: reasons.length === 0, reasons };
+}
+/** Section 3: is `issuer` the licensee, or a key the licensee's key was succeeded by in `lineage` (oldest first)? */
+export const licensedKey = (licensee, issuer, lineage = []) => licensee === issuer || (typeof licensee === "string" && typeof issuer === "string" && lineage.indexOf(licensee) >= 0 && lineage.indexOf(issuer) > lineage.indexOf(licensee));
+/**
+ * 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 function licenceCoverage(licence, cert, lineage = []) {
+    const claim = isObj(cert?.claim) ? cert.claim : {};
+    const applicant = isObj(claim.applicant) ? claim.applicant : {};
+    const reasons = [];
+    if (!licensedKey(licence.licensee, cert?.issuer, lineage))
+        reasons.push("licence is for another licensee than the certificate issuer");
+    const scope = (Array.isArray(licence.scope) ? licence.scope : []).find((e) => isObj(e) && e.profile === claim.profile);
+    if (!scope || !Array.isArray(scope.levels) || !scope.levels.includes(claim.level))
+        reasons.push(`licence does not cover profile ${String(claim.profile)} at level ${String(claim.level)}`);
+    if (!Array.isArray(licence.countries) || !licence.countries.includes(applicant.country))
+        reasons.push(`licence does not cover country ${String(applicant.country)}`);
+    const at = ms(cert?.issued_at);
+    if (!(ms(licence.valid_from) <= at && at <= ms(licence.valid_until)))
+        reasons.push("certificate was issued outside the licence's validity");
+    return reasons;
+}
+// ---------------------------------------------------------------- 2. licence status log
+export const LICENCE_ACTIONS = ["suspend", "reinstate", "withdraw"];
+export const LICENCE_REASONS = [
+    "ROYALTY_UNPAID",
+    "SCOPE_BREACH",
+    "MARK_MISUSE",
+    "AUDIT_FINDING",
+    "ACCREDITATION_LOST",
+    "LICENSEE_REQUEST",
+    "OTHER",
+];
+function statusError(s) {
+    if (!logPositionOk(s.seq, s.prev))
+        return "seq and prev are not a log position";
+    if (!isSha(s.licence))
+        return "licence must be a licence hash";
+    if (!LICENCE_ACTIONS.includes(s.action))
+        return "action must be suspend, reinstate or withdraw";
+    if (s.action === "reinstate" ? s.reason !== null : !LICENCE_REASONS.includes(s.reason))
+        return s.action === "reinstate" ? "reinstate takes no reason" : `${String(s.action)} needs a reason code`;
+    if (!isIso(s.at))
+        return "at must be an ISO timestamp";
+    if ("for_cause" in s || "effective_at" in s) {
+        if (s.for_cause !== true || !isIso(s.effective_at))
+            return "for_cause is true with an ISO effective_at";
+        if (s.action === "reinstate")
+            return "reinstate is never for cause";
+        if (!(ms(s.effective_at) <= ms(s.at)))
+            return "effective_at must not be after at";
+    }
+    return 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 async function buildLicenceStatus(f, signer) {
+    const unsigned = {
+        v: 1,
+        type: "certify.licence-status",
+        seq: f.seq,
+        prev: f.prev,
+        licence: f.licence,
+        action: f.action,
+        reason: f.reason,
+        at: f.at,
+        ...(f.effectiveAt !== undefined ? { for_cause: true, effective_at: f.effectiveAt } : {}),
+    };
+    const err = statusError(unsigned);
+    if (err)
+        throw new Error(err);
+    return signWith(unsigned, signer);
+}
+const NEXT = {
+    suspend: { from: ["active"], to: "suspended" },
+    reinstate: { from: ["suspended"], to: "active" },
+    withdraw: { from: ["active", "suspended"], to: "withdrawn" },
+};
+/**
+ * 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 function verifyLicenceLog(log, opts = {}) {
+    if (!Array.isArray(log) || log.length === 0)
+        return { ok: false, reasons: ["the licence status log is empty"] };
+    const reasons = [];
+    const state = new Map();
+    log.forEach((s, i) => {
+        const prev = i > 0 ? log[i - 1] : null;
+        if (!isObj(s) || s.v !== 1 || s.type !== "certify.licence-status" || Object.keys(s).length !== ("for_cause" in s || "effective_at" in s ? 12 : 10) || !verifySignedObject(s)) {
+            reasons.push(`entry ${i} is not a signed licence status entry`);
+            return;
+        }
+        const err = statusError(s);
+        if (err) {
+            reasons.push(`entry ${i} is malformed: ${err}`);
+            return;
+        }
+        if (s.seq !== i)
+            reasons.push(`entry ${i} is not at position ${i}`);
+        if (s.prev !== (i > 0 ? jcsHash(prev) : null))
+            reasons.push(`entry ${i} does not name the previous entry`);
+        if (i > 0 && isObj(log[0]) && s.signer !== log[0].signer)
+            reasons.push(`entry ${i} is signed by another key`);
+        if (i > 0 && isObj(prev) && !(ms(s.at) >= ms(prev.at)))
+            reasons.push(`entry ${i} is older than the previous entry`);
+        const now = state.get(s.licence) ?? "active";
+        const rule = NEXT[s.action];
+        if (!rule.from.includes(now))
+            reasons.push(`entry ${i} cannot ${String(s.action)} a licence that is ${now}`);
+        else
+            state.set(s.licence, rule.to);
+    });
+    const signer = isObj(log[0]) ? log[0].signer : undefined;
+    if (opts.owner === undefined)
+        reasons.push("no trusted scheme owner supplied: the licence status signer was NOT checked");
+    else if (signer !== opts.owner)
+        reasons.push("the licence status log is not signed by the scheme owner");
+    return { ok: reasons.length === 0, reasons };
+}
+/** Section 2: a licence's state at `at` from a verified log (changes at or before `at` apply). */
+export function licenceStateAt(log, licence, at) {
+    let state = "active";
+    for (const s of log)
+        if (s.licence === licence && ms(s.at) <= ms(at))
+            state = NEXT[s.action].to;
+    return state;
+}
+/** Section 3: the reasons a certificate is not covered by a licence that was valid when it was issued. */
+export function licenceReasons(cert, opts) {
+    if (opts.ownerHistory !== undefined && (!Array.isArray(opts.licences) || opts.licences.length > 50_000 || !withinVerificationBudget({ cert, licences: opts.licences, ownerHistory: opts.ownerHistory })))
+        return ["rotated-owner certificate evidence exceeds the JSON budget"];
+    const claim = isObj(cert?.claim) ? cert.claim : {};
+    if (!("licence" in claim))
+        return opts.ownIssuers?.includes(cert?.issuer) ? [] : ["certificate carries no licence"];
+    const licence = (Array.isArray(opts.licences) ? opts.licences : []).find((l) => isObj(l) && jcsHash(l) === claim.licence);
+    if (!isObj(licence))
+        return ["the certificate's licence was not supplied"];
+    const rotated = opts.ownerHistory === undefined ? null : verifyLicenceWithOwnerHistory(licence, { ...opts.ownerHistory, root: opts.owner });
+    const reasons = [...(rotated ?? verifyLicence(licence, { owner: opts.owner })).reasons, ...licenceCoverage(licence, cert, opts.lineage)];
+    if (opts.ownerHistory !== undefined) {
+        if (opts.log !== undefined)
+            reasons.push("choose ownerHistory or the legacy licence log, not both");
+        if (rotated?.ok) {
+            const log = opts.ownerHistory.log;
+            const state = licenceStateAt(log, claim.licence, String(cert.issued_at));
+            if (state !== "active")
+                reasons.push(`licence was ${state} when the certificate was issued`);
+            reasons.push(...forCauseReasons(cert, { ...opts, log }));
+        }
+        return reasons;
+    }
+    if (opts.log === undefined)
+        reasons.push("no licence status log supplied: licence suspension and withdrawal were NOT checked");
+    else {
+        const check = verifyLicenceLog(opts.log, { owner: opts.owner });
+        reasons.push(...check.reasons);
+        if (check.ok) {
+            const state = licenceStateAt(opts.log, claim.licence, String(cert.issued_at));
+            if (state !== "active")
+                reasons.push(`licence was ${state} when the certificate was issued`);
+            reasons.push(...forCauseReasons(cert, opts));
+        }
+    }
+    return reasons;
+}
+/**
+ * Section 2a: a for-cause entry on any licence of the certificate's issuer (the certificate's own
+ * licence and every supplied licence of the same licensee) refuses certificates issued from its
+ * `effective_at` until the licence is reinstated (for ever after a withdrawal). Needs a verified log.
+ */
+function forCauseReasons(cert, opts) {
+    const claim = isObj(cert?.claim) ? cert.claim : {};
+    const own = new Set([claim.licence]);
+    for (const l of Array.isArray(opts.licences) ? opts.licences : [])
+        if (isObj(l) && licensedKey(l.licensee, cert?.issuer, opts.lineage))
+            own.add(jcsHash(l));
+    const log = (opts.log ?? []);
+    const at = ms(cert?.issued_at);
+    const reasons = [];
+    log.forEach((e, i) => {
+        if (e.for_cause !== true || !own.has(e.licence))
+            return;
+        const back = log.slice(i + 1).find((x) => x.licence === e.licence && x.action === "reinstate");
+        if (ms(e.effective_at) <= at && (!back || at < ms(back.at)))
+            reasons.push(`licence was ${e.action === "withdraw" ? "withdrawn" : "suspended"} for cause from ${e.effective_at}, before the certificate was issued`);
+    });
+    return reasons;
+}
+/** Section 4: `jcsHash({items})` of the sorted, distinct certificate hashes. */
+export const certificateListHash = (certificates) => jcsHash({ items: sortedUnique(certificates) });
+function statementError(s) {
+    if (!isSha(s.licence))
+        return "licence must be a licence hash";
+    if (!isDid(s.licensee))
+        return "licensee must be a did:key";
+    const p = isObj(s.period) ? s.period : {};
+    if (!isObj(s.period) || Object.keys(p).length !== 2 || !isIso(p.from) || !isIso(p.until) || !(ms(p.until) > ms(p.from)))
+        return "period must be {from, until}, ISO timestamps, until after from";
+    if (!isInt(s.certificates, 0, MAX_STATEMENT_CERTIFICATES))
+        return `certificates must be an integer from 0 to ${MAX_STATEMENT_CERTIFICATES}`;
+    if (!isSha(s.certificates_sha256))
+        return "certificates_sha256 must be a sha256 hash";
+    if (!isInt(s.amount_minor, 0, Number.MAX_SAFE_INTEGER))
+        return "amount_minor must be a non-negative integer";
+    if (typeof s.currency !== "string" || !CURRENCY.test(s.currency))
+        return "currency must be an ISO 4217 code";
+    if (!isIso(s.issued_at))
+        return "issued_at must be an ISO timestamp";
+    return null;
+}
+/** Section 4: the statement signed by the licensee (`signer`, the licence's licensee key). */
+export async function buildRoyaltyStatement(f, signer) {
+    const l = f.licence;
+    if (!isLicence(l) || licenceError(l))
+        throw new Error("licence is not a licence (v1)");
+    if (signerDid(signer) !== l.licensee)
+        throw new Error("a royalty statement is signed by the licence's licensee");
+    if (!Array.isArray(f.certificates) || !f.certificates.every(isSha))
+        throw new Error("certificates must be certificate hashes");
+    const certs = sortedUnique(f.certificates);
+    const body = {
+        v: 1,
+        type: "certify.royalty-statement",
+        licence: jcsHash(l),
+        licensee: l.licensee,
+        period: { from: f.period?.from, until: f.period?.until },
+        certificates: certs.length,
+        certificates_sha256: certificateListHash(certs),
+        amount_minor: certs.length * l.royalty.per_certificate_minor,
+        currency: l.royalty.currency,
+        issued_at: f.issuedAt,
+    };
+    const err = statementError(body);
+    if (err)
+        throw new Error(err);
+    return withSignatures(body, [await bodySignature(body, signer)]);
+}
+/** Section 4: the scheme owner's countersignature, added beside the licensee's. */
+export async function countersignRoyaltyStatement(statement, signer) {
+    const { signatures, ...body } = statement;
+    if (!Array.isArray(signatures))
+        throw new Error("not a royalty statement (v1)");
+    return withSignatures(body, [...signatures, await bodySignature(body, signer)]);
+}
+/**
+ * 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 function verifyRoyaltyStatement(doc, opts = {}) {
+    let authorityOwner = opts.owner;
+    const authorityReasons = [];
+    if (opts.ownerHistory !== undefined) {
+        if (!withinVerificationBudget({ doc, opts }) || !isObj(opts.ownerHistory) || Object.keys(opts).some(k => !["owner", "licence", "certificates", "ownerHistory"].includes(k)))
+            return { ok: false, reasons: ["invalid rotated-owner royalty policy or evidence bounds"] };
+        const history = verifyLicenceOwnerHistory(opts.ownerHistory.log, { root: opts.owner, checkpoint: opts.ownerHistory.checkpoint });
+        if (!history.ok)
+            return { ok: false, reasons: history.reasons };
+        authorityReasons.push(...verifyLicenceWithOwnerHistory(opts.licence, { root: opts.owner, ...opts.ownerHistory }).reasons);
+        authorityOwner = history.currentOwner;
+    }
+    const s = isObj(doc) ? doc : {};
+    if (s.v !== 1 || s.type !== "certify.royalty-statement" || Object.keys(s).length !== 11)
+        return { ok: false, reasons: ["not a royalty statement (v1)"] };
+    const reasons = [...authorityReasons];
+    const err = statementError(s);
+    if (err)
+        reasons.push(`royalty statement is malformed: ${err}`);
+    const sig = signersOf(s);
+    if (!sig.wellFormed)
+        reasons.push("royalty statement carries a signature that is malformed or invalid");
+    if (!sig.signers.includes(s.licensee))
+        reasons.push("royalty statement is not signed by its licensee");
+    if (authorityOwner === undefined)
+        reasons.push("no trusted scheme owner supplied: the countersignature was NOT checked");
+    else {
+        if (!sig.signers.includes(authorityOwner))
+            reasons.push("royalty statement is not countersigned by the scheme owner");
+        if (sig.signers.some((d) => d !== s.licensee && d !== authorityOwner))
+            reasons.push("royalty statement carries a signature by neither the licensee nor the scheme owner");
+    }
+    if (opts.licence === undefined)
+        reasons.push("no licence supplied: the royalty amount was NOT checked");
+    else {
+        const l = isObj(opts.licence) ? opts.licence : {};
+        const r = isObj(l.royalty) ? l.royalty : {};
+        if (jcsHash(opts.licence) !== s.licence)
+            reasons.push("royalty statement is for another licence");
+        else if (l.licensee !== s.licensee)
+            reasons.push("royalty statement licensee is not the licence's");
+        else if (r.currency !== s.currency || !isInt(r.per_certificate_minor, 0, MAX_ROYALTY_MINOR) || !isInt(s.certificates, 0, MAX_STATEMENT_CERTIFICATES) ||
+            s.certificates * r.per_certificate_minor !== s.amount_minor)
+            reasons.push("royalty amount is not the certificate count times the licence royalty");
+    }
+    if (opts.certificates !== undefined) {
+        const certs = sortedUnique(opts.certificates);
+        if (certs.length !== s.certificates || certificateListHash(certs) !== s.certificates_sha256)
+            reasons.push("royalty statement certificates are not the supplied certificates");
+    }
+    return { ok: reasons.length === 0, reasons };
+}

package/dist/live-evidence.d.ts

@@ -0,0 +1,135 @@
+import { type Credential } from "@zanii/credentials";
+import { type Signer } from "./signer.ts";
+import { type AssuranceStatusPolicy } from "./assurance-status.ts";
+export interface LiveEvidence {
+    v: 1;
+    type: "certify.live-evidence";
+    certificate: string;
+    agent: string;
+    window: {
+        from: string;
+        to: string;
+    };
+    /** Blackbox sessions of the agent in the window. */
+    sessions: number;
+    /** Guard decisions with verdict `block` (spec guard.md section 8 of Blackbox). */
+    guard_blocks: number;
+    /** Summed Blackbox summary `claims`: `failed` is a claim contradicted by the reference. */
+    claims: {
+        satisfied: number;
+        failed: number;
+        unverified: number;
+    };
+    budget_breaches: number;
+    /** Summed Blackbox summary `findings` by severity. */
+    findings: {
+        advisory: number;
+        caution: number;
+        warning: number;
+    };
+    /** Incidents in the window: `serious` as the occurrence frameworks define it, `minor` the rest. */
+    incidents: {
+        serious: number;
+        minor: number;
+    };
+    near_misses: number;
+    /** Sorted, distinct Blackbox configuration ids the gateway saw (fingerprint.configuration). */
+    configurations: string[];
+    issued_at: string;
+    signed: {
+        by: string;
+        sig: string;
+    };
+}
+export type LiveEvidenceInput = Omit<LiveEvidence, "v" | "type" | "issued_at" | "signed" | "configurations"> & {
+    configurations: readonly string[];
+    issuedAt: string;
+};
+/** Sign live evidence as the deployer's Blackbox gateway (`signer` holds the gateway key). */
+export declare function buildLiveEvidence(fields: LiveEvidenceInput, signer: Signer): Promise<LiveEvidence>;
+/** Section 4: the platform attestation the lab verified for the gateway (e.g. an AWS Nitro Enclaves quote). */
+export interface GatewayAttestation {
+    platform: string;
+    /** sha256 of the attestation document the lab verified. */
+    document: string;
+    verified_at: string;
+}
+export interface GatewayEnrolment {
+    v: 1;
+    type: "certify.gateway-enrolment";
+    certificate: string;
+    gateway: string;
+    attestation: GatewayAttestation | null;
+    issued_at: string;
+    valid_until: string;
+    signer: string;
+    sig: string;
+}
+export interface GatewayEnrolmentInput {
+    certificate: string;
+    gateway: string;
+    attestation?: GatewayAttestation | null;
+    issuedAt: string;
+    validUntil: string;
+}
+/** Section 4: the lab enrols the deployer's gateway key for one certificate (`signer` is the lab key). */
+export declare function buildGatewayEnrolment(f: GatewayEnrolmentInput, signer: Signer): Promise<GatewayEnrolment>;
+/** Section 4: signed by a trusted lab (`labs`), well formed and (with `at`) in force at that time. */
+export declare function verifyGatewayEnrolment(doc: unknown, opts?: {
+    labs?: readonly string[];
+    at?: string;
+}): {
+    ok: boolean;
+    reasons: string[];
+};
+export interface LiveEvidenceVerifyOptions {
+    gateway?: string;
+    certificate?: Credential;
+    now?: string;
+    /** Section 4: accept the evidence only from a gateway the lab enrolled for its certificate. */
+    requireEnrolment?: boolean;
+    /** Section 4: the gateway's enrolment; its gateway is the expected signer when `gateway` is not given. */
+    enrolment?: unknown;
+    /** Section 4: the lab DIDs whose enrolments this verifier trusts. */
+    labs?: readonly string[];
+    /** Fresh authority status plus the last durably accepted report timestamp. */
+    gatewayStatus?: AssuranceStatusPolicy & {
+        after: string;
+        maxEvidenceAgeSeconds: number;
+    };
+}
+/** Pure acceptance gate; persist a new report watermark atomically with the accepted report. */
+export declare function liveEvidenceFreshnessReasons(evidence: unknown, opts: {
+    after: string;
+    now: string;
+    maxEvidenceAgeSeconds: number;
+}): string[];
+/**
+ * Verify live evidence: Blackbox signed form by `gateway` (the deployer's registered gateway
+ * DID), well formed, not from the future, and (with `certificate`) for that certificate and holder.
+ * With `enrolment` or `requireEnrolment` (section 4), also an enrolment of the signing gateway for
+ * the evidence's certificate in force at its `issued_at`; `attested` says whether that gateway is.
+ */
+export declare function verifyLiveEvidence(evidence: unknown, opts?: LiveEvidenceVerifyOptions): {
+    ok: boolean;
+    reasons: string[];
+    attested?: boolean;
+};
+export declare const LIVE_TRIGGERS: readonly ["SERIOUS_INCIDENT", "GUARD_BLOCKS", "CONTRADICTED_CLAIMS", "BUDGET_BREACHES", "CONFIGURATION_CHANGED"];
+export type LiveTrigger = (typeof LIVE_TRIGGERS)[number];
+export interface LiveThresholds {
+    /** Guard blocks per session, in ppm, above which a re-test is due. */
+    max_guard_block_ppm: number;
+    /** Contradicted claims per checked claim (satisfied + failed), in ppm. */
+    max_contradicted_claim_ppm: number;
+    max_budget_breaches: number;
+}
+/** Section 3: used for every threshold a profile's `live_evidence` does not set. */
+export declare const LIVE_DEFAULTS: LiveThresholds;
+/**
+ * Section 3: the re-test reasons in verified live evidence, in LIVE_TRIGGERS order; empty when none.
+ * Integer comparisons only (`a * 1e6 > max * b` rather than a division).
+ */
+export declare function liveEvidenceTriggers(evidence: LiveEvidence, profile: {
+    live_evidence?: Partial<LiveThresholds>;
+}, certificate?: Credential): LiveTrigger[];