@zanii/certify 0.0.0-stage → 0.5.0

package/dist/board.d.ts

@@ -0,0 +1,218 @@
+import { type Signer } from "./signer.ts";
+import type { SchemeLogsInput } from "./scheme-log.ts";
+/** Section 1: one signature over the canonical bytes of a document without `signatures`. */
+export interface BodySignature {
+    signer: string;
+    sig: string;
+}
+export declare function bodySignature(body: object, signer: Signer): Promise<BodySignature>;
+/** The document with its signatures sorted by signer; one signer signs once. */
+export declare function withSignatures<T extends object>(body: T, sigs: readonly BodySignature[]): T & {
+    signatures: BodySignature[];
+};
+/**
+ * Section 1: the signers of `doc` whose signature verifies, and whether `signatures` is well formed
+ * (1 to 64 `{signer, sig}`, strictly sorted by signer, each verifying, each in `allowed` when given).
+ */
+export declare function signersOf(doc: Record<string, unknown>, allowed?: readonly string[]): {
+    signers: string[];
+    wellFormed: boolean;
+};
+export interface BoardInput {
+    owner: string;
+    seq: number;
+    prev: string | null;
+    members: readonly string[];
+    threshold: number;
+    effectiveFrom: string;
+    /** scheme-log.md section 3: the scheme owner's ledger identity, the root of the delegation of its append receipts. */
+    ledger?: string;
+}
+export type BoardBody = {
+    v: 1;
+    type: "certify.board";
+    owner: string;
+    seq: number;
+    prev: string | null;
+    members: string[];
+    threshold: number;
+    effective_from: string;
+    ledger?: string;
+};
+export type Board = BoardBody & {
+    signatures: BodySignature[];
+};
+export interface BoardCheck {
+    ok: boolean;
+    reasons: string[];
+}
+declare function boardError(b: Record<string, unknown>): string | null;
+/** The unsigned board (each signer signs it with `bodySignature`). */
+export declare function boardBody(f: BoardInput): BoardBody;
+/** A board signed by `signers`: the owner for the first board, k of the previous board after. */
+export declare function buildBoard(f: BoardInput, signers: readonly Signer[]): Promise<Board>;
+export declare const isBoard: (b: unknown) => b is Record<string, unknown>;
+/**
+ * Section 2: the boards form one log: board i at seq i naming board i - 1, one owner, each taking
+ * effect after the previous one; board 0 signed by the owner, every later board by at least the
+ * previous board's threshold of its members, and no other signature.
+ */
+export declare function verifyBoardLog(boards: readonly unknown[], opts?: {
+    owner?: string;
+}): BoardCheck;
+export declare const RELEASE_KINDS: readonly ["scheme", "profile"];
+export type ReleaseKind = (typeof RELEASE_KINDS)[number];
+export interface ReleaseSubject {
+    kind: ReleaseKind;
+    /** `zanii-certify/<major>.<minor>` for a scheme, `<slug>/<version>` for a profile. */
+    ref: string;
+}
+export interface ReleaseInput {
+    seq: number;
+    prev: string | null;
+    subject: ReleaseSubject;
+    /** The released content: a scheme's published text, file hash; a profile, jcsHash of the profile. */
+    sha256: string;
+    effectiveFrom: string;
+    notes: {
+        en: string;
+        ar: string;
+    };
+    /** jcsHash of the board that signs the release (the board in force at effectiveFrom). */
+    board: string;
+}
+export type ReleaseBody = {
+    v: 1;
+    type: "certify.release";
+    seq: number;
+    prev: string | null;
+    subject: ReleaseSubject;
+    sha256: string;
+    effective_from: string;
+    notes: {
+        en: string;
+        ar: string;
+    };
+    board: string;
+};
+export type Release = ReleaseBody & {
+    signatures: BodySignature[];
+};
+export declare const isText: (t: unknown) => boolean;
+export declare function subjectOk(s: unknown): s is ReleaseSubject;
+declare function releaseError(r: Record<string, unknown>): string | null;
+export declare function releaseBody(f: ReleaseInput): ReleaseBody;
+/** A release signed by `signers` (members of the board it names). */
+export declare function buildRelease(f: ReleaseInput, signers: readonly Signer[]): Promise<Release>;
+export declare const isRelease: (r: unknown) => r is Record<string, unknown>;
+/**
+ * A board-signed document (release, withdrawal, body register) against a board log already checked:
+ * the board it names is in the log and in force at its effective_from, and k of its members signed it.
+ */
+export declare function boardSignedReasons(r: Record<string, unknown>, boards: readonly unknown[], noun: string): string[];
+/** Section 3: one release, with the board log it names (checked with `verifyBoardLog`). */
+export declare function verifyRelease(release: unknown, boards: readonly unknown[], opts?: {
+    owner?: string;
+}): BoardCheck;
+export declare const subjectKey: (s: unknown) => string;
+/** Section 4: the release log: every release valid, at seq i naming release i - 1, effective_from never going back, each subject released once. */
+export declare function verifyReleaseLog(releases: readonly unknown[], boards: readonly unknown[], opts?: {
+    owner?: string;
+    schemeLog?: SchemeLogsInput;
+}): BoardCheck;
+/**
+ * Section 5: may a lab use `subject` at `at`? The release log must verify, release the subject, take
+ * effect no later than `at` and (with `sha256`) for exactly that content. With `withdrawals`
+ * (section 6), a release withdrawn at or before `at` may not be used.
+ */
+export declare function requireRelease(releases: readonly unknown[], boards: readonly unknown[], subject: ReleaseSubject, at: string, opts?: {
+    owner?: string;
+    sha256?: string;
+    withdrawals?: readonly unknown[];
+    schemeLog?: SchemeLogsInput;
+}): BoardCheck & {
+    release: Release | null;
+    withdrawal?: ReleaseWithdrawal | null;
+};
+/**
+ * Section 4a: may `board` be appended to the board log now? The board log with it verifies, it takes
+ * effect after the effective_from of every release already in the release log, and the release log
+ * still verifies against the longer board log (a board change never breaks a release).
+ */
+export declare function verifyBoardAppend(boards: readonly unknown[], releases: readonly unknown[], board: unknown, opts?: {
+    owner?: string;
+}): BoardCheck;
+/**
+ * Section 4a: may `release` be appended to the release log now? The release log with it verifies,
+ * and it is signed by the newest board of the board log (a board that was replaced signs nothing more).
+ */
+export declare function verifyReleaseAppend(releases: readonly unknown[], boards: readonly unknown[], release: unknown, opts?: {
+    owner?: string;
+}): BoardCheck;
+export declare const WITHDRAWAL_REASONS: readonly ["DEFECT", "SECURITY", "LEGAL", "OTHER"];
+export type WithdrawalReason = (typeof WITHDRAWAL_REASONS)[number];
+export interface ReleaseWithdrawalInput {
+    seq: number;
+    prev: string | null;
+    subject: ReleaseSubject;
+    /** jcsHash of the release withdrawn. */
+    release: string;
+    reason: WithdrawalReason;
+    notes: {
+        en: string;
+        ar: string;
+    };
+    effectiveFrom: string;
+    /** jcsHash of the board that signs (the newest board when it is appended). */
+    board: string;
+}
+export type ReleaseWithdrawalBody = {
+    v: 1;
+    type: "certify.release-withdrawal";
+    seq: number;
+    prev: string | null;
+    subject: ReleaseSubject;
+    release: string;
+    reason: WithdrawalReason;
+    notes: {
+        en: string;
+        ar: string;
+    };
+    effective_from: string;
+    board: string;
+};
+export type ReleaseWithdrawal = ReleaseWithdrawalBody & {
+    signatures: BodySignature[];
+};
+declare function withdrawalError(w: Record<string, unknown>): string | null;
+export { boardError as boardFieldError, releaseError as releaseFieldError, withdrawalError as withdrawalFieldError };
+export declare function releaseWithdrawalBody(f: ReleaseWithdrawalInput): ReleaseWithdrawalBody;
+/** A release withdrawal signed by `signers` (k members of the board it names). */
+export declare function buildReleaseWithdrawal(f: ReleaseWithdrawalInput, signers: readonly Signer[]): Promise<ReleaseWithdrawal>;
+export declare const isWithdrawal: (w: unknown) => w is Record<string, unknown>;
+/**
+ * Section 6: the withdrawal log: the release log verifies, every withdrawal at seq i naming
+ * withdrawal i - 1, effective_from never going back, naming a release of the log with its subject,
+ * taking effect no earlier than it, each release withdrawn once, signed by k of the board in force.
+ */
+export declare function verifyWithdrawalLog(withdrawals: readonly unknown[], releases: readonly unknown[], boards: readonly unknown[], opts?: {
+    owner?: string;
+    schemeLog?: SchemeLogsInput;
+}): BoardCheck;
+/**
+ * Section 6: a certificate issued under a withdrawn scheme or profile version is flagged, never
+ * failed. `ok` is whether the withdrawal log verified; `flags` names each withdrawal that touches
+ * the certificate's scheme or profile.
+ */
+export declare function withdrawalFlags(cert: {
+    issued_at?: unknown;
+    claim?: unknown;
+}, logs: {
+    withdrawals: readonly unknown[];
+    releases: readonly unknown[];
+    boards: readonly unknown[];
+    owner?: string;
+    schemeLog?: SchemeLogsInput;
+}): BoardCheck & {
+    flags: string[];
+};

