@zanii/certify 0.0.0-stage → 0.5.0

package/dist/appliance.js

@@ -0,0 +1,253 @@
+// spec/appliance.md: the self-hosted lab appliance. The central lab enrols an appliance key; the
+// appliance exports a run as a signed bundle with its platform attestation, the evidence chain
+// heads and the transcripts sealed to the central lab (@zanii/pq X25519 + ML-KEM-768); offline
+// update bundles are signed by the lab release key.
+import { verifyAttestation } from "@zanii/attest";
+import { canonicalBytes, jcsHash, verifySignedObject } from "@zanii/core";
+import { hybridOpen, hybridSeal } from "@zanii/pq";
+import { MAX_SKEW_SECONDS } from "./beacon.js";
+import { isText } from "./board.js";
+import { buildApplianceExportBundle, bundleHash } from "./bundle.js";
+import { sha256Bytes } from "./fingerprint.js";
+import { isDid, isInt, isIso, isObj, isSha, ms, sortedUnique } from "./shared.js";
+import { signerDid, signWith } from "./signer.js";
+const COUNTRY = /^[A-Z]{2}$/;
+const PLATFORM = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const MEASUREMENT = /^[A-Za-z0-9:._+/=-]{1,256}$/;
+const CHAIN = /^[A-Za-z0-9._:-]{1,128}$/;
+const HEX = /^[0-9a-f]+$/;
+const VERSION = /^(0|[1-9][0-9]{0,3})\.(0|[1-9][0-9]{0,3})\.(0|[1-9][0-9]{0,3})$/;
+function enrolmentError(e) {
+    const c = isObj(e.customer) ? e.customer : {};
+    if (!isDid(e.appliance))
+        return "appliance must be a did:key";
+    if (!isObj(e.customer) || Object.keys(c).length !== 2 || typeof c.name !== "string" || c.name.length < 1 || c.name.length > 200 || typeof c.country !== "string" || !COUNTRY.test(c.country))
+        return "customer needs a name (1-200) and an ISO 3166-1 alpha-2 country";
+    const m = e.measurements;
+    if (!Array.isArray(m) || m.length < 1 || m.length > 32 || !m.every((x) => typeof x === "string" && MEASUREMENT.test(x)) || sortedUnique(m).join("\n") !== m.join("\n"))
+        return "measurements must be 1 to 32 sorted, distinct measurements";
+    if (!isIso(e.enrolled_at) || !isIso(e.valid_until) || !(ms(e.valid_until) > ms(e.enrolled_at)))
+        return "enrolled_at and valid_until must be ISO timestamps, valid_until after enrolled_at";
+    return null;
+}
+/** Section 1: the central lab enrols an appliance key and the code measurements it may run. */
+export async function buildApplianceEnrolment(f, signer) {
+    const unsigned = {
+        v: 1,
+        type: "certify.appliance-enrolment",
+        appliance: f.appliance,
+        customer: { name: f.customer?.name, country: f.customer?.country },
+        measurements: Array.isArray(f.measurements) ? sortedUnique(f.measurements) : f.measurements,
+        enrolled_at: f.enrolledAt,
+        valid_until: f.validUntil,
+    };
+    const err = enrolmentError(unsigned);
+    if (err)
+        throw new Error(err);
+    return signWith(unsigned, signer);
+}
+/** Section 2: the hash of the central lab's public key, `{x25519, mlkem}` hex. */
+export const labKeyId = (key) => jcsHash({ x25519: key.x25519, mlkem: key.mlkem });
+/** Section 2: seal the transcripts (any JSON value) to the central lab: its canonical bytes, hybrid sealed. */
+export function sealTranscripts(transcripts, labKey) {
+    return { recipient: labKeyId(labKey), sealed: hybridSeal(canonicalBytes(transcripts), labKey) };
+}
+/** Section 2: the report data the appliance's attestation quote binds. */
+export const applianceChallenge = (f) => jcsHash({ v: 1, type: "certify.appliance-challenge", appliance: f.appliance, bundle: f.bundle, evidence: f.evidence, transcripts: jcsHash(f.transcripts), exported_at: f.exportedAt });
+const sealedOk = (t) => {
+    if (!isObj(t) || Object.keys(t).length !== 2 || !isSha(t.recipient) || !isObj(t.sealed))
+        return false;
+    const s = t.sealed;
+    const hex = (v, n) => typeof v === "string" && HEX.test(v) && (n === undefined || v.length === n);
+    return Object.keys(s).length === 7 && s.v === 1 && s.kem === "x25519+mlkem768" && hex(s.ephemeral, 64) && hex(s.mlkemCipherText, 2176) && hex(s.iv, 24) && hex(s.tag, 32) && (s.ct === "" || hex(s.ct));
+};
+const headOk = (h) => isObj(h) && Object.keys(h).length === 3 && typeof h.chain === "string" && CHAIN.test(h.chain) && isSha(h.head) && isInt(h.size, 1, Number.MAX_SAFE_INTEGER);
+function exportError(x) {
+    if (!isObj(x.bundle) || ![1, 2].includes(x.bundle.v) || x.bundle.type !== "certify.result-bundle")
+        return "bundle must be a result bundle";
+    const e = x.evidence;
+    if (!Array.isArray(e) || e.length > 10_000 || !e.every(headOk) || e.some((h, i) => i > 0 && !(h.chain > e[i - 1].chain)))
+        return "evidence must be sorted, distinct {chain, head, size}";
+    if (!sealedOk(x.transcripts))
+        return "transcripts must be {recipient, sealed} sealed with x25519+mlkem768";
+    if (x.bundle.v === 2) {
+        const b = x.bundle;
+        if (Object.keys(b).length !== 15 || b.phase !== "undecided" || !isObj(b.staff) || Object.keys(b.staff).length !== 3 || b.staff.reviewer !== null || b.staff.decider !== null)
+            return "appliance bundle must be explicitly undecided (v2)";
+        try {
+            const input = b;
+            const rebuilt = buildApplianceExportBundle({ scheme: input.scheme, profile: input.profile, level: input.level, fingerprint: input.fingerprint, plan: input.plan, results: input.results, evidence: input.evidence, suite_snapshot: input.suite_snapshot, testers: input.staff.testers, execution: input.execution, started_at: input.started_at, ended_at: input.ended_at });
+            if (jcsHash(rebuilt) !== jcsHash(b))
+                return "appliance bundle fields or scores are not canonical (v2)";
+            const identity = rebuilt.execution, heads = new Map(e.map(head => [head.chain, head.head]));
+            if (identity.appliance !== x.appliance || identity.recipient !== x.transcripts.recipient || !heads.has(identity.source_run) || heads.size !== rebuilt.evidence.length + 1 || rebuilt.evidence.some(head => heads.get(`${identity.source_run}:${head.case_id}`) !== head.chain_head))
+                return "appliance bundle execution identity does not bind this export";
+        }
+        catch {
+            return "appliance bundle is malformed (v2)";
+        }
+    }
+    if (!isIso(x.exported_at))
+        return "exported_at must be an ISO timestamp";
+    return null;
+}
+function attestationOk(a, x) {
+    if (!isObj(a) || Object.keys(a).length !== 6 || a.v !== 1)
+        return false;
+    const challenge = applianceChallenge({
+        appliance: String(x.appliance),
+        bundle: bundleHash(x.bundle),
+        evidence: x.evidence,
+        transcripts: x.transcripts,
+        exportedAt: String(x.exported_at),
+    });
+    return (typeof a.platform === "string" && PLATFORM.test(a.platform) &&
+        typeof a.measurement === "string" && MEASUREMENT.test(a.measurement) &&
+        isSha(a.quote_hash) && a.nonce === challenge && isIso(a.attested_at) &&
+        Math.abs(ms(a.attested_at) - ms(x.exported_at)) <= MAX_SKEW_SECONDS * 1000);
+}
+/** Section 2: the export, signed by the appliance key (`signer`, the enrolled appliance). */
+export async function buildApplianceExport(f, signer) {
+    const appliance = signerDid(signer);
+    if (!isObj(f.enrolment) || f.enrolment.appliance !== appliance)
+        throw new Error("the enrolment is for another appliance");
+    const unsigned = {
+        v: 1,
+        type: "certify.appliance-export",
+        appliance,
+        enrolment: f.enrolment,
+        attestation: f.attestation,
+        bundle: f.bundle,
+        evidence: Array.isArray(f.evidence)
+            ? f.evidence.map((h) => ({ chain: h?.chain, head: h?.head, size: h?.size })).sort((a, b) => (a.chain < b.chain ? -1 : a.chain > b.chain ? 1 : 0))
+            : f.evidence,
+        transcripts: f.transcripts,
+        exported_at: f.exportedAt,
+    };
+    const err = exportError(unsigned);
+    if (err)
+        throw new Error(err);
+    if (!attestationOk(unsigned.attestation, unsigned))
+        throw new Error("attestation is malformed or does not bind this export's applianceChallenge");
+    return signWith(unsigned, signer);
+}
+/**
+ * Section 3: signed by its appliance, enrolled by a trusted central lab (`labs`) for the time of
+ * export, attested for this export with an enrolled measurement, sealed to `labKey` when given, and
+ * (with `verifyQuote`) the attestation quote verified by the injected platform verifier.
+ */
+export async function verifyApplianceExport(doc, opts = {}) {
+    const x = isObj(doc) ? doc : {};
+    if (x.v !== 1 || x.type !== "certify.appliance-export" || Object.keys(x).length !== 11 || !isDid(x.appliance))
+        return { ok: false, reasons: ["not an appliance export (v1)"], attested: null };
+    const reasons = [];
+    if (!verifySignedObject(x) || x.signer !== x.appliance)
+        reasons.push("bad appliance export signature");
+    const err = exportError(x);
+    if (err)
+        return { ok: false, reasons: [...reasons, `appliance export is malformed: ${err}`], attested: null };
+    const e = isObj(x.enrolment) ? x.enrolment : {};
+    if (e.v !== 1 || e.type !== "certify.appliance-enrolment" || Object.keys(e).length !== 9 || !verifySignedObject(e) || enrolmentError(e))
+        reasons.push("the enrolment is not a signed appliance enrolment");
+    else {
+        if (e.appliance !== x.appliance)
+            reasons.push("the enrolment is for another appliance");
+        if (!opts.labs)
+            reasons.push("no trusted central lab supplied: the enrolment was NOT checked");
+        else if (!opts.labs.includes(e.signer))
+            reasons.push("the enrolment is not signed by a trusted central lab");
+        if (!(ms(e.enrolled_at) <= ms(x.exported_at) && ms(x.exported_at) <= ms(e.valid_until)))
+            reasons.push("the export is outside the appliance's enrolment");
+    }
+    const a = x.attestation;
+    const bound = attestationOk(a, x);
+    if (!bound)
+        reasons.push("appliance attestation is malformed or does not bind the export");
+    else if (!Array.isArray(e.measurements) || !e.measurements.includes(a.measurement))
+        reasons.push("appliance attestation measurement is not an enrolled measurement");
+    if (opts.labKey !== undefined && x.transcripts.recipient !== labKeyId(opts.labKey))
+        reasons.push("transcripts are not sealed to this lab key");
+    const now = opts.now ? ms(opts.now) : Date.now();
+    if (ms(x.exported_at) > now + MAX_SKEW_SECONDS * 1000)
+        reasons.push("appliance export exported_at is in the future");
+    let attested = null;
+    if (!bound)
+        attested = null;
+    else if (!opts.verifyQuote)
+        reasons.push("no quote verifier supplied: the appliance attestation was NOT verified");
+    else {
+        const q = a;
+        const r = await verifyAttestation({ v: 1, platform: q.platform, measurement: q.measurement, quoteHash: q.quote_hash, nonce: q.nonce, attestedAt: q.attested_at }, { verifyQuote: opts.verifyQuote });
+        attested = r.quoteVerified === true;
+        if (!attested)
+            reasons.push("appliance attestation quote verification failed");
+    }
+    return { ok: reasons.length === 0, reasons, attested };
+}
+/** Section 4: the central lab opens the transcripts with its secret key; throws on a wrong key or tampering. */
+export function openApplianceExport(doc, secretKey) {
+    if (!isObj(doc) || !sealedOk(doc.transcripts))
+        throw new Error("not an appliance export (v1)");
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(hybridOpen(doc.transcripts.sealed, secretKey)));
+}
+function updateError(u) {
+    if (typeof u.version !== "string" || !VERSION.test(u.version))
+        return "version must be <major>.<minor>.<patch>";
+    if (!isSha(u.sha256))
+        return "sha256 must be the update file hash";
+    if (!isSha(u.enrolment))
+        return "enrolment must be the hash of the enrolment of the appliance the update is for";
+    if (!isIso(u.released_at))
+        return "released_at must be an ISO timestamp";
+    if (!isText(u.notes))
+        return "notes need en and ar text (1-4000)";
+    return null;
+}
+/** Section 5: an offline update bundle's manifest for one enrolled appliance (`enrolment`, the jcsHash of its enrolment), signed by the lab release key. */
+export async function buildApplianceUpdate(f, signer) {
+    const unsigned = {
+        v: 1, type: "certify.appliance-update", version: f.version, sha256: f.sha256, enrolment: f.enrolment,
+        released_at: f.releasedAt, notes: { en: f.notes?.en, ar: f.notes?.ar },
+    };
+    const err = updateError(unsigned);
+    if (err)
+        throw new Error(err);
+    return signWith(unsigned, signer);
+}
+const versionParts = (v) => v.split(".").map(Number);
+const newer = (a, b) => {
+    const [x, y] = [versionParts(a), versionParts(b)];
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return x[i] > y[i];
+    return false;
+};
+/** Section 5: signed by a trusted release key (`keys`), for `content` when given, for the appliance whose enrolment hash is `enrolment`, and newer than `installed` when given. */
+export function verifyApplianceUpdate(doc, opts = {}) {
+    const u = isObj(doc) ? doc : {};
+    if (u.v !== 1 || u.type !== "certify.appliance-update" || Object.keys(u).length !== 9)
+        return { ok: false, reasons: ["not an appliance update (v1)"] };
+    const reasons = [];
+    if (!verifySignedObject(u))
+        reasons.push("bad appliance update signature");
+    const err = updateError(u);
+    if (err)
+        reasons.push(`appliance update is malformed: ${err}`);
+    if (!opts.keys)
+        reasons.push("no trusted release keys supplied: the signer was NOT checked");
+    else if (!opts.keys.includes(u.signer))
+        reasons.push("appliance update is not signed by a trusted release key");
+    if (opts.content !== undefined && sha256Bytes(opts.content) !== u.sha256)
+        reasons.push("the update content is not the signed content");
+    if (opts.enrolment === undefined)
+        reasons.push("no enrolment supplied: the appliance the update is for was NOT checked");
+    else if (u.enrolment !== opts.enrolment)
+        reasons.push("appliance update is for another appliance's enrolment");
+    if (opts.installed !== undefined) {
+        if (!VERSION.test(opts.installed))
+            throw new Error("installed must be <major>.<minor>.<patch>");
+        if (err || !newer(u.version, opts.installed))
+            reasons.push("appliance update is not newer than the installed version");
+    }
+    return { ok: reasons.length === 0, reasons };
+}

