@zanii/certify 0.0.0-stage → 0.6.0

package/dist/governance.d.ts

@@ -0,0 +1,244 @@
+import { type Credential } from "@zanii/credentials";
+import type { RiskProfile } from "@zanii/insurance";
+import { type ResultBundle } from "./bundle.ts";
+import { type Signer } from "./signer.ts";
+import type { StatusEntry } from "./status.ts";
+type Text = {
+    en: string;
+    ar: string;
+};
+type Lang = "en" | "ar";
+export declare const RISK_NOTE = "a certificate attests lab test results at a point in time plus surveillance; it is not a guarantee of behaviour, and what was not tested is unknown, not good";
+export interface CertifyRiskFacts {
+    certificate: string;
+    profile: string;
+    level: number;
+    status: StatusEntry["status"];
+    reason: string | null;
+    since: string;
+    issued_at: string;
+    exp: string;
+    expired: boolean;
+    days_certified: number;
+    days_since_status_change: number;
+    categories: number;
+    categories_passed: number;
+    min_margin_ppm: number;
+    suspensions: number;
+    incident_suspensions: number;
+    retests_passed: number;
+    retests_failed: number;
+    incident_retests: number;
+    overdue_retests: number;
+    conflicts: string[];
+    under_committee_review: boolean;
+}
+/** The @zanii/insurance RiskProfile with certification facts in place of ledger facts. */
+export type CertifyRiskProfile = Omit<RiskProfile, "type" | "facts"> & {
+    type: "certify.risk_profile";
+    facts: CertifyRiskFacts;
+};
+export interface RiskProfileInput {
+    certificate: Credential;
+    bundle: ResultBundle;
+    status: StatusEntry;
+    history: readonly {
+        action: "suspend" | "revoke" | "reinstate";
+        reason: string | null;
+        at: string;
+    }[];
+    retests: readonly {
+        outcome: "grant" | "refuse";
+        at: string;
+        incident: boolean;
+    }[];
+    /** Complete retained-history counts, when a caller aggregates rather than loading history. */
+    historyFacts?: Pick<CertifyRiskFacts, "suspensions" | "incident_suspensions" | "retests_passed" | "retests_failed" | "incident_retests">;
+    overdueRetests: number;
+    underCommitteeReview: boolean;
+    asOf: string;
+}
+/** Underwriting facts about one certificate: pure and deterministic. */
+export declare function certifyRiskProfile(input: RiskProfileInput): CertifyRiskProfile;
+/** Section 1a: a risk profile signed by the lab's report key, so a holder can check the lab produced it. */
+export type SignedRiskProfile = CertifyRiskProfile & {
+    signer: string;
+    sig: string;
+};
+export declare function signRiskProfile(profile: CertifyRiskProfile, signer: Signer): Promise<SignedRiskProfile>;
+/** Section 1a: signed and (with `signers`, the lab's report keys) by a trusted key. */
+export declare function verifyRiskProfile(doc: unknown, opts?: {
+    signers?: readonly string[];
+    at?: string;
+    maxAgeSeconds?: number;
+}): GovernanceCheck;
+interface ClauseMapLike {
+    slug: string;
+    version: number;
+    title: Text;
+    source: Record<string, unknown>;
+    clauses: {
+        id: string;
+        title: Text;
+        ref: string;
+        interpretation: boolean;
+    }[];
+}
+interface ProfileLike {
+    slug: string;
+    version: number;
+    clause_maps: string[];
+    categories: {
+        id: string;
+        title: Text;
+        clauses: string[];
+    }[];
+}
+export interface FilingPackInput {
+    lang: Lang;
+    lab: {
+        name: string;
+        domain: string;
+    };
+    clauseMap: ClauseMapLike;
+    profile: ProfileLike;
+    certificate: Credential;
+    status: StatusEntry;
+    bundle: ResultBundle;
+    /** The signed PDF report in `lang`: its file name and file hash. */
+    report: {
+        name: string;
+        sha256: string;
+    };
+    /** Optional evidence-share.json attachment, hashed as a file. */
+    evidenceShare?: {
+        sha256: string;
+    };
+    generatedAt: string;
+}
+export type FilingPack = Record<string, unknown> & {
+    v: 1;
+    type: "certify.filing-pack";
+    signer: string;
+    sig: string;
+};
+/** The per-clause filing pack, signed by the report key. */
+export declare function buildFilingPack(input: FilingPackInput, signer: Signer): Promise<FilingPack>;
+export interface GovernanceCheck {
+    ok: boolean;
+    reasons: string[];
+}
+/** Verify a filing pack's signer and the file hashes of supplied report and evidence-share bytes. */
+export declare function verifyFilingPack(pack: unknown, opts?: {
+    signers?: readonly string[];
+    report?: Uint8Array;
+    evidenceShare?: Uint8Array;
+}): GovernanceCheck;
+export declare const CASE_KINDS: readonly ["objection", "appeal", "complaint"];
+export type CaseKind = (typeof CASE_KINDS)[number];
+export declare const OUTCOMES: Record<CaseKind, readonly string[]>;
+export interface GovernanceOutcomeInput {
+    case: {
+        kind: CaseKind;
+        id: string;
+    };
+    decision: string | null;
+    certificate: string | null;
+    outcome: string;
+    note: string;
+    handledBy: string;
+    decidedAt: string;
+    /** An objection signed by an approved browser key: the lab's approval of that key for `handledBy`. */
+    approval?: SigningKeyApproval;
+}
+export type GovernanceOutcome = {
+    v: 1;
+    type: "certify.governance-outcome";
+    case: {
+        kind: CaseKind;
+        id: string;
+    };
+    decision: string | null;
+    certificate: string | null;
+    outcome: string;
+    note: string;
+    handled_by: string;
+    decided_at: string;
+    approval?: SigningKeyApproval;
+    signer: string;
+    sig: string;
+};
+/** The unsigned outcome (the committee member signs this with their own key). */
+export declare function governanceOutcomeBody(f: GovernanceOutcomeInput): Omit<GovernanceOutcome, "signer" | "sig">;
+/** Sign a governance outcome: an objection by the committee member who decided it, an appeal or complaint by the lab issuer. */
+export declare function buildGovernanceOutcome(f: GovernanceOutcomeInput, signer: Signer): Promise<GovernanceOutcome>;
+/**
+ * `issuers`: the issuer DIDs that sign appeal and complaint outcomes and signing key approvals.
+ * `committee`: the committee members' DIDs; given, an objection outcome must be handled by one of
+ * them (without it any DID that signs as `handled_by` passes, so an external verifier passes the
+ * lab's committee). `approvals`: the lab's later approval documents (revocations), from its
+ * public list; an objection signed by an approved key must be decided while the approval was in force.
+ * `external`: the active external committee members (section 3b); given, an objection is decided by one.
+ */
+export declare function verifyGovernanceOutcome(doc: unknown, opts?: {
+    issuers?: readonly string[];
+    committee?: readonly string[];
+    approvals?: readonly unknown[];
+    external?: readonly string[];
+}): GovernanceCheck;
+/** Section 3a: the lab issuer's public statement that `key` signs objection outcomes for the committee member `staff`. */
+export type SigningKeyApproval = {
+    v: 1;
+    type: "certify.signing-key-approval";
+    staff: string;
+    key: string;
+    approved_at: string;
+    revoked_at: string | null;
+    signer: string;
+    sig: string;
+};
+export interface SigningKeyApprovalInput {
+    staff: string;
+    key: string;
+    approvedAt: string;
+    revokedAt?: string | null;
+}
+/** The unsigned approval; a revocation is a new approval document with `revoked_at` set. */
+export declare function signingKeyApprovalBody(f: SigningKeyApprovalInput): Omit<SigningKeyApproval, "signer" | "sig">;
+/** Signed by the lab issuer. */
+export declare function buildSigningKeyApproval(f: SigningKeyApprovalInput, signer: Signer): Promise<SigningKeyApproval>;
+/** Section 3a: well formed and signed by one of `issuers` (the issuer document's `dids`). */
+export declare function verifySigningKeyApproval(doc: unknown, opts?: {
+    issuers?: readonly string[];
+}): GovernanceCheck;
+export interface AccreditationExport {
+    manifest: {
+        v: 1;
+        type: "certify.accreditation-export";
+        lab: {
+            name: string;
+            domain: string;
+        };
+        generated_at: string;
+        sections: {
+            name: string;
+            count: number;
+            sha256: string;
+        }[];
+        signer: string;
+        sig: string;
+    };
+    sections: Record<string, Record<string, unknown>[]>;
+}
+export declare function buildAccreditationExport(input: {
+    lab: {
+        name: string;
+        domain: string;
+    };
+    generatedAt: string;
+    sections: Record<string, Record<string, unknown>[]>;
+}, signer: Signer): Promise<AccreditationExport>;
+export declare function verifyAccreditationExport(archive: unknown, opts?: {
+    signers?: readonly string[];
+}): GovernanceCheck;
+export {};

