@zanii/blackbox 0.3.0 → 0.4.0

package/dist/constitution/index.js

@@ -0,0 +1,131 @@
+// The signed rulebook (spec/governance.md), in Zanii's constitution v1 format, byte for byte with
+// @zanii/constitution / zanii.constitution, and a session's governance against it. Pure; mirrors
+// sdks/python/src/zanii_blackbox/constitution.py; pinned by spec/vectors/governance.json.
+import { canonicalBytes, jcsHash, publicKeyFromDid, scopeCovers } from "@zanii/core";
+import { ed25519Sign, ed25519Verify } from "../transparency/index.js";
+const EFFECTS = new Set(["forbid", "require_approval", "allow"]);
+/** Builds and signs the rulebook; rules are evaluated first match wins, top to bottom. */
+export function createConstitution(input) {
+    const { issuer, name, rules, defaultEffect = "allow", createdAt } = input;
+    if (!issuer)
+        throw new Error("issuer is required");
+    if (!name)
+        throw new Error("name is required");
+    if (!rules.length)
+        throw new Error("a constitution with no rules constrains nothing");
+    const ids = new Set();
+    for (const r of rules) {
+        if (!r.id)
+            throw new Error("every rule needs an id");
+        if (ids.has(r.id))
+            throw new Error(`duplicate rule id '${r.id}'`);
+        ids.add(r.id);
+        if (!EFFECTS.has(r.effect))
+            throw new Error(`rule '${r.id}': invalid effect '${r.effect}'`);
+        if (!r.targets?.length)
+            throw new Error(`rule '${r.id}' has no targets`);
+    }
+    if (defaultEffect !== "allow" && defaultEffect !== "forbid")
+        throw new Error("default_effect must be 'allow' or 'forbid'");
+    if (Number.isNaN(Date.parse(createdAt)))
+        throw new Error("created_at must be an ISO timestamp");
+    const unsigned = {
+        v: 1,
+        type: "constitution",
+        issuer,
+        name,
+        rules,
+        default: defaultEffect,
+        created_at: createdAt,
+    };
+    const sig = Buffer.from(ed25519Sign(input.issuerPrivateKey, canonicalBytes(unsigned))).toString("hex");
+    return { ...unsigned, sig: `ed25519:${sig}` };
+}
+/** Structure and the issuer's signature. */
+export function verifyConstitution(c) {
+    const p = (c ?? {});
+    if (p.v !== 1 || p.type !== "constitution" || !p.issuer || !p.name)
+        return false;
+    if (!Array.isArray(p.rules) || p.rules.length === 0)
+        return false;
+    const ids = p.rules.map((r) => (r && typeof r === "object" ? r.id : undefined));
+    if (new Set(ids).size !== ids.length)
+        return false;
+    for (const r of p.rules)
+        if (!r || typeof r !== "object" || !EFFECTS.has(r.effect) || !r.targets?.length)
+            return false;
+    if (p.default !== "allow" && p.default !== "forbid")
+        return false;
+    const pub = publicKeyFromDid(p.issuer);
+    const m = typeof p.sig === "string" ? /^ed25519:([0-9a-f]{128})$/.exec(p.sig) : null;
+    if (!pub || !m)
+        return false;
+    const { sig: _sig, ...unsigned } = p;
+    return ed25519Verify(pub, canonicalBytes(unsigned), Buffer.from(m[1], "hex"));
+}
+/** The `manifest_hash`: RFC 8785 JSON, SHA-256. */
+export const constitutionHash = (c) => jcsHash(c);
+/** First match wins, then the default. */
+export function evaluateConstitution(c, target) {
+    for (const r of c.rules)
+        if (r.targets.some((t) => scopeCovers(t, target)))
+            return { effect: r.effect, rule: r };
+    return { effect: c.default, rule: null };
+}
+/** spec/governance.md §3: the action's target, or null when the event isn't an action. */
+function targetOf(e) {
+    const m = e.meta;
+    const policy = m.policy;
+    if (policy?.action === "deny")
+        return null; // refused: it never ran
+    if (e.kind === "tool.call" && typeof m.tool === "string")
+        return m.server !== undefined
+            ? `mcp.${String(m.server)}.${m.tool}`
+            : `tool.${String(m.via)}.${m.tool}`;
+    if (e.kind === "llm.request")
+        return `model.${String(m.provider ?? "unknown")}`;
+    if (e.kind === "sdk.event" && m.type === "tool.call")
+        return `sdk.${String(m.name ?? "unknown")}`;
+    return null;
+}
+/** spec/governance.md §3: a session's record against the rulebook. */
+export function governanceOf(lines, c) {
+    const manifest = constitutionHash(c);
+    const events = lines.map((l) => JSON.parse(l));
+    const open = events.find((e) => e.kind === "session.open");
+    const governed = open?.meta.manifest_hash === manifest;
+    const approved = new Set(events
+        .filter((e) => e.kind === "control" && e.meta.action === "approval" && e.meta.decision === "approve")
+        .map((e) => e.meta.call_seq));
+    const violations = [];
+    const approvals = [];
+    let actions = 0;
+    for (const e of events) {
+        const target = targetOf(e);
+        if (target === null)
+            continue;
+        actions++;
+        if (!governed) {
+            violations.push({ seq: e.seq, target, kind: "ungoverned" });
+            continue;
+        }
+        const ev = evaluateConstitution(c, target);
+        if (ev.effect === "forbid")
+            violations.push({
+                seq: e.seq,
+                target,
+                kind: "forbidden",
+                ...(ev.rule ? { rule_id: ev.rule.id } : {}),
+            });
+        else if (ev.effect === "require_approval" && ev.rule)
+            approvals.push({ seq: e.seq, target, rule_id: ev.rule.id, approved: approved.has(e.seq) });
+    }
+    return {
+        manifest_hash: manifest,
+        governed,
+        ok: violations.length === 0,
+        actions,
+        violations,
+        approvals_required: approvals,
+    };
+}

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