@zanii/certify 0.0.0-stage → 0.6.0

package/dist/federation.js

@@ -0,0 +1,240 @@
+// spec/federation.md: each instance (UAE, KSA, a licensee) publishes a signed, append-only feed of
+// its certificates and their status, checkpointed like the status log; the public registry verifies
+// every feed and merges them, reporting conflicts between feeds and never resolving them.
+import { canonicalBytes, createSTHAsync, jcsHash, leafHash, merkleRoot, verifySignedObject, verifySTH } from "@zanii/core";
+import { isDid, isInt, isIso, isObj, isSha, ms, SLUG, sortedUnique } from "./shared.js";
+import { signerDid, signWith } from "./signer.js";
+import { logPositionOk } from "./status.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+const PROFILE_REF = new RegExp(`^${SLUG.source.slice(1, -1)}/[1-9][0-9]*$`);
+const STATUSES = ["valid", "suspended", "revoked"];
+/** Section 1: the most entries one page carries. */
+export const MAX_FEED_ENTRIES = 10_000;
+export const MAX_FEED_PAGE_BYTES = 4 * 1024 * 1024;
+const entryOk = (e) => isObj(e) && Object.keys(e).length === 6 && isSha(e.certificate) && typeof e.profile === "string" && e.profile.length <= 128 && PROFILE_REF.test(e.profile) &&
+    isInt(e.level, 1, 3) && STATUSES.includes(e.status) && isIso(e.since) && (e.licence === null || isSha(e.licence));
+export { entryOk as isFeedEntry };
+function pageError(p) {
+    if (typeof p.instance !== "string" || !SLUG.test(p.instance))
+        return "instance must be a slug";
+    if (typeof p.region !== "string" || !SLUG.test(p.region))
+        return "region must be a slug";
+    const i = p.issuers;
+    if (!Array.isArray(i) || i.length < 1 || i.length > 16 || !i.every(isDid) || sortedUnique(i).join("\n") !== i.join("\n"))
+        return "issuers must be 1 to 16 sorted, distinct did:keys";
+    if (!logPositionOk(p.seq, p.prev))
+        return "seq and prev are not a log position";
+    const e = p.entries;
+    if (!Array.isArray(e) || e.length > MAX_FEED_ENTRIES || !e.every(entryOk))
+        return `entries must be up to ${MAX_FEED_ENTRIES} well formed entries`;
+    if (e.some((x, n) => n > 0 && !(x.certificate > e[n - 1].certificate)))
+        return "entries must be sorted by certificate, each once";
+    if (!isIso(p.issued_at))
+        return "issued_at must be an ISO timestamp";
+    return null;
+}
+/** Section 1: one feed page, signed by one of the instance's issuers. */
+export async function buildFeedPage(f, signer) {
+    if (Array.isArray(f.entries) && f.entries.length > MAX_FEED_ENTRIES)
+        throw new Error(`entries must be up to ${MAX_FEED_ENTRIES} well formed entries`);
+    if (!withinVerificationBudget(f, { maxBytes: MAX_FEED_PAGE_BYTES - 1024, maxNodes: 150_000 }))
+        throw new Error("the feed page exceeds the verification byte/depth budget");
+    const entries = Array.isArray(f.entries)
+        ? f.entries
+            .map((e) => ({ certificate: e?.certificate, profile: e?.profile, level: e?.level, status: e?.status, since: e?.since, licence: e?.licence }))
+            .sort((a, b) => (a.certificate < b.certificate ? -1 : a.certificate > b.certificate ? 1 : 0))
+        : f.entries;
+    const unsigned = {
+        v: 1,
+        type: "certify.feed",
+        instance: f.instance,
+        region: f.region,
+        issuers: Array.isArray(f.issuers) ? sortedUnique(f.issuers) : f.issuers,
+        seq: f.seq,
+        prev: f.prev,
+        entries,
+        issued_at: f.issuedAt,
+    };
+    const err = pageError(unsigned);
+    if (err)
+        throw new Error(err);
+    if (!unsigned.issuers.includes(signerDid(signer)))
+        throw new Error("a feed page is signed by one of its issuers");
+    return signWith(unsigned, signer);
+}
+const leaves = (pages) => pages.map((p) => leafHash(canonicalBytes(p)));
+const rootOf = (pages) => `sha256:${Buffer.from(merkleRoot(leaves(pages))).toString("hex")}`;
+/** Validate one extension using authenticated prior certificate state, without reloading its history. */
+export function verifyFeedPage(page, opts) {
+    const i = opts.cursor.size;
+    const bad = (reason) => ({ ok: false, reasons: [`feed page ${i} ${reason}`], entries: [] });
+    if (!isInt(i, 0, Number.MAX_SAFE_INTEGER) || i > 0 && (!isSha(opts.cursor.last_hash) || !isIso(opts.cursor.last_issued_at) || typeof opts.cursor.region !== "string"))
+        return bad("has an invalid authenticated cursor");
+    if (!withinVerificationBudget(page, { maxBytes: MAX_FEED_PAGE_BYTES, maxNodes: 150_000 }))
+        return bad("exceeds the verification byte/depth budget");
+    if (!isObj(page) || page.v !== 1 || page.type !== "certify.feed" || Object.keys(page).length !== 11)
+        return bad("is not a signed feed page");
+    const malformed = pageError(page);
+    if (malformed)
+        return bad(`is malformed: ${malformed}`);
+    if (!verifySignedObject(page))
+        return bad("is not a signed feed page");
+    const p = page, before = opts.cursor;
+    const reasons = [];
+    if (!p.issuers.includes(p.signer))
+        reasons.push(`feed page ${i} is not signed by one of its issuers`);
+    if (!opts.issuers.includes(p.signer))
+        reasons.push(`feed page ${i} is not signed by a trusted instance issuer`);
+    if (p.seq !== i)
+        reasons.push(`feed page ${i} is not at position ${i}`);
+    if (p.prev !== before.last_hash)
+        reasons.push(`feed page ${i} does not name the previous page`);
+    if (p.instance !== before.instance)
+        reasons.push(`feed page ${i} is of instance ${p.instance}, not ${before.instance}`);
+    else if (before.region !== null && p.region !== before.region)
+        reasons.push(`feed page ${i} is for another instance or region`);
+    if (before.last_issued_at !== null && ms(p.issued_at) < ms(before.last_issued_at))
+        reasons.push(`feed page ${i} is older than the previous page`);
+    if (reasons.length)
+        return { ok: false, reasons, entries: [] };
+    for (const entry of p.entries) {
+        const was = opts.entry(entry.certificate);
+        if (!was)
+            continue;
+        if (was.profile !== entry.profile || was.level !== entry.level || was.licence !== entry.licence)
+            reasons.push(`feed page ${i} changes the profile, level or licence of ${entry.certificate}`);
+        if (ms(entry.since) < ms(was.since))
+            reasons.push(`feed page ${i} moves ${entry.certificate} back in time`);
+        if (was.status === "revoked" && entry.status !== "revoked")
+            reasons.push(`feed page ${i} changes revoked certificate ${entry.certificate}`);
+    }
+    return { ok: !reasons.length, reasons, entries: reasons.length ? [] : p.entries };
+}
+/** Section 2: the signed tree head over the feed (leaf i = page i), by the issuer that signed the last page. */
+export async function feedCheckpoint(pages, ts, signer) {
+    if (!withinVerificationBudget(pages))
+        throw new Error("the feed exceeds the verification byte/depth budget");
+    const check = verifyFeed(pages, { issuers: sortedUnique(pages.flatMap((p) => (isObj(p) && Array.isArray(p.issuers) ? p.issuers : []))) });
+    if (!check.ok)
+        throw new Error(check.reasons[0]);
+    if (!pages.at(-1).issuers.includes(signerDid(signer)))
+        throw new Error("signer is not an issuer of the feed");
+    if (!isIso(ts) || ms(ts) < ms(pages.at(-1).issued_at))
+        throw new Error("ts must be an ISO UTC timestamp, not before the last page");
+    return createSTHAsync({ logId: signerDid(signer), size: pages.length, root: rootOf(pages), ts }, signer.sign);
+}
+/**
+ * Section 1 and 2: the pages form one feed of one instance and region (page i at seq i naming page
+ * i - 1, issued_at never going back, each signed by one of its issuers and, with `issuers`, by a
+ * trusted one); a certificate keeps its profile, level and licence, its `since` never goes back and
+ * a revoked certificate stays revoked. With `checkpoint`, it is a tree head over exactly these pages
+ * signed by an issuer of the last page.
+ */
+export function verifyFeed(pages, opts = {}) {
+    if (!withinVerificationBudget(pages))
+        return { ok: false, reasons: ["the feed exceeds the verification byte/depth budget"], entries: [] };
+    if (!Array.isArray(pages) || pages.length === 0)
+        return { ok: false, reasons: ["the feed is empty"], entries: [] };
+    const reasons = [];
+    const state = new Map();
+    const first = isObj(pages[0]) ? pages[0] : {};
+    pages.forEach((p, i) => {
+        if (!withinVerificationBudget(p, { maxBytes: MAX_FEED_PAGE_BYTES, maxNodes: 150_000 })) {
+            reasons.push(`feed page ${i} exceeds the verification byte/depth budget`);
+            return;
+        }
+        const prev = i > 0 ? pages[i - 1] : null;
+        if (!isObj(p) || p.v !== 1 || p.type !== "certify.feed" || Object.keys(p).length !== 11 || !verifySignedObject(p)) {
+            reasons.push(`feed page ${i} is not a signed feed page`);
+            return;
+        }
+        const err = pageError(p);
+        if (err) {
+            reasons.push(`feed page ${i} is malformed: ${err}`);
+            return;
+        }
+        if (!p.issuers.includes(p.signer))
+            reasons.push(`feed page ${i} is not signed by one of its issuers`);
+        if (opts.issuers && !opts.issuers.includes(p.signer))
+            reasons.push(`feed page ${i} is not signed by a trusted instance issuer`);
+        if (p.seq !== i)
+            reasons.push(`feed page ${i} is not at position ${i}`);
+        if (p.prev !== (i > 0 ? jcsHash(prev) : null))
+            reasons.push(`feed page ${i} does not name the previous page`);
+        if (p.instance !== first.instance || p.region !== first.region)
+            reasons.push(`feed page ${i} is for another instance or region`);
+        if (i > 0 && isObj(prev) && !(ms(p.issued_at) >= ms(prev.issued_at)))
+            reasons.push(`feed page ${i} is older than the previous page`);
+        for (const e of p.entries) {
+            const was = state.get(e.certificate);
+            if (was) {
+                if (was.profile !== e.profile || was.level !== e.level || was.licence !== e.licence)
+                    reasons.push(`feed page ${i} changes the profile, level or licence of ${e.certificate}`);
+                if (!(ms(e.since) >= ms(was.since)))
+                    reasons.push(`feed page ${i} moves ${e.certificate} back in time`);
+                if (was.status === "revoked" && e.status !== "revoked")
+                    reasons.push(`feed page ${i} changes revoked certificate ${e.certificate}`);
+            }
+            state.set(e.certificate, e);
+        }
+    });
+    if (!opts.issuers)
+        reasons.push("no trusted instance issuers supplied: the signer was NOT checked");
+    if (opts.checkpoint !== undefined) {
+        const cp = opts.checkpoint;
+        const last = pages.at(-1);
+        const signers = isObj(last) && Array.isArray(last.issuers) ? last.issuers : [];
+        if (!isObj(cp) || !signers.includes(cp.log_id) || !verifySTH(cp))
+            reasons.push("feed checkpoint is not signed by an issuer of the feed");
+        else if (cp.size !== pages.length || cp.root !== rootOf(pages))
+            reasons.push("feed checkpoint is not over this feed");
+    }
+    const entries = [...state.values()].sort((a, b) => (a.certificate < b.certificate ? -1 : 1));
+    return { ok: reasons.length === 0, reasons, entries };
+}
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * Section 3: verify each feed and merge them. A feed that does not verify is rejected; an instance
+ * id published by two feeds, an issuer DID authenticated by signed pages of two instances and a certificate listed by two
+ * instances are conflicts. Conflicting instances, issuers and certificates are left out of `entries`.
+ */
+export function mergeFeeds(feeds) {
+    if (!withinVerificationBudget(feeds))
+        return { entries: [], conflicts: [], rejected: [{ instance: "", reasons: ["the federation merge exceeds the verification byte/depth budget"] }] };
+    const rejected = [];
+    const ok = [];
+    for (const f of feeds) {
+        const pages = Array.isArray(f?.pages) ? f.pages : [];
+        const head = isObj(pages[0]) ? pages[0] : {};
+        const instance = typeof head.instance === "string" ? head.instance : "";
+        const check = verifyFeed(pages, { issuers: f?.issuers ?? [], ...(f?.checkpoint !== undefined ? { checkpoint: f.checkpoint } : {}) });
+        if (!check.ok)
+            rejected.push({ instance, reasons: check.reasons });
+        else {
+            ok.push({ instance, region: head.region, authenticatedIssuers: [...new Set(pages.map((p) => p.signer))], entries: check.entries });
+        }
+    }
+    const conflicts = [];
+    const group = (kind, pairs) => {
+        const by = new Map();
+        for (const [id, inst] of pairs)
+            by.set(id, [...(by.get(id) ?? []), inst]);
+        for (const [id, insts] of by)
+            if (insts.length > 1)
+                conflicts.push({ kind, id, instances: insts.sort(cmp) });
+    };
+    group("instance", ok.map((f) => [f.instance, f.instance]));
+    const twice = new Set(conflicts.map((c) => c.id));
+    const kept = ok.filter((f) => !twice.has(f.instance));
+    group("issuer", kept.flatMap((f) => f.authenticatedIssuers.map((d) => [d, f.instance])));
+    group("certificate", kept.flatMap((f) => f.entries.map((e) => [e.certificate, f.instance])));
+    const contestedIssuers = new Set(conflicts.filter((c) => c.kind === "issuer").map((c) => c.id));
+    const contested = new Set(conflicts.filter((c) => c.kind === "certificate").map((c) => c.id));
+    const entries = kept.filter((f) => !f.authenticatedIssuers.some((d) => contestedIssuers.has(d)))
+        .flatMap((f) => f.entries.filter((e) => !contested.has(e.certificate)).map((e) => ({ ...e, instance: f.instance, region: f.region })))
+        .sort((a, b) => cmp(a.certificate, b.certificate));
+    const order = { instance: 0, issuer: 1, certificate: 2 };
+    conflicts.sort((a, b) => order[a.kind] - order[b.kind] || cmp(a.id, b.id));
+    rejected.sort((a, b) => cmp(a.instance, b.instance));
+    return { entries, conflicts, rejected };
+}

