@zanii/certify 0.0.0-stage → 0.6.0

package/dist/scheme-text.js

@@ -0,0 +1,46 @@
+import { jcsHash } from "@zanii/core";
+import { isObj, isSha } from "./shared.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+export const SCHEME_TEXT_MAX_BYTES = 4_194_304;
+const scheme = (value) => typeof value === "string" && /^zanii-certify\/(0|[1-9][0-9]{0,3})\.(0|[1-9][0-9]{0,3})$/.exec(value)?.[0] === value;
+const path = (value) => typeof value === "string" && /^[a-z0-9][a-z0-9._/-]{0,127}$/.exec(value)?.[0] === value && !value.endsWith("/") && value.split("/").every(part => part !== "" && part !== "." && part !== "..");
+const text = (value) => typeof value === "string" && value.length <= 524_288 && value.isWellFormed() && Buffer.byteLength(value, "utf8") <= 524_288 && !value.startsWith("\uFEFF") && !/[\x00-\x08\x0b-\x1f\x7f]/.test(value);
+function reasons(doc) {
+    if (!withinVerificationBudget(doc, { maxBytes: SCHEME_TEXT_MAX_BYTES, maxNodes: 1000, maxDepth: 4 }))
+        return ["scheme text exceeds its 4 MiB JSON budget"];
+    if (!isObj(doc) || Object.keys(doc).length !== 4 || doc.v !== 1 || doc.type !== "certify.scheme-text" || !scheme(doc.scheme) || !Array.isArray(doc.files) || doc.files.length < 1 || doc.files.length > 64)
+        return ["invalid scheme text bundle or file count"];
+    let previous = "";
+    for (const file of doc.files) {
+        if (!isObj(file) || Object.keys(file).length !== 2 || !path(file.path) || file.path <= previous || !text(file.text) || file.text.includes("\r"))
+            return ["scheme files must be sorted distinct relative paths and bounded UTF-8 text with LF endings"];
+        previous = file.path;
+    }
+    return [];
+}
+/** LF normalization is explicit; Unicode content is retained byte for byte otherwise. */
+export function buildSchemeTextBundle(input) {
+    if (!withinVerificationBudget(input, { maxBytes: SCHEME_TEXT_MAX_BYTES, maxNodes: 1000, maxDepth: 4 }) || !isObj(input) || Object.keys(input).length !== 2 || !scheme(input.scheme) || !Array.isArray(input.files) || input.files.length < 1 || input.files.length > 64)
+        throw new Error("invalid bounded scheme text input");
+    const files = input.files.map(file => { if (!isObj(file) || Object.keys(file).length !== 2 || !path(file.path) || typeof file.text !== "string")
+        throw new Error("invalid scheme file"); return { path: file.path, text: file.text.replace(/\r\n?/g, "\n") }; }).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const bundle = { v: 1, type: "certify.scheme-text", scheme: input.scheme, files }, bad = reasons(bundle);
+    if (bad.length)
+        throw new Error(bad[0]);
+    return bundle;
+}
+/** The released file is these canonical JSON bytes; a digest alone is not board approval. */
+export function schemeTextBundleHash(doc) { const bad = reasons(doc); if (bad.length)
+    throw new Error(bad[0]); return jcsHash(doc); }
+export function verifySchemeTextBundle(doc, expected) {
+    if (!isObj(expected) || Object.keys(expected).length !== 2 || !scheme(expected.scheme) || typeof expected.sha256 !== "string" || expected.sha256.length !== 71 || !isSha(expected.sha256))
+        return { ok: false, reasons: ["independently selected scheme and released digest are required"] };
+    const bad = reasons(doc);
+    if (bad.length)
+        return { ok: false, reasons: bad };
+    if (doc.scheme !== expected.scheme)
+        bad.push("scheme text names another scheme version");
+    if (jcsHash(doc) !== expected.sha256)
+        bad.push("scheme text does not match the released content digest");
+    return { ok: bad.length === 0, reasons: bad };
+}

package/dist/scheme-timing.d.ts