package/dist/board.js

@@ -0,0 +1,428 @@
+// spec/governance-board.md: the scheme governance board (k of n; each membership change signed by
+// k of the outgoing board, the first by the scheme owner) and the append-only log of scheme and
+// profile releases the board signs. A lab may only use a scheme or profile version with a release.
+import { jcsHash } from "@zanii/core";
+import { isDid, isInt, isIso, isObj, isSha, ms, SLUG, sortedUnique } from "./shared.js";
+import { signatureOk, signatureOver, signerDid } from "./signer.js";
+import { logPositionOk } from "./status.js";
+import { schemeAuthority } from "./scheme-authority.js";
+export async function bodySignature(body, signer) {
+    if ("signatures" in body)
+        throw new Error("sign the body, without signatures");
+    return { signer: signerDid(signer), sig: await signatureOver(body, signer) };
+}
+const bySigner = (a, b) => (a.signer < b.signer ? -1 : a.signer > b.signer ? 1 : 0);
+/** The document with its signatures sorted by signer; one signer signs once. */
+export function withSignatures(body, sigs) {
+    if ("signatures" in body)
+        throw new Error("the body already carries signatures");
+    const sorted = sigs.map((s) => ({ signer: s.signer, sig: s.sig })).sort(bySigner);
+    if (new Set(sorted.map((s) => s.signer)).size !== sorted.length)
+        throw new Error("a signer signs once");
+    return { ...body, signatures: sorted };
+}
+/**
+ * Section 1: the signers of `doc` whose signature verifies, and whether `signatures` is well formed
+ * (1 to 64 `{signer, sig}`, strictly sorted by signer, each verifying, each in `allowed` when given).
+ */
+export function signersOf(doc, allowed) {
+    const { signatures, ...body } = doc;
+    if (!Array.isArray(signatures) || signatures.length < 1 || signatures.length > (doc.type === "certify.board-transition" ? 65 : 64))
+        return { signers: [], wellFormed: false };
+    const signers = [];
+    let wellFormed = true;
+    let last = "";
+    for (const s of signatures) {
+        if (!isObj(s) || Object.keys(s).length !== 2 || !isDid(s.signer) || s.signer <= last) {
+            wellFormed = false;
+            continue;
+        }
+        last = s.signer;
+        if (!signatureOk(body, s.sig, s.signer) || (allowed && !allowed.includes(s.signer)))
+            wellFormed = false;
+        else
+            signers.push(s.signer);
+    }
+    return { signers, wellFormed };
+}
+const sortedDistinct = (xs) => Array.isArray(xs) && xs.every((x) => typeof x === "string") && sortedUnique(xs).join("\n") === xs.join("\n");
+function boardError(b) {
+    if (!isDid(b.owner))
+        return "owner must be a did:key";
+    if (!logPositionOk(b.seq, b.prev))
+        return "seq and prev are not a log position";
+    const m = b.members;
+    if (!Array.isArray(m) || m.length < 1 || m.length > 64 || !m.every(isDid) || !sortedDistinct(m))
+        return "members must be 1 to 64 sorted, distinct did:keys";
+    if (!isInt(b.threshold, 1, m.length))
+        return "threshold must be an integer from 1 to the number of members";
+    if (!isIso(b.effective_from))
+        return "effective_from must be an ISO timestamp";
+    if ("ledger" in b && !isDid(b.ledger))
+        return "ledger must be a did:key";
+    return null;
+}
+/** The unsigned board (each signer signs it with `bodySignature`). */
+export function boardBody(f) {
+    const body = {
+        v: 1,
+        type: "certify.board",
+        owner: f.owner,
+        seq: f.seq,
+        prev: f.prev,
+        members: Array.isArray(f.members) ? sortedUnique(f.members) : f.members,
+        threshold: f.threshold,
+        effective_from: f.effectiveFrom,
+        ...(f.ledger !== undefined ? { ledger: f.ledger } : {}),
+    };
+    const err = boardError(body);
+    if (err)
+        throw new Error(err);
+    return body;
+}
+/** A board signed by `signers`: the owner for the first board, k of the previous board after. */
+export async function buildBoard(f, signers) {
+    const body = boardBody(f);
+    return withSignatures(body, await Promise.all(signers.map((s) => bodySignature(body, s))));
+}
+export const isBoard = (b) => isObj(b) && b.v === 1 && b.type === "certify.board" && Object.keys(b).length === ("ledger" in b ? 10 : 9);
+const ownerReason = (owner, opts) => opts.owner === undefined
+    ? ["no trusted scheme owner supplied: the owner was NOT checked"]
+    : owner !== opts.owner
+        ? ["the board log is not the trusted scheme owner's"]
+        : [];
+/**
+ * Section 2: the boards form one log: board i at seq i naming board i - 1, one owner, each taking
+ * effect after the previous one; board 0 signed by the owner, every later board by at least the
+ * previous board's threshold of its members, and no other signature.
+ */
+export function verifyBoardLog(boards, opts = {}) {
+    if (!Array.isArray(boards) || boards.length === 0)
+        return { ok: false, reasons: ["the board log is empty"] };
+    const reasons = [];
+    boards.forEach((b, i) => {
+        const prev = i > 0 ? boards[i - 1] : null;
+        if (!isBoard(b)) {
+            reasons.push(`board ${i} is not a board (v1)`);
+            return;
+        }
+        const err = boardError(b);
+        if (err) {
+            reasons.push(`board ${i} is malformed: ${err}`);
+            return;
+        }
+        if (b.seq !== i)
+            reasons.push(`board ${i} is not at position ${i}`);
+        if (b.prev !== (i > 0 ? jcsHash(prev) : null))
+            reasons.push(`board ${i} does not name the previous board`);
+        if (i > 0 && isObj(boards[0]) && b.owner !== boards[0].owner)
+            reasons.push(`board ${i} names another scheme owner`);
+        if (i > 0 && isBoard(prev) && !(ms(b.effective_from) > ms(prev.effective_from)))
+            reasons.push(`board ${i} does not take effect after the previous board`);
+        const allowed = i === 0 ? [b.owner] : isBoard(prev) && Array.isArray(prev.members) ? prev.members : [];
+        const need = i === 0 ? 1 : isBoard(prev) && Number.isInteger(prev.threshold) ? prev.threshold : 1;
+        const s = signersOf(b, allowed);
+        if (!s.wellFormed)
+            reasons.push(`board ${i} carries a signature that is malformed, invalid or not by an authorised signer`);
+        if (i === 0 && s.signers.length < 1)
+            reasons.push("board 0 is not signed by the scheme owner");
+        if (i > 0 && s.signers.length < need)
+            reasons.push(`board ${i} is signed by ${s.signers.length} of the ${need} previous board members required`);
+    });
+    reasons.push(...ownerReason(isObj(boards[0]) ? boards[0].owner : undefined, opts));
+    return { ok: reasons.length === 0, reasons };
+}
+// ---------------------------------------------------------------- 3. releases
+export const RELEASE_KINDS = ["scheme", "profile"];
+const SCHEME_REF = /^zanii-certify\/(0|[1-9][0-9]{0,3})\.(0|[1-9][0-9]{0,3})$/;
+const PROFILE_REF = new RegExp(`^${SLUG.source.slice(1, -1)}/[1-9][0-9]{0,5}$`);
+const text = (v) => typeof v === "string" && v.length >= 1 && v.length <= 4000;
+export const isText = (t) => isObj(t) && Object.keys(t).length === 2 && text(t.en) && text(t.ar);
+export function subjectOk(s) {
+    if (!isObj(s) || Object.keys(s).length !== 2 || typeof s.ref !== "string")
+        return false;
+    return s.kind === "scheme" ? SCHEME_REF.test(s.ref) : s.kind === "profile" && PROFILE_REF.test(s.ref);
+}
+function releaseError(r) {
+    if (!logPositionOk(r.seq, r.prev))
+        return "seq and prev are not a log position";
+    if (!subjectOk(r.subject))
+        return "subject must be {kind: scheme, ref: zanii-certify/<m>.<n>} or {kind: profile, ref: <slug>/<version>}";
+    if (!isSha(r.sha256))
+        return "sha256 must be a sha256 hash";
+    if (!isIso(r.effective_from))
+        return "effective_from must be an ISO timestamp";
+    if (!isText(r.notes))
+        return "notes need en and ar text (1-4000)";
+    if (!isSha(r.board))
+        return "board must be a board hash";
+    return null;
+}
+export function releaseBody(f) {
+    const body = {
+        v: 1,
+        type: "certify.release",
+        seq: f.seq,
+        prev: f.prev,
+        subject: { kind: f.subject?.kind, ref: f.subject?.ref },
+        sha256: f.sha256,
+        effective_from: f.effectiveFrom,
+        notes: { en: f.notes?.en, ar: f.notes?.ar },
+        board: f.board,
+    };
+    const err = releaseError(body);
+    if (err)
+        throw new Error(err);
+    return body;
+}
+/** A release signed by `signers` (members of the board it names). */
+export async function buildRelease(f, signers) {
+    const body = releaseBody(f);
+    return withSignatures(body, await Promise.all(signers.map((s) => bodySignature(body, s))));
+}
+export const isRelease = (r) => isObj(r) && r.v === 1 && r.type === "certify.release" && Object.keys(r).length === 10;
+/**
+ * A board-signed document (release, withdrawal, body register) against a board log already checked:
+ * the board it names is in the log and in force at its effective_from, and k of its members signed it.
+ */
+export function boardSignedReasons(r, boards, noun) {
+    const reasons = [];
+    const i = boards.findIndex((b) => isBoard(b) && jcsHash(b) === r.board);
+    const board = boards[i];
+    if (!isBoard(board))
+        return [`${noun} names a board that is not in the board log`];
+    const next = boards[i + 1];
+    const at = ms(r.effective_from);
+    if (!(ms(board.effective_from) <= at) || (isBoard(next) && !(ms(next.effective_from) > at)))
+        reasons.push(`the named board is not the board in force at the ${noun}'s effective_from`);
+    const need = Number.isInteger(board.threshold) ? board.threshold : 1;
+    const s = signersOf(r, Array.isArray(board.members) ? board.members : []);
+    if (!s.wellFormed)
+        reasons.push(`${noun} carries a signature that is malformed, invalid or not by a board member`);
+    if (s.signers.length < need)
+        reasons.push(`${noun} is signed by ${s.signers.length} of the ${need} board members required`);
+    return reasons;
+}
+/** One release against a board log already checked: fields, its board in force, k board signatures. */
+function releaseReasons(r, boards) {
+    if (!isRelease(r))
+        return ["not a scheme release (v1)"];
+    const err = releaseError(r);
+    if (err)
+        return [`release is malformed: ${err}`];
+    return boardSignedReasons(r, boards, "release");
+}
+/** Section 3: one release, with the board log it names (checked with `verifyBoardLog`). */
+export function verifyRelease(release, boards, opts = {}) {
+    const reasons = [...verifyBoardLog(boards, opts).reasons, ...releaseReasons(release, Array.isArray(boards) ? boards : [])];
+    return { ok: reasons.length === 0, reasons };
+}
+export const subjectKey = (s) => (isObj(s) ? `${String(s.kind)} ${String(s.ref)}` : "?");
+/** Section 4: the release log: every release valid, at seq i naming release i - 1, effective_from never going back, each subject released once. */
+export function verifyReleaseLog(releases, boards, opts = {}) {
+    if (opts.schemeLog !== undefined) {
+        const { reasons } = schemeAuthority(opts.schemeLog, opts.owner, { "certify.board": boards, "certify.release": releases });
+        return { ok: reasons.length === 0, reasons };
+    }
+    const reasons = [...verifyBoardLog(boards, opts).reasons];
+    if (!Array.isArray(releases) || releases.length === 0)
+        return { ok: false, reasons: [...reasons, "the release log is empty"] };
+    const seen = new Set();
+    releases.forEach((r, i) => {
+        reasons.push(...releaseReasons(r, Array.isArray(boards) ? boards : []).map((x) => `release ${i}: ${x}`));
+        if (!isRelease(r))
+            return;
+        const prev = i > 0 ? releases[i - 1] : null;
+        if (r.seq !== i)
+            reasons.push(`release ${i} is not at position ${i}`);
+        if (r.prev !== (i > 0 ? jcsHash(prev) : null))
+            reasons.push(`release ${i} does not name the previous release`);
+        if (i > 0 && isRelease(prev) && !(ms(r.effective_from) >= ms(prev.effective_from)))
+            reasons.push(`release ${i} takes effect before the previous release`);
+        const key = subjectKey(r.subject);
+        if (seen.has(key))
+            reasons.push(`release ${i} releases ${key} again`);
+        seen.add(key);
+    });
+    return { ok: reasons.length === 0, reasons };
+}
+/**
+ * Section 5: may a lab use `subject` at `at`? The release log must verify, release the subject, take
+ * effect no later than `at` and (with `sha256`) for exactly that content. With `withdrawals`
+ * (section 6), a release withdrawn at or before `at` may not be used.
+ */
+export function requireRelease(releases, boards, subject, at, opts = {}) {
+    if (!isIso(at))
+        throw new Error("at must be an ISO timestamp");
+    const authority = opts.schemeLog !== undefined ? schemeAuthority(opts.schemeLog, opts.owner, { "certify.board": boards, "certify.release": releases, ...(opts.withdrawals ? { "certify.release-withdrawal": opts.withdrawals } : {}) }) : null;
+    const reasons = [...(authority ? authority.reasons : verifyReleaseLog(releases, boards, opts).reasons)];
+    const key = subjectKey(subject);
+    const r = (Array.isArray(releases) ? releases : []).find((x) => isRelease(x) && !authority?.canceled.has(jcsHash(x)) && subjectKey(x.subject) === key);
+    if (!r)
+        reasons.push(`${key} has no release`);
+    else {
+        if (!(ms(r.effective_from) <= ms(at)))
+            reasons.push(`${key} is not released until ${r.effective_from}`);
+        if (opts.sha256 !== undefined && r.sha256 !== opts.sha256)
+            reasons.push(`${key} content is not the released content`);
+    }
+    if (opts.withdrawals === undefined)
+        return { ok: reasons.length === 0, reasons, release: r ?? null };
+    if (!authority)
+        reasons.push(...withdrawalReasons(opts.withdrawals, releases, boards));
+    const w = r ? withdrawalOf((Array.isArray(opts.withdrawals) ? opts.withdrawals : []).filter(x => !authority?.canceled.size || !authority.canceled.has(jcsHash(x))), r) : null;
+    if (w && ms(w.effective_from) <= ms(at))
+        reasons.push(`${key} is withdrawn from ${w.effective_from} (${w.reason})`);
+    return { ok: reasons.length === 0, reasons, release: r ?? null, withdrawal: w };
+}
+/**
+ * Section 4a: may `board` be appended to the board log now? The board log with it verifies, it takes
+ * effect after the effective_from of every release already in the release log, and the release log
+ * still verifies against the longer board log (a board change never breaks a release).
+ */
+export function verifyBoardAppend(boards, releases, board, opts = {}) {
+    const next = [...(Array.isArray(boards) ? boards : []), board];
+    const rel = Array.isArray(releases) ? releases : [];
+    const reasons = [...verifyBoardLog(next, opts).reasons];
+    if (isBoard(board) && isIso(board.effective_from) && rel.some((r) => isRelease(r) && isIso(r.effective_from) && !(ms(board.effective_from) > ms(r.effective_from))))
+        reasons.push("the board does not take effect after every release's effective_from");
+    if (rel.length)
+        reasons.push(...verifyReleaseLog(rel, next, opts).reasons);
+    return { ok: reasons.length === 0, reasons: [...new Set(reasons)] };
+}
+/**
+ * Section 4a: may `release` be appended to the release log now? The release log with it verifies,
+ * and it is signed by the newest board of the board log (a board that was replaced signs nothing more).
+ */
+export function verifyReleaseAppend(releases, boards, release, opts = {}) {
+    const reasons = [...verifyReleaseLog([...(Array.isArray(releases) ? releases : []), release], boards, opts).reasons];
+    const last = Array.isArray(boards) ? boards.at(-1) : undefined;
+    if (isRelease(release) && !(isBoard(last) && release.board === jcsHash(last)))
+        reasons.push("the release is not signed by the newest board of the board log");
+    return { ok: reasons.length === 0, reasons: [...new Set(reasons)] };
+}
+// ---------------------------------------------------------------- 6. release withdrawals
+export const WITHDRAWAL_REASONS = ["DEFECT", "SECURITY", "LEGAL", "OTHER"];
+function withdrawalError(w) {
+    if (!logPositionOk(w.seq, w.prev))
+        return "seq and prev are not a log position";
+    if (!subjectOk(w.subject))
+        return "subject must be {kind: scheme, ref: zanii-certify/<m>.<n>} or {kind: profile, ref: <slug>/<version>}";
+    if (!isSha(w.release))
+        return "release must be a release hash";
+    if (!WITHDRAWAL_REASONS.includes(w.reason))
+        return `reason must be one of ${WITHDRAWAL_REASONS.join(", ")}`;
+    if (!isText(w.notes))
+        return "notes need en and ar text (1-4000)";
+    if (!isIso(w.effective_from))
+        return "effective_from must be an ISO timestamp";
+    if (!isSha(w.board))
+        return "board must be a board hash";
+    return null;
+}
+// Shared by the incremental verifier; field rules have one implementation.
+export { boardError as boardFieldError, releaseError as releaseFieldError, withdrawalError as withdrawalFieldError };
+export function releaseWithdrawalBody(f) {
+    const body = {
+        v: 1,
+        type: "certify.release-withdrawal",
+        seq: f.seq,
+        prev: f.prev,
+        subject: { kind: f.subject?.kind, ref: f.subject?.ref },
+        release: f.release,
+        reason: f.reason,
+        notes: { en: f.notes?.en, ar: f.notes?.ar },
+        effective_from: f.effectiveFrom,
+        board: f.board,
+    };
+    const err = withdrawalError(body);
+    if (err)
+        throw new Error(err);
+    return body;
+}
+/** A release withdrawal signed by `signers` (k members of the board it names). */
+export async function buildReleaseWithdrawal(f, signers) {
+    const body = releaseWithdrawalBody(f);
+    return withSignatures(body, await Promise.all(signers.map((s) => bodySignature(body, s))));
+}
+export const isWithdrawal = (w) => isObj(w) && w.v === 1 && w.type === "certify.release-withdrawal" && Object.keys(w).length === 11;
+/** The withdrawal of `release` in a list (a release is withdrawn at most once), or null. */
+function withdrawalOf(withdrawals, release) {
+    const h = jcsHash(release);
+    return (Array.isArray(withdrawals) ? withdrawals : []).find((w) => isWithdrawal(w) && w.release === h) ?? null;
+}
+/** Section 6 without the release log's own reasons. */
+function withdrawalReasons(withdrawals, releases, boards) {
+    if (!Array.isArray(withdrawals))
+        return ["the withdrawal log is not a list"];
+    const rel = Array.isArray(releases) ? releases : [];
+    const bl = Array.isArray(boards) ? boards : [];
+    const reasons = [];
+    const seen = new Set();
+    withdrawals.forEach((w, i) => {
+        if (!isWithdrawal(w)) {
+            reasons.push(`withdrawal ${i} is not a release withdrawal (v1)`);
+            return;
+        }
+        const err = withdrawalError(w);
+        if (err) {
+            reasons.push(`withdrawal ${i} is malformed: ${err}`);
+            return;
+        }
+        const prev = i > 0 ? withdrawals[i - 1] : null;
+        if (w.seq !== i)
+            reasons.push(`withdrawal ${i} is not at position ${i}`);
+        if (w.prev !== (i > 0 ? jcsHash(prev) : null))
+            reasons.push(`withdrawal ${i} does not name the previous withdrawal`);
+        if (i > 0 && isWithdrawal(prev) && !(ms(w.effective_from) >= ms(prev.effective_from)))
+            reasons.push(`withdrawal ${i} takes effect before the previous withdrawal`);
+        const r = rel.find((x) => isRelease(x) && jcsHash(x) === w.release);
+        if (!isRelease(r))
+            reasons.push(`withdrawal ${i} names a release that is not in the release log`);
+        else {
+            if (subjectKey(r.subject) !== subjectKey(w.subject))
+                reasons.push(`withdrawal ${i} subject is not the release's subject`);
+            if (!(ms(w.effective_from) >= ms(r.effective_from)))
+                reasons.push(`withdrawal ${i} takes effect before the release`);
+        }
+        if (seen.has(w.release))
+            reasons.push(`withdrawal ${i} withdraws a release again`);
+        seen.add(w.release);
+        reasons.push(...boardSignedReasons(w, bl, "withdrawal").map((x) => `withdrawal ${i}: ${x}`));
+    });
+    return reasons;
+}
+/**
+ * Section 6: the withdrawal log: the release log verifies, every withdrawal at seq i naming
+ * withdrawal i - 1, effective_from never going back, naming a release of the log with its subject,
+ * taking effect no earlier than it, each release withdrawn once, signed by k of the board in force.
+ */
+export function verifyWithdrawalLog(withdrawals, releases, boards, opts = {}) {
+    if (opts.schemeLog !== undefined) {
+        const { reasons } = schemeAuthority(opts.schemeLog, opts.owner, { "certify.board": boards, "certify.release": releases, "certify.release-withdrawal": withdrawals });
+        return { ok: reasons.length === 0, reasons };
+    }
+    const reasons = [...verifyReleaseLog(releases, boards, opts).reasons, ...withdrawalReasons(withdrawals, releases, boards)];
+    return { ok: reasons.length === 0, reasons };
+}
+/**
+ * Section 6: a certificate issued under a withdrawn scheme or profile version is flagged, never
+ * failed. `ok` is whether the withdrawal log verified; `flags` names each withdrawal that touches
+ * the certificate's scheme or profile.
+ */
+export function withdrawalFlags(cert, logs) {
+    const authority = logs.schemeLog !== undefined ? schemeAuthority(logs.schemeLog, logs.owner, { "certify.board": logs.boards, "certify.release": logs.releases, "certify.release-withdrawal": logs.withdrawals }) : null;
+    const reasons = authority ? authority.reasons : verifyWithdrawalLog(logs.withdrawals, logs.releases, logs.boards, logs.owner === undefined ? {} : { owner: logs.owner }).reasons;
+    const claim = isObj(cert?.claim) ? cert.claim : {};
+    const flags = [];
+    for (const subject of [{ kind: "scheme", ref: claim.scheme }, { kind: "profile", ref: claim.profile }]) {
+        const key = subjectKey(subject);
+        const r = (Array.isArray(logs.releases) ? logs.releases : []).find((x) => isRelease(x) && !authority?.canceled.has(jcsHash(x)) && subjectKey(x.subject) === key);
+        const w = r ? withdrawalOf((Array.isArray(logs.withdrawals) ? logs.withdrawals : []).filter(x => !authority?.canceled.size || !authority.canceled.has(jcsHash(x))), r) : null;
+        if (!w)
+            continue;
+        const after = ms(cert?.issued_at) >= ms(w.effective_from) ? "; the certificate was issued after it" : "";
+        flags.push(`${key} was withdrawn from ${w.effective_from} (${w.reason})${after}`);
+    }
+    return { ok: reasons.length === 0, reasons, flags };
+}