@zanii/certify 0.0.0-stage → 0.5.0

package/dist/shared.d.ts

@@ -0,0 +1,16 @@
+export declare const SHA256: RegExp;
+export declare const ISO_UTC: RegExp;
+export declare const DID: RegExp;
+export declare const SLUG: RegExp;
+/** A real UTC instant in the section 2 form (Date.parse alone accepts 2026-02-30). */
+export declare const isIso: (v: unknown) => v is string;
+export declare const isSha: (v: unknown) => v is string;
+export declare const isDid: (v: unknown) => v is string;
+export declare const isObj: (v: unknown) => v is Record<string, unknown>;
+export declare const isInt: (v: unknown, min: number, max: number) => v is number;
+/** Milliseconds since the epoch; NaN for anything that is not an ISO timestamp. */
+export declare const ms: (v: unknown) => number;
+/** `t` plus `days` whole days, as `toISOString()` writes it. */
+export declare const addDays: (t: string, days: number) => string;
+/** Sorted (UTF-16 code unit order, as JCS sorts keys), duplicates removed. */
+export declare const sortedUnique: (xs: readonly string[]) => string[];

package/dist/shared.js

@@ -0,0 +1,20 @@
+// Field rules shared by every Certify format (spec/README.md §2).
+export const SHA256 = /^sha256:[0-9a-f]{64}$/;
+export const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/;
+export const DID = /^did:key:z[1-9A-HJ-NP-Za-km-z]{40,60}$/;
+export const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** A real UTC instant in the section 2 form (Date.parse alone accepts 2026-02-30). */
+export const isIso = (v) => typeof v === "string" &&
+    ISO_UTC.test(v) &&
+    !Number.isNaN(Date.parse(v)) &&
+    new Date(v).toISOString().slice(0, 19) === v.slice(0, 19);
+export const isSha = (v) => typeof v === "string" && SHA256.test(v);
+export const isDid = (v) => typeof v === "string" && DID.test(v);
+export const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export const isInt = (v, min, max) => Number.isInteger(v) && v >= min && v <= max;
+/** Milliseconds since the epoch; NaN for anything that is not an ISO timestamp. */
+export const ms = (v) => (isIso(v) ? Date.parse(v) : Number.NaN);
+/** `t` plus `days` whole days, as `toISOString()` writes it. */
+export const addDays = (t, days) => new Date(Date.parse(t) + days * 86_400_000).toISOString();
+/** Sorted (UTF-16 code unit order, as JCS sorts keys), duplicates removed. */
+export const sortedUnique = (xs) => [...new Set(xs)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));

package/dist/signer.d.ts

@@ -0,0 +1,18 @@
+export interface Signer {
+    /** The raw 32-byte Ed25519 public key. */
+    publicKey: Uint8Array;
+    /** Returns the raw 64-byte Ed25519 signature over `message`. */
+    sign: (message: Uint8Array) => Promise<Uint8Array>;
+}
+/** A Signer over a raw 32-byte Ed25519 seed held in this process (tests, development). */
+export declare function keySigner(privateKey: Uint8Array): Signer;
+export declare const signerDid: (signer: Signer) => string;
+/** `ed25519:<hex>` over the RFC 8785 bytes of `unsigned`. */
+export declare function signatureOver(unsigned: object, signer: Signer): Promise<string>;
+/** Does `sig` (`ed25519:<hex>`) by `did` verify over the RFC 8785 bytes of `unsigned`? Never throws. */
+export declare function signatureOk(unsigned: object, sig: unknown, did: string): boolean;
+/** @zanii/core signObject with a Signer: the same bytes, verified by verifySignedObject. */
+export declare function signWith<T extends object>(obj: T, signer: Signer): Promise<T & {
+    signer: string;
+    sig: string;
+}>;

package/dist/signer.js

