@zanii/blackbox 0.2.0 → 0.4.0

package/dist/cv/index.d.ts

@@ -0,0 +1,39 @@
+type Obj = Record<string, unknown>;
+/** Zanii's agentcv from its parts. */
+export declare function buildCv(o: {
+    did: string;
+    summary: Obj;
+    generatedAt: string;
+    owner?: string | null;
+    work?: Obj[];
+    authority?: Obj[];
+    benchmarks?: Obj[];
+    skills?: string[];
+}): Obj;
+export declare const cvHash: (cv: Obj) => string;
+/** Zanii's offline check: structure, the subject's signature when there is one, and warnings. */
+export declare function verifyCv(cv: unknown): {
+    ok: boolean;
+    reasons: string[];
+    signed: boolean | null;
+    warnings: string[];
+};
+type Summary = {
+    session_id: string;
+    label: string | null;
+    started_at: string;
+    last_event_at: string;
+    closed: boolean;
+    outcome: string | null;
+    tools: Record<string, number>;
+};
+/**
+ * The agent behind a label, as Zanii's agentcv, from session summaries (spec/fleet.md §1) and the
+ * anchor receipt of each anchored session: summary.receipts counts the anchored sessions, and each
+ * work entry (the newest 20) cites its anchor receipt.
+ */
+export declare function agentCv(label: string, summaries: readonly Summary[], o: {
+    anchored: Readonly<Record<string, string>>;
+    generatedAt: string;
+}): Obj;
+export {};

package/dist/cv/index.js

