@zanii/blackbox 0.2.0 → 0.3.0

package/dist/a2a/index.d.ts

@@ -0,0 +1,50 @@
+import { type Json } from "../verify/envelope.ts";
+type Meta = {
+    [key: string]: Json;
+};
+/** The methods whose answer is an SSE stream. */
+export declare const A2A_STREAMING: Set<string>;
+/** The v1.0 name of an A2A method, either name set, or undefined for one A2A doesn't define. */
+export declare function a2aMethod(method: string): string | undefined;
+/**
+ * §2: a request's meta. `version` and `extensions` are the A2A-Version and A2A-Extensions headers
+ * (or the A2A-Version query parameter); an empty version means 0.3.
+ */
+export declare function a2aRequestMeta(body: Uint8Array, headers?: {
+    version?: string | null;
+    extensions?: string | null;
+}): Meta;
+/** §2: an answer's meta: a JSON body, or (for a stream) one SSE event's `data:` lines. */
+export declare function a2aResponseMeta(bytes: Uint8Array, contentType: string | undefined): Meta;
+/** `sha256:<hex>` of the card's JCS form without `signatures`: what `agent.card_digest` names. */
+export declare function agentCardDigest(card: Record<string, unknown>): string;
+/** What an Agent Card's JWS signs: BASE64URL(JCS(card without signatures)). */
+export declare function agentCardPayload(card: Record<string, unknown>): string;
+export interface AgentCardReport {
+    ok: boolean;
+    digest: string | null;
+    /** Each signature's kid and alg, and whether it verifies under the keys given (null: no such key). */
+    signatures: Array<{
+        kid: string | null;
+        alg: string | null;
+        ok: boolean | null;
+    }>;
+    problems: string[];
+}
+type Jwk = {
+    kty?: string;
+    crv?: string;
+    kid?: string;
+    x?: string;
+    y?: string;
+    n?: string;
+    e?: string;
+};
+/**
+ * §3: checks an Agent Card's signatures against trusted JWKs (by kid): each is a JWS over
+ * BASE64URL(protected) "." BASE64URL(JCS(card without signatures)), ES256, RS256 or EdDSA. The card
+ * is canonicalised as received (A2A's proto default-dropping can't be known from JSON). `ok` when at
+ * least one signature verifies.
+ */
+export declare function verifyAgentCard(card: unknown, keys: readonly Jwk[]): AgentCardReport;
+export {};

package/dist/a2a/index.js