@@ -0,0 +1,49 @@
+// spec/certificate.md §4: everything Certify signs goes through a Signer, the same shape as
+// @zanii/sdk AgentSigner and @zanii/kms RemoteSigner, so the issuer key can live in a KMS or HSM.
+import { createPrivateKey, createPublicKey, sign as nodeSign, verify as nodeVerify } from "node:crypto";
+import { canonicalBytes, didFromPublicKey, publicKeyFromDid } from "@zanii/core";
+const PKCS8_ED25519 = Buffer.from("302e020100300506032b657004220420", "hex");
+const SPKI_ED25519 = Buffer.from("302a300506032b6570032100", "hex");
+/** A Signer over a raw 32-byte Ed25519 seed held in this process (tests, development). */
+export function keySigner(privateKey) {
+    if (privateKey.length !== 32)
+        throw new Error("ed25519 private key must be 32 bytes");
+    const key = createPrivateKey({
+        key: Buffer.concat([PKCS8_ED25519, privateKey]),
+        format: "der",
+        type: "pkcs8",
+    });
+    const spki = createPublicKey(key).export({ format: "der", type: "spki" });
+    return {
+        publicKey: new Uint8Array(spki.subarray(spki.length - 32)),
+        sign: async (message) => new Uint8Array(nodeSign(null, message, key)),
+    };
+}
+export const signerDid = (signer) => didFromPublicKey(signer.publicKey);
+/** `ed25519:<hex>` over the RFC 8785 bytes of `unsigned`. */
+export async function signatureOver(unsigned, signer) {
+    const sig = await signer.sign(canonicalBytes(unsigned));
+    if (sig.length !== 64)
+        throw new Error("signer returned a signature that is not 64 bytes");
+    return `ed25519:${Buffer.from(sig).toString("hex")}`;
+}
+/** Does `sig` (`ed25519:<hex>`) by `did` verify over the RFC 8785 bytes of `unsigned`? Never throws. */
+export function signatureOk(unsigned, sig, did) {
+    const pub = publicKeyFromDid(did);
+    if (!pub || typeof sig !== "string" || !/^ed25519:[0-9a-f]{128}$/.test(sig))
+        return false;
+    try {
+        const key = createPublicKey({ key: Buffer.concat([SPKI_ED25519, pub]), format: "der", type: "spki" });
+        return nodeVerify(null, canonicalBytes(unsigned), key, Buffer.from(sig.slice(8), "hex"));
+    }
+    catch {
+        return false;
+    }
+}
+/** @zanii/core signObject with a Signer: the same bytes, verified by verifySignedObject. */
+export async function signWith(obj, signer) {
+    if ("sig" in obj)
+        throw new Error("signWith: the object already carries a sig");
+    const unsigned = { ...obj, signer: signerDid(signer) };
+    return { ...unsigned, sig: await signatureOver(unsigned, signer) };
+}

package/dist/signing-identity.d.ts

@@ -0,0 +1 @@
+export declare function signingIdentityReasons(owner: unknown, issuers: unknown, statusIssuers?: unknown): string[];

package/dist/signing-identity.js

@@ -0,0 +1,11 @@
+// A witness log id is its signing DID: an owner and a status issuer must never share that key.
+import { publicKeyFromDid } from "@zanii/core";
+const did = (v) => typeof v === "string" && v.length <= 69 && publicKeyFromDid(v) !== null;
+export function signingIdentityReasons(owner, issuers, statusIssuers = []) {
+    if (!did(owner))
+        return ["signing identity: an actual Ed25519 owner DID is required"];
+    const valid = (list) => Array.isArray(list) && list.length <= 256 && Array.from(list).every(did) && new Set(list).size === list.length;
+    if (!valid(issuers) || !valid(statusIssuers))
+        return ["signing identity: issuer and status identities must be distinct bounded Ed25519 DID lists"];
+    return issuers.includes(owner) || statusIssuers.includes(owner) ? ["signing identity: the owner key must not also be an issuer or status signing key"] : [];
+}

package/dist/status.d.ts

