@zanii/certify 0.0.0-stage → 0.6.0

package/dist/evidence-share.js

@@ -0,0 +1,479 @@
+// spec/evidence-share.md: evidence shared outside the lab. Customer identifiers and configured
+// secrets are replaced by keyed tokens (Blackbox identifier detection and fingerprints), and every
+// entry is committed field by field (@zanii/redact) so the receiver checks what it was shown
+// against the chain heads without seeing what was removed.
+import { createHmac, hkdfSync } from "node:crypto";
+import { CORE_IDENTIFIERS, canaryIdentifier, dataFingerprint, luhn, normalizeValue } from "@zanii/blackbox";
+import { canonicalBytes, jcsHash, leafHash, merkleRoot, verifySignedObject } from "@zanii/core";
+import { flattenJson, verifyDisclosure } from "@zanii/redact";
+import { isIso, isObj, isSha, sortedUnique } from "./shared.js";
+import { signWith } from "./signer.js";
+import { withinVerificationBudget } from "./verification-bounds.js";
+const SHARE_SOURCE_BYTES = 8_388_608, SHARE_ENTRY_BYTES = 2_097_152, SHARE_FIELDS = 50_000, SHARE_ENTRY_FIELDS = 4096;
+const sourceBudget = (value, maxBytes = SHARE_SOURCE_BYTES) => withinVerificationBudget(value, { maxBytes, maxDepth: 24, maxNodes: 250_000 });
+const redactionOptionsBudget = (opts) => withinVerificationBudget({ secrets: opts.secrets ?? [], kinds: opts.kinds ?? [], withhold: opts.withhold ?? [] }, { maxBytes: 65_536, maxDepth: 4, maxNodes: 4096 });
+/** Section 1: the GCC formats Blackbox's core identifiers do not cover. */
+export const GCC_IDENTIFIERS = [
+    { id: "emirates_id", title: "Emirates ID", pattern: "(?<![0-9])784[ -]?[0-9]{4}[ -]?[0-9]{7}[ -]?[0-9](?![0-9])", normalize: "digits", personal: true },
+    {
+        id: "phone_gcc",
+        title: "Phone number (GCC)",
+        pattern: "(?<![0-9+])(?:(?:\\+|00)(?:971|966|965|974|973|968)[ -]?[0-9](?:[ -]?[0-9]){6,8}|05[0-9](?:[ -]?[0-9]){7})(?![0-9])",
+        normalize: "digits",
+        personal: true,
+    },
+    {
+        id: "passport",
+        title: "Passport number",
+        pattern: "(?:[Pp]assport|PASSPORT|جواز(?: السفر)?)(?: (?:[Nn]o\\.?|[Nn]umber|رقم))?[ :#]{0,3}([A-Z0-9]{6,9})(?![A-Za-z0-9])",
+        normalize: "upper",
+        personal: true,
+        group: 1,
+    },
+];
+const byId = new Map([...CORE_IDENTIFIERS, ...GCC_IDENTIFIERS].map((i) => [i.id, i]));
+/** Section 1: earlier kinds win an overlapping span; secrets come before all of them. */
+const ORDER = ["emirates_id", "card", "iban", "email", "phone_e164", "phone_gcc", "passport"];
+/** Section 1: every identifier kind `redactEvidence` knows, sorted. */
+export const REDACTION_KINDS = sortedUnique(ORDER);
+const TENANT = "certify.evidence-share";
+const TOKEN = /\[redacted:[a-z0-9_]{1,32}:[0-9a-f]{32}\]/;
+/** Top-level entry fields that are the chain's own links, never redacted. */
+const LINKS = new Set(["seq", "prev", "hash"]);
+const keyBytes = (key) => (typeof key === "string" ? Buffer.from(key, "utf8") : key);
+/** Section 1: the token key and the salt key: the redaction key itself (version 1), or HKDF-SHA256 of it under the run's seed. */
+function keysOf(opts) {
+    if (!(typeof opts.key === "string" || opts.key instanceof Uint8Array) || keyBytes(opts.key).length < 16)
+        throw new Error("key must be at least 16 bytes");
+    const seed = opts.saltSeed;
+    if (seed === undefined)
+        return { token: opts.key, salt: opts.key };
+    if (!(seed instanceof Uint8Array) || seed.length !== 32)
+        throw new Error("saltSeed must be 32 bytes");
+    const derive = (label) => new Uint8Array(hkdfSync("sha256", keyBytes(opts.key), seed, label, 32));
+    return { token: derive("certify-evidence-token-v2"), salt: derive("certify-evidence-salt-v2") };
+}
+function identifiersOf(opts) {
+    const kinds = opts.kinds ?? REDACTION_KINDS;
+    if (!Array.isArray(kinds) || !kinds.every((k) => REDACTION_KINDS.includes(k)))
+        throw new Error(`kinds must be among ${REDACTION_KINDS.join(", ")}`);
+    const secrets = opts.secrets ?? [];
+    if (!Array.isArray(secrets) || !secrets.every((s) => typeof s === "string"))
+        throw new Error("secrets must be strings");
+    const out = secrets.some((s) => s !== "") ? [{ ...canaryIdentifier(secrets), id: "secret", title: "Configured secret" }] : [];
+    return [...out, ...ORDER.filter((k) => kinds.includes(k)).map((k) => byId.get(k))];
+}
+function withholdOf(opts) {
+    const w = opts.withhold ?? [];
+    if (!Array.isArray(w) || !w.every((p) => typeof p === "string" && /^\/./.test(p)))
+        throw new Error("withhold must be RFC 6901 pointers");
+    return [...w];
+}
+/** Section 1: Unicode spaces as a space, and a dot or slash between two digits as a space (one code unit for one). */
+const SPACES = /[   -   　]/g;
+const DIGIT_SEPARATOR = /(?<=[0-9])[./](?=[0-9])/g;
+const fold = (s) => s.replace(SPACES, " ").replace(DIGIT_SEPARATOR, " ");
+const asciiDigits = (s) => s.replace(/[٠-٩]/g, (c) => String.fromCharCode(c.charCodeAt(0) - 0x0660 + 48)).replace(/[۰-۹]/g, (c) => String.fromCharCode(c.charCodeAt(0) - 0x06f0 + 48));
+/** Section 1: wrapped values: percent-encoded runs (holding a `%XX`) and base64 tokens of 8 to 1024 characters. */
+const PERCENT_RUN = /(?:[A-Za-z0-9._~+-]|%[0-9A-Fa-f]{2})+/g;
+const JSON_ESCAPE_RUN = /(?:[A-Za-z0-9._~+-]|\\u[0-9A-Fa-f]{4})+/g;
+const QUOTED_PRINTABLE_RUN = /(?:[A-Za-z0-9._~+-]|=[0-9A-Fa-f]{2}|=\r?\n)+/g;
+const HTML_ENTITY_RUN = /(?:[A-Za-z0-9._~+-]|&(?:#(?:[xX][0-9A-Fa-f]{1,6}|[0-9]{1,7});?|[A-Za-z][A-Za-z0-9]{1,31};))+/g;
+const HEX_RUN = /(?<![0-9A-Fa-f])(?:[0-9A-Fa-f]{2}){4,512}(?![0-9A-Fa-f])/g;
+const BASE64_RUN = /(?<![A-Za-z0-9+/=_-])[A-Za-z0-9+/_-]{8,1024}={0,2}(?![A-Za-z0-9+/=_-])/g;
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+const HTML_ASCII = {
+    AMP: "&", DiacriticalGrave: "`", GT: ">", Hat: "^", LT: "<", MediumSpace: "\u205f", NewLine: "\n", NonBreakingSpace: "\u00a0", QUOT: "\"", Tab: "\t", UnderBar: "_", VerticalLine: "|",
+    ThinSpace: "\u2009", VeryThinSpace: "\u200a", amp: "&", apos: "'", ast: "*", bsol: "\\", colon: ":", comma: ",", commat: "@", dollar: "$", emsp: "\u2003", emsp13: "\u2004", emsp14: "\u2005", ensp: "\u2002", equals: "=", excl: "!", grave: "`", gt: ">", hairsp: "\u200a", lbrace: "{", lbrack: "[", lcub: "{", lowbar: "_", lpar: "(", lsqb: "[", lt: "<", midast: "*", nbsp: "\u00a0", num: "#", numsp: "\u2007", percnt: "%", period: ".", plus: "+", puncsp: "\u2008", quest: "?", quot: "\"", rbrace: "}", rbrack: "]", rcub: "}", rpar: ")", rsqb: "]", semi: ";", sol: "/", thinsp: "\u2009", verbar: "|", vert: "|",
+};
+function strictText(bytes) {
+    try {
+        return utf8.decode(Uint8Array.from(bytes));
+    }
+    catch {
+        return null;
+    }
+}
+/** Base64, standard or URL-safe, padding optional, the unused bits zero, as strict UTF-8; else null. */
+function unBase64(s) {
+    const body = s.replace(/=+$/, "");
+    if (body.length % 4 === 1)
+        return null;
+    const out = [];
+    let acc = 0;
+    let bits = 0;
+    for (const ch of body) {
+        acc = (acc << 6) | B64.indexOf(ch === "-" ? "+" : ch === "_" ? "/" : ch);
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out.push((acc >> bits) & 255);
+        }
+        acc &= (1 << bits) - 1;
+    }
+    return acc === 0 ? strictText(out) : null;
+}
+/** A percent-encoded run's bytes as strict UTF-8; else null. */
+function unPercent(s) {
+    const out = [];
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === "%") {
+            out.push(Number.parseInt(s.slice(i + 1, i + 3), 16));
+            i += 2;
+        }
+        else
+            out.push(s.charCodeAt(i));
+    }
+    return strictText(out);
+}
+function unJsonEscapes(s) {
+    return s.includes("\\u") ? s.replace(/\\u([0-9A-Fa-f]{4})/g, (_m, hex) => String.fromCharCode(Number.parseInt(hex, 16))) : null;
+}
+function unQuotedPrintable(s) {
+    if (!/=[0-9A-Fa-f]{2}|=\r?\n/.test(s))
+        return null;
+    const out = [];
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] !== "=")
+            out.push(s.charCodeAt(i));
+        else if (s[i + 1] === "\r" || s[i + 1] === "\n")
+            i += s[i + 1] === "\r" ? 2 : 1;
+        else {
+            out.push(Number.parseInt(s.slice(i + 1, i + 3), 16));
+            i += 2;
+        }
+    }
+    return strictText(out);
+}
+function unHex(s) {
+    if (s.length % 2)
+        return null;
+    const out = [];
+    for (let i = 0; i < s.length; i += 2)
+        out.push(Number.parseInt(s.slice(i, i + 2), 16));
+    return strictText(out);
+}
+function unHtml(s) {
+    if (!s.includes("&"))
+        return null;
+    return s.replace(/&(?:#(?:[xX][0-9A-Fa-f]{1,6}|[0-9]{1,7});?|[A-Za-z][A-Za-z0-9]{1,31};)/g, (ref) => {
+        const numeric = /^&#([xX]?)([0-9A-Fa-f]+);?$/.exec(ref);
+        if (numeric) {
+            const point = Number.parseInt(numeric[2], numeric[1] ? 16 : 10);
+            return point > 0 && point <= 0x10ffff && !(point >= 0xd800 && point <= 0xdfff) ? String.fromCodePoint(point) : "\ufffd";
+        }
+        return HTML_ASCII[ref.slice(1, -1)] ?? ref;
+    });
+}
+const overlaps = (spans, start, end) => spans.some(([a, b]) => start < b && end > a);
+const tokenOf = (key, kind, value) => `[redacted:${kind}:${dataFingerprint(key, TENANT, kind, value).slice(3)}]`;
+/** Section 1: the matches in one text, kind by kind, then kind by kind in its folded form where it differs. */
+function matches(text, idents) {
+    const spans = [];
+    for (const t of new Set([text, asciiDigits(text), fold(text), fold(asciiDigits(text))]))
+        for (const ident of idents)
+            for (const m of t.matchAll(new RegExp(ident.pattern, ident.group ? "gd" : "g"))) {
+                const [start, end] = ident.group ? m.indices[1] : [m.index, m.index + m[0].length];
+                if (end === start || overlaps(spans, start, end))
+                    continue;
+                const value = normalizeValue(asciiDigits(text.slice(start, end)), ident.normalize);
+                if (value === "" || (ident.check === "luhn" && !luhn(value)))
+                    continue;
+                spans.push([start, end, ident.id, value]);
+            }
+    return spans;
+}
+const wrappers = [[PERCENT_RUN, unPercent, true], [JSON_ESCAPE_RUN, unJsonEscapes, false], [QUOTED_PRINTABLE_RUN, unQuotedPrintable, false], [HTML_ENTITY_RUN, unHtml, false], [HEX_RUN, unHex, false], [BASE64_RUN, unBase64, false]];
+function redactTextAt(text, idents, key, counts, depth) {
+    const taken = matches(text, idents);
+    const spans = taken.map(([a, b, kind, value]) => {
+        counts[kind] = (counts[kind] ?? 0) + 1;
+        return [a, b, tokenOf(key, kind, value)];
+    });
+    if (depth < 2)
+        for (const [re, decode, percent] of wrappers)
+            for (const m of text.matchAll(re)) {
+                const [start, end] = [m.index, m.index + m[0].length];
+                if ((percent && !m[0].includes("%")) || overlaps(taken, start, end))
+                    continue;
+                const inner = decode(m[0]);
+                if (inner === null)
+                    continue;
+                const redacted = redactTextAt(inner, idents, key, counts, depth + 1);
+                if (!redacted.changed)
+                    continue;
+                taken.push([start, end, "", ""]);
+                spans.push([start, end, redacted.text]);
+            }
+    let out = text;
+    for (const [a, b, t] of spans.sort((x, y) => y[0] - x[0]))
+        out = out.slice(0, a) + t + out.slice(b);
+    return { text: out, changed: spans.length > 0 };
+}
+/** Section 1: one string with every direct or wrapped match replaced; counts added to `counts`. */
+function redactText(text, idents, key, counts) {
+    return redactTextAt(text, idents, key, counts, 0).text;
+}
+const escapePointer = (k) => k.replace(/~/g, "~0").replace(/\//g, "~1");
+/** Section 1: each leaf of a withheld field as a `withheld` token of its JCS text; containers stay, so the fields are the same. */
+function withheldValue(v, key, counts) {
+    if (Array.isArray(v) && v.length)
+        return v.map((x) => withheldValue(x, key, counts));
+    if (isObj(v) && Object.keys(v).length)
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, withheldValue(x, key, counts)]));
+    counts.withheld = (counts.withheld ?? 0) + 1;
+    return tokenOf(key, "withheld", Buffer.from(canonicalBytes(v)).toString("utf8"));
+}
+function redactValue(v, w, at) {
+    if (w.withhold.includes(at))
+        return withheldValue(v, w.key, w.counts);
+    if (typeof v === "string")
+        return redactText(v, w.idents, w.key, w.counts);
+    if (Array.isArray(v))
+        return v.map((x, i) => redactValue(x, w, `${at}/${i}`));
+    if (isObj(v))
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, redactValue(x, w, `${at}/${escapePointer(k)}`)]));
+    return v;
+}
+const sortCounts = (c) => Object.fromEntries(sortedUnique(Object.keys(c)).map((k) => [k, c[k]]));
+/**
+ * Section 1: the entries with every identifier of the chosen kinds and every configured secret
+ * replaced by a keyed token, in every string value (the top-level `seq`, `prev` and `hash` are
+ * kept), every withheld field replaced whole, and how many of each kind were replaced.
+ */
+export function redactEvidence(entries, opts) {
+    if (!sourceBudget(entries) || !redactionOptionsBudget(opts))
+        throw new Error("evidence share source exceeds its JSON budget");
+    const w = { key: keysOf(opts).token, idents: identifiersOf(opts), withhold: withholdOf(opts), counts: {} };
+    if (!Array.isArray(entries) || !entries.every(isObj))
+        throw new Error("entries must be objects");
+    const out = entries.map((e) => Object.fromEntries(Object.entries(e).map(([k, v]) => [k, LINKS.has(k) ? v : redactValue(v, w, `/${escapePointer(k)}`)])));
+    return { entries: out, redactions: sortCounts(w.counts) };
+}
+// ---------------------------------------------------------------- 2. the share
+export const AUDIENCES = ["reviewer", "regulator", "applicant"];
+const CHAIN = /^[A-Za-z0-9._:-]{1,128}$/;
+const MAX_ITEMS = 10_000;
+const hex = (b) => Buffer.from(b).toString("hex");
+const hmacHex = (key, data) => createHmac("sha256", keyBytes(key)).update(data).digest("hex");
+const same = (a, b) => Buffer.from(canonicalBytes(a)).equals(Buffer.from(canonicalBytes(b)));
+const withoutHash = (e) => Object.fromEntries(Object.entries(e).filter(([k]) => k !== "hash"));
+/** Section 2: the chain rules: seq from 0, each prev the hash before (null first), each hash the entry's jcsHash. */
+function chainError(chain, entries) {
+    if (!CHAIN.test(chain))
+        return "chain must match ^[A-Za-z0-9._:-]{1,128}$";
+    if (!Array.isArray(entries) || entries.length < 1)
+        return `chain ${chain} has no entries`;
+    for (const [i, e] of entries.entries()) {
+        if (!isObj(e) || e.seq !== i || e.prev !== (i === 0 ? null : entries[i - 1].hash) || !isSha(e.hash) || e.hash !== jcsHash(withoutHash(e)))
+            return `chain ${chain} entry ${i} does not chain: seq, prev or hash`;
+    }
+    return null;
+}
+/**
+ * Section 2: @zanii/redact's commitment to the fields, with salts derived from the salt key (its
+ * `commit` draws random ones), so the share is reproducible while the salt key exists; the envelope
+ * and disclosures are @zanii/redact's and verify with its `verifyDisclosure`.
+ */
+function commitments(saltKey, chain, original) {
+    const fields = flattenJson(original);
+    const keys = sortedUnique(Object.keys(fields));
+    const salts = keys.map((k) => hmacHex(saltKey, `certify-evidence-salt\n${chain}\n${String(original.seq)}\n${k}`).slice(0, 32));
+    const leaves = keys.map((k, i) => leafHash(canonicalBytes(["zr-field-v1", k, fields[k], salts[i]])));
+    // Reuse each subtree across disclosures; rebuilding it per field made wide entries quadratic.
+    const levels = [leaves];
+    while (levels.at(-1).length > 1) {
+        const level = levels.at(-1);
+        const next = [];
+        for (let i = 0; i < level.length; i += 2)
+            next.push(i + 1 < level.length ? merkleRoot([level[i], level[i + 1]]) : level[i]);
+        levels.push(next);
+    }
+    const root = `sha256:${hex(levels.at(-1)[0])}`;
+    const disclose = (i) => {
+        const proof = [];
+        let at = i;
+        for (const level of levels.slice(0, -1)) {
+            const sibling = at % 2 ? at - 1 : at + 1;
+            if (sibling < level.length)
+                proof.push(hex(level[sibling]));
+            at = Math.floor(at / 2);
+        }
+        return { _zr: "sd-disclosure-v1", key: keys[i], value: fields[keys[i]], salt: salts[i], index: i, size: keys.length, proof, root };
+    };
+    return { fields, keys, root, disclose };
+}
+function commitEntry(saltKey, chain, original, redacted) {
+    const { fields, keys, root, disclose } = commitments(saltKey, chain, original);
+    const shown = flattenJson(redacted);
+    const disclosures = keys.flatMap((k, i) => (same(fields[k], shown[k]) ? [disclose(i)] : []));
+    return { envelope: { _zr: "sd-v1", root, keys }, disclosures };
+}
+/**
+ * Section 4: the @zanii/redact disclosure of one field (`pointer`) of an original chain entry, as a
+ * share built with the same key and seed committed it: a field the share hid, opened for one
+ * receiver. Throws when the entry has no such field.
+ */
+export function discloseEvidenceField(entry, chain, pointer, opts) {
+    if (!sourceBudget(entry, SHARE_ENTRY_BYTES))
+        throw new Error("evidence entry exceeds its JSON budget");
+    if (!isObj(entry) || typeof chain !== "string" || !CHAIN.test(chain))
+        throw new Error("entry must be an object and chain a chain id");
+    if (Object.keys(flattenJson(entry)).length > SHARE_ENTRY_FIELDS)
+        throw new Error("evidence entry exceeds its field budget");
+    const c = commitments(keysOf(opts).salt, chain, entry);
+    const i = c.keys.indexOf(pointer);
+    if (i < 0)
+        throw new Error(`the entry has no field ${pointer}`);
+    return c.disclose(i);
+}
+/** Section 2: redact whole evidence chains and sign them, with their heads and commitments, for one audience. */
+export async function buildEvidenceShare(f, signer) {
+    return signWith(buildEvidenceShareDraft(f), signer);
+}
+/** Internal detached-signing stage used by the server's bounded private broker worker. */
+export function buildEvidenceShareDraft(f) {
+    if (!AUDIENCES.includes(f.audience))
+        throw new Error(`audience must be one of ${AUDIENCES.join(", ")}`);
+    if (!isIso(f.sharedAt))
+        throw new Error("sharedAt must be an ISO UTC timestamp");
+    if (!Array.isArray(f.chains) || f.chains.length < 1)
+        throw new Error("chains must list at least one chain");
+    if (f.chains.reduce((n, c) => n + (Array.isArray(c?.entries) ? c.entries.length : 0), 0) > MAX_ITEMS)
+        throw new Error(`at most ${MAX_ITEMS} entries`);
+    if (!sourceBudget(f.chains) || !redactionOptionsBudget(f))
+        throw new Error("evidence share source exceeds its JSON budget");
+    let fields = 0;
+    for (const chain of f.chains)
+        if (chain && Array.isArray(chain.entries))
+            for (const entry of chain.entries) {
+                if (!sourceBudget(entry, SHARE_ENTRY_BYTES))
+                    throw new Error("evidence entry exceeds its JSON budget");
+                const count = Object.keys(flattenJson(entry)).length;
+                fields += count;
+                if (count > SHARE_ENTRY_FIELDS || fields > SHARE_FIELDS)
+                    throw new Error("evidence share exceeds its field budget");
+            }
+    const chains = [...f.chains].sort((a, b) => (a.chain < b.chain ? -1 : a.chain > b.chain ? 1 : 0));
+    for (const [i, c] of chains.entries()) {
+        const err = chainError(c?.chain, c?.entries);
+        if (err)
+            throw new Error(err);
+        if (i > 0 && c.chain === chains[i - 1].chain)
+            throw new Error(`chain ${c.chain} is listed twice`);
+    }
+    const saltKey = keysOf(f).salt;
+    const counts = {};
+    const items = [];
+    for (const c of chains) {
+        const r = redactEvidence(c.entries, f);
+        for (const [k, n] of Object.entries(r.redactions))
+            counts[k] = (counts[k] ?? 0) + n;
+        c.entries.forEach((e, i) => items.push({ chain: c.chain, entry: r.entries[i], ...commitEntry(saltKey, c.chain, e, r.entries[i]) }));
+    }
+    const kinds = sortedUnique([
+        ...(f.kinds ?? REDACTION_KINDS),
+        ...((f.secrets ?? []).some((s) => s !== "") ? ["secret"] : []),
+        ...((f.withhold ?? []).length ? ["withheld"] : []),
+    ]);
+    const heads = chains.map((c) => ({ chain: c.chain, head: c.entries.at(-1).hash, size: c.entries.length }));
+    const doc = { v: 1, type: "certify.evidence-share", audience: f.audience, heads, kinds, redactions: sortCounts(counts), items, shared_at: f.sharedAt };
+    if (!withinVerificationBudget(doc, { maxBytes: 67_107_840 }))
+        throw new Error("evidence share exceeds its output JSON budget");
+    return doc;
+}
+const disclosureOk = (d, env) => {
+    try {
+        return verifyDisclosure(d, env);
+    }
+    catch {
+        return false;
+    }
+};
+/** Section 3: is every shared field committed, every other one a token, every chain whole and ending at its head? */
+function itemReasons(items, heads) {
+    const out = [];
+    let at = 0;
+    for (const h of heads) {
+        let prev = null;
+        for (let seq = 0; seq < h.size; seq++, at++) {
+            const it = items[at];
+            const label = `${h.chain} entry ${seq}`;
+            if (!isObj(it) || it.chain !== h.chain || !isObj(it.entry) || !isObj(it.envelope) || !Array.isArray(it.disclosures)) {
+                out.push(`${label} is missing or malformed`);
+                return out;
+            }
+            const env = it.envelope;
+            const shown = flattenJson(it.entry);
+            const keys = sortedUnique(Object.keys(shown));
+            if (env._zr !== "sd-v1" || !Array.isArray(env.keys) || keys.join("\n") !== env.keys.join("\n"))
+                out.push(`${label}: its fields are not the committed ones`);
+            const disclosed = new Set();
+            const offered = new Set();
+            let bad = false;
+            for (const d of it.disclosures) {
+                const k = isObj(d) && typeof d.key === "string" ? d.key : null;
+                if (k === null || offered.has(k) || !(k in shown) || !disclosureOk(d, env) || !same(d.value, shown[k]))
+                    bad = true;
+                else
+                    disclosed.add(k);
+                if (k !== null)
+                    offered.add(k);
+            }
+            if (bad)
+                out.push(`${label}: a disclosure does not verify against its commitment`);
+            for (const k of keys)
+                if (!offered.has(k) && !(typeof shown[k] === "string" && TOKEN.test(shown[k])))
+                    out.push(`${label}: field ${k} is neither disclosed nor redacted`);
+            const e = it.entry;
+            if (!disclosed.has("/seq") || !disclosed.has("/hash") || !disclosed.has("/prev") || e.seq !== seq || e.prev !== prev || !isSha(e.hash))
+                out.push(`${label}: seq, prev and hash must be disclosed and chain`);
+            prev = e.hash;
+        }
+        if (prev !== h.head)
+            out.push(`chain ${h.chain} does not end at its head`);
+    }
+    if (at !== items.length)
+        out.push("items hold entries of no listed chain");
+    return out;
+}
+const headOk = (h) => isObj(h) && Object.keys(h).length === 3 && typeof h.chain === "string" && CHAIN.test(h.chain) && isSha(h.head) && Number.isInteger(h.size) && h.size >= 1;
+/**
+ * Section 3: `signers` are the lab DIDs this receiver trusts; `heads` the chain heads it holds from
+ * elsewhere (the result bundle's), each of which the share must carry unchanged.
+ */
+export function verifyEvidenceShare(doc, opts = {}) {
+    if (!withinVerificationBudget(doc))
+        return { ok: false, reasons: ["evidence share exceeds its JSON verification budget"] };
+    const d = isObj(doc) ? doc : {};
+    const heads = d.heads;
+    if (d.v !== 1 || d.type !== "certify.evidence-share" || Object.keys(d).length !== 10 || !Array.isArray(heads) || !Array.isArray(d.items))
+        return { ok: false, reasons: ["not an evidence share (v1)"] };
+    const reasons = [];
+    if (!verifySignedObject(d))
+        reasons.push("bad evidence share signature");
+    if (!opts.signers)
+        reasons.push("no trusted signers supplied: the signer was NOT checked");
+    else if (!opts.signers.includes(d.signer))
+        reasons.push("evidence share signer is not a trusted lab key");
+    if (!AUDIENCES.includes(d.audience))
+        reasons.push("audience must be reviewer, regulator or applicant");
+    if (!isIso(d.shared_at))
+        reasons.push("shared_at must be an ISO timestamp");
+    const kinds = d.kinds;
+    if (!Array.isArray(kinds) || !kinds.every((k) => k === "secret" || k === "withheld" || REDACTION_KINDS.includes(k)) || sortedUnique(kinds).join("\n") !== kinds.join("\n"))
+        reasons.push("kinds must be sorted, distinct redaction kinds");
+    const r = d.redactions;
+    if (!isObj(r) || !Object.entries(r).every(([k, n]) => Array.isArray(kinds) && kinds.includes(k) && Number.isInteger(n) && n >= 1))
+        reasons.push("redactions must count kinds of the share");
+    if (heads.length < 1 || !heads.every(headOk) || heads.some((h, i) => i > 0 && !(h.chain > heads[i - 1].chain)) || heads.reduce((n, h) => n + h.size, 0) > MAX_ITEMS)
+        return { ok: false, reasons: [...reasons, "heads must be 1 or more sorted, distinct {chain, head, size}"] };
+    for (const want of opts.heads ?? []) {
+        const got = heads.find((h) => h.chain === want.chain);
+        if (!got || got.head !== want.head || got.size !== want.size)
+            reasons.push(`chain ${String(want.chain)} is not at the expected head`);
+    }
+    reasons.push(...itemReasons(d.items, heads));
+    return { ok: reasons.length === 0, reasons };
+}