package/dist/assurance-status.d.ts

@@ -0,0 +1,58 @@
+import { type Signer } from "./signer.ts";
+export type AssurancePurpose = "gateway-enrolment" | "agent-binding";
+interface AssuranceRef {
+    purpose: AssurancePurpose;
+    subject: string;
+    principal: string;
+    context: string;
+}
+export interface AssuranceRevocation extends AssuranceRef {
+    v: 1;
+    type: "certify.assurance-revocation";
+    reason: string;
+    revoked_at: string;
+    issued_at: string;
+    signer: string;
+    sig: string;
+}
+export interface AssuranceStatus extends AssuranceRef {
+    v: 1;
+    type: "certify.assurance-status";
+    epoch: number;
+    status: "active" | "revoked";
+    revocation: string | null;
+    issued_at: string;
+    valid_until: string;
+    signer: string;
+    sig: string;
+}
+export interface AssuranceAuthority {
+    owner: string;
+    domain: string;
+    document: unknown;
+}
+export interface AssuranceStatusPolicy {
+    document: unknown;
+    signers: readonly string[];
+    minEpoch: number;
+    maxAgeSeconds: number;
+    revocation?: unknown;
+    authority?: AssuranceAuthority;
+}
+export interface AssuranceStatusOptions {
+    purpose: AssurancePurpose;
+    artifact: unknown;
+    signers: readonly string[];
+    now: string;
+    minEpoch: number;
+    maxAgeSeconds: number;
+    revocation?: unknown;
+    authority?: AssuranceAuthority;
+}
+export declare function buildAssuranceRevocation(fields: Omit<AssuranceRevocation, "v" | "type" | "signer" | "sig">, signer: Signer): Promise<AssuranceRevocation>;
+export declare function buildAssuranceStatus(fields: Omit<AssuranceStatus, "v" | "type" | "signer" | "sig">, signer: Signer): Promise<AssuranceStatus>;
+export declare function verifyAssuranceStatus(document: unknown, opts: AssuranceStatusOptions): {
+    ok: boolean;
+    reasons: string[];
+};
+export {};