@@ -0,0 +1,16 @@
+export interface SchemeTimingPolicy {
+    v: 1;
+    type: "certify.scheme-timing-policy";
+    max_future_s: number;
+}
+export type SchemeTimingCode = "SCHEME_TIMING_POLICY" | "SCHEME_EFFECTIVE_INVALID" | "SCHEME_EFFECTIVE_PAST" | "SCHEME_EFFECTIVE_TOO_FAR";
+export interface SchemeTimingCheck {
+    ok: boolean;
+    codes: SchemeTimingCode[];
+    reasons: string[];
+}
+/** Check again under the append lock using the trusted commit clock. No clock skew allowance. */
+export declare function verifySchemeEffectiveTime(doc: unknown, opts: {
+    policy: unknown;
+    now: string;
+}): SchemeTimingCheck;

package/dist/scheme-timing.js

@@ -0,0 +1,22 @@
+// Admission policy for NEW owner submissions, never a reinterpretation of signed history.
+import { isInt, isIso, isObj, ms } from "./shared.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+const TYPES = ["certify.board", "certify.release", "certify.release-withdrawal", "certify.body-register"];
+/** Check again under the append lock using the trusted commit clock. No clock skew allowance. */
+export function verifySchemeEffectiveTime(doc, opts) {
+    const codes = [], reasons = [];
+    const fail = (code, reason) => { codes.push(code); reasons.push(reason); };
+    const p = opts?.policy;
+    if (!isObj(p) || Object.keys(p).length !== 3 || p.v !== 1 || p.type !== "certify.scheme-timing-policy" || !isInt(p.max_future_s, 1, 2_592_000))
+        fail("SCHEME_TIMING_POLICY", "a closed scheme timing policy with max_future_s from 1 to 2592000 is required");
+    if (!isIso(opts?.now) || !withinVerificationBudget(doc, { maxBytes: 1_048_576, maxNodes: 100_000 }) || !isObj(doc) || !TYPES.includes(doc.type) || !isIso(doc.effective_from))
+        fail("SCHEME_EFFECTIVE_INVALID", "a supported scheme entry, effective_from and trusted reference time are required");
+    if (!codes.length && isObj(doc) && isObj(p)) {
+        const delta = ms(doc.effective_from) - ms(opts.now);
+        if (delta < 0)
+            fail("SCHEME_EFFECTIVE_PAST", "effective_from must not precede the protected append time");
+        else if (delta > Number(p.max_future_s) * 1000)
+            fail("SCHEME_EFFECTIVE_TOO_FAR", "effective_from exceeds the scheme timing policy's future limit");
+    }
+    return { ok: codes.length === 0, codes, reasons };
+}

package/dist/scheme-transition.d.ts

@@ -0,0 +1,47 @@
+import { type BodySignature } from "./board.ts";
+import { type SchemeAppendStatement } from "./scheme-log.ts";
+import { type Signer } from "./signer.ts";
+export interface SchemeTransitionBody {
+    v: 1;
+    type: "certify.board-transition";
+    owner: string;
+    from: string;
+    to: string;
+    epoch: number;
+    at: string;
+    cancel: string[];
+}
+export type SchemeTransition = SchemeTransitionBody & {
+    signatures: BodySignature[];
+};
+export interface SchemeTransitionAnchor {
+    statement: SchemeAppendStatement;
+    append: unknown;
+    receipt: unknown;
+}
+export interface SchemeTransitionContext {
+    owner: string;
+    /** Authenticated newest board, exact proposed next board and next scheme-log position. */
+    board: unknown;
+    nextBoard: unknown;
+    index: number;
+    previousAt: string;
+    /** ONLY authenticated prefix entries. Canceled records remain in this history. */
+    entry: (hash: string) => unknown;
+    anchor: SchemeTransitionAnchor;
+    nextAnchor: SchemeTransitionAnchor;
+}
+export declare function buildSchemeTransition(fields: Omit<SchemeTransitionBody, "v" | "type">, signers: readonly Signer[]): Promise<SchemeTransition>;
+/** Strict effect verification: both authenticated append receipts are mandatory. */
+export declare function verifySchemeTransition(doc: unknown, c: SchemeTransitionContext): {
+    ok: boolean;
+    reasons: string[];
+    canceled: string[];
+};
+/** Admission only. This does NOT authorize cancellation or a new board before anchoring. */
+export declare function verifySchemeTransitionProposal(doc: unknown, c: Omit<SchemeTransitionContext, "anchor" | "nextAnchor"> & {
+    now: string;
+}): {
+    ok: boolean;
+    reasons: string[];
+};