@@ -0,0 +1,108 @@
+// Agent CVs (spec/fleet.md §7): Zanii's agentcv, a portable view over what the record already
+// holds, every work entry backed by a ledger ref (@zanii/cv), built here from the gateway's own
+// logbook. Pure; mirrors sdks/python/src/zanii_blackbox/cv.py; pinned by spec/vectors/cv.json.
+import { canonicalBytes, jcsHash, publicKeyFromDid } from "@zanii/core";
+import { ed25519Verify } from "../transparency/index.js";
+const WORK_SHOWN = 20;
+const validTs = (ts) => typeof ts === "string" && !Number.isNaN(Date.parse(ts));
+/** Zanii's agentcv from its parts. */
+export function buildCv(o) {
+    if (!o.did)
+        throw new Error("did is required");
+    if (!o.summary || Object.keys(o.summary).length === 0)
+        throw new Error("summary is required (the ledger aggregate — the un-inflatable part)");
+    if (!validTs(o.generatedAt))
+        throw new Error("generated_at must be an ISO timestamp");
+    return {
+        v: 1,
+        type: "agentcv",
+        did: o.did,
+        owner: o.owner ?? null,
+        summary: o.summary,
+        work: o.work ?? [],
+        authority: o.authority ?? [],
+        benchmarks: o.benchmarks ?? [],
+        skills: o.skills ?? [],
+        generated_at: o.generatedAt,
+    };
+}
+export const cvHash = (cv) => jcsHash(cv);
+const skillBacked = (skill, scopes) => [...scopes].some((sc) => typeof sc === "string" &&
+    (sc === skill || sc === "*" || (sc.endsWith(".*") && skill.startsWith(sc.slice(0, -1)))));
+/** Zanii's offline check: structure, the subject's signature when there is one, and warnings. */
+export function verifyCv(cv) {
+    const c = (cv ?? {});
+    const reasons = [];
+    const warnings = [];
+    if (c.v !== 1 || c.type !== "agentcv")
+        reasons.push("not an agentcv (v1)");
+    if (!c.did)
+        reasons.push("missing did");
+    const summary = c.summary;
+    if (!summary || typeof summary !== "object" || !Number.isSafeInteger(summary.receipts))
+        reasons.push("missing/invalid summary (the ledger aggregate)");
+    if (!validTs(c.generated_at))
+        reasons.push("missing/invalid generated_at");
+    let signed = null;
+    if (typeof c.sig === "string") {
+        const pub = publicKeyFromDid(String(c.did));
+        const m = /^ed25519:([0-9a-f]{128})$/.exec(c.sig);
+        if (!pub || !m) {
+            signed = false;
+            reasons.push("malformed signature or subject key");
+        }
+        else {
+            const { sig: _sig, ...unsigned } = c;
+            signed = ed25519Verify(pub, canonicalBytes(unsigned), Buffer.from(m[1], "hex"));
+            if (!signed)
+                reasons.push("signature does not verify against the subject did (CV was altered or signed by someone else)");
+        }
+    }
+    if (reasons.length === 0 && summary) {
+        const scopes = new Set((c.authority ?? []).map((a) => a.scope));
+        for (const s of c.skills ?? [])
+            if (!skillBacked(s, scopes))
+                warnings.push(`skill "${s}" is claimed but not backed by any delegated authority scope`);
+        const work = c.work ?? [];
+        if (work.length > summary.receipts)
+            warnings.push(`work lists ${work.length} entries but the ledger only counts ${summary.receipts} receipts — the curated list cannot exceed the real total`);
+        if (summary.revoked)
+            warnings.push("the subject's authority is REVOKED on the ledger");
+    }
+    return { ok: reasons.length === 0, reasons, signed, warnings };
+}
+/**
+ * The agent behind a label, as Zanii's agentcv, from session summaries (spec/fleet.md §1) and the
+ * anchor receipt of each anchored session: summary.receipts counts the anchored sessions, and each
+ * work entry (the newest 20) cites its anchor receipt.
+ */
+export function agentCv(label, summaries, o) {
+    const mine = summaries.filter((s) => s.label === label);
+    if (mine.length === 0)
+        throw new Error(`no sessions for ${label}`);
+    const tools = new Set(mine.flatMap((s) => Object.keys(s.tools ?? {})));
+    const closed = mine.filter((s) => s.closed);
+    const onLedger = mine.filter((s) => s.session_id in o.anchored);
+    const newest = [...onLedger].sort((a, b) => a.last_event_at < b.last_event_at ? 1 : a.last_event_at > b.last_event_at ? -1 : 0);
+    const max = (xs) => xs.reduce((a, b) => (b > a ? b : a));
+    const min = (xs) => xs.reduce((a, b) => (b < a ? b : a));
+    return buildCv({
+        did: `urn:blackbox:agent:${label}`,
+        summary: {
+            receipts: onLedger.length,
+            distinct_counterparties: tools.size,
+            first_seen: min(mine.map((s) => s.started_at)),
+            last_seen: max(mine.map((s) => s.last_event_at)),
+            revoked: false,
+            fully_anchored: closed.length > 0 && closed.every((s) => s.session_id in o.anchored),
+            audit_bundle: null,
+        },
+        generatedAt: o.generatedAt,
+        work: newest.slice(0, WORK_SHOWN).map((s) => ({
+            session_id: s.session_id,
+            outcome: s.outcome,
+            at: s.last_event_at,
+            ref: o.anchored[s.session_id],
+        })),
+    });
+}

package/dist/disclosure/index.d.ts

@@ -0,0 +1,31 @@
+export interface DisclosureEnvelope {
+    _zr: "sd-v1";
+    root: string;
+    keys: string[];
+}
+export interface Disclosure {
+    _zr: "sd-disclosure-v1";
+    key: string;
+    value: unknown;
+    salt: string;
+    index: number;
+    size: number;
+    proof: string[];
+    root: string;
+}
+/**
+ * The scalar leaves of `args` (an empty object or array is a leaf too), as [JSON Pointer, value],
+ * sorted by pointer; null when `args` isn't an object, or is too big or too deep to commit to.
+ */
+export declare function argumentLeaves(args: unknown): Array<[string, unknown]> | null;
+/** `meta.disclosure` for a call with these arguments and body hash; null when there's none. */
+export declare function disclosureEnvelope(args: unknown, bodyHash: string, key: Uint8Array): DisclosureEnvelope | null;
+/** One disclosure per pointer. Throws on a pointer that isn't a leaf of the arguments. */
+export declare function discloseFields(args: unknown, bodyHash: string, key: Uint8Array, pointers: readonly string[]): Disclosure[];
+/** Zanii's check: the root and size match, keys[index] is the key, and the proof verifies. */
+export declare function verifyDisclosure(d: unknown, envelope: unknown): boolean;
+/** Checks disclosures against the envelope in a stored event line's `meta.disclosure`. */
+export declare function verifyEventDisclosure(line: string, disclosures: readonly unknown[]): {
+    ok: boolean;
+    fields: Record<string, unknown>;
+};

