@zanii/blackbox 0.1.0 → 0.2.0

package/dist/analysis/faults.js

@@ -203,6 +203,46 @@ export const FAULTS = {
         en: "Flying a model it isn't rated on",
         ar: "يعمل على نموذج غير مؤهل له",
     },
+    DATA_LEFT_REGION: {
+        fault: "BBX-9101",
+        en: "Personal data sent outside the data region",
+        ar: "بيانات شخصية أُرسلت خارج منطقة البيانات",
+    },
+    DATA_REGION_UNKNOWN: {
+        fault: "BBX-9102",
+        en: "Personal data sent to a model of unknown region",
+        ar: "بيانات شخصية أُرسلت إلى نموذج منطقته غير معروفة",
+    },
+    DATA_TO_UNAPPROVED_DESTINATION: {
+        fault: "BBX-9103",
+        en: "Data sent to a destination its rules don't allow",
+        ar: "بيانات أُرسلت إلى وجهة لا تسمح بها قواعدها",
+    },
+    DATA_CANARY_TRIPPED: {
+        fault: "BBX-9104",
+        en: "A canary value left the gateway",
+        ar: "قيمة إنذار خرجت من البوابة",
+    },
+    CONSENT_WITHDRAWN_USE: {
+        fault: "BBX-9105",
+        en: "Data used after consent was withdrawn",
+        ar: "استُخدمت بيانات بعد سحب الموافقة",
+    },
+    UNEVIDENCED_SIDE_EFFECT: {
+        fault: "BBX-9201",
+        en: "A change the touched system gave no proof of",
+        ar: "تغيير لم يقدّم النظام المعني دليلاً عليه",
+    },
+    TOOL_WITNESS_INVALID: {
+        fault: "BBX-9202",
+        en: "A tool's signature doesn't verify",
+        ar: "توقيع الأداة غير صالح",
+    },
+    EGRESS_OPEN: {
+        fault: "BBX-9301",
+        en: "The agent can reach the internet around the gateway",
+        ar: "يستطيع الوكيل الوصول إلى الإنترنت متجاوزاً البوابة",
+    },
 };
 /** The fault for a finding code; unknown codes get a generic entry, never an exception. */
 export function faultOf(code) {

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/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;