package/dist/scheme-transition.js

@@ -0,0 +1,101 @@
+// An explicit anchored cancellation of future entries, followed immediately by one exact board.
+import { jcsHash } from "@zanii/core";
+import { boardFieldError, bodySignature, isBoard, isRelease, isWithdrawal, releaseFieldError, signersOf, withSignatures, withdrawalFieldError } from "./board.js";
+import { isBodyRegister, registerFieldError } from "./register.js";
+import { verifySchemeAppend } from "./scheme-log.js";
+import { isDid, isInt, isIso, isObj, isSha, ms } from "./shared.js";
+import {} from "./signer.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+function fieldError(d) {
+    if (!isObj(d) || Object.keys(d).length !== 9 || d.v !== 1 || d.type !== "certify.board-transition")
+        return "not a closed board-transition (v1)";
+    if (!isDid(d.owner) || !isSha(d.from) || !isSha(d.to) || !isInt(d.epoch, 1, Number.MAX_SAFE_INTEGER) || !isIso(d.at))
+        return "invalid transition authority, board binding, epoch or time";
+    if (!Array.isArray(d.cancel) || d.cancel.length < 1 || d.cancel.length > 100 || !d.cancel.every((h, i, xs) => isSha(h) && (i === 0 || xs[i - 1] < h)))
+        return "cancel must contain 1 to 100 sorted distinct entry hashes";
+    return null;
+}
+export async function buildSchemeTransition(fields, signers) {
+    if (!withinVerificationBudget(fields, { maxBytes: 32_768, maxNodes: 1_000 }) || !Array.isArray(signers) || signers.length < 1 || signers.length > 65)
+        throw new Error("transition exceeds its signing budget");
+    const body = { v: 1, type: "certify.board-transition", owner: fields.owner, from: fields.from, to: fields.to, epoch: fields.epoch, at: fields.at, cancel: Array.isArray(fields.cancel) ? [...fields.cancel] : fields.cancel };
+    const err = fieldError({ ...body, signatures: [] });
+    if (err)
+        throw new Error(err);
+    return withSignatures(body, await Promise.all(signers.map((s) => bodySignature(body, s))));
+}
+/** The caller must atomically accept this entry and its immediately following exact next board. */
+function transitionCheck(doc, c, proposalNow) {
+    const reasons = [];
+    const out = () => ({ ok: reasons.length === 0, reasons, canceled: reasons.length || !isObj(doc) ? [] : [...doc.cancel] });
+    if (!withinVerificationBudget(doc, { maxBytes: 65_536, maxNodes: 3_000 }) || !withinVerificationBudget(c?.board, { maxBytes: 65_536, maxNodes: 3_000 }) || !withinVerificationBudget(c?.nextBoard, { maxBytes: 65_536, maxNodes: 3_000 }) || proposalNow === undefined && (!withinVerificationBudget(c?.anchor, { maxBytes: 655_360, maxNodes: 60_000 }) || !withinVerificationBudget(c?.nextAnchor, { maxBytes: 655_360, maxNodes: 60_000 })))
+        return { ok: false, reasons: ["board transition exceeds the verification budget"], canceled: [] };
+    const err = fieldError(doc);
+    if (err || !isObj(doc))
+        return { ok: false, reasons: [err], canceled: [] };
+    const b = c?.board, next = c?.nextBoard;
+    if (!isDid(c?.owner) || doc.owner !== c.owner || !isBoard(b) || boardFieldError(b) || b.owner !== c.owner || !isBoard(next) || boardFieldError(next) || next.owner !== c.owner)
+        return { ok: false, reasons: ["trusted outgoing and next boards are required"], canceled: [] };
+    if (doc.from !== jcsHash(b) || doc.to !== jcsHash(next) || doc.epoch !== next.seq || next.seq !== Number(b.seq) + 1 || next.prev !== doc.from)
+        reasons.push("transition is not bound to the exact outgoing and next board epoch");
+    if (!isDid(b.ledger) || next.ledger !== b.ledger)
+        reasons.push("transition requires the same explicit ledger identity on both boards");
+    if (!(ms(next.effective_from) > ms(b.effective_from)))
+        reasons.push("next board does not take effect after the outgoing board");
+    if (!isIso(c.previousAt))
+        reasons.push("the authenticated previous append time is required");
+    const allowed = [c.owner, ...b.members];
+    const signed = signersOf(doc, allowed), members = signed.signers.filter((s) => b.members.includes(s));
+    if (!signed.wellFormed || !signed.signers.includes(c.owner) || members.length < Number(b.threshold))
+        reasons.push("transition requires the owner and outgoing board threshold signatures");
+    const nextSigned = signersOf(next, b.members);
+    if (!nextSigned.wellFormed || nextSigned.signers.length < Number(b.threshold))
+        reasons.push("next board is not signed by the outgoing threshold");
+    let anchoredAt = proposalNow ?? "";
+    if (proposalNow !== undefined && (!isIso(proposalNow) || ms(proposalNow) < ms(doc.at) || ms(proposalNow) - ms(doc.at) > 60_000))
+        reasons.push("transition proposal must be within 60 seconds after its authorization time");
+    if (proposalNow === undefined) {
+        for (const [offset, target, a] of [[0, doc, c.anchor], [1, next, c.nextAnchor]]) {
+            if (!a || !isObj(a.statement) || Object.keys(a.statement).length !== 7 || a.statement.v !== 1 || a.statement.type !== "certify.scheme-append" || !isInt(c.index, 1, Number.MAX_SAFE_INTEGER - 2) || a.statement?.index !== c.index + offset || a.statement?.size !== c.index + offset + 1 || a.statement?.log !== c.owner || a.statement?.entry !== jcsHash(target) || !isSha(a.statement?.root))
+                reasons.push("authenticated transition and next-board appends at the exact prefix positions are required");
+            else
+                reasons.push(...verifySchemeAppend(a.statement, target, a.append, a.receipt, { ledger: b.ledger }).reasons);
+            if (!isObj(a?.receipt) || a.receipt.v !== 1 || a.receipt.action !== "certify.scheme-append" || a.receipt.target !== `certify.scheme/${c.index + offset}`)
+                reasons.push("transition anchor receipt has another purpose or target");
+            const time = isObj(a?.append) ? a.append.anchored_at : undefined;
+            if (!isIso(time) || ms(time) < ms(doc.at) || ms(time) - ms(doc.at) > 60_000 || ms(time) < ms(c.previousAt) || anchoredAt && ms(time) < ms(anchoredAt))
+                reasons.push("transition anchors must be ordered within 60 seconds after their authorization time");
+            if (isIso(time))
+                anchoredAt = time;
+        }
+    }
+    if (!isIso(anchoredAt) || ms(next.effective_from) < ms(anchoredAt))
+        reasons.push("next board takes effect before the authenticated transition anchors");
+    for (const hash of doc.cancel) {
+        let entry;
+        try {
+            entry = c.entry(hash);
+        }
+        catch {
+            reasons.push("transition prefix lookup failed");
+            break;
+        }
+        if (!withinVerificationBudget(entry, { maxBytes: 1_048_576, maxNodes: 100_000 }) || !isObj(entry)) {
+            reasons.push("cancellation target is absent from the authenticated prefix");
+            continue;
+        }
+        const invalid = isRelease(entry) ? releaseFieldError(entry) : isWithdrawal(entry) ? withdrawalFieldError(entry) : isBodyRegister(entry) ? registerFieldError(entry) : "not cancellable";
+        if (invalid || jcsHash(entry) !== hash || entry.board !== doc.from)
+            reasons.push("cancellation target is not an outgoing-board release, withdrawal or register");
+        if (!isIso(anchoredAt) || !(ms(entry.effective_from) > ms(anchoredAt)))
+            reasons.push("cancellation target is already effective at the authenticated transition anchor");
+    }
+    return out();
+}
+/** Strict effect verification: both authenticated append receipts are mandatory. */
+export function verifySchemeTransition(doc, c) { return transitionCheck(doc, c); }
+/** Admission only. This does NOT authorize cancellation or a new board before anchoring. */
+export function verifySchemeTransitionProposal(doc, c) {
+    const { ok, reasons } = transitionCheck(doc, c, c?.now ?? "");
+    return { ok, reasons };
+}