package/dist/assurance-status.js

@@ -0,0 +1,86 @@
+// Fresh, purpose-bound status for immutable enrolments/bindings; callers retain epoch/revocation watermarks.
+import { jcsHash, publicKeyFromDid } from "@zanii/core";
+import { issuerArtifactAuthorization } from "./issuer-authorization.js";
+import { isInt, isIso, isObj, isSha, ms } from "./shared.js";
+import { signatureOk, signerDid, signWith } from "./signer.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+const keys = (v, names) => isObj(v) && Object.keys(v).length === names.split(" ").length && names.split(" ").every((k) => Object.hasOwn(v, k));
+const did = (v) => typeof v === "string" && v.length <= 69 && publicKeyFromDid(v) !== null;
+const hash = (v) => isSha(v) && v.length === 71;
+const ref = (v) => (v.purpose === "gateway-enrolment" || v.purpose === "agent-binding") && hash(v.subject) && did(v.principal) && hash(v.context);
+const signed = (v, type) => v.v === 1 && v.type === type && did(v.signer) && typeof v.sig === "string" && v.sig.length === 136 && /^ed25519:[0-9a-f]{128}$/.test(v.sig);
+const revocationShape = (v) => keys(v, "v type purpose subject principal context reason revoked_at issued_at signer sig") && signed(v, "certify.assurance-revocation") && ref(v)
+    && typeof v.reason === "string" && v.reason.length <= 64 && /^[A-Z][A-Z0-9_]*$/.test(v.reason) && v.reason.trim() === v.reason && isIso(v.revoked_at) && isIso(v.issued_at) && ms(v.revoked_at) <= ms(v.issued_at);
+const statusShape = (v) => keys(v, "v type purpose subject principal context epoch status revocation issued_at valid_until signer sig") && signed(v, "certify.assurance-status") && ref(v)
+    && isInt(v.epoch, 1, Number.MAX_SAFE_INTEGER) && (v.status === "active" ? v.revocation === null : v.status === "revoked" && hash(v.revocation))
+    && isIso(v.issued_at) && isIso(v.valid_until) && ms(v.valid_until) > ms(v.issued_at) && ms(v.valid_until) - ms(v.issued_at) <= 300_000;
+const small = (v) => withinVerificationBudget(v, { maxBytes: 16_384, maxNodes: 200, maxDepth: 8 });
+const validSignature = (doc) => { const { sig, ...unsigned } = doc; return signatureOk(unsigned, sig, doc.signer); };
+const placeholder = `ed25519:${"0".repeat(128)}`;
+export async function buildAssuranceRevocation(fields, signer) {
+    if (!isObj(fields) || !small(fields) || ["v", "type", "signer", "sig"].some((k) => Object.hasOwn(fields, k)))
+        throw new Error("invalid assurance revocation input");
+    const doc = { ...fields, v: 1, type: "certify.assurance-revocation", signer: signerDid(signer), sig: placeholder };
+    if (!revocationShape(doc))
+        throw new Error("invalid assurance revocation v1");
+    const { sig: _, signer: __, ...unsigned } = doc;
+    return signWith(unsigned, signer);
+}
+export async function buildAssuranceStatus(fields, signer) {
+    if (!isObj(fields) || !small(fields) || ["v", "type", "signer", "sig"].some((k) => Object.hasOwn(fields, k)))
+        throw new Error("invalid assurance status input");
+    const doc = { ...fields, v: 1, type: "certify.assurance-status", signer: signerDid(signer), sig: placeholder };
+    if (!statusShape(doc))
+        throw new Error("invalid assurance status v1");
+    const { sig: _, signer: __, ...unsigned } = doc;
+    return signWith(unsigned, signer);
+}
+function artifactRef(artifact, purpose) {
+    const names = purpose === "gateway-enrolment" ? "v type certificate gateway attestation issued_at valid_until signer sig" : "v type applicant legal_name domain kyb agent bound_at valid_until signer sig";
+    if (!small(artifact) || !keys(artifact, names) || artifact.v !== 1 || artifact.type !== `certify.${purpose}`
+        || !did(artifact.signer) || !isIso(artifact.valid_until) || typeof artifact.sig !== "string" || artifact.sig.length !== 136 || !validSignature(artifact))
+        return null;
+    const principal = purpose === "gateway-enrolment" ? artifact.gateway : artifact.agent, context = purpose === "gateway-enrolment" ? artifact.certificate : artifact.kyb;
+    const at = purpose === "gateway-enrolment" ? artifact.issued_at : artifact.bound_at;
+    if (!did(principal) || !hash(context) || !isIso(at))
+        return null;
+    return { purpose, subject: jcsHash(artifact), principal, context, signer: artifact.signer, issued_at: at, valid_until: artifact.valid_until };
+}
+const sameRef = (doc, expected) => doc.purpose === expected.purpose && doc.subject === expected.subject && doc.principal === expected.principal && doc.context === expected.context;
+function historicalAuthority(signer, issued_at, current, authority, at) {
+    if (!authority)
+        return signer === current ? [] : ["historical assurance signer needs authorized issuer lineage"];
+    return issuerArtifactAuthorization({ signer, issued_at }, current, authority.document, authority.owner, authority.domain, at);
+}
+export function verifyAssuranceStatus(document, opts) {
+    const denied = (reason) => ({ ok: false, reasons: [reason] });
+    if (!isObj(opts) || (opts.purpose !== "gateway-enrolment" && opts.purpose !== "agent-binding") || !small(document) || !withinVerificationBudget({ artifact: opts.artifact, authority: opts.authority ?? null, revocation: opts.revocation ?? null }, { maxBytes: 4_194_304 })
+        || !Array.isArray(opts.signers) || opts.signers.length < 1 || opts.signers.length > 64 || !Array.from(opts.signers).every(did) || !isIso(opts.now)
+        || !isInt(opts.minEpoch, 1, Number.MAX_SAFE_INTEGER) || !isInt(opts.maxAgeSeconds, 1, 300))
+        return denied("independent assurance pins, epoch, time and bounded evidence are required");
+    const expected = artifactRef(opts.artifact, opts.purpose);
+    if (!expected || !statusShape(document) || !sameRef(document, expected))
+        return denied("assurance status does not match the expected artifact and purpose");
+    const reasons = [];
+    if (!opts.signers.includes(document.signer) || !validSignature(document))
+        reasons.push("assurance status is not signed by a trusted current authority");
+    if (document.epoch < opts.minEpoch)
+        reasons.push("assurance status epoch is older than the retained watermark");
+    if (ms(document.issued_at) > ms(opts.now) || ms(document.valid_until) <= ms(opts.now) || ms(opts.now) - ms(document.issued_at) >= opts.maxAgeSeconds * 1000)
+        reasons.push("assurance status is stale or from the future");
+    if (ms(document.issued_at) < ms(expected.issued_at) || ms(expected.valid_until) <= ms(opts.now))
+        reasons.push("assurance artifact is not in force at the reference time");
+    reasons.push(...historicalAuthority(expected.signer, expected.issued_at, document.signer, opts.authority, document.issued_at));
+    const revocation = opts.revocation;
+    if (document.status === "revoked" || revocation != null) {
+        if (!small(revocation) || !revocationShape(revocation) || !sameRef(revocation, expected) || !validSignature(revocation) || ms(revocation.issued_at) > ms(opts.now))
+            reasons.push("missing or invalid assurance revocation evidence");
+        else {
+            reasons.push(...historicalAuthority(revocation.signer, revocation.issued_at, document.signer, opts.authority, document.issued_at));
+            if (document.status !== "revoked" || document.revocation !== jcsHash(revocation))
+                reasons.push("assurance status does not reference the known revocation");
+        }
+        reasons.push("assurance artifact is revoked");
+    }
+    return { ok: reasons.length === 0, reasons: [...new Set(reasons)] };
+}