package/dist/feed-snapshot.d.ts

@@ -0,0 +1,97 @@
+import { type SignedTreeHead } from "@zanii/core";
+import { type FeedEntry, type FeedPage } from "./federation.ts";
+import { type Signer } from "./signer.ts";
+export declare const FEED_SNAPSHOT_CHUNK_ENTRIES = 100;
+export declare const MAX_FEED_SNAPSHOT_BYTES = 4259840;
+export declare const MAX_FEED_SNAPSHOT_CHUNK_BYTES = 262144;
+export interface FeedSnapshotNode {
+    level: number;
+    index: number;
+    hash: string;
+}
+export interface FeedSnapshotManifest {
+    v: 1;
+    type: "certify.feed-snapshot";
+    mode: "current-state-attestation";
+    instance: string;
+    region: string;
+    feed_checkpoint: SignedTreeHead;
+    head_page: FeedPage;
+    head_proof: string[];
+    frontier: FeedSnapshotNode[];
+    state_root: string;
+    chunk_count: number;
+    entry_count: number;
+    created_at: string;
+    signer: string;
+    sig: string;
+}
+/** Authenticated header returned only after manifest verification; callers persist it with the accepted manifest. */
+export interface FeedSnapshotHeader {
+    id: string;
+    instance: string;
+    region: string;
+    feed_checkpoint: SignedTreeHead;
+    head_hash: string;
+    last_issued_at: string;
+    last_issuers: string[];
+    frontier: FeedSnapshotNode[];
+    state_root: string;
+    chunk_count: number;
+    entry_count: number;
+    head_entries: readonly FeedEntry[];
+}
+export interface FeedSnapshotCursor {
+    snapshot: string;
+    next_chunk: number;
+    entry_count: number;
+    last_certificate: string | null;
+    complete: boolean;
+}
+export interface FeedSnapshotChunk {
+    snapshot: string;
+    index: number;
+    entries: FeedEntry[];
+    proof: string[];
+}
+/** The complete RFC subtrees covering a prefix, left to right, with exact positions. */
+export declare function feedSnapshotFrontier(size: number, get: (level: number, index: number) => string | undefined): FeedSnapshotNode[];
+export declare function buildFeedSnapshot(f: {
+    instance: string;
+    region: string;
+    checkpoint: SignedTreeHead;
+    head: FeedPage;
+    headProof: string[];
+    frontier: FeedSnapshotNode[];
+    stateRoot: string;
+    chunkCount: number;
+    entryCount: number;
+    createdAt: string;
+}, signer: Signer): Promise<FeedSnapshotManifest>;
+export declare function verifyFeedSnapshot(doc: unknown, opts: {
+    issuers: readonly string[];
+    instance: string;
+    previous?: {
+        checkpoint: SignedTreeHead;
+        proof: unknown;
+    };
+}): {
+    ok: boolean;
+    reasons: string[];
+    header?: FeedSnapshotHeader;
+};
+export declare const feedSnapshotCursor: (header: FeedSnapshotHeader) => FeedSnapshotCursor;
+export declare function feedSnapshotChunkHash(index: number, entries: readonly FeedEntry[]): string;
+/** A verified manifest header and an authenticated prior-state range lookup are mandatory.
+ * knownInRange returns ALL prior entries in (after,through], or the tail when through=null, up to101.
+ * More than100 proves a100-entry chunk omitted known state, so no full-history array is needed. */
+export declare function verifyFeedSnapshotChunk(chunk: unknown, opts: {
+    header: FeedSnapshotHeader;
+    cursor: FeedSnapshotCursor;
+    knownInRange: (after: string | null, through: string | null) => readonly FeedEntry[];
+}): {
+    ok: boolean;
+    reasons: string[];
+    entries: FeedEntry[];
+    cursor?: FeedSnapshotCursor;
+};