@@ -0,0 +1,202 @@
+// A2A v1.0 capture (spec/a2a.md): what the gateway records of an agent-to-agent JSON-RPC call (both
+// the v1.0 PascalCase methods and the v0.3 names), of each answer or stream event, and the check of
+// an Agent Card's JWS signatures (A2A §8.4: detached, over the JCS card without `signatures`).
+// Mirrors sdks/python/src/zanii_blackbox/a2a.py.
+import { createHash, createPublicKey, verify } from "node:crypto";
+import { canonicalBytes } from "@zanii/core";
+import { assertSafeIntegers } from "../verify/envelope.js";
+/** v0.3 method names → v1.0 (A2A §9.4). */
+const LEGACY = {
+    "message/send": "SendMessage",
+    "message/stream": "SendStreamingMessage",
+    "tasks/get": "GetTask",
+    "tasks/list": "ListTasks",
+    "tasks/cancel": "CancelTask",
+    "tasks/resubscribe": "SubscribeToTask",
+    "tasks/pushNotificationConfig/set": "CreateTaskPushNotificationConfig",
+    "tasks/pushNotificationConfig/get": "GetTaskPushNotificationConfig",
+    "tasks/pushNotificationConfig/list": "ListTaskPushNotificationConfigs",
+    "tasks/pushNotificationConfig/delete": "DeleteTaskPushNotificationConfig",
+    "agent/getAuthenticatedExtendedCard": "GetExtendedAgentCard",
+};
+const V1 = new Set(Object.values(LEGACY));
+/** The methods whose answer is an SSE stream. */
+export const A2A_STREAMING = new Set(["SendStreamingMessage", "SubscribeToTask"]);
+/** The v1.0 name of an A2A method, either name set, or undefined for one A2A doesn't define. */
+export function a2aMethod(method) {
+    return V1.has(method) ? method : LEGACY[method];
+}
+const str = (v, max) => (typeof v === "string" && v.length <= max ? v : undefined);
+const obj = (v) => typeof v === "object" && v !== null && !Array.isArray(v) ? v : {};
+const rpcId = (id) => typeof id === "string" && id.length <= 256
+    ? id
+    : typeof id === "number" && Number.isSafeInteger(id)
+        ? id
+        : undefined;
+const put = (meta, key, value) => {
+    if (value !== undefined)
+        meta[key] = value;
+};
+/**
+ * §2: a request's meta. `version` and `extensions` are the A2A-Version and A2A-Extensions headers
+ * (or the A2A-Version query parameter); an empty version means 0.3.
+ */
+export function a2aRequestMeta(body, headers = {}) {
+    let rpc = {};
+    try {
+        rpc = obj(JSON.parse(Buffer.from(body).toString("utf8")));
+    }
+    catch { }
+    const meta = { a2a_version: str(headers.version, 16) || "0.3" };
+    const ext = (headers.extensions ?? "")
+        .split(",")
+        .map((e) => e.trim())
+        .filter((e) => e !== "" && e.length <= 256)
+        .slice(0, 10);
+    if (ext.length > 0)
+        meta.extensions = ext;
+    const method = str(rpc.method, 128);
+    put(meta, "method", method);
+    const canonical = method === undefined ? undefined : a2aMethod(method);
+    put(meta, "a2a_method", canonical);
+    if (method !== undefined && canonical !== undefined && canonical !== method)
+        meta.legacy = true;
+    put(meta, "rpc_id", rpcId(rpc.id));
+    const p = obj(rpc.params);
+    put(meta, "tenant", str(p.tenant, 128));
+    if (canonical === "SendMessage" || canonical === "SendStreamingMessage") {
+        const m = obj(p.message);
+        put(meta, "message_id", str(m.messageId, 128));
+        put(meta, "context_id", str(m.contextId, 128));
+        put(meta, "task_id", str(m.taskId, 128));
+        put(meta, "role", str(m.role, 32));
+    }
+    else if (canonical !== undefined && /Task$/.test(canonical))
+        put(meta, "task_id", str(p.id, 128));
+    return meta;
+}
+const LEGACY_KINDS = {
+    task: "task",
+    message: "message",
+    "status-update": "statusUpdate",
+    "artifact-update": "artifactUpdate",
+};
+const STATE = /^TASK_STATE_[A-Z_]{1,32}$/;
+const legacyState = (s) => typeof s === "string" && /^[a-z-]{1,32}$/.test(s)
+    ? `TASK_STATE_${s.replaceAll("-", "_").toUpperCase()}`
+    : undefined;
+/** One JSON-RPC response (or SSE event's data), as meta. */
+function responseOf(rpc) {
+    const meta = {};
+    put(meta, "rpc_id", rpcId(rpc.id));
+    const code = obj(rpc.error).code;
+    if (typeof code === "number" && Number.isSafeInteger(code))
+        meta.rpc_error = code;
+    const result = obj(rpc.result);
+    // v1.0: a oneof by key; v0.3: `kind`
+    let type = ["task", "message", "statusUpdate", "artifactUpdate"].find((k) => k in result);
+    let inner = type ? obj(result[type]) : {};
+    if (!type && typeof result.kind === "string" && result.kind in LEGACY_KINDS) {
+        type = LEGACY_KINDS[result.kind];
+        inner = result;
+    }
+    if (!type)
+        return meta;
+    meta.result_type = type;
+    put(meta, "task_id", str(type === "task" ? inner.id : inner.taskId, 128));
+    put(meta, "context_id", str(inner.contextId, 128));
+    const state = obj(inner.status).state;
+    put(meta, "task_state", typeof state === "string" && STATE.test(state) ? state : legacyState(state));
+    if (type === "artifactUpdate")
+        put(meta, "artifact_id", str(obj(inner.artifact).artifactId, 128));
+    return meta;
+}
+/** §2: an answer's meta: a JSON body, or (for a stream) one SSE event's `data:` lines. */
+export function a2aResponseMeta(bytes, contentType) {
+    let text = Buffer.from(bytes).toString("utf8");
+    if (contentType?.includes("text/event-stream"))
+        text = text
+            .split(/\r?\n/)
+            .filter((l) => l.startsWith("data:"))
+            .map((l) => l.slice(5).trim())
+            .join("\n");
+    try {
+        return responseOf(obj(JSON.parse(text)));
+    }
+    catch {
+        return {};
+    }
+}
+// ---------------------------------------------------------------- Agent Cards (A2A §8.4)
+const b64u = (b) => Buffer.from(b).toString("base64url");
+/** `sha256:<hex>` of the card's JCS form without `signatures`: what `agent.card_digest` names. */
+export function agentCardDigest(card) {
+    const { signatures: _, ...rest } = card;
+    assertSafeIntegers(rest); // as Python's canonical JSON does
+    return `sha256:${createHash("sha256")
+        .update(canonicalBytes(rest))
+        .digest("hex")}`;
+}
+/** What an Agent Card's JWS signs: BASE64URL(JCS(card without signatures)). */
+export function agentCardPayload(card) {
+    const { signatures: _, ...rest } = card;
+    assertSafeIntegers(rest);
+    return b64u(canonicalBytes(rest));
+}
+function verifyJws(alg, jwk, input, sig) {
+    try {
+        const key = createPublicKey({ key: jwk, format: "jwk" });
+        if (alg === "ES256" && jwk.kty === "EC" && jwk.crv === "P-256")
+            return verify("sha256", input, { key, dsaEncoding: "ieee-p1363" }, sig);
+        if (alg === "RS256" && jwk.kty === "RSA")
+            return verify("sha256", input, key, sig);
+        if (alg === "EdDSA" && jwk.kty === "OKP" && jwk.crv === "Ed25519")
+            return verify(null, input, key, sig);
+    }
+    catch { }
+    return false;
+}
+/**
+ * §3: checks an Agent Card's signatures against trusted JWKs (by kid): each is a JWS over
+ * BASE64URL(protected) "." BASE64URL(JCS(card without signatures)), ES256, RS256 or EdDSA. The card
+ * is canonicalised as received (A2A's proto default-dropping can't be known from JSON). `ok` when at
+ * least one signature verifies.
+ */
+export function verifyAgentCard(card, keys) {
+    const report = { ok: false, digest: null, signatures: [], problems: [] };
+    const c = obj(card);
+    if (Object.keys(c).length === 0)
+        return { ...report, problems: ["not an Agent Card"] };
+    let payload;
+    try {
+        report.digest = agentCardDigest(c);
+        payload = agentCardPayload(c);
+    }
+    catch {
+        return { ...report, problems: ["the card can't be canonicalised (non-integer numbers?)"] };
+    }
+    const sigs = Array.isArray(c.signatures) ? c.signatures.slice(0, 10) : [];
+    if (sigs.length === 0)
+        report.problems.push("the card isn't signed");
+    for (const s of sigs) {
+        const sig = obj(s);
+        let header = {};
+        try {
+            header = obj(JSON.parse(Buffer.from(String(sig.protected), "base64url").toString("utf8")));
+        }
+        catch { }
+        const kid = str(header.kid, 256) ?? null;
+        const alg = str(header.alg, 16) ?? null;
+        const jwk = keys.find((k) => k.kid !== undefined && k.kid === kid);
+        const ok = jwk && alg && typeof sig.protected === "string" && typeof sig.signature === "string"
+            ? verifyJws(alg, jwk, Buffer.from(`${sig.protected}.${payload}`), Buffer.from(sig.signature, "base64url"))
+            : null;
+        report.signatures.push({ kid, alg, ok });
+    }
+    report.ok = report.signatures.some((s) => s.ok === true);
+    if (sigs.length > 0 && !report.ok)
+        report.problems.push(report.signatures.some((s) => s.ok === false)
+            ? "a signature doesn't verify"
+            : "no signature is by a trusted key");
+    return report;
+}

