@zanii/blackbox 0.1.0 → 0.3.0

package/dist/cli.js

@@ -45,6 +45,7 @@ const USAGE = `usage (spec/cli.md):
   blackbox mcp   (an MCP server on stdio: spec/mcp-server.md)
   blackbox mcp-wrap --server <name> -- <command> [args...]
   blackbox reconcile --harness claude-code|codex --bundle <bundle.json> --bodies <dir> [--agent-session <id>]... [--require-receipts] <path>
+  blackbox reconcile-system --connector <connector.json> --log <export.csv|jsonl> [--pack <pack.json>] <session_id>
   blackbox workspace-receipt   (a Claude Code PreToolUse / PostToolUse hook; reads the hook JSON on stdin)
   blackbox attest   (a Claude Code PostToolUse hook: spec/attestation.md §4)`;
 async function main(argv) {
@@ -55,6 +56,8 @@ async function main(argv) {
         return wrap(rest);
     if (command === "reconcile")
         return reconcileCommand(rest);
+    if (command === "reconcile-system")
+        return reconcileSystemCommand(rest);
     if (command === "workspace-receipt")
         return receiptCommand();
     if (command === "attest")
@@ -1007,6 +1010,41 @@ async function drainCommand(rest) {
     process.stdout.write(`${JSON.stringify({ ok: results.every((r) => r.shipped), sessions: results })}\n`);
     return results.every((r) => r.shipped) ? 0 : 2;
 }
+/** spec/data.md §10: the session's record against a touched system's own audit-log export, run
+ *  here so the export never leaves this machine. Exits 1 on any finding. */
+async function reconcileSystemCommand(rest) {
+    const { flags, positional } = parse(rest, []);
+    const id = positional[0] ?? "";
+    if (positional.length !== 1 || !SESSION_ID.test(id) || !flags.connector || !flags.log)
+        return usage();
+    const { checkAuditConnector, parseAuditLog, reconcileSystem, CORE_EVIDENCE } = await import("./data/index.js");
+    const { packData } = await import("./packs/index.js");
+    const connector = JSON.parse(readFileSync(flags.connector, "utf8"));
+    const bad = checkAuditConnector(connector);
+    if (bad)
+        throw new ServerError(`--connector: ${bad}`);
+    const evidence = flags.pack
+        ? packData([JSON.parse(readFileSync(flags.pack, "utf8"))]).evidence
+        : CORE_EVIDENCE;
+    const c = connector;
+    const rows = parseAuditLog(readFileSync(flags.log, "utf8"), c);
+    const bundle = (await adminJson(`/v1/sessions/${id}/bundle`));
+    // Only the bodies the comparison reads: tool calls and results, and SDK events.
+    const bodies = new Map();
+    for (const line of bundle.lines) {
+        const e = JSON.parse(line);
+        if (!["tool.call", "tool.result", "sdk.event"].includes(e.kind) || bodies.has(e.body_hash))
+            continue;
+        if (!/^sha256:[0-9a-f]{64}$/.test(e.body_hash))
+            continue;
+        const res = await admin(`/v1/bodies/${e.body_hash}`, undefined, [404, 410]);
+        if (res.status === 200)
+            bodies.set(e.body_hash, Buffer.from(await res.arrayBuffer()));
+    }
+    const report = reconcileSystem(bundle.lines, (h) => bodies.get(h), rows, c, evidence);
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return report.findings.length > 0 ? 1 : 0;
+}
 function usage() {
     process.stderr.write(`${USAGE}\n`);
     return 2;

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

package/dist/compliance/art12.js

@@ -0,0 +1,163 @@
+// EU AI Act Article 12 (record-keeping) for one session's record (spec/art12.md): what the record
+// shows against Art. 12(1), 12(2)(a)-(c), 12(3)(a)-(d), and the six-month log retention of Art. 19(1)
+// and 26(6). Evidence mapping from the public text of Regulation (EU) 2024/1689, not legal advice.
+// Mirrors sdks/python/src/zanii_blackbox/art12.py.
+/** Art. 19(1) and 26(6): "at least six months". Counted as 183 days, the longest six months. */
+export const ART12_MIN_RETENTION_DAYS = 183;
+const NOT_PEOPLE = new Set(["timeout", "unattended", "classifier"]);
+const NOTES = "Evidence mapping from the public text of Regulation (EU) 2024/1689, not legal advice. Article 12 applies to high-risk AI systems; whether a system is one, and whether it complies, is for its provider, deployer and counsel to judge. One session shows one period of use, not the system's lifetime.";
+const sorted = (s) => [...new Set(s)].sort();
+const count = (into, key) => {
+    into[key] = (into[key] ?? 0) + 1;
+};
+/**
+ * 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 function art12Check(record, options) {
+    const events = record.lines.map((l) => JSON.parse(l));
+    const annex = options.annexIII1a === true;
+    let gaps = 0;
+    let lostContact = 0;
+    let errors = 0;
+    let inputs = 0;
+    let outcome = null;
+    const findings = {};
+    const codes = [];
+    const controls = {};
+    const models = [];
+    const providers = [];
+    const sources = [];
+    const deciders = [];
+    let decisions = 0;
+    for (const e of events) {
+        const m = e.meta;
+        if (e.kind === "capture.gap")
+            gaps += typeof m.missed === "number" ? m.missed : 1;
+        else if (e.kind === "session.lost_contact")
+            lostContact++;
+        else if (e.kind === "finding") {
+            count(findings, typeof m.severity === "string" ? m.severity : "unknown");
+            if (typeof m.code === "string")
+                codes.push(m.code);
+        }
+        else if (e.kind === "control" && typeof m.action === "string") {
+            count(controls, m.action);
+            if (m.action === "approval" && typeof m.by === "string") {
+                decisions++;
+                deciders.push(m.by);
+            }
+        }
+        else if (e.kind === "llm.request") {
+            inputs++;
+            if (typeof m.provider === "string")
+                providers.push(m.provider);
+        }
+        else if (e.kind === "llm.response") {
+            if (typeof m.model === "string")
+                models.push(m.model);
+            if (typeof m.status === "number" && m.status >= 400)
+                errors++;
+        }
+        else if (e.kind === "tool.call") {
+            inputs++;
+            if (typeof m.server === "string")
+                sources.push(typeof m.tool === "string" ? `${m.server}/${m.tool}` : m.server);
+        }
+        else if (e.kind === "outcome" && typeof m.outcome === "string")
+            outcome = m.outcome;
+    }
+    const open = events.find((e) => e.kind === "session.open");
+    const close = events.find((e) => e.kind === "session.close");
+    const people = sorted(deciders.filter((d) => !NOT_PEOPLE.has(d)));
+    const retention = options.retentionDays;
+    const checks = [
+        {
+            id: "automatic-recording",
+            article: "12(1)",
+            requirement: "Events are recorded automatically over the system's lifetime: here, a record that verifies and has no capture gaps.",
+            applies: true,
+            ok: record.verified && open !== undefined && gaps === 0,
+            evidence: {
+                events: events.length,
+                verified: record.verified,
+                capture_gaps: gaps,
+                lost_contact: lostContact,
+            },
+        },
+        {
+            id: "risk-situations",
+            article: "12(2)(a)",
+            requirement: "Events relevant to identifying situations that may present a risk (Art. 79(1)) or a substantial modification.",
+            applies: true,
+            ok: null,
+            evidence: { findings, finding_codes: sorted(codes), models: sorted(models) },
+        },
+        {
+            id: "post-market-monitoring",
+            article: "12(2)(b)",
+            requirement: "Events that facilitate post-market monitoring (Art. 72).",
+            applies: true,
+            ok: null,
+            evidence: { providers: sorted(providers), models: sorted(models), errors, outcome },
+        },
+        {
+            id: "operation-monitoring",
+            article: "12(2)(c)",
+            requirement: "Events for deployers' monitoring of the system's operation (Art. 26(5)).",
+            applies: true,
+            ok: null,
+            evidence: { controls, unattended: open?.meta.unattended === true },
+        },
+        {
+            id: "period-of-use",
+            article: "12(3)(a)",
+            requirement: "The start and end date and time of each use.",
+            applies: annex,
+            ok: open !== undefined && close !== undefined,
+            evidence: { start: open?.ts ?? null, end: close?.ts ?? null },
+        },
+        {
+            id: "reference-database",
+            article: "12(3)(b)",
+            requirement: "The reference database against which input data was checked.",
+            applies: annex,
+            ok: null,
+            evidence: { sources: sorted(sources) },
+        },
+        {
+            id: "input-data",
+            article: "12(3)(c)",
+            requirement: "The input data for which the search led to a match.",
+            applies: annex,
+            ok: null,
+            evidence: { inputs },
+        },
+        {
+            id: "verifying-persons",
+            article: "12(3)(d), 14(5)",
+            requirement: "The natural persons who verified the results; for Art. 14(5), at least two, separately.",
+            applies: annex,
+            // ponytail: decisions name a role (admin, tenant), not a person; false until SSO subjects are recorded
+            ok: decisions === 0 ? null : false,
+            evidence: { decisions, deciders: people, persons_identified: false },
+        },
+        {
+            id: "log-retention",
+            article: "19(1), 26(6)",
+            requirement: "Logs are kept for at least six months, unless other Union or national law says otherwise.",
+            applies: true,
+            ok: retention === null || retention >= ART12_MIN_RETENTION_DAYS,
+            evidence: { retention_days: retention, minimum_days: ART12_MIN_RETENTION_DAYS },
+        },
+    ];
+    return {
+        session_id: events[0]?.session_id ?? "",
+        regulation: "Regulation (EU) 2024/1689",
+        annex_iii_1a: annex,
+        ok: checks.every((c) => !c.applies || c.ok !== false),
+        checks,
+        notes: NOTES,
+    };
+}

package/dist/data/index.d.ts

@@ -0,0 +1,191 @@
+export interface Identifier {
+    id: string;
+    title: string;
+    pattern: string;
+    normalize: "digits" | "lower" | "upper" | "exact";
+    keep_last?: number;
+    check?: "luhn";
+    personal: boolean;
+}
+/** spec/data/identifiers-v1.json: always on. */
+export declare const CORE_IDENTIFIERS: readonly Identifier[];
+/** spec/data/core-v1.json: evidence defaults for common writes (§5). */
+export declare const CORE_EVIDENCE: ReadonlyArray<{
+    tool: string;
+    field: string;
+}>;
+/**
+ * §6: the canary values as one identifier, matched literally. Longer values first, so a value that
+ * contains another wins. ASCII punctuation is escaped the same way both languages read it.
+ */
+export declare function canaryIdentifier(values: readonly string[]): Identifier;
+export declare function normalizeValue(value: string, how: Identifier["normalize"]): string;
+export declare function luhn(digits: string): boolean;
+export interface Found {
+    id: string;
+    value: string;
+}
+/** §1: each distinct (id, normalized value) in text order, at most 200. Earlier identifiers win a span. */
+export declare function dataScan(text: string, identifiers: readonly Identifier[]): Found[];
+/** Every match counted (not only distinct ones), for `data.classes`. */
+export declare function dataClasses(text: string, identifiers: readonly Identifier[]): Record<string, number>;
+/** §2: the tenant's fingerprint of one identifier value. */
+export declare function dataFingerprint(key: Uint8Array | string, tenant: string, id: string, value: string): string;
+/** §2: the `data` meta of a body, or undefined when it holds no identifier. */
+export declare function dataMeta(text: string, identifiers: readonly Identifier[], key: Uint8Array | string, tenant: string): {
+    classes: Record<string, number>;
+    fps: Array<{
+        id: string;
+        fp: string;
+    }>;
+} | undefined;
+export interface Lineage {
+    subjects: Array<{
+        fp: string;
+        id: string;
+        first: {
+            seq: number;
+            kind: string;
+            from: string;
+        };
+        sent: Array<{
+            seq: number;
+            to: string;
+            region?: string;
+        }>;
+    }>;
+    destinations: Array<{
+        to: string;
+        region?: string;
+        classes: Record<string, number>;
+        subjects: number;
+    }>;
+}
+/** §3: where each subject's data came from and went in one session. */
+export declare function lineage(lines: readonly string[]): Lineage;
+export interface Topology {
+    nodes: Array<{
+        id: string;
+        kind: string;
+        region?: string;
+        sessions: number;
+    }>;
+    edges: Array<{
+        from: string;
+        to: string;
+        region?: string;
+        classes: Record<string, number>;
+        subjects: number;
+        sessions: number;
+        flags: Array<"outside_region" | "region_unknown">;
+    }>;
+}
+/**
+ * §3a: many sessions' lineage as one map: where data is read from (nodes on the left) and sent to,
+ * with how many subjects and sessions each flow carried. With `dataRegion`, a flow to a model in
+ * another region is flagged `outside_region`, one to a model of no known region `region_unknown`.
+ */
+export declare function dataTopology(sessions: ReadonlyArray<{
+    session_id: string;
+    lines: readonly string[];
+}>, dataRegion?: string | null): Topology;
+export interface DataRules {
+    identifiers: readonly Identifier[];
+    residency: boolean;
+    restricted: ReadonlyArray<{
+        identifiers: readonly string[];
+        allow: readonly string[];
+    }>;
+    evidence: ReadonlyArray<{
+        tool: string;
+        field: string;
+    }>;
+}
+export interface DataFinding {
+    code: "DATA_LEFT_REGION" | "DATA_REGION_UNKNOWN" | "DATA_TO_UNAPPROVED_DESTINATION" | "DATA_CANARY_TRIPPED" | "CONSENT_WITHDRAWN_USE" | "EGRESS_OPEN" | "TOOL_WITNESS_INVALID" | "UNEVIDENCED_SIDE_EFFECT";
+    severity: "advisory" | "caution" | "warning";
+    ref: Record<string, string | number>;
+}
+/** §4, §6, §7, §9: findings over a session's events. */
+export declare function dataFindings(lines: readonly string[], rules: Pick<DataRules, "identifiers" | "residency" | "restricted">, dataRegion: string | null): DataFinding[];
+export declare const hasEvidence: (value: unknown, field: string) => boolean;
+/** §5: successful results of state-changing tools with no evidence of their own. */
+export declare function unevidenced(lines: readonly string[], body: (hash: string) => Uint8Array | undefined, rules: DataRules["evidence"]): DataFinding[];
+/** §9: a tool signs what it returns, so the result is the tool's word, not the agent's. */
+export declare function toolWitness(keypair: {
+    did?: string;
+    privateKey: Uint8Array;
+}): {
+    did: string;
+    sign(result: unknown): {
+        result: unknown;
+        witness: {
+            did: string;
+            sig: string;
+        };
+    };
+};
+/** §9: does `witness` sign `result`? */
+export declare function verifyToolWitness(result: unknown, witness: {
+    did?: unknown;
+    sig?: unknown;
+}): boolean;
+/** §9: the witness an MCP result or an SDK tool.result body carries, checked; undefined if none. */
+export declare function witnessOf(bodyJson: unknown): {
+    did: string;
+    ok: boolean;
+} | undefined;
+export interface Connector {
+    v: 1;
+    id: string;
+    format: "csv" | "jsonl";
+    fields: {
+        at: string;
+        action: string;
+        object?: string;
+        evidence?: string;
+        amount?: string;
+        actor?: string;
+    };
+    actions: Record<string, string>;
+    /** Which tool arguments hold the object and the amount the call acted on. */
+    arguments?: {
+        object?: string;
+        amount?: string;
+    };
+    window_seconds?: number;
+}
+export interface AuditRow {
+    row: number;
+    at: number;
+    action: string;
+    object?: string;
+    evidence?: string;
+    amount?: string;
+    actor?: string;
+}
+/** §10: why a connector is invalid, or undefined. */
+export declare function checkAuditConnector(value: unknown): string | undefined;
+/** RFC 4180: a header row, then rows; quoted fields may hold commas, quotes ("") and newlines. */
+export declare function parseCsv(text: string): string[][];
+/** §10: the rows of an audit-log export, in file order; rows without a time or action are skipped. */
+export declare function parseAuditLog(text: string, connector: Connector): AuditRow[];
+export interface SystemReport {
+    connector: string;
+    calls: number;
+    rows: number;
+    matched: Array<{
+        seq: number;
+        row: number;
+        by: "evidence" | "action";
+    }>;
+    findings: Array<{
+        code: "AGENT_ACTION_NOT_IN_SYSTEM" | "SYSTEM_CHANGE_NOT_IN_RECORD" | "SYSTEM_RECORD_MISMATCH";
+        ref: {
+            seq?: number;
+            row?: number;
+        };
+    }>;
+}
+/** §10: the session's successful mapped tool calls against the system's own log. */
+export declare function reconcileSystem(lines: readonly string[], body: (hash: string) => Uint8Array | undefined, rows: readonly AuditRow[], connector: Connector, evidence: DataRules["evidence"]): SystemReport;