package/dist/audit-renewal.d.ts

@@ -0,0 +1,39 @@
+import { type Credential } from "@zanii/credentials";
+import { type AssuranceAuthority } from "./assurance-status.ts";
+import { type Signer } from "./signer.ts";
+export interface AuditRenewal {
+    v: 1;
+    type: "certify.audit-renewal";
+    certificate: string;
+    original_audit: string;
+    audit: string;
+    epoch: number;
+    issued_at: string;
+    valid_until: string;
+    signer: string;
+    sig: string;
+}
+export interface AuditRenewalPolicy {
+    document: unknown;
+    originalAudit: unknown;
+    issuers: readonly string[];
+    minEpoch: number;
+    authority?: AssuranceAuthority;
+    originalTrustedBodies?: readonly string[];
+}
+export interface AuditRenewalOptions {
+    certificate: Credential;
+    originalAudit: unknown;
+    audit: unknown;
+    issuers: readonly string[];
+    trustedBodies: readonly string[];
+    originalTrustedBodies?: readonly string[];
+    now: string;
+    minEpoch: number;
+    authority?: AssuranceAuthority;
+}
+export declare function buildAuditRenewal(fields: Omit<AuditRenewal, "v" | "type" | "signer" | "sig">, signer: Signer): Promise<AuditRenewal>;
+export declare function verifyAuditRenewal(document: unknown, opts: AuditRenewalOptions): {
+    ok: boolean;
+    reasons: string[];
+};