@@ -0,0 +1,113 @@
+import { type SignedTreeHead } from "@zanii/core";
+import type { RevocationList } from "@zanii/credentials";
+import { type PqBinding } from "@zanii/pq";
+import type { WitnessCosignature } from "@zanii/witness";
+import { type PqCosignature } from "./pq.ts";
+import { type Signer } from "./signer.ts";
+import STATUS_V2_SCHEMA from "./formats/status-v2.schema.json";
+export { STATUS_V2_SCHEMA };
+export declare const REASONS: readonly ["FINGERPRINT_MISMATCH", "RETEST_OVERDUE", "RETEST_FAILED", "INCIDENT", "APPLICANT_REQUEST", "ISSUER_ERROR", 
+/** licensing.md section 2a: the issuing licensee's licence was withdrawn or suspended for cause. */
+"LICENCE_WITHDRAWN", 
+/** audit.md section 3: a Level 3 certificate's audit attestation lapsed. */
+"AUDIT_EXPIRED"];
+export declare const REASONS_V2: readonly ["FINGERPRINT_MISMATCH", "RETEST_OVERDUE", "RETEST_FAILED", "INCIDENT", "APPLICANT_REQUEST", "ISSUER_ERROR", "LICENCE_WITHDRAWN", "AUDIT_EXPIRED", "MARK_MISUSE"];
+export declare const STATUS_V2_MAX_ENTRIES = 100000;
+export type Reason = (typeof REASONS_V2)[number];
+export type StatusVersion = 1 | 2;
+export type CertificateStatus = "valid" | "suspended" | "revoked";
+export type StatusAction = "grant" | "suspend" | "revoke" | "reinstate";
+export interface StatusEntry {
+    status: CertificateStatus;
+    /** Null when valid; the reason code when suspended or revoked. */
+    reason: Reason | null;
+    since: string;
+}
+/** Keyed by the certificate's credential hash. */
+export type StatusEntries = Record<string, StatusEntry>;
+export interface StatusDocument {
+    v: StatusVersion;
+    type: "certify.status";
+    issuer: string;
+    entries: StatusEntries;
+    issued_at: string;
+    valid_until: string;
+    /** spec/witness.md: the document's position in the status log, from 0. */
+    seq?: number;
+    /** spec/witness.md: jcsHash of the previous document in the log; null at seq 0. */
+    prev?: string | null;
+    /** Section 5: bindingHash of the issuer's @zanii/pq binding, when co-signed. */
+    pq_binding?: string;
+    signer: string;
+    sig: string;
+}
+/** spec/witness.md section 3: what a verifier needs to require a witnessed checkpoint. */
+export interface StatusWitness {
+    /** The issuer's signed tree head over the status log (`statusCheckpoint`). */
+    checkpoint: SignedTreeHead;
+    /** The inclusion proof of the document at index `seq` (`statusInclusionProof`), hex. */
+    proof: string[];
+    cosignatures: WitnessCosignature[];
+    /** The witness DIDs this verifier trusts. */
+    trusted: string[];
+    /** How many of them must have co-signed the checkpoint. */
+    k: number;
+}
+/** A log position is `seq` and `prev` together: seq 0 has prev null, later ones a hash. */
+export declare const logPositionOk: (seq: unknown, prev: unknown) => boolean;
+/**
+ * §2: apply one status change and return the new entries (the input is not changed). Throws on a
+ * change the rules forbid: revoked is final, only a valid certificate is suspended, only a
+ * suspended one is reinstated, and time never goes backwards for one certificate.
+ */
+export declare function applyStatus(entries: StatusEntries, certificate: string, action: StatusAction, reason: Reason | null, at: string, opts?: {
+    version?: StatusVersion;
+}): StatusEntries;
+/** §1: sign a status document. `valid_until` is the freshness bound verifiers enforce. */
+export declare function buildStatus(fields: {
+    version?: StatusVersion;
+    entries: StatusEntries;
+    issuedAt: string;
+    validUntil: string;
+    /** spec/witness.md: place the document in the status log (both or neither). */
+    seq?: number;
+    prev?: string | null;
+    /** Section 5: commit to the issuer's @zanii/pq binding so the document can be co-signed. */
+    pqBinding?: PqBinding;
+}, signer: Signer): Promise<StatusDocument>;
+export interface StatusCheck {
+    ok: boolean;
+    reasons: string[];
+    freshness: "fresh" | "stale" | null;
+    /** Only with a `witness` policy: the trusted witnesses that co-signed the checkpoint. */
+    witnesses?: string[];
+    /** Only with `issuerDoc` (section 5a): `required`, `opted_out` or `not_required`. */
+    pqPolicy?: "required" | "opted_out" | "not_required";
+}
+export interface StatusVerifyOptions {
+    /** Independently known scheme log owner, which cannot share this status signing identity. */
+    schemeOwner?: string;
+    issuer?: string;
+    now?: string;
+    /** Section 5: the document's post-quantum co-signature. */
+    pq?: PqCosignature;
+    /** Section 5: refuse a document without a valid post-quantum co-signature. */
+    requirePq?: boolean;
+    /** spec/witness.md: require the document in a checkpoint co-signed by k trusted witnesses. */
+    witness?: StatusWitness;
+    /** Section 5a: the issuer document; `require_pq: true` in it makes `requirePq` the default. */
+    issuerDoc?: unknown;
+    /** Section 5a: explicitly verify without the co-signature the issuer document requires. */
+    allowNoPq?: boolean;
+}
+/**
+ * Is this an intact status document from `issuer` (when given), still fresh at `now`? With `pq`
+ * or `requirePq` also its post-quantum co-signature, with `witness` its witnessed checkpoint.
+ */
+export declare function verifyStatus(doc: unknown, opts?: StatusVerifyOptions): StatusCheck;
+/**
+ * §3: the @zanii/credentials revocation list for a status document: every certificate whose status
+ * is not valid, with the same issued_at and valid_until. Byte-identical to `buildRevocationList`
+ * with the issuer's key, so plain credential verifiers refuse suspended and revoked certificates.
+ */
+export declare function revocationListFromStatus(doc: StatusDocument, signer: Signer): Promise<RevocationList>;