package/dist/governance.js

@@ -0,0 +1,418 @@
+// spec/governance.md: the risk profile for insurers and buyers (the @zanii/insurance RiskProfile
+// shape, facts never a score), the regulator filing pack, the signed governance outcome of an
+// objection, appeal or complaint, and the signed accreditation export.
+import { jcsHash, verifySignedObject } from "@zanii/core";
+import { credentialHash } from "@zanii/credentials";
+import { bundleHash } from "./bundle.js";
+import { sha256Bytes } from "./fingerprint.js";
+import { isDid, isInt, isIso, isObj, isSha, ms } from "./shared.js";
+import { signWith } from "./signer.js";
+const DAY = 86_400_000;
+const days = (from, to) => Math.max(0, Math.floor((ms(to) - ms(from)) / DAY));
+const claimOf = (c) => c.claim;
+// ---------------------------------------------------------------- 1. risk profile
+export const RISK_NOTE = "a certificate attests lab test results at a point in time plus surveillance; it is not a guarantee of behaviour, and what was not tested is unknown, not good";
+/** Underwriting facts about one certificate: pure and deterministic. */
+export function certifyRiskProfile(input) {
+    const { certificate: c, bundle: b, status: s } = input;
+    if (!isIso(input.asOf))
+        throw new Error("asOf must be an ISO timestamp");
+    const claim = claimOf(c);
+    if (bundleHash(b) !== claim.bundle)
+        throw new Error("bundle is not the certificate's (claim.bundle)");
+    if (!b.results.length)
+        throw new Error("bundle has no results");
+    if (!Number.isInteger(input.overdueRetests) || input.overdueRetests < 0)
+        throw new Error("overdueRetests must be a non-negative integer");
+    const count = (xs, f) => xs.filter(f).length;
+    const totals = input.historyFacts ?? {
+        suspensions: count(input.history, h => h.action === "suspend"),
+        incident_suspensions: count(input.history, h => h.action === "suspend" && h.reason === "INCIDENT"),
+        retests_passed: count(input.retests, r => r.outcome === "grant"),
+        retests_failed: count(input.retests, r => r.outcome === "refuse"),
+        incident_retests: count(input.retests, r => r.incident),
+    };
+    if (Object.keys(totals).sort().join(",") !== "incident_retests,incident_suspensions,retests_failed,retests_passed,suspensions" ||
+        !Object.values(totals).every(n => Number.isSafeInteger(n) && n >= 0) ||
+        totals.incident_suspensions > totals.suspensions || totals.incident_retests > totals.retests_passed + totals.retests_failed)
+        throw new Error("historyFacts must contain consistent non-negative safe integer counts");
+    const facts = {
+        certificate: credentialHash(c),
+        profile: claim.profile,
+        level: claim.level,
+        status: s.status,
+        reason: s.reason,
+        since: s.since,
+        issued_at: c.issued_at,
+        exp: c.exp,
+        expired: ms(input.asOf) > ms(c.exp),
+        days_certified: days(c.issued_at, input.asOf),
+        days_since_status_change: days(s.since, input.asOf),
+        categories: b.results.length,
+        categories_passed: count(b.results, (r) => r.verdict === "pass"),
+        min_margin_ppm: Math.min(...b.results.map((r) => r.low_ppm - r.threshold_ppm)),
+        ...totals,
+        overdue_retests: input.overdueRetests,
+        conflicts: [...claim.conflicts],
+        under_committee_review: input.underCommitteeReview === true,
+    };
+    const flags = [];
+    if (facts.status === "revoked")
+        flags.push("REVOKED");
+    if (facts.status === "suspended")
+        flags.push("SUSPENDED");
+    if (facts.expired)
+        flags.push("EXPIRED");
+    if (facts.overdue_retests > 0)
+        flags.push("RETEST_OVERDUE");
+    if (facts.retests_failed > 0)
+        flags.push("RETEST_FAILED_HISTORY");
+    if (facts.incident_suspensions > 0)
+        flags.push("INCIDENT_HISTORY");
+    if (facts.conflicts.length > 0)
+        flags.push("CONFLICTS_DECLARED");
+    if (facts.under_committee_review)
+        flags.push("UNDER_COMMITTEE_REVIEW");
+    return { v: 1, type: "certify.risk_profile", did: c.holder, owner: claim.applicant.name, as_of: input.asOf, facts, flags, note: RISK_NOTE };
+}
+export async function signRiskProfile(profile, signer) {
+    if (!isObj(profile) || profile.v !== 1 || profile.type !== "certify.risk_profile" || !isObj(profile.facts))
+        throw new Error("not a risk profile (v1)");
+    return signWith(profile, signer);
+}
+/** Section 1a: signed and (with `signers`, the lab's report keys) by a trusted key. */
+export function verifyRiskProfile(doc, opts = {}) {
+    const p = isObj(doc) ? doc : {};
+    if (p.v !== 1 || p.type !== "certify.risk_profile" || !isObj(p.facts) || Object.keys(p).length !== 10)
+        return { ok: false, reasons: ["not a signed risk profile (v1)"] };
+    const reasons = [];
+    if (!verifySignedObject(p))
+        reasons.push("bad risk profile signature");
+    if (!opts.signers)
+        reasons.push("no trusted signers supplied: the signer was NOT checked");
+    else if (!opts.signers.includes(p.signer))
+        reasons.push("risk profile signer is not a trusted signer");
+    if (opts.at !== undefined || opts.maxAgeSeconds !== undefined) {
+        if (!isIso(opts.at) || !isInt(opts.maxAgeSeconds, 1, 31_536_000))
+            reasons.push("risk profile freshness needs an ISO reference time and maxAgeSeconds from 1 to 31536000");
+        else if (!isIso(p.as_of))
+            reasons.push("risk profile as_of is not an ISO timestamp");
+        else if (ms(p.as_of) > ms(opts.at))
+            reasons.push("risk profile is from after the reference time");
+        else if (ms(opts.at) - ms(p.as_of) >= opts.maxAgeSeconds * 1000)
+            reasons.push("risk profile is stale at the reference time");
+    }
+    return { ok: reasons.length === 0, reasons };
+}
+const T = {
+    en: {
+        interpretation: (ref) => `Mapped by the lab's interpretation of ${ref}.`,
+        opening: (lab, profile, level) => `Tested by ${lab} under Zanii Certify profile ${profile}, Level ${level}.`,
+        category: (t, v, p, n, lo, hi, th) => `${t}: ${v}, ${p} of ${n} trials passed, 95% range ${lo} to ${hi} ppm against a threshold of ${th} ppm.`,
+        closing: (c, s, since) => `Certificate ${c}, status ${s} since ${since}.`,
+        notCovered: "Not covered by this certificate's tests.",
+        verdict: { pass: "pass", fail: "fail", inconclusive: "inconclusive" },
+        status: { valid: "valid", suspended: "suspended", revoked: "revoked" },
+        notes: (domain, c) => `Clauses marked interpretation are the lab's reading of the source document, not the regulator's own mapping. The certificate attests test results at a point in time plus surveillance; check its live status at https://${domain}/v1/certificates/${c}.`,
+    },
+    ar: {
+        interpretation: (ref) => `هذا الربط تفسير من المختبر لـ ${ref}.`,
+        opening: (lab, profile, level) => `اختبره ${lab} وفق ملف زاني سيرتيفاي ${profile}، المستوى ${level}.`,
+        category: (t, v, p, n, lo, hi, th) => `${t}: ${v}، نجحت ${p} من ${n} محاولة، نطاق الثقة 95% من ${lo} إلى ${hi} جزء من مليون مقابل عتبة ${th} جزء من مليون.`,
+        closing: (c, s, since) => `الشهادة ${c}، حالتها ${s} منذ ${since}.`,
+        notCovered: "لا تغطيه اختبارات هذه الشهادة.",
+        verdict: { pass: "ناجح", fail: "راسب", inconclusive: "غير حاسم" },
+        status: { valid: "سارية", suspended: "موقوفة", revoked: "ملغاة" },
+        notes: (domain, c) => `البنود الموسومة بأنها تفسير هي قراءة المختبر للوثيقة المصدر وليست ربطا صادرا عن الجهة التنظيمية. تشهد الشهادة على نتائج اختبار في وقت محدد مع المراقبة اللاحقة؛ تحقق من حالتها الحالية في https://${domain}/v1/certificates/${c}.`,
+    },
+};
+/** The per-clause filing pack, signed by the report key. */
+export async function buildFilingPack(input, signer) {
+    const { lang, clauseMap: m, profile: p, certificate: c, bundle: b, status: s } = input;
+    if (lang !== "en" && lang !== "ar")
+        throw new Error("lang must be en or ar");
+    if (!isIso(input.generatedAt))
+        throw new Error("generatedAt must be an ISO timestamp");
+    if (!isSha(input.report.sha256))
+        throw new Error("report.sha256 must be a sha256 hash");
+    if (input.evidenceShare !== undefined && (!isObj(input.evidenceShare) || !isSha(input.evidenceShare.sha256)))
+        throw new Error("evidenceShare.sha256 must be a sha256 hash");
+    const claim = claimOf(c);
+    const mapRef = `${m.slug}/${m.version}`;
+    if (`${p.slug}/${p.version}` !== claim.profile)
+        throw new Error("profile is not the certificate's (claim.profile)");
+    if (!p.clause_maps.includes(mapRef))
+        throw new Error("the profile does not cite this clause map");
+    if (bundleHash(b) !== claim.bundle)
+        throw new Error("bundle is not the certificate's (claim.bundle)");
+    const t = T[lang];
+    const hash = credentialHash(c);
+    const attach = [input.report.name, "result-bundle.json", "certificate.json", ...(input.evidenceShare ? ["evidence-share.json"] : [])];
+    const results = new Map(b.results.map((r) => [r.category, r]));
+    const notEvidenced = [];
+    const clauses = m.clauses.map((cl) => {
+        const categories = p.categories
+            .filter((cat) => cat.clauses.includes(`${m.slug}:${cl.id}`) && results.has(cat.id))
+            .sort((x, y) => (x.id < y.id ? -1 : x.id > y.id ? 1 : 0))
+            .map((cat) => {
+            const r = results.get(cat.id);
+            return {
+                id: cat.id, title: cat.title[lang], verdict: r.verdict, trials: r.trials, passes: r.passes,
+                rate_ppm: r.rate_ppm, low_ppm: r.low_ppm, high_ppm: r.high_ppm, threshold_ppm: r.threshold_ppm,
+            };
+        });
+        let paste;
+        if (!categories.length) {
+            notEvidenced.push(cl.id);
+            paste = t.notCovered;
+        }
+        else
+            paste = [
+                ...(cl.interpretation ? [t.interpretation(cl.ref)] : []),
+                t.opening(input.lab.name, claim.profile, claim.level),
+                ...categories.map((x) => t.category(x.title, t.verdict[x.verdict] ?? x.verdict, x.passes, x.trials, x.low_ppm, x.high_ppm, x.threshold_ppm)),
+                t.closing(hash, t.status[s.status] ?? s.status, s.since),
+            ].join(" ");
+        return { id: cl.id, ref: cl.ref, title: cl.title[lang], interpretation: cl.interpretation, categories, paste, attach: categories.length ? attach : [] };
+    });
+    return signWith({
+        v: 1,
+        type: "certify.filing-pack",
+        lang,
+        lab: { name: input.lab.name, domain: input.lab.domain },
+        map: { ref: mapRef, title: m.title[lang], source: m.source },
+        certificate: hash,
+        holder: c.holder,
+        applicant: claim.applicant,
+        profile: claim.profile,
+        level: claim.level,
+        status: { status: s.status, reason: s.reason, since: s.since },
+        clauses,
+        not_evidenced: notEvidenced,
+        attachments: [
+            { name: "certificate.json", sha256: hash },
+            { name: "result-bundle.json", sha256: claim.bundle },
+            { name: input.report.name, sha256: input.report.sha256 },
+            ...(input.evidenceShare ? [{ name: "evidence-share.json", sha256: input.evidenceShare.sha256 }] : []),
+        ],
+        notes: t.notes(input.lab.domain, hash),
+        generated_at: input.generatedAt,
+    }, signer);
+}
+/** Verify a filing pack's signer and the file hashes of supplied report and evidence-share bytes. */
+export function verifyFilingPack(pack, opts = {}) {
+    const p = isObj(pack) ? pack : {};
+    if (p.v !== 1 || p.type !== "certify.filing-pack")
+        return { ok: false, reasons: ["not a filing pack (v1)"] };
+    const reasons = [];
+    if (!verifySignedObject(p))
+        reasons.push("bad filing pack signature");
+    if (!opts.signers)
+        reasons.push("no trusted signers supplied: the signer was NOT checked");
+    else if (!opts.signers.includes(p.signer))
+        reasons.push("filing pack signer is not a trusted signer");
+    if (opts.report) {
+        const name = `test-report-${String(p.lang)}.pdf`;
+        const a = (Array.isArray(p.attachments) ? p.attachments : []).find((x) => isObj(x) && x.name === name);
+        if (!a || a.sha256 !== sha256Bytes(opts.report))
+            reasons.push("the report is not the one the filing pack names");
+    }
+    if (opts.evidenceShare) {
+        const a = (Array.isArray(p.attachments) ? p.attachments : []).find((x) => isObj(x) && x.name === "evidence-share.json");
+        if (!a || a.sha256 !== sha256Bytes(opts.evidenceShare))
+            reasons.push("the evidence share is not the one the filing pack names");
+    }
+    return { ok: reasons.length === 0, reasons };
+}
+// ---------------------------------------------------------------- 3. governance outcome
+export const CASE_KINDS = ["objection", "appeal", "complaint"];
+export const OUTCOMES = {
+    objection: ["upheld", "dismissed"],
+    appeal: ["upheld", "partly_upheld", "rejected"],
+    complaint: ["upheld", "partly_upheld", "rejected"],
+};
+const RECORD_ID = /^[a-z]{3}_[a-z2-7]{24}$/;
+function outcomeError(o) {
+    const k = isObj(o.case) ? o.case : {};
+    if (!isObj(o.case) || Object.keys(k).length !== 2 || !CASE_KINDS.includes(k.kind) || typeof k.id !== "string" || !RECORD_ID.test(k.id))
+        return "case must be {kind, id} with a known kind and a record id";
+    if (o.decision !== null && (typeof o.decision !== "string" || !RECORD_ID.test(o.decision)))
+        return "decision must be a decision id or null";
+    if (o.certificate !== null && !isSha(o.certificate))
+        return "certificate must be a certificate hash or null";
+    if (o.decision === null && o.certificate === null)
+        return "decision and certificate cannot both be null";
+    if (!OUTCOMES[k.kind].includes(o.outcome))
+        return `outcome must be one of ${OUTCOMES[k.kind].join(", ")}`;
+    if (typeof o.note !== "string" || o.note.length < 1 || o.note.length > 4000)
+        return "note must be 1 to 4000 characters";
+    if (!isDid(o.handled_by))
+        return "handled_by must be a did:key";
+    if (!isIso(o.decided_at))
+        return "decided_at must be an ISO timestamp";
+    if ("approval" in o && (k.kind !== "objection" || !isObj(o.approval)))
+        return "approval is a signing key approval, on an objection outcome only";
+    return null;
+}
+/** The unsigned outcome (the committee member signs this with their own key). */
+export function governanceOutcomeBody(f) {
+    const body = {
+        v: 1,
+        type: "certify.governance-outcome",
+        case: { kind: f.case?.kind, id: f.case?.id },
+        decision: f.decision,
+        certificate: f.certificate,
+        outcome: f.outcome,
+        note: f.note,
+        handled_by: f.handledBy,
+        decided_at: f.decidedAt,
+        ...(f.approval !== undefined ? { approval: f.approval } : {}),
+    };
+    const err = outcomeError(body);
+    if (err)
+        throw new Error(err);
+    return body;
+}
+/** Sign a governance outcome: an objection by the committee member who decided it, an appeal or complaint by the lab issuer. */
+export async function buildGovernanceOutcome(f, signer) {
+    return signWith(governanceOutcomeBody(f), signer);
+}
+/**
+ * `issuers`: the issuer DIDs that sign appeal and complaint outcomes and signing key approvals.
+ * `committee`: the committee members' DIDs; given, an objection outcome must be handled by one of
+ * them (without it any DID that signs as `handled_by` passes, so an external verifier passes the
+ * lab's committee). `approvals`: the lab's later approval documents (revocations), from its
+ * public list; an objection signed by an approved key must be decided while the approval was in force.
+ * `external`: the active external committee members (section 3b); given, an objection is decided by one.
+ */
+export function verifyGovernanceOutcome(doc, opts = {}) {
+    const o = isObj(doc) ? doc : {};
+    if (o.v !== 1 || o.type !== "certify.governance-outcome" || Object.keys(o).length !== ("approval" in o ? 12 : 11))
+        return { ok: false, reasons: ["not a governance outcome (v1)"] };
+    const reasons = [];
+    if (!verifySignedObject(o))
+        reasons.push("bad governance outcome signature");
+    const err = outcomeError(o);
+    if (err)
+        reasons.push(`governance outcome is malformed: ${err}`);
+    const kind = isObj(o.case) ? o.case.kind : undefined;
+    if (kind === "objection" && "approval" in o) {
+        reasons.push(...approvalInForce(o, opts));
+        if (opts.committee && !opts.committee.includes(o.handled_by))
+            reasons.push("objection outcome signer is not a committee member");
+    }
+    else if (kind === "objection") {
+        if (o.signer !== o.handled_by)
+            reasons.push("an objection outcome is signed by the committee member who decided it");
+        else if (opts.committee && !opts.committee.includes(o.signer))
+            reasons.push("objection outcome signer is not a committee member");
+    }
+    else if (!opts.issuers)
+        reasons.push("no trusted issuers supplied: the signer was NOT checked");
+    else if (!opts.issuers.includes(o.signer))
+        reasons.push("governance outcome signer is not a trusted issuer");
+    // Section 3b: given the external members, an objection is decided by one of them.
+    if (kind === "objection" && opts.external && !opts.external.includes(o.handled_by))
+        reasons.push("an objection outcome is decided by an external committee member");
+    return { ok: reasons.length === 0, reasons };
+}
+function approvalError(a) {
+    if (!isDid(a.staff))
+        return "staff must be a did:key";
+    if (!isDid(a.key) || a.key === a.staff)
+        return "key must be a did:key other than staff";
+    if (!isIso(a.approved_at))
+        return "approved_at must be an ISO timestamp";
+    if (a.revoked_at !== null && !(isIso(a.revoked_at) && ms(a.revoked_at) >= ms(a.approved_at)))
+        return "revoked_at must be null or an ISO timestamp not before approved_at";
+    return null;
+}
+/** The unsigned approval; a revocation is a new approval document with `revoked_at` set. */
+export function signingKeyApprovalBody(f) {
+    const body = { v: 1, type: "certify.signing-key-approval", staff: f.staff, key: f.key, approved_at: f.approvedAt, revoked_at: f.revokedAt ?? null };
+    const err = approvalError(body);
+    if (err)
+        throw new Error(err);
+    return body;
+}
+/** Signed by the lab issuer. */
+export async function buildSigningKeyApproval(f, signer) {
+    return signWith(signingKeyApprovalBody(f), signer);
+}
+/** Section 3a: well formed and signed by one of `issuers` (the issuer document's `dids`). */
+export function verifySigningKeyApproval(doc, opts = {}) {
+    const a = isObj(doc) ? doc : {};
+    if (a.v !== 1 || a.type !== "certify.signing-key-approval" || Object.keys(a).length !== 8)
+        return { ok: false, reasons: ["not a signing key approval (v1)"] };
+    const reasons = [];
+    if (!verifySignedObject(a))
+        reasons.push("bad signing key approval signature");
+    const err = approvalError(a);
+    if (err)
+        reasons.push(`signing key approval is malformed: ${err}`);
+    if (!opts.issuers)
+        reasons.push("no trusted issuers supplied: the approval signer was NOT checked");
+    else if (!opts.issuers.includes(a.signer))
+        reasons.push("signing key approval signer is not a trusted issuer");
+    return { ok: reasons.length === 0, reasons };
+}
+/** An objection outcome's approval: for its signer and member, in force at `decided_at` (no revocation in `approvals` at or before it). */
+function approvalInForce(o, opts) {
+    const a = o.approval;
+    const check = verifySigningKeyApproval(a, opts);
+    if (!check.ok)
+        return check.reasons;
+    if (a.staff !== o.handled_by || a.key !== o.signer)
+        return ["the signing key approval is not for this outcome's signer and handled_by"];
+    const at = ms(o.decided_at);
+    if (!(ms(a.approved_at) <= at))
+        return ["the signing key was not approved when the outcome was decided"];
+    const revoked = [a, ...(opts.approvals ?? [])].some((x) => isObj(x) && x.staff === a.staff && x.key === a.key && x.revoked_at !== null && verifySigningKeyApproval(x, opts).ok && !(at < ms(x.revoked_at)));
+    return revoked ? ["the signing key approval was revoked when the outcome was decided"] : [];
+}
+// ---------------------------------------------------------------- 4. accreditation export
+const SECTION = /^[a-z][a-z0-9_]{0,63}$/;
+export async function buildAccreditationExport(input, signer) {
+    if (!isIso(input.generatedAt))
+        throw new Error("generatedAt must be an ISO timestamp");
+    const names = Object.keys(input.sections).sort();
+    for (const n of names) {
+        if (!SECTION.test(n))
+            throw new Error(`section name ${n} is not allowed`);
+        if (!Array.isArray(input.sections[n]) || !input.sections[n].every(isObj))
+            throw new Error(`section ${n} must be a list of objects`);
+    }
+    const manifest = await signWith({
+        v: 1,
+        type: "certify.accreditation-export",
+        lab: { name: input.lab.name, domain: input.lab.domain },
+        generated_at: input.generatedAt,
+        sections: names.map((name) => ({ name, count: input.sections[name].length, sha256: jcsHash({ items: input.sections[name] }) })),
+    }, signer);
+    return { manifest, sections: Object.fromEntries(names.map((n) => [n, input.sections[n]])) };
+}
+export function verifyAccreditationExport(archive, opts = {}) {
+    const a = isObj(archive) ? archive : {};
+    const m = isObj(a.manifest) ? a.manifest : {};
+    if (m.v !== 1 || m.type !== "certify.accreditation-export" || !isObj(a.sections) || !Array.isArray(m.sections))
+        return { ok: false, reasons: ["not an accreditation export (v1)"] };
+    const reasons = [];
+    if (!verifySignedObject(m))
+        reasons.push("bad accreditation export signature");
+    if (!opts.signers)
+        reasons.push("no trusted signers supplied: the signer was NOT checked");
+    else if (!opts.signers.includes(m.signer))
+        reasons.push("accreditation export signer is not a trusted signer");
+    const listed = m.sections.map((s) => String(isObj(s) ? s.name : ""));
+    const present = Object.keys(a.sections).sort();
+    if (listed.join("\n") !== present.join("\n"))
+        reasons.push("the archive's sections are not the manifest's");
+    for (const s of m.sections) {
+        const items = a.sections[s.name];
+        if (!Array.isArray(items))
+            continue;
+        if (items.length !== s.count || jcsHash({ items }) !== s.sha256)
+            reasons.push(`section ${s.name} does not match the manifest`);
+    }
+    return { ok: reasons.length === 0, reasons };
+}