package/dist/audit-renewal.js

@@ -0,0 +1,62 @@
+// Immutable Level 3 credentials retain their original audit; a current issuer explicitly attaches its renewal.
+import { jcsHash, publicKeyFromDid } from "@zanii/core";
+import { credentialHash } from "@zanii/credentials";
+import { verifyAuditAttestation } from "./audit.js";
+import {} from "./assurance-status.js";
+import { issuerArtifactAuthorization } from "./issuer-authorization.js";
+import { isInt, isIso, isObj, isSha, ms } from "./shared.js";
+import { signatureOk, signerDid, signWith } from "./signer.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+const did = (v) => typeof v === "string" && v.length <= 69 && publicKeyFromDid(v) !== null;
+const shape = (v) => isObj(v) && Object.keys(v).length === 10 && "v type certificate original_audit audit epoch issued_at valid_until signer sig".split(" ").every((k) => Object.hasOwn(v, k))
+    && v.v === 1 && v.type === "certify.audit-renewal" && isSha(v.certificate) && isSha(v.original_audit) && isSha(v.audit) && v.audit !== v.original_audit && isInt(v.epoch, 1, Number.MAX_SAFE_INTEGER)
+    && isIso(v.issued_at) && isIso(v.valid_until) && ms(v.valid_until) > ms(v.issued_at) && did(v.signer) && typeof v.sig === "string" && /^ed25519:[0-9a-f]{128}$/.test(v.sig);
+export async function buildAuditRenewal(fields, signer) {
+    if (!isObj(fields) || !withinVerificationBudget(fields, { maxBytes: 16_384, maxNodes: 200, maxDepth: 8 }) || ["v", "type", "signer", "sig"].some((k) => Object.hasOwn(fields, k)))
+        throw new Error("invalid audit renewal input");
+    const doc = { ...fields, v: 1, type: "certify.audit-renewal", signer: signerDid(signer), sig: `ed25519:${"0".repeat(128)}` };
+    if (!shape(doc))
+        throw new Error("invalid audit renewal v1");
+    const { sig: _, signer: __, ...unsigned } = doc;
+    return signWith(unsigned, signer);
+}
+export function verifyAuditRenewal(document, opts) {
+    const denied = (reason) => ({ ok: false, reasons: [reason] });
+    if (!withinVerificationBudget({ document, opts }, { maxBytes: 4_194_304 }) || !shape(document) || !isObj(opts) || !isIso(opts.now) || !isInt(opts.minEpoch, 1, Number.MAX_SAFE_INTEGER)
+        || !Array.isArray(opts.issuers) || opts.issuers.length < 1 || opts.issuers.length > 64 || !opts.issuers.every(did)
+        || !Array.isArray(opts.trustedBodies) || opts.trustedBodies.length < 1 || opts.trustedBodies.length > 64 || !opts.trustedBodies.every(did)
+        || (opts.originalTrustedBodies !== undefined && (!Array.isArray(opts.originalTrustedBodies) || opts.originalTrustedBodies.length > 64 || !opts.originalTrustedBodies.every(did))))
+        return denied("audit renewal needs bounded evidence, current issuer/body pins, retained epoch and time");
+    const c = opts.certificate, a = opts.audit, original = opts.originalAudit;
+    if (!isObj(c) || c.v !== 1 || c.type !== "credential" || Object.keys(c).length !== 10 || !isObj(c.claim) || c.claim.level !== 3 || !did(c.issuer) || !isIso(c.issued_at) || !isIso(c.exp) || typeof c.sig !== "string" || !isObj(a) || !isObj(original))
+        return denied("audit renewal needs its original Level 3 certificate and both audit attestations");
+    const reasons = [];
+    const { sig, ...unsigned } = c;
+    if (!signatureOk(unsigned, sig, c.issuer))
+        reasons.push("bad original certificate signature");
+    if (document.certificate !== credentialHash(c) || document.original_audit !== c.claim.audit || document.original_audit !== jcsHash(original) || document.audit !== jcsHash(a))
+        reasons.push("audit renewal references a different certificate or audit");
+    if (!opts.issuers.includes(document.signer))
+        reasons.push("audit renewal is not signed by a trusted current issuer");
+    const { sig: renewalSig, ...renewalUnsigned } = document;
+    if (!signatureOk(renewalUnsigned, renewalSig, document.signer))
+        reasons.push("bad audit renewal signature");
+    if (opts.authority)
+        reasons.push(...issuerArtifactAuthorization({ signer: c.issuer, issued_at: c.issued_at }, document.signer, opts.authority.document, opts.authority.owner, opts.authority.domain, document.issued_at));
+    else if (c.issuer !== document.signer)
+        reasons.push("historical certificate signer needs authorized issuer lineage");
+    reasons.push(...verifyAuditAttestation(original, { certificate: c, trustedBodies: opts.originalTrustedBodies ?? opts.trustedBodies, now: c.issued_at }).reasons);
+    reasons.push(...verifyAuditAttestation(a, { trustedBodies: opts.trustedBodies, now: opts.now }).reasons);
+    const applicant = isObj(c.claim.applicant) ? c.claim.applicant : {}, ap = isObj(a.applicant) ? a.applicant : {};
+    if (a.holder !== c.holder || ap.name !== applicant.name || ap.country !== applicant.country)
+        reasons.push("renewed audit names another agent or applicant");
+    const scope = isObj(a.scope) ? a.scope : {}, previousScope = isObj(original.scope) ? original.scope : {};
+    if (a.standard !== original.standard || scope.en !== previousScope.en || scope.ar !== previousScope.ar || !Array.isArray(a.controls) || !Array.isArray(original.controls) || !original.controls.every((control) => a.controls.includes(control)))
+        reasons.push("renewed audit changes scope, standard or drops original controls; a new certificate is required");
+    if (!isIso(a.issued_at) || !isIso(a.audited_at) || !isIso(original.issued_at) || ms(original.issued_at) > ms(c.issued_at) || ms(a.issued_at) > ms(document.issued_at) || ms(a.audited_at) <= ms(original.audited_at) || ms(document.issued_at) < ms(c.issued_at) || ms(document.issued_at) > ms(opts.now)
+        || ms(document.valid_until) <= ms(opts.now) || ms(document.valid_until) > ms(a.valid_until) || ms(document.valid_until) > ms(c.exp) || ms(a.valid_until) <= ms(opts.now))
+        reasons.push("audit renewal is expired, future-dated or outside certificate/audit validity");
+    if (document.epoch < opts.minEpoch)
+        reasons.push("audit renewal epoch is older than the retained watermark");
+    return { ok: reasons.length === 0, reasons: [...new Set(reasons)] };
+}