package/dist/feed-snapshot.js

@@ -0,0 +1,186 @@
+// Optional current-state attestation. This authenticates the publisher's summarized state; it
+// does NOT claim the verifier replayed historical deltas. Original feeds remain independently usable.
+import { createHash } from "node:crypto";
+import { canonicalBytes, jcsHash, leafHash, verifyConsistency, verifyInclusion, verifySignedObject, verifySTH } from "@zanii/core";
+import { isFeedEntry, verifyFeedPage } from "./federation.js";
+import { isDid, isInt, isIso, isObj, isSha, ms, SLUG } from "./shared.js";
+import { signerDid, signWith } from "./signer.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+export const FEED_SNAPSHOT_CHUNK_ENTRIES = 100;
+export const MAX_FEED_SNAPSHOT_BYTES = 4_259_840;
+export const MAX_FEED_SNAPSHOT_CHUNK_BYTES = 262_144;
+const HEX = /^[0-9a-f]{64}$/, hex = (value) => Buffer.from(value).toString("hex");
+const bytes = (value) => new Uint8Array(Buffer.from(value.replace(/^sha256:/, ""), "hex"));
+const proofShape = (value) => Array.isArray(value) && value.length <= 64 && value.every((h) => typeof h === "string" && HEX.test(h));
+const join = (left, right) => createHash("sha256").update(Buffer.from([1])).update(bytes(left)).update(bytes(right)).digest("hex");
+const widthOf = (remaining) => { let width = 1; while (width * 2 <= remaining)
+    width *= 2; return width; };
+/** The complete RFC subtrees covering a prefix, left to right, with exact positions. */
+export function feedSnapshotFrontier(size, get) {
+    if (!isInt(size, 1, Number.MAX_SAFE_INTEGER))
+        throw new Error("snapshot prefix size is invalid");
+    const out = [];
+    let start = 0, remaining = size;
+    while (remaining) {
+        const width = widthOf(remaining), level = Math.log2(width), index = start / width, hash = get(level, index);
+        if (!hash || !HEX.test(hash))
+            throw new Error("snapshot frontier subtree is missing");
+        out.push({ level, index, hash });
+        start += width;
+        remaining -= width;
+    }
+    return out;
+}
+function frontierRoot(size, value) {
+    if (!isInt(size, 1, Number.MAX_SAFE_INTEGER) || !Array.isArray(value) || value.length < 1 || value.length > 53)
+        return null;
+    let start = 0, remaining = size;
+    const hashes = [];
+    for (const node of value) {
+        const width = widthOf(remaining), level = Math.log2(width);
+        if (!remaining || !isObj(node) || Object.keys(node).length !== 3 || node.level !== level || node.index !== start / width || typeof node.hash !== "string" || !HEX.test(node.hash))
+            return null;
+        hashes.push(node.hash);
+        start += width;
+        remaining -= width;
+    }
+    if (remaining)
+        return null;
+    let root = hashes.pop();
+    while (hashes.length)
+        root = join(hashes.pop(), root);
+    return `sha256:${root}`;
+}
+function manifestReasons(doc, issuers, signature = true) {
+    if (!withinVerificationBudget(doc, { maxBytes: MAX_FEED_SNAPSHOT_BYTES, maxNodes: 175_000 }))
+        return ["snapshot manifest exceeds the JSON verification budget"];
+    if (!isObj(doc) || Object.keys(doc).length !== (signature ? 15 : 13) || doc.v !== 1 || doc.type !== "certify.feed-snapshot" || doc.mode !== "current-state-attestation")
+        return ["not a current-state snapshot manifest (v1)"];
+    if (!Array.isArray(issuers) || issuers.length < 1 || issuers.length > 16 || !issuers.every(isDid))
+        return ["snapshot requires independently trusted instance issuers"];
+    if (typeof doc.instance !== "string" || !SLUG.test(doc.instance) || typeof doc.region !== "string" || !SLUG.test(doc.region)
+        || !isInt(doc.chunk_count, 1, Number.MAX_SAFE_INTEGER) || !isInt(doc.entry_count, 0, Number.MAX_SAFE_INTEGER) || !isSha(doc.state_root) || !isIso(doc.created_at))
+        return ["snapshot manifest fields are malformed"];
+    if (signature && (!issuers.includes(doc.signer) || !verifySignedObject(doc)))
+        return ["snapshot is not signed by an independently trusted instance issuer"];
+    const cp = doc.feed_checkpoint, head = doc.head_page;
+    if (!isObj(cp) || !verifySTH(cp) || !issuers.includes(cp.log_id) || !isInt(cp.size, 1, Number.MAX_SAFE_INTEGER) || !isSha(cp.root))
+        return ["snapshot feed checkpoint is not independently trusted"];
+    if (!isObj(head) || head.instance !== doc.instance || head.region !== doc.region || head.seq !== cp.size - 1 || !Array.isArray(head.issuers) || !head.issuers.includes(cp.log_id))
+        return ["snapshot head does not match its checkpoint"];
+    const page = verifyFeedPage(head, { issuers, cursor: { instance: doc.instance, region: head.region, size: head.seq, last_hash: head.prev, last_issued_at: head.seq ? head.issued_at : null }, entry: () => undefined });
+    if (!page.ok)
+        return ["snapshot head page is invalid", ...page.reasons];
+    if (ms(cp.ts) < ms(head.issued_at))
+        return ["snapshot feed checkpoint precedes its authenticated head page"];
+    if (!proofShape(doc.head_proof) || !verifyInclusion(leafHash(canonicalBytes(head)), head.seq, cp.size, doc.head_proof.map(bytes), bytes(cp.root)))
+        return ["snapshot head is not included in its feed checkpoint"];
+    if (frontierRoot(cp.size, doc.frontier) !== cp.root)
+        return ["snapshot frontier does not authenticate its feed prefix"];
+    if (ms(doc.created_at) < ms(cp.ts) || ms(doc.created_at) < ms(head.issued_at))
+        return ["snapshot creation time precedes its feed checkpoint"];
+    if (Number(doc.chunk_count) > Math.max(1, Number(doc.entry_count)) || Number(doc.entry_count) > Number(doc.chunk_count) * FEED_SNAPSHOT_CHUNK_ENTRIES)
+        return ["snapshot chunk and entry counts disagree"];
+    return [];
+}
+export async function buildFeedSnapshot(f, signer) {
+    const body = { v: 1, type: "certify.feed-snapshot", mode: "current-state-attestation", instance: f.instance, region: f.region,
+        feed_checkpoint: f.checkpoint, head_page: f.head, head_proof: f.headProof, frontier: f.frontier, state_root: f.stateRoot,
+        chunk_count: f.chunkCount, entry_count: f.entryCount, created_at: f.createdAt };
+    if (!withinVerificationBudget(body, { maxBytes: MAX_FEED_SNAPSHOT_BYTES - 1024, maxNodes: 175_000 }))
+        throw new Error("snapshot manifest exceeds the JSON verification budget");
+    const trusted = [...new Set([...f.head.issuers, signerDid(signer)])], bad = manifestReasons(body, trusted, false);
+    if (bad.length)
+        throw new Error(bad[0]);
+    return signWith(body, signer);
+}
+export function verifyFeedSnapshot(doc, opts) {
+    const reasons = manifestReasons(doc, opts.issuers);
+    if (reasons.length)
+        return { ok: false, reasons };
+    const manifest = doc, cp = manifest.feed_checkpoint;
+    if (manifest.instance !== opts.instance)
+        reasons.push("snapshot belongs to another instance");
+    if (opts.previous) {
+        const old = opts.previous.checkpoint;
+        if (!old || !verifySTH(old) || !opts.issuers.includes(old.log_id) || old.size > cp.size || !proofShape(opts.previous.proof)
+            || !verifyConsistency(old.size, cp.size, bytes(old.root), bytes(cp.root), opts.previous.proof.map(bytes)))
+            reasons.push("snapshot does not extend the retained feed checkpoint");
+    }
+    if (reasons.length)
+        return { ok: false, reasons };
+    return { ok: true, reasons, header: { id: jcsHash(manifest), instance: manifest.instance, region: manifest.region, feed_checkpoint: cp,
+            head_hash: jcsHash(manifest.head_page), last_issued_at: manifest.head_page.issued_at, last_issuers: [...manifest.head_page.issuers],
+            frontier: manifest.frontier.map((n) => ({ ...n })), state_root: manifest.state_root, chunk_count: manifest.chunk_count, entry_count: manifest.entry_count, head_entries: manifest.head_page.entries } };
+}
+export const feedSnapshotCursor = (header) => ({ snapshot: header.id, next_chunk: 0, entry_count: 0, last_certificate: null, complete: false });
+export function feedSnapshotChunkHash(index, entries) {
+    if (!isInt(index, 0, Number.MAX_SAFE_INTEGER) || !Array.isArray(entries) || entries.length > FEED_SNAPSHOT_CHUNK_ENTRIES || !entries.every(isFeedEntry)
+        || !withinVerificationBudget(entries, { maxBytes: MAX_FEED_SNAPSHOT_CHUNK_BYTES, maxNodes: 10_000 }))
+        throw new Error("snapshot chunk is malformed or exceeds its byte budget");
+    return hex(leafHash(canonicalBytes({ index, entries })));
+}
+/** A verified manifest header and an authenticated prior-state range lookup are mandatory.
+ * knownInRange returns ALL prior entries in (after,through], or the tail when through=null, up to101.
+ * More than100 proves a100-entry chunk omitted known state, so no full-history array is needed. */
+export function verifyFeedSnapshotChunk(chunk, opts) {
+    const out = (reason) => ({ ok: false, reasons: [reason], entries: [] });
+    if (!withinVerificationBudget(chunk, { maxBytes: MAX_FEED_SNAPSHOT_CHUNK_BYTES, maxNodes: 10_000 }))
+        return out("snapshot chunk exceeds the JSON verification budget");
+    const { header: h, cursor: c } = opts;
+    if (!isObj(chunk) || Object.keys(chunk).length !== 4 || chunk.snapshot !== h.id || chunk.index !== c.next_chunk || c.snapshot !== h.id || c.complete
+        || !isInt(c.next_chunk, 0, h.chunk_count - 1) || !isInt(c.entry_count, 0, h.entry_count) || c.last_certificate !== null && !isSha(c.last_certificate))
+        return out("snapshot chunk does not extend its cursor");
+    const entries = chunk.entries;
+    if (!Array.isArray(entries) || entries.length > FEED_SNAPSHOT_CHUNK_ENTRIES || !entries.every(isFeedEntry) || !proofShape(chunk.proof)
+        || !entries.length && !(h.chunk_count === 1 && h.entry_count === 0) || entries.some((e, i) => e.certificate <= (i ? entries[i - 1].certificate : c.last_certificate ?? "")))
+        return out("snapshot entries are malformed or out of order");
+    if (entries.some((entry) => ms(entry.since) > ms(h.last_issued_at)))
+        return out("snapshot certificate state is newer than its authenticated feed prefix");
+    if (!verifyInclusion(bytes(feedSnapshotChunkHash(c.next_chunk, entries)), c.next_chunk, h.chunk_count, chunk.proof.map(bytes), bytes(h.state_root)))
+        return out("snapshot chunk is not included in its signed state root");
+    const last = entries.at(-1)?.certificate ?? c.last_certificate, known = opts.knownInRange(c.last_certificate, last);
+    if (!Array.isArray(known) || known.length > FEED_SNAPSHOT_CHUNK_ENTRIES || !known.every(isFeedEntry))
+        return out("snapshot omits known certificate state");
+    const current = new Map(entries.map((entry) => [entry.certificate, entry]));
+    const bound = (key) => {
+        if (key === null)
+            return 0;
+        let lo = 0, hi = h.head_entries.length;
+        while (lo < hi) {
+            const middle = Math.floor((lo + hi) / 2);
+            if (h.head_entries[middle].certificate <= key)
+                lo = middle + 1;
+            else
+                hi = middle;
+        }
+        return lo;
+    };
+    const headStart = bound(c.last_certificate), headEnd = last === null ? h.head_entries.length : bound(last);
+    if (headEnd - headStart > 100)
+        return out("snapshot omits state from its authenticated head page");
+    for (let i = headStart; i < headEnd; i++) {
+        const expected = h.head_entries[i], entry = current.get(expected.certificate);
+        if (!entry || ["profile", "level", "licence", "status", "since"].some((key) => entry[key] !== expected[key]))
+            return out("snapshot contradicts its authenticated head page");
+    }
+    for (const prior of known) {
+        const entry = current.get(prior.certificate);
+        if (!entry)
+            return out("snapshot omits known certificate state");
+        if (entry.profile !== prior.profile || entry.level !== prior.level || entry.licence !== prior.licence || ms(entry.since) < ms(prior.since)
+            || prior.status === "revoked" && entry.status !== "revoked")
+            return out("snapshot changes immutable or revoked certificate state");
+    }
+    const complete = c.next_chunk + 1 === h.chunk_count, count = c.entry_count + entries.length;
+    if (count > h.entry_count || complete && count !== h.entry_count)
+        return out("snapshot entry count does not match its manifest");
+    if (complete) {
+        const tail = opts.knownInRange(last, null);
+        if (!Array.isArray(tail) || tail.length)
+            return out("snapshot omits known certificate state after its final chunk");
+        if (bound(last) < h.head_entries.length)
+            return out("snapshot omits state from its authenticated head page");
+    }
+    return { ok: true, reasons: [], entries, cursor: { snapshot: h.id, next_chunk: c.next_chunk + 1, entry_count: count, last_certificate: last, complete } };
+}