package/dist/scoring.d.ts

@@ -0,0 +1,35 @@
+export type Verdict = "pass" | "fail" | "inconclusive";
+export interface CategoryScore {
+    rate_ppm: number;
+    low_ppm: number;
+    high_ppm: number;
+    verdict: Verdict;
+}
+/** Section 1: the 95% Wilson range of `passes` in `trials`, judged against `thresholdPpm`. */
+export declare function scoreCategory(passes: number, trials: number, thresholdPpm: number): CategoryScore;
+export interface ScoredResult {
+    category: string;
+    trials: number;
+    threshold_ppm: number;
+    verdict: Verdict;
+}
+export interface ProfileCategoryRule {
+    id: string;
+    required_levels: number[];
+    min_trials: number;
+    threshold_ppm: number;
+}
+export interface Overall {
+    pass: boolean;
+    /** Codes `<RULE>:<category>` (or `LEVEL_NOT_IN_PROFILE`), sorted. Empty on a pass. */
+    reasons: string[];
+}
+/**
+ * Section 2: pass only when the level is in the profile and every category the profile requires
+ * at that level is present, passes, ran at least min_trials and was judged at a threshold no
+ * lower than the profile's.
+ */
+export declare function overallVerdict(results: readonly ScoredResult[], profile: {
+    levels: number[];
+    categories: readonly ProfileCategoryRule[];
+}, level: number): Overall;