package/dist/status.js

@@ -0,0 +1,204 @@
+// spec/status.md: the signed status document and the revocation list derived from it.
+import { publicKeyFromDid, verifySignedObject } from "@zanii/core";
+import { bindingHash } from "@zanii/pq";
+import { checkPqBinding, pqCommitment, pqPolicyOf, verifyPqCosignature } from "./pq.js";
+import { isDid, isInt, isIso, isObj, isSha, ms, sortedUnique } from "./shared.js";
+import { signatureOver, signerDid, signWith } from "./signer.js";
+import { compromisedKeyReasons, issuerLineage, succeeds } from "./succession.js";
+import { witnessReasons } from "./witness.js";
+import { signingIdentityReasons } from "./signing-identity.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+import STATUS_V2_SCHEMA from "./formats/status-v2.schema.json" with { type: "json" };
+export { STATUS_V2_SCHEMA };
+export const REASONS = [
+    "FINGERPRINT_MISMATCH",
+    "RETEST_OVERDUE",
+    "RETEST_FAILED",
+    "INCIDENT",
+    "APPLICANT_REQUEST",
+    "ISSUER_ERROR",
+    /** licensing.md section 2a: the issuing licensee's licence was withdrawn or suspended for cause. */
+    "LICENCE_WITHDRAWN",
+    /** audit.md section 3: a Level 3 certificate's audit attestation lapsed. */
+    "AUDIT_EXPIRED",
+];
+export const REASONS_V2 = [...REASONS, "MARK_MISUSE"];
+export const STATUS_V2_MAX_ENTRIES = 100_000;
+/** A log position is `seq` and `prev` together: seq 0 has prev null, later ones a hash. */
+export const logPositionOk = (seq, prev) => isInt(seq, 0, Number.MAX_SAFE_INTEGER) && (seq === 0 ? prev === null : isSha(prev));
+const isReason = (v, version = 1) => (version === 2 ? REASONS_V2 : REASONS).includes(v);
+/**
+ * §2: apply one status change and return the new entries (the input is not changed). Throws on a
+ * change the rules forbid: revoked is final, only a valid certificate is suspended, only a
+ * suspended one is reinstated, and time never goes backwards for one certificate.
+ */
+export function applyStatus(entries, certificate, action, reason, at, opts = {}) {
+    if (opts.version !== undefined && opts.version !== 1 && opts.version !== 2)
+        throw new Error("status version must be 1 or 2");
+    if (!isSha(certificate))
+        throw new Error("certificate must be a credential hash");
+    if (!isIso(at))
+        throw new Error("at must be an ISO UTC timestamp");
+    const now = entries[certificate];
+    const wantsReason = action === "suspend" || action === "revoke";
+    if (wantsReason ? !isReason(reason, opts.version) : reason !== null)
+        throw new Error(wantsReason ? `${action} needs a reason code` : `${action} takes no reason`);
+    if (now && ms(at) < ms(now.since))
+        throw new Error("at is before the current status");
+    let next;
+    if (action === "grant") {
+        if (now)
+            throw new Error("certificate already has a status");
+        next = "valid";
+    }
+    else if (!now) {
+        throw new Error("certificate has no status; grant it first");
+    }
+    else if (now.status === "revoked") {
+        throw new Error("certificate is revoked; revocation is final");
+    }
+    else if (action === "suspend") {
+        if (now.status !== "valid")
+            throw new Error("only a valid certificate can be suspended");
+        next = "suspended";
+    }
+    else if (action === "reinstate") {
+        if (now.status !== "suspended")
+            throw new Error("only a suspended certificate can be reinstated");
+        next = "valid";
+    }
+    else {
+        next = "revoked";
+    }
+    return { ...entries, [certificate]: { status: next, reason, since: at } };
+}
+function entryOk(e, version = 1) {
+    if (!isObj(e) || Object.keys(e).length !== 3 || !isIso(e.since))
+        return false;
+    if (e.status === "valid")
+        return e.reason === null;
+    return (e.status === "suspended" || e.status === "revoked") && isReason(e.reason, version);
+}
+function v2Error(d) {
+    if (!withinVerificationBudget(d, { maxDepth: 8 }) || !isObj(d.entries) || Object.keys(d.entries).length > STATUS_V2_MAX_ENTRIES)
+        return "status v2 exceeds its JSON or entry budget";
+    if ("v type issuer entries issued_at valid_until signer sig".split(" ").some(k => !Object.hasOwn(d, k)) || Object.keys(d).some(k => !"v type issuer entries issued_at valid_until signer sig seq prev pq_binding".split(" ").includes(k)))
+        return "status v2 has missing or unknown fields";
+    if (typeof d.issuer !== "string" || d.issuer.length > 69 || !publicKeyFromDid(d.issuer) || d.signer !== d.issuer || typeof d.sig !== "string" || !/^ed25519:[0-9a-f]{128}$/.test(d.sig))
+        return "status v2 needs matching Ed25519 issuer and signer";
+    if (!isIso(d.issued_at) || !isIso(d.valid_until) || ms(d.valid_until) <= ms(d.issued_at) || ms(d.valid_until) - ms(d.issued_at) > 3_600_000)
+        return "status v2 lifetime must be positive and at most one hour";
+    if (Object.entries(d.entries).some(([hash, entry]) => !isSha(hash) || !entryOk(entry, 2) || ms(entry.since) > ms(d.issued_at)))
+        return "status v2 has a malformed or future entry";
+    if ((("seq" in d || "prev" in d) && !logPositionOk(d.seq, d.prev)) || ("pq_binding" in d && !isSha(d.pq_binding)))
+        return "status v2 has a malformed log position or PQ binding";
+    return null;
+}
+/** §1: sign a status document. `valid_until` is the freshness bound verifiers enforce. */
+export async function buildStatus(fields, signer) {
+    const version = fields.version ?? 1;
+    if (version !== 1 && version !== 2)
+        throw new Error("status version must be 1 or 2");
+    if (version === 2 && (!isObj(fields.entries) || Object.keys(fields.entries).length > STATUS_V2_MAX_ENTRIES || Object.keys(fields).some(k => !["version", "entries", "issuedAt", "validUntil", "seq", "prev", "pqBinding"].includes(k)) || !withinVerificationBudget(fields, { maxDepth: 10 })))
+        throw new Error("status v2 exceeds its JSON or entry budget");
+    if (!isIso(fields.issuedAt) || !isIso(fields.validUntil))
+        throw new Error("issuedAt and validUntil must be ISO UTC timestamps");
+    if (ms(fields.validUntil) < ms(fields.issuedAt))
+        throw new Error("validUntil is before issuedAt");
+    for (const [k, e] of Object.entries(fields.entries))
+        if (!isSha(k) || !entryOk(e, version))
+            throw new Error(`malformed status entry ${k}`);
+    const logged = fields.seq !== undefined || fields.prev !== undefined;
+    if (logged && !logPositionOk(fields.seq, fields.prev))
+        throw new Error("seq and prev: seq 0 with prev null, or seq >= 1 with the previous document hash");
+    const issuer = signerDid(signer);
+    if (fields.pqBinding !== undefined)
+        checkPqBinding(fields.pqBinding, issuer);
+    const unsigned = {
+        v: version,
+        type: "certify.status",
+        issuer,
+        entries: version === 2 ? structuredClone(fields.entries) : fields.entries,
+        issued_at: fields.issuedAt,
+        valid_until: fields.validUntil,
+        ...(logged ? { seq: fields.seq, prev: fields.prev } : {}),
+        ...(fields.pqBinding ? { pq_binding: bindingHash(fields.pqBinding) } : {}),
+    };
+    if (version === 2) {
+        const error = v2Error({ ...unsigned, signer: issuer, sig: `ed25519:${"0".repeat(128)}` });
+        if (error)
+            throw new Error(error);
+    }
+    return signWith(unsigned, signer);
+}
+/**
+ * Is this an intact status document from `issuer` (when given), still fresh at `now`? With `pq`
+ * or `requirePq` also its post-quantum co-signature, with `witness` its witnessed checkpoint.
+ */
+export function verifyStatus(doc, opts = {}) {
+    const d = isObj(doc) ? doc : {};
+    const pqPolicy = opts.issuerDoc === undefined ? undefined : pqPolicyOf(opts.issuerDoc, opts.allowNoPq);
+    const policy = pqPolicy ? { pqPolicy } : {};
+    if ((d.v !== 1 && d.v !== 2) || d.type !== "certify.status" || !isDid(d.issuer) || !isObj(d.entries))
+        return { ok: false, reasons: ["not a status document (v1)"], freshness: null, ...policy };
+    const v2 = d.v === 2 ? v2Error(d) : null;
+    if (v2)
+        return { ok: false, reasons: [v2], freshness: null, ...policy };
+    const reasons = [];
+    if (!verifySignedObject(d) || d.signer !== d.issuer)
+        reasons.push("bad status document signature");
+    if (opts.schemeOwner !== undefined)
+        reasons.push(...signingIdentityReasons(opts.schemeOwner, [], [d.issuer]));
+    // Section 5b: with an issuer document listing successions, a later key of `issuer`'s lineage may sign.
+    const lineage = opts.issuerDoc === undefined ? null : issuerLineage(opts.issuerDoc);
+    if (lineage)
+        reasons.push(...lineage.reasons, ...compromisedKeyReasons(lineage, d.issuer, "status document"));
+    if (opts.issuer !== undefined && d.issuer !== opts.issuer && !succeeds(lineage, opts.issuer, d.issuer))
+        reasons.push("status document is from a different issuer");
+    for (const [k, e] of Object.entries(d.entries))
+        if (!isSha(k) || !entryOk(e, d.v)) {
+            reasons.push("status document has a malformed entry");
+            break;
+        }
+    if (("seq" in d || "prev" in d) && !logPositionOk(d.seq, d.prev))
+        reasons.push("status document has a malformed log position");
+    if ("pq_binding" in d && !isSha(d.pq_binding))
+        reasons.push("status document has a malformed pq_binding");
+    const now = opts.now ? ms(opts.now) : Date.now();
+    if (d.v === 2 && ((!Number.isFinite(now)) || ms(d.issued_at) > now))
+        reasons.push("status v2 reference time is invalid or issuance is in the future");
+    const freshness = (d.v === 2 ? ms(d.valid_until) > now : ms(d.valid_until) >= now) ? "fresh" : "stale";
+    if (freshness === "stale")
+        reasons.push(`status document expired on ${String(d.valid_until)}`);
+    if (opts.pq)
+        reasons.push(...verifyPqCosignature(d, opts.pq).reasons.map((r) => `status: ${r}`));
+    else if (opts.requirePq || pqPolicy === "required")
+        reasons.push(pqCommitment(d)
+            ? "status: no post-quantum co-signature supplied: a post-quantum signature is required"
+            : "status: document has no post-quantum co-signature: a post-quantum signature is required");
+    if (!opts.witness)
+        return { ok: reasons.length === 0, reasons, freshness, ...policy };
+    const w = witnessReasons(d, opts.witness);
+    reasons.push(...w.reasons);
+    return { ok: reasons.length === 0, reasons, freshness, witnesses: w.witnesses, ...policy };
+}
+/**
+ * §3: the @zanii/credentials revocation list for a status document: every certificate whose status
+ * is not valid, with the same issued_at and valid_until. Byte-identical to `buildRevocationList`
+ * with the issuer's key, so plain credential verifiers refuse suspended and revoked certificates.
+ */
+export async function revocationListFromStatus(doc, signer) {
+    if (doc.issuer !== signerDid(signer))
+        throw new Error("signer is not the status document issuer");
+    const unsigned = {
+        v: 1,
+        type: "revocation_list",
+        issuer: doc.issuer,
+        revoked: sortedUnique(Object.entries(doc.entries)
+            .filter(([, e]) => e.status !== "valid")
+            .map(([k]) => k)),
+        issued_at: doc.issued_at,
+        valid_until: doc.valid_until,
+    };
+    return { ...unsigned, sig: await signatureOver(unsigned, signer) };
+}