package/dist/fingerprint.d.ts

@@ -0,0 +1,23 @@
+import { promptSha256 } from "@zanii/blackbox";
+export { promptSha256 };
+export interface FingerprintInput {
+    model: string;
+    prompt: string | null;
+    tools: string | null;
+    policy: string | null;
+    knowledge: string | null;
+}
+export interface Fingerprint extends FingerprintInput {
+    v: 1;
+    type: "certify.fingerprint";
+    configuration: string;
+    id: string;
+}
+/** `sha256:<hex>` of raw bytes (a policy or knowledge pack file). Strings are UTF-8. */
+export declare function sha256Bytes(data: Uint8Array | string): string;
+/** The Blackbox gateway's `tools_sha256` for these tool definitions; null when there are none. */
+export declare function toolsSha256(definitions: readonly unknown[]): string | null;
+/** Build a fingerprint. Throws on a malformed input. */
+export declare function buildFingerprint(input: FingerprintInput): Fingerprint;
+/** Is this a well-formed fingerprint whose configuration and id recompute? Never throws. */
+export declare function checkFingerprint(fp: unknown): fp is Fingerprint;

package/dist/fingerprint.js

@@ -0,0 +1,48 @@
+// spec/fingerprint.md: the agent fingerprint a certificate is bound to.
+import { createHash } from "node:crypto";
+import { configurationId, promptSha256, toolsHash } from "@zanii/blackbox";
+import { jcsHash } from "@zanii/core";
+import { isObj, isSha } from "./shared.js";
+export { promptSha256 };
+const PARTS = ["prompt", "tools", "policy", "knowledge"];
+/** `sha256:<hex>` of raw bytes (a policy or knowledge pack file). Strings are UTF-8. */
+export function sha256Bytes(data) {
+    return `sha256:${createHash("sha256").update(data).digest("hex")}`;
+}
+/** The Blackbox gateway's `tools_sha256` for these tool definitions; null when there are none. */
+export function toolsSha256(definitions) {
+    return toolsHash({ tools: definitions });
+}
+/** Build a fingerprint. Throws on a malformed input. */
+export function buildFingerprint(input) {
+    if (typeof input.model !== "string" || input.model.length < 1 || input.model.length > 200)
+        throw new Error("model must be 1-200 characters");
+    for (const k of PARTS)
+        if (input[k] !== null && !isSha(input[k]))
+            throw new Error(`${k} must be sha256: and 64 hex, or null`);
+    const body = {
+        v: 1,
+        type: "certify.fingerprint",
+        model: input.model,
+        prompt: input.prompt,
+        tools: input.tools,
+        policy: input.policy,
+        knowledge: input.knowledge,
+        configuration: configurationId(input.prompt, input.tools, input.model),
+    };
+    return { ...body, id: jcsHash(body) };
+}
+/** Is this a well-formed fingerprint whose configuration and id recompute? Never throws. */
+export function checkFingerprint(fp) {
+    if (!isObj(fp) || fp.v !== 1 || fp.type !== "certify.fingerprint")
+        return false;
+    if (Object.keys(fp).length !== 9)
+        return false;
+    try {
+        const again = buildFingerprint(fp);
+        return again.configuration === fp.configuration && again.id === fp.id;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/formats/status-v2.schema.json

@@ -0,0 +1,31 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://zanii.agency/certify/formats/status-v2.schema.json",
+    "title": "Zanii Certify status version 2",
+    "$comment": "Use a complete draft 2020-12 validator for this standalone format schema. SDK verification additionally checks actual DIDs, signatures, cross-field times, trust, PQ and witness policy.",
+    "type": "object",
+    "required": ["v", "type", "issuer", "entries", "issued_at", "valid_until", "signer", "sig"],
+    "additionalProperties": false,
+    "properties": {
+        "v": { "const": 2 }, "type": { "const": "certify.status" },
+        "issuer": { "$ref": "#/$defs/did" }, "signer": { "$ref": "#/$defs/did" },
+        "sig": { "type": "string", "pattern": "^ed25519:[0-9a-f]{128}$", "maxLength": 136 },
+        "issued_at": { "$ref": "#/$defs/time" }, "valid_until": { "$ref": "#/$defs/time" },
+        "entries": { "type": "object", "maxProperties": 100000, "patternProperties": { "^sha256:[0-9a-f]{64}$": { "$ref": "#/$defs/entry" } }, "additionalProperties": false },
+        "seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+        "prev": { "anyOf": [{ "type": "null" }, { "$ref": "#/$defs/hash" }] },
+        "pq_binding": { "$ref": "#/$defs/hash" }
+    },
+    "dependentRequired": { "seq": ["prev"], "prev": ["seq"] },
+    "allOf": [{ "if": { "required": ["seq"], "properties": { "seq": { "const": 0 } } }, "then": { "properties": { "prev": { "type": "null" } } }, "else": { "properties": { "prev": { "$ref": "#/$defs/hash" } } } }],
+    "$defs": {
+        "did": { "type": "string", "pattern": "^did:key:z[1-9A-HJ-NP-Za-km-z]{40,60}$", "maxLength": 69 },
+        "hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "maxLength": 71 },
+        "time": { "type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{3})?Z$", "maxLength": 24 },
+        "reason": { "enum": ["FINGERPRINT_MISMATCH", "RETEST_OVERDUE", "RETEST_FAILED", "INCIDENT", "APPLICANT_REQUEST", "ISSUER_ERROR", "LICENCE_WITHDRAWN", "AUDIT_EXPIRED", "MARK_MISUSE"] },
+        "entry": { "type": "object", "required": ["status", "reason", "since"], "additionalProperties": false,
+            "properties": { "status": { "enum": ["valid", "suspended", "revoked"] }, "reason": { "anyOf": [{ "type": "null" }, { "$ref": "#/$defs/reason" }] }, "since": { "$ref": "#/$defs/time" } },
+            "oneOf": [{ "properties": { "status": { "const": "valid" }, "reason": { "type": "null" } } }, { "properties": { "status": { "enum": ["suspended", "revoked"] }, "reason": { "$ref": "#/$defs/reason" } } }]
+        }
+    }
+}