package/dist/disclosure/index.js

@@ -0,0 +1,113 @@
+// Selective disclosure of a tool call's arguments (spec/disclosure.md), in Zanii's Selective
+// Disclosure v1 format (@zanii/redact / zanii.redact, byte for byte). Pure; mirrors
+// sdks/python/src/zanii_blackbox/disclosure.py; pinned by spec/vectors/disclosure.json.
+import { createHmac } from "node:crypto";
+import { canonicalBytes, inclusionProof, leafHash, merkleRoot, verifyInclusion } from "@zanii/core";
+const MAX_LEAVES = 256;
+const MAX_DEPTH = 8;
+const hex = (b) => Buffer.from(b).toString("hex");
+const escapeKey = (k) => k.replaceAll("~", "~0").replaceAll("/", "~1");
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * The scalar leaves of `args` (an empty object or array is a leaf too), as [JSON Pointer, value],
+ * sorted by pointer; null when `args` isn't an object, or is too big or too deep to commit to.
+ */
+export function argumentLeaves(args) {
+    if (!isObj(args))
+        return null;
+    const out = [];
+    let tooDeep = false;
+    const walk = (v, ptr, depth) => {
+        if (depth > MAX_DEPTH)
+            tooDeep = true;
+        if (tooDeep || out.length > MAX_LEAVES)
+            return;
+        if (isObj(v) && Object.keys(v).length)
+            for (const [k, x] of Object.entries(v))
+                walk(x, `${ptr}/${escapeKey(k)}`, depth + 1);
+        else if (Array.isArray(v) && v.length)
+            for (const [i, x] of v.entries())
+                walk(x, `${ptr}/${i}`, depth + 1);
+        else
+            out.push([ptr, v]);
+    };
+    walk(args, "", 0);
+    if (tooDeep || out.length > MAX_LEAVES || out.length === 0)
+        return null;
+    return out.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+const salt = (key, bodyHash, pointer) => createHmac("sha256", key).update(`${bodyHash}\n${pointer}`).digest("hex").slice(0, 32);
+const leaf = (pointer, value, s) => leafHash(canonicalBytes(["zr-field-v1", pointer, value, s]));
+function tree(args, bodyHash, key) {
+    const leaves = argumentLeaves(args);
+    if (!leaves)
+        return null;
+    const salts = leaves.map(([p]) => salt(key, bodyHash, p));
+    const hashes = leaves.map(([p, v], i) => leaf(p, v, salts[i]));
+    return { leaves, salts, hashes, root: `sha256:${hex(merkleRoot(hashes))}` };
+}
+/** `meta.disclosure` for a call with these arguments and body hash; null when there's none. */
+export function disclosureEnvelope(args, bodyHash, key) {
+    const t = tree(args, bodyHash, key);
+    return t ? { _zr: "sd-v1", root: t.root, keys: t.leaves.map(([p]) => p) } : null;
+}
+/** One disclosure per pointer. Throws on a pointer that isn't a leaf of the arguments. */
+export function discloseFields(args, bodyHash, key, pointers) {
+    const t = tree(args, bodyHash, key);
+    if (!t)
+        throw new Error("these arguments have no commitment");
+    return pointers.map((p) => {
+        const index = t.leaves.findIndex(([k]) => k === p);
+        if (index < 0)
+            throw new Error(`not a field of this call: ${p}`);
+        return {
+            _zr: "sd-disclosure-v1",
+            key: p,
+            value: t.leaves[index][1],
+            salt: t.salts[index],
+            index,
+            size: t.leaves.length,
+            proof: inclusionProof(index, t.hashes).map(hex),
+            root: t.root,
+        };
+    });
+}
+/** Zanii's check: the root and size match, keys[index] is the key, and the proof verifies. */
+export function verifyDisclosure(d, envelope) {
+    const x = d;
+    const e = envelope;
+    if (!x || !e || x.root !== e.root || !Array.isArray(e.keys) || typeof e.root !== "string")
+        return false;
+    const { index, size, key, salt: s, proof } = x;
+    if (size !== e.keys.length || typeof index !== "number" || !Number.isInteger(index))
+        return false;
+    if (index < 0 || index >= e.keys.length || e.keys[index] !== key)
+        return false;
+    if (typeof key !== "string" || typeof s !== "string" || !Array.isArray(proof))
+        return false;
+    try {
+        return verifyInclusion(leaf(key, x.value, s), index, size, proof.map((p) => new Uint8Array(Buffer.from(String(p), "hex"))), new Uint8Array(Buffer.from(e.root.replace(/^sha256:/, ""), "hex")));
+    }
+    catch {
+        return false;
+    }
+}
+/** Checks disclosures against the envelope in a stored event line's `meta.disclosure`. */
+export function verifyEventDisclosure(line, disclosures) {
+    let envelope;
+    try {
+        envelope = JSON.parse(line).meta?.disclosure;
+    }
+    catch {
+        return { ok: false, fields: {} };
+    }
+    const fields = {};
+    let ok = envelope !== undefined && disclosures.length > 0;
+    for (const d of disclosures) {
+        if (verifyDisclosure(d, envelope))
+            fields[d.key] = d.value;
+        else
+            ok = false;
+    }
+    return { ok, fields };
+}

package/dist/encryption/index.d.ts

@@ -0,0 +1,9 @@
+export interface SealedSegment {
+    hash: string;
+    /** base64: the stored bytes (nonce ‖ ciphertext ‖ tag), or the plain bytes when `key` is null. */
+    sealed: string;
+    /** base64: the segment's own key, or null for a segment stored before encryption. */
+    key: string | null;
+}
+/** The body, when every segment opens, hashes to its own hash, and they join to `bodyHash`; else null. */
+export declare function openSegments(segments: readonly SealedSegment[], bodyHash: string): Uint8Array | null;

package/dist/encryption/index.js

@@ -0,0 +1,31 @@
+// The auditor's side of spec/encryption.md §4: open one body from its sealed segments and their
+// keys, and check it against the hash in the chain. Pure; mirrors
+// sdks/python/src/zanii_blackbox/encryption.py; pinned by spec/vectors/body-encryption.json.
+import { createDecipheriv, createHash } from "node:crypto";
+const sha256 = (b) => `sha256:${createHash("sha256").update(b).digest("hex")}`;
+function open(key, hash, sealed) {
+    if (key.length !== 32 || sealed.length < 28)
+        return null;
+    try {
+        const d = createDecipheriv("aes-256-gcm", key, sealed.subarray(0, 12));
+        d.setAAD(Buffer.from(hash, "utf8"));
+        d.setAuthTag(sealed.subarray(sealed.length - 16));
+        return Buffer.concat([d.update(sealed.subarray(12, sealed.length - 16)), d.final()]);
+    }
+    catch {
+        return null;
+    }
+}
+/** The body, when every segment opens, hashes to its own hash, and they join to `bodyHash`; else null. */
+export function openSegments(segments, bodyHash) {
+    const parts = [];
+    for (const s of segments) {
+        const bytes = Buffer.from(s.sealed, "base64");
+        const plain = s.key === null ? bytes : open(Buffer.from(s.key, "base64"), s.hash, bytes);
+        if (!plain || sha256(plain) !== s.hash)
+            return null;
+        parts.push(plain);
+    }
+    const body = Buffer.concat(parts);
+    return sha256(body) === bodyHash ? new Uint8Array(body) : null;
+}

package/dist/evidence/index.d.ts

@@ -0,0 +1,60 @@
+import type { Bundle, BundleReport } from "../verify/index.ts";
+type Text = {
+    en: string;
+    ar: string;
+};
+export interface EvidencePackOptions {
+    generated_at: string;
+    bundle_sha256: string;
+    proofs: "checked" | "not_checked";
+}
+/** spec/investigations.md §7. */
+export declare function evidencePack(bundle: Bundle, report: BundleReport, opts: EvidencePackOptions): {
+    v: 1;
+    kind: "blackbox-evidence-pack";
+    session_id: string;
+    label: string | null;
+    agent: {} | null;
+    anchored_by: string | null;
+    ledger_url: string | null;
+    record: {
+        events: number;
+        head: string | null;
+        first_at: string | null;
+        last_at: string | null;
+        closed: boolean;
+    };
+    anchors: {
+        count: number;
+        last: {
+            count: number;
+            receipt_hash: string;
+            anchored_at: string;
+        } | null;
+    };
+    transparency: {
+        statement: boolean;
+        receipt: boolean;
+        checkpoint: boolean;
+        timestamp: boolean;
+    } | null;
+    verified: boolean;
+    verification: {
+        chain: string;
+        identity: string;
+        proofs: string;
+    };
+    legal_basis: Text;
+    steps: {
+        en: string;
+        ar: string;
+        n: number;
+    }[];
+    reproduce: string[];
+    generated_at: string;
+    bundle_sha256: string;
+};
+export type EvidencePack = ReturnType<typeof evidencePack>;
+/** The Markdown copy (spec/investigations.md §7): `en`, `ar` or `both`. */
+export declare function renderEvidencePack(pack: EvidencePack, lang?: "en" | "ar" | "both"): string;
+export {};

package/dist/evidence/index.js

@@ -0,0 +1,151 @@
+// The court evidence pack (spec/investigations.md §7): why a court, or an expert it appoints, can
+// rely on a record, and how to check it without trusting the operator. Arabic and English. Pure;
+// mirrors sdks/python/src/zanii_blackbox/evidence.py; pinned by spec/vectors/evidence-pack.json.
+import { hashLine } from "../verify/envelope.js";
+const LEGAL_BASIS = {
+    en: "Under UAE Federal Decree-Law No. 46 of 2021 on Electronic Transactions and Trust Services, an electronic record and an electronic signature have legal effect and may be admitted as evidence. This pack lets a court, or an expert it appoints, check the record's integrity and origin independently, without relying on the operator. It maps the evidence; it is not legal advice.",
+    ar: "بموجب المرسوم بقانون اتحادي رقم 46 لسنة 2021 في شأن المعاملات الإلكترونية وخدمات الثقة، يكون للسجل الإلكتروني والتوقيع الإلكتروني أثر قانوني ويجوز قبولهما دليلًا. تتيح هذه الحزمة للمحكمة، أو لخبير تعيّنه، التحقق المستقل من سلامة السجل ومصدره دون الاعتماد على المشغّل. هي بيان للأدلة، وليست استشارة قانونية.",
+};
+const STEPS = [
+    {
+        en: "The hash chain: each event's hash covers its content and the previous event's hash (SHA-256 over RFC 8785 JSON). Recomputing them gives the last hash shown above.",
+        ar: "سلسلة التجزئة: تجزئة كل حدث تشمل محتواه وتجزئة الحدث السابق (SHA-256 على JSON وفق RFC 8785). إعادة حسابها تعطي آخر تجزئة المذكورة أعلاه.",
+    },
+    {
+        en: "The bodies: each body's SHA-256 matches the hash its event recorded. An erased body is gone, but its hash stays, so the chain still checks.",
+        ar: "المحتوى: تطابق تجزئة SHA-256 لكل محتوى التجزئةَ التي سجّلها حدثه. المحتوى الممحوّ لم يعد موجودًا، لكن تجزئته باقية، فتبقى السلسلة قابلة للتحقق.",
+    },
+    {
+        en: "The anchors: each ledger receipt commits to the session, its number of events and its last hash, and is signed by the gateway's DID under a delegation from its owner.",
+        ar: "التثبيت: كل إيصال في دفتر الأستاذ يلتزم بالجلسة وعدد أحداثها وآخر تجزئة لها، وموقّع بهوية البوابة (DID) بتفويض من مالكها.",
+    },
+    {
+        en: "The ledger: each receipt is in the ledger's Merkle log (an inclusion proof) under a signed tree head, and the log only ever grew.",
+        ar: "دفتر الأستاذ: كل إيصال مُدرَج في سجل ميركل الخاص بدفتر الأستاذ (إثبات إدراج) تحت رأس شجرة موقّع، والسجل لم يزد إلا نموًّا.",
+    },
+    {
+        en: "The gateway's own log, when present: the session's signed statement, its inclusion in the gateway's transparency log, the witnesses' cosignatures and the RFC 3161 time-stamp.",
+        ar: "سجل البوابة نفسها، إن وُجد: البيان الموقّع للجلسة، وإدراجه في سجل الشفافية للبوابة، وتواقيع الشهود المشتركة، والختم الزمني وفق RFC 3161.",
+    },
+];
+const REPRODUCE = [
+    "npx @zanii/blackbox verify bundle.json --proofs",
+    "pip install zanii-blackbox && blackbox verify bundle.json --proofs",
+];
+const parse = (line) => {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return {};
+    }
+};
+/** spec/investigations.md §7. */
+export function evidencePack(bundle, report, opts) {
+    const lines = bundle.lines;
+    const first = lines.length ? parse(lines[0]) : {};
+    const last = lines.length ? parse(lines.at(-1)) : {};
+    const open = first.kind === "session.open" ? first : {};
+    const newest = bundle.anchors.at(-1);
+    const t = bundle.transparency;
+    const proofs = report.proofs === null || opts.proofs === "not_checked"
+        ? "not_checked"
+        : report.proofs.every((p) => p.ok)
+            ? "checked"
+            : "failed";
+    return {
+        v: 1,
+        kind: "blackbox-evidence-pack",
+        session_id: bundle.session.session_id,
+        label: typeof bundle.session.label === "string" ? bundle.session.label : null,
+        agent: open.meta?.agent ?? null,
+        anchored_by: bundle.anchored_by,
+        ledger_url: bundle.ledger_url,
+        record: {
+            events: lines.length,
+            head: lines.length ? hashLine(lines.at(-1)) : null,
+            first_at: typeof first.ts === "string" ? first.ts : null,
+            last_at: typeof last.ts === "string" ? last.ts : null,
+            closed: last.kind === "session.close",
+        },
+        anchors: {
+            count: bundle.anchors.length,
+            last: newest
+                ? {
+                    count: newest.count,
+                    receipt_hash: newest.receipt_hash,
+                    anchored_at: newest.anchored_at,
+                }
+                : null,
+        },
+        transparency: t
+            ? {
+                statement: t.statement !== undefined,
+                receipt: t.receipt !== undefined,
+                checkpoint: t.checkpoint !== undefined,
+                timestamp: t.timestamp !== undefined,
+            }
+            : null,
+        verified: report.ok,
+        verification: {
+            chain: report.chain.ok ? "ok" : report.chain.code,
+            identity: report.identity.ok ? "ok" : "mismatch",
+            proofs,
+        },
+        legal_basis: LEGAL_BASIS,
+        steps: STEPS.map((s, i) => ({ n: i + 1, ...s })),
+        reproduce: REPRODUCE,
+        generated_at: opts.generated_at,
+        bundle_sha256: opts.bundle_sha256,
+    };
+}
+// U+2067 … U+2069 isolate the Arabic paragraphs, so they read right to left in any viewer.
+const rtl = (s) => `⁧${s}⁩`;
+/** The Markdown copy (spec/investigations.md §7): `en`, `ar` or `both`. */
+export function renderEvidencePack(pack, lang = "both") {
+    const show = (b) => lang === "en" ? b.en : lang === "ar" ? rtl(b.ar) : `${b.en}\n\n> ${rtl(b.ar)}`;
+    const label = (en, ar) => lang === "en" ? en : lang === "ar" ? rtl(ar) : `${en} / ${rtl(ar)}`;
+    const r = pack.record;
+    const verdict = pack.verified
+        ? label("VERIFIED", "تم التحقق")
+        : label("FAILED VERIFICATION", "فشل التحقق");
+    const rows = [
+        [label("Session", "الجلسة"), `\`${pack.session_id}\``],
+        [label("Label", "التسمية"), pack.label ? pack.label.replaceAll("|", "\\|") : "—"],
+        [label("Events", "الأحداث"), String(r.events)],
+        [label("Last hash", "آخر تجزئة"), r.head ? `\`${r.head}\`` : "—"],
+        [label("Period", "المدة"), `${r.first_at ?? "—"} → ${r.last_at ?? "—"}`],
+        [label("Closed", "مغلقة"), r.closed ? label("yes", "نعم") : label("no", "لا")],
+        [label("Anchored by", "ثبّتها"), pack.anchored_by ? `\`${pack.anchored_by}\`` : "—"],
+        [label("Anchors", "التثبيتات"), String(pack.anchors.count)],
+        [label("Chain", "السلسلة"), pack.verification.chain],
+        [label("Identity", "الهوية"), pack.verification.identity],
+        [label("Ledger proofs", "إثباتات دفتر الأستاذ"), pack.verification.proofs],
+        [label("Bundle SHA-256", "تجزئة الحزمة"), `\`${pack.bundle_sha256}\``],
+        [label("Generated", "أُنشئت"), pack.generated_at],
+    ];
+    return [
+        `# ${label("Evidence pack", "حزمة الأدلة")}`,
+        "",
+        `**${verdict}**`,
+        "",
+        `| | |`,
+        `|---|---|`,
+        ...rows.map(([k, v]) => `| ${k} | ${v} |`),
+        "",
+        `## ${label("Legal basis", "الأساس القانوني")}`,
+        "",
+        show(pack.legal_basis),
+        "",
+        `## ${label("How to check it", "خطوات التحقق")}`,
+        "",
+        ...pack.steps.map((s) => `${s.n}. ${show(s)}`),
+        "",
+        `## ${label("Reproduce offline", "إعادة التحقق دون اتصال")}`,
+        "",
+        "```sh",
+        ...pack.reproduce,
+        "```",
+        "",
+    ].join("\n");
+}