package/dist/succession.d.ts

@@ -0,0 +1,21 @@
+export interface IssuerLineage {
+    ok: boolean;
+    reasons: string[];
+    /** Oldest to newest issuer DID, ending at the issuer document's current DID. */
+    lineage: string[];
+    /** Each DID retired by a compromise succession, and its `compromised_at`. */
+    compromised: Record<string, string>;
+}
+/**
+ * Section 5a: the issuer document's succession chain (`successions`, signed by its `owner`), or
+ * null when it lists none. Every link is a valid @zanii/succession signed by the owner, a planned
+ * one (rotation, retirement) also by the old key, and the links run from the oldest issuer DID to
+ * `dids[0]`.
+ */
+export declare function issuerLineage(issuerDoc: unknown): IssuerLineage | null;
+/** Does a valid lineage lead from `from` to the later key `to`? */
+export declare const succeeds: (lin: IssuerLineage | null, from: unknown, to: unknown) => boolean;
+/** Current status authority cannot come from a compromised key, even with a backdated timestamp. */
+export declare const compromisedKeyReasons: (lin: IssuerLineage | null, did: unknown, what: string) => string[];
+/** The reason, when `did` was retired by a compromise and signed something dated at or after it. */
+export declare function afterCompromise(lin: IssuerLineage | null, did: unknown, at: unknown, what: string): string[];