package/dist/scoring.js

@@ -0,0 +1,50 @@
+// spec/scoring.md: per-category verdicts from repeated trials, and the overall pass rule.
+import { successRange } from "@zanii/blackbox";
+import { isInt } from "./shared.js";
+/** Section 1: the 95% Wilson range of `passes` in `trials`, judged against `thresholdPpm`. */
+export function scoreCategory(passes, trials, thresholdPpm) {
+    if (!isInt(trials, 1, 1_000_000))
+        throw new Error("trials must be an integer 1-1000000");
+    if (!isInt(passes, 0, trials))
+        throw new Error("passes must be an integer 0-trials");
+    if (!isInt(thresholdPpm, 0, 1_000_000))
+        throw new Error("threshold_ppm must be 0-1000000");
+    const [low, high] = successRange(passes, trials);
+    const verdict = low >= thresholdPpm ? "pass" : high < thresholdPpm ? "fail" : "inconclusive";
+    return {
+        rate_ppm: Math.floor((passes * 1_000_000) / trials),
+        low_ppm: low,
+        high_ppm: high,
+        verdict,
+    };
+}
+/**
+ * Section 2: pass only when the level is in the profile and every category the profile requires
+ * at that level is present, passes, ran at least min_trials and was judged at a threshold no
+ * lower than the profile's.
+ */
+export function overallVerdict(results, profile, level) {
+    const reasons = [];
+    if (!profile.levels.includes(level))
+        reasons.push("LEVEL_NOT_IN_PROFILE");
+    const by = new Map(results.map((r) => [r.category, r]));
+    for (const c of profile.categories) {
+        if (!c.required_levels.includes(level))
+            continue;
+        const r = by.get(c.id);
+        if (!r) {
+            reasons.push(`CATEGORY_MISSING:${c.id}`);
+            continue;
+        }
+        if (r.trials < c.min_trials)
+            reasons.push(`TOO_FEW_TRIALS:${c.id}`);
+        if (r.threshold_ppm < c.threshold_ppm)
+            reasons.push(`THRESHOLD_BELOW_PROFILE:${c.id}`);
+        if (r.verdict === "fail")
+            reasons.push(`CATEGORY_FAILED:${c.id}`);
+        if (r.verdict === "inconclusive")
+            reasons.push(`CATEGORY_INCONCLUSIVE:${c.id}`);
+    }
+    reasons.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return { pass: reasons.length === 0, reasons };
+}

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>;