package/dist/analysis/taxonomy.d.ts

@@ -0,0 +1,18 @@
+export declare const OWASP_ASI: Readonly<Record<string, string>>;
+export declare const MITRE_ATLAS: Readonly<Record<string, string>>;
+export declare const TAXONOMY: Readonly<Record<string, {
+    owasp?: readonly string[];
+    atlas?: readonly string[];
+}>>;
+export interface Taxonomy {
+    owasp: Array<{
+        id: string;
+        title: string;
+    }>;
+    atlas: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+/** The OWASP ASI and MITRE ATLAS entries a finding code maps to; empty lists when none fits. */
+export declare function taxonomyOf(code: string): Taxonomy;

package/dist/analysis/taxonomy.js

@@ -0,0 +1,65 @@
+// Threat taxonomy per finding code (spec/findings.md §7, spec/faults/taxonomy-v1.json): OWASP Top 10
+// for Agentic Applications 2026 and MITRE ATLAS technique ids. A test checks this table matches the
+// file exactly. Mirrors analysis/taxonomy.py.
+export const OWASP_ASI = {
+    ASI01: "Agent Goal Hijack",
+    ASI02: "Tool Misuse & Exploitation",
+    ASI03: "Identity & Privilege Abuse",
+    ASI04: "Agentic Supply Chain Vulnerabilities",
+    ASI05: "Unexpected Code Execution (RCE)",
+    ASI06: "Memory & Context Poisoning",
+    ASI07: "Insecure Inter-Agent Communication",
+    ASI08: "Cascading Failures",
+    ASI09: "Human-Agent Trust Exploitation",
+    ASI10: "Rogue Agents",
+};
+export const MITRE_ATLAS = {
+    "AML.T0034": "Cost Harvesting",
+    "AML.T0034.000": "Cost Harvesting: Excessive Queries",
+    "AML.T0034.001": "Cost Harvesting: Resource-Intensive Queries",
+    "AML.T0034.002": "Cost Harvesting: Agentic Resource Consumption",
+    "AML.T0053": "AI Agent Tool Invocation",
+    "AML.T0057": "LLM Data Leakage",
+    "AML.T0080.000": "AI Agent Context Poisoning: Memory",
+    "AML.T0086": "Exfiltration via AI Agent Tool Invocation",
+    "AML.T0091.000": "Application Access Token",
+    "AML.T0099": "AI Agent Tool Data Poisoning",
+    "AML.T0110.002": "AI Agent Tool Poisoning: Runtime Response",
+};
+export const TAXONOMY = {
+    ABNORMAL_RUN: { owasp: ["ASI10"] },
+    ALTERED: { owasp: ["ASI10"] },
+    AUTOMATION_SURPRISE: { owasp: ["ASI10"] },
+    BYPASS: { owasp: ["ASI10"] },
+    CALL_LIMIT: { atlas: ["AML.T0034", "AML.T0034.000"] },
+    CLAIM_UNVERIFIED: { owasp: ["ASI09"] },
+    D1_REPEAT_CALL: { atlas: ["AML.T0034.002"] },
+    D2_ACTION_LOOP: { atlas: ["AML.T0034.002"] },
+    D4_CONTEXT_BLOAT: { atlas: ["AML.T0034.001"] },
+    D6_SPEND: { atlas: ["AML.T0034", "AML.T0034.002"] },
+    DATA_CANARY_TRIPPED: { owasp: ["ASI02"], atlas: ["AML.T0086", "AML.T0057"] },
+    DATA_TO_UNAPPROVED_DESTINATION: { owasp: ["ASI02"], atlas: ["AML.T0086"] },
+    EXTRA_LOCAL: { owasp: ["ASI10"] },
+    FALSE_CLAIM: { owasp: ["ASI09", "ASI10"] },
+    FALSE_SUCCESS: { owasp: ["ASI09", "ASI10"] },
+    MISSING_LOCAL: { owasp: ["ASI10"] },
+    PLAN_DEVIATION: { owasp: ["ASI01", "ASI10"] },
+    PLAN_VIOLATION: { owasp: ["ASI02", "ASI10"], atlas: ["AML.T0053"] },
+    POLICY_AUDIT: { owasp: ["ASI02"], atlas: ["AML.T0053"] },
+    POLICY_DENIED: { owasp: ["ASI02"], atlas: ["AML.T0053"] },
+    POLICY_VIOLATION: { owasp: ["ASI02"], atlas: ["AML.T0053"] },
+    RETRY_STORM: { owasp: ["ASI08"] },
+    REVOKED_MEMORY_READ: { owasp: ["ASI06"], atlas: ["AML.T0080.000"] },
+    STERILE_VIOLATION: { owasp: ["ASI02", "ASI10"], atlas: ["AML.T0053"] },
+    TOKEN_MISUSE: { owasp: ["ASI03"], atlas: ["AML.T0091.000", "AML.T0086"] },
+    TOOL_OUTPUT_MISMATCH: { owasp: ["ASI04", "ASI06"], atlas: ["AML.T0110.002", "AML.T0099"] },
+    TOOL_WITNESS_INVALID: { owasp: ["ASI04"], atlas: ["AML.T0110.002"] },
+};
+/** The OWASP ASI and MITRE ATLAS entries a finding code maps to; empty lists when none fits. */
+export function taxonomyOf(code) {
+    const t = TAXONOMY[code];
+    return {
+        owasp: (t?.owasp ?? []).map((id) => ({ id, title: OWASP_ASI[id] ?? id })),
+        atlas: (t?.atlas ?? []).map((id) => ({ id, name: MITRE_ATLAS[id] ?? id })),
+    };
+}

package/dist/archive/index.d.ts

@@ -0,0 +1,39 @@
+export interface ArchiveFile {
+    name: string;
+    sha256: string;
+    bytes: number;
+}
+export interface ArchiveManifest {
+    v: 1;
+    id: string;
+    created_at: string;
+    files: ArchiveFile[];
+    /** RFC 9162 root over leafHash(`<name> <sha256>`), in name order. */
+    root: string;
+    /** The log checkpoint (a signed note) when it was made, or null. */
+    checkpoint: string | null;
+    /** RFC 3161 TimeStampResps, base64, oldest first. */
+    timestamps: string[];
+}
+/** §2: one file's entry. Names are plain: 1-128 of [A-Za-z0-9._-]. */
+export declare function archiveEntry(name: string, data: Uint8Array): ArchiveFile;
+/** §2: the manifest, without timestamps, for these entries (unique names). */
+export declare function archiveManifest(id: string, createdAt: string, entries: readonly ArchiveFile[], checkpoint: string | null): ArchiveManifest;
+/** §3: what the `n`th timestamp stamps: SHA-256 of the manifest's core, then of that and the previous token. */
+export declare function archiveDigest(manifest: ArchiveManifest, n: number): Uint8Array;
+export interface ArchiveReport {
+    ok: boolean;
+    /** Each file's hash and size match; null when no files were given. */
+    files: boolean | null;
+    root: boolean;
+    /** Each timestamp's time, oldest first, while the chain holds. */
+    timestamps: string[];
+    problems: string[];
+}
+/**
+ * §4: checks a manifest offline: its root, each file given (by name), and the timestamp chain,
+ * each token against the digest it must stamp and `tsaRoots`.
+ */
+export declare function verifyArchive(manifest: ArchiveManifest, files: ReadonlyMap<string, Uint8Array> | null, options?: {
+    tsaRoots?: readonly string[];
+}): ArchiveReport;

package/dist/archive/index.js

@@ -0,0 +1,96 @@
+// Cold archives (spec/archive.md): a set of closed sessions' records, kept for years as plain JSONL
+// files with a manifest: each file's SHA-256, an RFC 9162 Merkle root over them, the log checkpoint
+// they sit under, and a chain of RFC 3161 timestamps. Each renewal stamps the manifest and the
+// previous token, so the evidence outlives the TSA's certificate and its algorithms (the RFC 4998
+// idea). Mirrors sdks/python/src/zanii_blackbox/archive.py.
+import { createHash } from "node:crypto";
+import { canonicalBytes } from "@zanii/core";
+import { verifyTimestamp } from "../timestamp/index.js";
+import { leafHash, merkleRoot } from "../transparency/index.js";
+const sha256 = (...parts) => {
+    const h = createHash("sha256");
+    for (const p of parts)
+        h.update(p);
+    return new Uint8Array(h.digest());
+};
+const hex = (b) => Buffer.from(b).toString("hex");
+const NAME = /^[A-Za-z0-9._-]{1,128}$/;
+/** §2: one file's entry. Names are plain: 1-128 of [A-Za-z0-9._-]. */
+export function archiveEntry(name, data) {
+    if (!NAME.test(name))
+        throw new Error(`an archive file name must be 1-128 of [A-Za-z0-9._-]: ${name}`);
+    return { name, sha256: hex(sha256(data)), bytes: data.length };
+}
+/** §2: the manifest, without timestamps, for these entries (unique names). */
+export function archiveManifest(id, createdAt, entries, checkpoint) {
+    const names = new Set(entries.map((f) => f.name));
+    if (names.size !== entries.length)
+        throw new Error("archive file names must be unique");
+    const listed = [...entries]
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+        .map((f) => ({ name: f.name, sha256: f.sha256, bytes: f.bytes }));
+    return {
+        v: 1,
+        id,
+        created_at: createdAt,
+        files: listed,
+        root: hex(merkleRoot(listed.map((f) => leafHash(Buffer.from(`${f.name} ${f.sha256}`, "utf8"))))),
+        checkpoint,
+        timestamps: [],
+    };
+}
+/** §3: what the `n`th timestamp stamps: SHA-256 of the manifest's core, then of that and the previous token. */
+export function archiveDigest(manifest, n) {
+    const { timestamps, ...core } = manifest;
+    const first = sha256(canonicalBytes(core));
+    if (n === 0)
+        return first;
+    const previous = timestamps[n - 1];
+    if (previous === undefined)
+        throw new Error(`the archive has no timestamp ${n - 1}`);
+    return sha256(first, Buffer.from(previous, "base64"));
+}
+/**
+ * §4: checks a manifest offline: its root, each file given (by name), and the timestamp chain,
+ * each token against the digest it must stamp and `tsaRoots`.
+ */
+export function verifyArchive(manifest, files, options = {}) {
+    const report = {
+        ok: false,
+        files: null,
+        root: false,
+        timestamps: [],
+        problems: [],
+    };
+    const leaves = manifest.files.map((f) => leafHash(Buffer.from(`${f.name} ${f.sha256}`, "utf8")));
+    report.root = leaves.length > 0 && hex(merkleRoot(leaves)) === manifest.root;
+    if (!report.root)
+        report.problems.push("the root isn't the files'");
+    if (files) {
+        const bad = manifest.files.filter((f) => {
+            const data = files.get(f.name);
+            return !data || data.length !== f.bytes || hex(sha256(data)) !== f.sha256;
+        });
+        report.files = bad.length === 0;
+        for (const f of bad)
+            report.problems.push(`${f.name} is missing or changed`);
+    }
+    let last = Number.NEGATIVE_INFINITY;
+    for (let i = 0; i < manifest.timestamps.length; i++) {
+        const t = verifyTimestamp(new Uint8Array(Buffer.from(manifest.timestamps[i], "base64")), {
+            digest: archiveDigest(manifest, i),
+            ...(options.tsaRoots ? { roots: options.tsaRoots } : {}),
+        });
+        const at = t.gen_time ? Date.parse(t.gen_time) : Number.NaN;
+        if (!t.ok || !t.gen_time || !(at >= last)) {
+            report.problems.push(`timestamp ${i} doesn't hold: ${t.problems.join("; ") || "out of order"}`);
+            break;
+        }
+        last = at;
+        report.timestamps.push(t.gen_time);
+    }
+    if (manifest.timestamps.length === 0)
+        report.problems.push("the archive has no timestamp");
+    report.ok = report.problems.length === 0;
+    return report;
+}

package/dist/bom/index.d.ts

@@ -0,0 +1,14 @@
+export interface AgentIdentity {
+    id: string;
+    version?: string;
+    /** A SPIFFE ID for the workload the agent runs as. */
+    workload?: string;
+    /** The user or agent it acts for. */
+    on_behalf_of?: string;
+    /** The SHA-256 of its A2A Agent Card, `sha256:<hex>`. */
+    card_digest?: string;
+}
+/** spec/bom.md §1: an error message, or undefined for a valid `agent`. */
+export declare function checkAgent(value: unknown): string | undefined;
+/** spec/bom.md §2: a CycloneDX 1.6 JSON ML-BOM of one session's record. */
+export declare function sessionBom(lines: readonly string[]): Record<string, unknown>;

package/dist/bom/index.js

@@ -0,0 +1,132 @@
+// Agent identity and the agent's bill of materials (spec/bom.md): the `agent` a session is opened
+// with, and a CycloneDX 1.6 ML-BOM of what one session actually used (models, providers, tool
+// servers), made from its record. Deterministic: the same record gives the same bytes.
+// Mirrors sdks/python/src/zanii_blackbox/bom.py.
+import { createHash } from "node:crypto";
+import { hashLine } from "../verify/envelope.js";
+const AGENT_KEYS = new Set(["id", "version", "workload", "on_behalf_of", "card_digest"]);
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** spec/bom.md §1: an error message, or undefined for a valid `agent`. */
+export function checkAgent(value) {
+    if (!isObject(value))
+        return "agent must be an object";
+    const extra = Object.keys(value).find((k) => !AGENT_KEYS.has(k));
+    if (extra !== undefined)
+        return `agent.${extra} isn't a field`;
+    const { id, version, workload, on_behalf_of: onBehalfOf, card_digest: card } = value;
+    if (typeof id !== "string" || !/^[A-Za-z0-9._:@/-]{1,128}$/.test(id))
+        return "agent.id must be 1-128 of [A-Za-z0-9._:@/-]";
+    if (version !== undefined &&
+        (typeof version !== "string" || !/^[A-Za-z0-9._+-]{1,64}$/.test(version)))
+        return "agent.version must be 1-64 of [A-Za-z0-9._+-]";
+    if (workload !== undefined &&
+        (typeof workload !== "string" ||
+            !/^spiffe:\/\/[^\s/]+(\/\S*)?$/.test(workload) ||
+            workload.length > 2048))
+        return "agent.workload must be a SPIFFE ID (spiffe://trust-domain/path)";
+    if (onBehalfOf !== undefined &&
+        (typeof onBehalfOf !== "string" ||
+            onBehalfOf.length < 1 ||
+            onBehalfOf.length > 256 ||
+            [...onBehalfOf].some((c) => c < " " || c === "\u007f")))
+        return "agent.on_behalf_of must be 1-256 characters, no control characters";
+    if (card !== undefined && (typeof card !== "string" || !/^sha256:[0-9a-f]{64}$/.test(card)))
+        return "agent.card_digest must be sha256:<64 hex>";
+    return undefined;
+}
+const props = (pairs) => pairs
+    .filter((p) => typeof p[1] === "string" || typeof p[1] === "number")
+    .map(([name, value]) => ({ name, value: String(value) }));
+/** A UUID (version 8, RFC 9562) from the record's identity: the same record, the same serial. */
+function serialOf(sessionId, count, head) {
+    const h = createHash("sha256").update(`${sessionId}\n${count}\n${head}`).digest();
+    h[6] = (h[6] & 0x0f) | 0x80;
+    h[8] = (h[8] & 0x3f) | 0x80;
+    const x = h.subarray(0, 16).toString("hex");
+    return `urn:uuid:${x.slice(0, 8)}-${x.slice(8, 12)}-${x.slice(12, 16)}-${x.slice(16, 20)}-${x.slice(20)}`;
+}
+/** spec/bom.md §2: a CycloneDX 1.6 JSON ML-BOM of one session's record. */
+export function sessionBom(lines) {
+    const events = lines.map((l) => JSON.parse(l));
+    const first = events[0];
+    const last = lines.at(-1);
+    if (!first || last === undefined)
+        throw new Error("a BOM needs a record");
+    const sid = first.session_id;
+    const open = events.find((e) => e.kind === "session.open");
+    const agent = (isObject(open?.meta.agent) ? open.meta.agent : {});
+    const label = typeof open?.meta.label === "string" ? open.meta.label : undefined;
+    const providerOf = new Map();
+    const providers = new Map();
+    const models = new Map();
+    const servers = new Map();
+    for (const e of events) {
+        const m = e.meta;
+        if (e.kind === "llm.request" && typeof m.provider === "string") {
+            providerOf.set(e.seq, m.provider);
+            providers.set(m.provider, (providers.get(m.provider) ?? 0) + 1);
+        }
+        else if (e.kind === "llm.response" && typeof m.model === "string") {
+            const provider = providerOf.get(m.request_seq) ?? "unknown";
+            const key = `${provider}/${m.model}`;
+            const had = models.get(key) ?? { provider, model: m.model, calls: 0 };
+            had.calls++;
+            models.set(key, had);
+        }
+        else if (e.kind === "tool.call" && typeof m.server === "string") {
+            const tools = servers.get(m.server) ?? new Set();
+            if (typeof m.tool === "string")
+                tools.add(m.tool);
+            servers.set(m.server, tools);
+        }
+    }
+    const byKey = (m) => [...m.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const components = byKey(models).map(([key, v]) => ({
+        type: "machine-learning-model",
+        "bom-ref": `model:${key}`,
+        name: v.model,
+        publisher: v.provider,
+        properties: props([["zanii:calls", v.calls]]),
+    }));
+    const services = [
+        ...byKey(providers).map(([id, calls]) => ({
+            "bom-ref": `provider:${id}`,
+            name: id,
+            group: "llm-provider",
+            properties: props([["zanii:calls", calls]]),
+        })),
+        ...byKey(servers).map(([id, tools]) => ({
+            "bom-ref": `tools:${id}`,
+            name: id,
+            group: "tool-server",
+            properties: [...tools].sort().map((t) => ({ name: "zanii:tool", value: t })),
+        })),
+    ];
+    const refs = [...components.map((c) => c["bom-ref"]), ...services.map((s) => s["bom-ref"])];
+    return {
+        bomFormat: "CycloneDX",
+        specVersion: "1.6",
+        serialNumber: serialOf(sid, lines.length, hashLine(last)),
+        version: 1,
+        metadata: {
+            timestamp: events.at(-1).ts,
+            tools: { components: [{ type: "application", name: "zanii-blackbox" }] },
+            component: {
+                type: "application",
+                "bom-ref": "agent",
+                name: agent.id ?? label ?? sid,
+                ...(agent.version ? { version: agent.version } : {}),
+                properties: props([
+                    ["zanii:session_id", sid],
+                    ["zanii:workload", agent.workload],
+                    ["zanii:on_behalf_of", agent.on_behalf_of],
+                    ["zanii:card_digest", agent.card_digest],
+                    ["zanii:record_head", hashLine(last)],
+                ]),
+            },
+        },
+        components,
+        services,
+        dependencies: [{ ref: "agent", dependsOn: refs }],
+    };
+}

package/dist/compliance/art12.d.ts

@@ -0,0 +1,35 @@
+type Evidence = Record<string, number | string | boolean | null | string[] | Record<string, number>>;
+export interface Art12Check {
+    id: string;
+    article: string;
+    requirement: string;
+    /** False: the paragraph covers only Annex III point 1(a) systems (remote biometric identification). */
+    applies: boolean;
+    /** True or false where the record can show it; null where a person must judge the evidence. */
+    ok: boolean | null;
+    evidence: Evidence;
+}
+export interface Art12Report {
+    session_id: string;
+    regulation: "Regulation (EU) 2024/1689";
+    annex_iii_1a: boolean;
+    /** Every applicable check that can pass, passes. */
+    ok: boolean;
+    checks: Art12Check[];
+    notes: string;
+}
+/** Art. 19(1) and 26(6): "at least six months". Counted as 183 days, the longest six months. */
+export declare const ART12_MIN_RETENTION_DAYS = 183;
+/**
+ * Checks one session's record against Article 12. `verified`: whether its chain verifies (the caller
+ * runs the check). `retentionDays`: the deployment's retention, null when records are kept forever.
+ * `annexIII1a`: the system is a remote biometric identification system, so 12(3) applies.
+ */
+export declare function art12Check(record: {
+    lines: readonly string[];
+    verified: boolean;
+}, options: {
+    retentionDays: number | null;
+    annexIII1a?: boolean;
+}): Art12Report;
+export {};