package/dist/audit.d.ts

@@ -0,0 +1,69 @@
+import type { Credential } from "@zanii/credentials";
+import { type Signer } from "./signer.ts";
+export declare const AUDIT_OUTCOMES: readonly ["conforming", "minor_nonconformities", "major_nonconformities"];
+export type AuditOutcome = (typeof AUDIT_OUTCOMES)[number];
+/** A clause or Annex A control id, by number only (`8.2`, `A.6.2.4`). */
+export declare const CONTROL: RegExp;
+export interface AuditAttestation {
+    v: 1;
+    type: "certify.audit-attestation";
+    /** The certification body's did:key; equals `signer`. */
+    body: string;
+    /** The audited agent (the certificate holder). */
+    holder: string;
+    applicant: {
+        name: string;
+        country: string;
+    };
+    scope: {
+        en: string;
+        ar: string;
+    };
+    standard: string;
+    controls: string[];
+    audited_at: string;
+    valid_until: string;
+    outcome: AuditOutcome;
+    issued_at: string;
+    signer: string;
+    sig: string;
+}
+export interface AuditInput {
+    holder: string;
+    applicant: {
+        name: string;
+        country: string;
+    };
+    scope: {
+        en: string;
+        ar: string;
+    };
+    standard: string;
+    controls: readonly string[];
+    auditedAt: string;
+    validUntil: string;
+    outcome: AuditOutcome;
+    issuedAt: string;
+}
+/** Sign an audit attestation as the certification body (`signer` holds the body's key). */
+export declare function buildAuditAttestation(fields: AuditInput, signer: Signer): Promise<AuditAttestation>;
+export interface AuditCheck {
+    ok: boolean;
+    reasons: string[];
+}
+/**
+ * Verify an audit attestation: signed by its body, well formed, from a body in `trustedBodies`,
+ * still valid at `now`, not a major nonconformity, and (with `certificate`) for that certificate's
+ * holder and applicant, referenced by its `claim.audit` and dated no later than its issue.
+ */
+export declare function verifyAuditAttestation(att: unknown, opts?: {
+    trustedBodies?: readonly string[];
+    now?: string;
+    certificate?: Credential;
+}): AuditCheck;
+/**
+ * Section 3: has the audit attestation of a Level 3 certificate lapsed at `now`? Surveillance then
+ * suspends the certificate with reason AUDIT_EXPIRED. False below Level 3; throws when `audit` is
+ * not the attestation the certificate references.
+ */
+export declare function auditLapsed(certificate: Credential, audit: AuditAttestation, now: string): boolean;