package/dist/succession.js

@@ -0,0 +1,67 @@
+// spec/certificate.md section 5a: issuer key succession. The issuer document lists the
+// @zanii/succession documents from each old issuer DID to the next, signed by the lab owner key;
+// a verifier follows them from the key that signed a certificate to the key that signs status now.
+import { verifyLineage, verifySuccession } from "@zanii/succession";
+import { isDid, isIso, isObj, ms } from "./shared.js";
+import { signingIdentityReasons } from "./signing-identity.js";
+const MAX_SUCCESSIONS = 64;
+/**
+ * Section 5a: the issuer document's succession chain (`successions`, signed by its `owner`), or
+ * null when it lists none. Every link is a valid @zanii/succession signed by the owner, a planned
+ * one (rotation, retirement) also by the old key, and the links run from the oldest issuer DID to
+ * `dids[0]`.
+ */
+export function issuerLineage(issuerDoc) {
+    const doc = isObj(issuerDoc) ? issuerDoc : {};
+    if (doc.owner !== undefined) {
+        const reasons = signingIdentityReasons(doc.owner, doc.dids ?? [], doc.status_dids ?? []);
+        if (reasons.length)
+            return { ok: false, reasons, lineage: [], compromised: {} };
+    }
+    const list = doc.successions;
+    if (list === undefined || (Array.isArray(list) && list.length === 0))
+        return null;
+    const fail = (r) => ({ ok: false, reasons: [`issuer succession: ${r}`], lineage: [], compromised: {} });
+    if (!Array.isArray(list) || list.length > MAX_SUCCESSIONS)
+        return fail(`successions must be a list of at most ${MAX_SUCCESSIONS}`);
+    if (!isDid(doc.owner))
+        return fail("the issuer document names no owner for its successions");
+    const current = Array.isArray(doc.dids) ? doc.dids[0] : undefined;
+    if (!isDid(current))
+        return fail("the issuer document names no current issuer DID");
+    const reasons = [];
+    const compromised = {};
+    list.forEach((s, i) => {
+        if (!isObj(s) || !isObj(s.body) || !Array.isArray(s.signatures) || !s.signatures.every(isObj))
+            return reasons.push(`link ${i}: not a succession (v1)`);
+        const check = verifySuccession(s);
+        if (!check.ok)
+            return reasons.push(...check.reasons.map((r) => `link ${i}: ${r}`));
+        const b = s.body;
+        if (b.owner !== doc.owner)
+            reasons.push(`link ${i} is not signed by the issuer document's owner`);
+        if (b.reason === "compromise" && !isIso(b.compromised_at))
+            reasons.push(`link ${i}: compromised_at must be an ISO UTC timestamp`);
+        else if (b.reason === "compromise")
+            compromised[b.predecessor] = b.compromised_at;
+        else if (!check.cosigned)
+            reasons.push(`link ${i}: a planned succession must be countersigned by the old key`);
+    });
+    if (reasons.length)
+        return { ok: false, reasons: reasons.map((r) => `issuer succession: ${r}`), lineage: [], compromised: {} };
+    const lin = verifyLineage(list, current);
+    if (!lin.ok)
+        return { ok: false, reasons: lin.reasons.map((r) => `issuer succession: ${r}`), lineage: [], compromised: {} };
+    return { ok: true, reasons: [], lineage: lin.lineage, compromised };
+}
+/** Does a valid lineage lead from `from` to the later key `to`? */
+export const succeeds = (lin, from, to) => !!lin?.ok && typeof from === "string" && typeof to === "string" && lin.lineage.indexOf(from) >= 0 && lin.lineage.indexOf(to) > lin.lineage.indexOf(from);
+/** Current status authority cannot come from a compromised key, even with a backdated timestamp. */
+export const compromisedKeyReasons = (lin, did, what) => lin?.ok && typeof did === "string" && Object.hasOwn(lin.compromised, did) ? [`${what} is signed by a compromised issuer key`] : [];
+/** The reason, when `did` was retired by a compromise and signed something dated at or after it. */
+export function afterCompromise(lin, did, at, what) {
+    const t = lin?.ok && typeof did === "string" ? lin.compromised[did] : undefined;
+    if (t === undefined)
+        return [];
+    return ms(at) >= ms(t) || Number.isNaN(ms(at)) ? [`${what} was signed by the issuer key after its compromise at ${t}`] : [];
+}