package/dist/federation.d.ts

@@ -0,0 +1,103 @@
+import { type SignedTreeHead } from "@zanii/core";
+import { type Signer } from "./signer.ts";
+declare const STATUSES: readonly ["valid", "suspended", "revoked"];
+/** Section 1: the most entries one page carries. */
+export declare const MAX_FEED_ENTRIES = 10000;
+export declare const MAX_FEED_PAGE_BYTES: number;
+export interface FeedEntry {
+    certificate: string;
+    profile: string;
+    level: number;
+    status: (typeof STATUSES)[number];
+    since: string;
+    licence: string | null;
+}
+export interface FeedPage {
+    v: 1;
+    type: "certify.feed";
+    instance: string;
+    region: string;
+    issuers: string[];
+    seq: number;
+    prev: string | null;
+    entries: FeedEntry[];
+    issued_at: string;
+    signer: string;
+    sig: string;
+}
+export interface FeedPageInput {
+    instance: string;
+    region: string;
+    issuers: readonly string[];
+    seq: number;
+    prev: string | null;
+    entries: readonly FeedEntry[];
+    issuedAt: string;
+}
+declare const entryOk: (e: unknown) => e is FeedEntry;
+export { entryOk as isFeedEntry };
+/** Section 1: one feed page, signed by one of the instance's issuers. */
+export declare function buildFeedPage(f: FeedPageInput, signer: Signer): Promise<FeedPage>;
+export interface FeedCheck {
+    ok: boolean;
+    reasons: string[];
+    /** The instance's current entries (the last state of each certificate), sorted by certificate. */
+    entries: FeedEntry[];
+}
+/** A previously authenticated prefix; callers must commit its entries and cursor atomically. */
+export interface FeedCursor {
+    instance: string;
+    region: string | null;
+    size: number;
+    last_hash: string | null;
+    last_issued_at: string | null;
+}
+/** Validate one extension using authenticated prior certificate state, without reloading its history. */
+export declare function verifyFeedPage(page: unknown, opts: {
+    cursor: FeedCursor;
+    issuers: readonly string[];
+    entry: (certificate: string) => FeedEntry | undefined;
+}): FeedCheck;
+/** Section 2: the signed tree head over the feed (leaf i = page i), by the issuer that signed the last page. */
+export declare function feedCheckpoint(pages: readonly FeedPage[], ts: string, signer: Signer): Promise<SignedTreeHead>;
+/**
+ * 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 declare function verifyFeed(pages: readonly unknown[], opts?: {
+    issuers?: readonly string[];
+    checkpoint?: SignedTreeHead;
+}): FeedCheck;
+export interface FederatedFeed {
+    pages: readonly unknown[];
+    /** The issuer DIDs the registry trusts for this instance. */
+    issuers: readonly string[];
+    checkpoint?: SignedTreeHead;
+}
+export interface FeedConflict {
+    kind: "instance" | "issuer" | "certificate";
+    /** The instance id, issuer DID or certificate hash in conflict. */
+    id: string;
+    /** The instances involved, sorted (an instance twice when two feeds claim one id). */
+    instances: string[];
+}
+export interface MergedRegistry {
+    entries: (FeedEntry & {
+        instance: string;
+        region: string;
+    })[];
+    conflicts: FeedConflict[];
+    rejected: {
+        instance: string;
+        reasons: string[];
+    }[];
+}
+/**
+ * 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 declare function mergeFeeds(feeds: readonly FederatedFeed[]): MergedRegistry;