package/dist/federation/index.d.ts

@@ -0,0 +1,35 @@
+import { type SignedTreeHead } from "@zanii/core";
+/** Zanii's witness co-signature over a signed tree head the caller has checked (signed, append-only). */
+export declare function cosignLedgerSth(sth: SignedTreeHead, o: {
+    did: string;
+    privateKey: Uint8Array;
+}): {
+    v: number;
+    witnessed_log_id: string;
+    cosignature: SignedTreeHead;
+};
+/** Zanii's check: a valid co-signature over the same (size, root) of a valid tree head. */
+export declare function verifyLedgerCosignature(c: unknown, sth: SignedTreeHead): boolean;
+/** Zanii's equivocation proof: one log key, one size, two roots. Throws unless it really is one. */
+export declare function buildEquivocationProof(a: SignedTreeHead, b: SignedTreeHead): {
+    v: number;
+    type: string;
+    log_id: string;
+    size: number;
+    sths: SignedTreeHead[];
+};
+/** Re-checks a proof from scratch: both signatures, same log, same size, different roots. */
+export declare function verifyEquivocationProof(proof: unknown): boolean;
+/**
+ * Zanii's gossip comparison over views already fetched: views of other logs and bad signatures
+ * are set aside, and two valid views at one size with different roots are an equivocation proof.
+ */
+export declare function compareViews(logId: string, views: ReadonlyArray<{
+    source: string;
+    sth?: unknown;
+    error?: string;
+}>): {
+    ok: boolean;
+    reasons: string[];
+    equivocation?: ReturnType<typeof buildEquivocationProof>;
+};