@zanii/blackbox 0.21.2 → 0.23.0

package/dist/analysis/guard.js

@@ -0,0 +1,240 @@
+// spec/guard.md: the inline guard. Decides on a tool call before the gateway forwards it (an MCP
+// tools/call) or before it accepts the tool's result back (a model's tool_use): canary tools and
+// tokens, tool pinning, exfiltration sequences, holds on high-risk calls after untrusted content.
+// Pure: the caller keeps the state and passes the clock. Ported from @zanii/guard (the rules and
+// their names), with Blackbox's own injection rules (analysis/injection.ts). Mirrors
+// analysis/guard.py; pinned by spec/vectors/guard.json.
+import { injectionRule } from "./injection.js";
+const LISTS = [
+    "canary_tools",
+    "canary_tokens",
+    "untrusted_sources",
+    "sensitive",
+    "egress",
+    "high_risk",
+];
+const MODES = ["off", "monitor", "enforce"];
+/** The strictest of several modes (off < monitor < enforce); unknown values count as off. */
+export function guardMode(...modes) {
+    let best = 0;
+    for (const m of modes)
+        best = Math.max(best, MODES.indexOf(m));
+    return MODES[best];
+}
+/** spec/guard.md §1: a guard file, checked; throws on anything wrong. */
+export function loadGuardConfig(doc) {
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc))
+        throw new Error("guard: the file must be a JSON object");
+    const d = doc;
+    if (d.version !== 1)
+        throw new Error("guard: version must be 1");
+    for (const k of Object.keys(d))
+        if (k !== "version" &&
+            k !== "exfil_window_seconds" &&
+            !LISTS.includes(k))
+            throw new Error(`guard: unknown field ${k}`);
+    const out = { exfil_window_seconds: 600 };
+    for (const k of LISTS) {
+        const v = d[k] ?? [];
+        const re = k === "canary_tokens" ? /^[A-Za-z0-9_.:-]{12,128}$/ : /^[^\s]{1,256}$/;
+        if (!Array.isArray(v) || v.length > 100 || !v.every((x) => typeof x === "string" && re.test(x)))
+            throw new Error(k === "canary_tokens"
+                ? "guard: canary_tokens must be at most 100 strings of 12-128 letters, digits or _.:-"
+                : `guard: ${k} must be at most 100 tool patterns of 1-256 characters, no spaces`);
+        out[k] = v;
+    }
+    const w = d.exfil_window_seconds;
+    if (w !== undefined) {
+        if (!Number.isSafeInteger(w) || w < 1 || w > 86_400)
+            throw new Error("guard: exfil_window_seconds must be an integer 1-86400");
+        out.exfil_window_seconds = w;
+    }
+    return out;
+}
+/** A session's state before anything was seen. */
+export function guardState() {
+    return { taint: null, sensitive: null, pins: {}, changed: [] };
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const glob = (p) => new RegExp(`^${p.split("*").map(escapeRe).join(".*")}$`);
+const matches = (patterns, names) => patterns.some((p) => {
+    const re = glob(p);
+    return names.some((n) => re.test(n));
+});
+/** Every string in a JSON value, depth first, in key order, one per line. */
+function textOf(v) {
+    const out = [];
+    const walk = (x) => {
+        if (typeof x === "string")
+            out.push(x);
+        else if (Array.isArray(x))
+            for (const y of x)
+                walk(y);
+        else if (x && typeof x === "object")
+            for (const y of Object.values(x))
+                walk(y);
+    };
+    walk(v);
+    return out.join("\n");
+}
+/** spec/guard.md §2: the decision on one call, and the state after it. */
+export function guardCheck(config, state, call) {
+    const tool = call.names[0] ?? "";
+    const findings = [];
+    let verdict = "allow";
+    const add = (f, v) => {
+        findings.push(f);
+        if (v === "block" || (v === "hold" && verdict === "allow"))
+            verdict = v;
+    };
+    const text = textOf(call.args);
+    if (matches(config.canary_tools, call.names))
+        add({
+            rule: "canary-tool",
+            severity: "critical",
+            asi: "ASI10",
+            detail: `${tool} is a canary no legitimate run calls`,
+        }, "block");
+    if (config.canary_tokens.some((t) => text.includes(t)))
+        add({
+            rule: "canary-token",
+            severity: "critical",
+            asi: "ASI02",
+            detail: `a planted canary token is leaving through ${tool}`,
+        }, "block");
+    if (state.changed.includes(tool))
+        add({
+            rule: "tool-changed",
+            severity: "high",
+            asi: "ASI04",
+            detail: `${tool} changed since it was first listed in this session`,
+        }, "block");
+    const s = state.sensitive;
+    if (s &&
+        matches(config.egress, call.names) &&
+        call.at_ms - s.at_ms <= config.exfil_window_seconds * 1000)
+        add({
+            rule: "exfil-sequence",
+            severity: "high",
+            asi: "ASI02",
+            detail: `egress through ${tool} right after reading ${s.tool}`,
+        }, "block");
+    if (injectionRule(text) !== null)
+        add({
+            rule: "injection-in-args",
+            severity: "high",
+            asi: "ASI01",
+            detail: `the arguments to ${tool} carry instructions aimed at an agent`,
+        }, "hold");
+    const t = state.taint;
+    if (t && matches(config.high_risk, call.names))
+        add({
+            rule: "tainted-high-risk",
+            severity: t.markers > 0 ? "high" : "medium",
+            asi: "ASI01",
+            detail: `a high-risk call after reading untrusted content from ${t.source}${t.markers > 0 ? " that contained injection attempts" : ""}`,
+        }, "hold");
+    const next = matches(config.sensitive, call.names)
+        ? { ...state, sensitive: { tool, at_ms: call.at_ms } }
+        : state;
+    return { verdict, findings, state: next };
+}
+/** spec/guard.md §3: a tool's result coming back. From an untrusted source, it taints the session. */
+export function guardObserve(config, state, result) {
+    if (!matches(config.untrusted_sources, result.names))
+        return state;
+    const marked = injectionRule(textOf(result.content)) !== null ? 1 : 0;
+    return {
+        ...state,
+        taint: { source: result.names[0] ?? "", markers: (state.taint?.markers ?? 0) + marked },
+    };
+}
+/** spec/guard.md §4: a tools/list answer's definition hashes. The first one seen for each tool is its
+ * pin; a later, different one marks the tool changed for the rest of the session. */
+export function guardPin(state, defs) {
+    const pins = { ...state.pins };
+    const changed = [];
+    for (const [name, hash] of Object.entries(defs)) {
+        const pin = pins[name];
+        if (pin === undefined)
+            pins[name] = hash;
+        else if (pin !== hash && !state.changed.includes(name))
+            changed.push(name);
+    }
+    return { state: { ...state, pins, changed: [...state.changed, ...changed] }, changed };
+}
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const parsed = (v) => {
+    if (typeof v !== "string")
+        return v ?? {};
+    try {
+        return JSON.parse(v);
+    }
+    catch {
+        return v;
+    }
+};
+/**
+ * spec/guard.md §5: the tool results a model request's newest turn hands back, each with the call
+ * that asked for it (from the same request). Anthropic Messages, Chat Completions and Responses.
+ * A result whose call isn't in the request (a Responses `previous_response_id`) is left out.
+ */
+export function guardToolResults(body) {
+    if (!isObj(body))
+        return [];
+    const out = [];
+    const calls = new Map();
+    const messages = body.messages;
+    if (Array.isArray(messages) && messages.length) {
+        let i = messages.length - 1;
+        while (i > 0 && messages[i]?.role === "tool")
+            i -= 1;
+        for (const m of messages.slice(0, i + 1).filter(isObj)) {
+            if (m.role !== "assistant")
+                continue;
+            if (Array.isArray(m.content))
+                for (const b of m.content.filter(isObj))
+                    if (b.type === "tool_use" && typeof b.id === "string" && typeof b.name === "string")
+                        calls.set(b.id, { name: b.name, args: b.input ?? {} });
+            if (Array.isArray(m.tool_calls))
+                for (const c of m.tool_calls.filter(isObj)) {
+                    const f = isObj(c.function) ? c.function : {};
+                    if (typeof c.id === "string" && typeof f.name === "string")
+                        calls.set(c.id, { name: f.name, args: parsed(f.arguments) });
+                }
+        }
+        const take = (id, content) => {
+            const c = typeof id === "string" ? calls.get(id) : undefined;
+            if (c)
+                out.push({ id: id, name: c.name, args: c.args, content: content ?? null });
+        };
+        for (const m of messages.slice(i).filter(isObj)) {
+            if (m.role === "tool")
+                take(m.tool_call_id, m.content);
+            else if (m.role === "user" && Array.isArray(m.content))
+                for (const b of m.content.filter(isObj))
+                    if (b.type === "tool_result")
+                        take(b.tool_use_id, b.content);
+        }
+        return out;
+    }
+    const input = body.input;
+    if (!Array.isArray(input) || input.length === 0)
+        return out;
+    let i = input.length - 1;
+    while (i > 0 && input[i]?.type === "function_call_output")
+        i -= 1;
+    for (const item of input.slice(0, i + 1).filter(isObj))
+        if (item.type === "function_call" &&
+            typeof item.call_id === "string" &&
+            typeof item.name === "string")
+            calls.set(item.call_id, { name: item.name, args: parsed(item.arguments) });
+    for (const item of input.slice(i).filter(isObj)) {
+        if (item.type !== "function_call_output" || typeof item.call_id !== "string")
+            continue;
+        const c = calls.get(item.call_id);
+        if (c)
+            out.push({ id: item.call_id, name: c.name, args: c.args, content: item.output ?? null });
+    }
+    return out;
+}

package/dist/analysis/hallucination.js

@@ -3,7 +3,7 @@
 // right after an error; quoting a tool it never called. Pure functions over the record, no model.
 // Mirrors sdks/python/src/zanii_blackbox/analysis/hallucination.py; pinned by
 // spec/vectors/hallucination.json.
-import { callsOf } from "../reconcile/record.js";
+import { callsOf, envelopesOf } from "../reconcile/record.js";
 import { canonical, isObj } from "../reconcile/shared.js";
 import { toolCallsOf, toolResultsOf } from "./detectors.js";
 const decoder = new TextDecoder();
@@ -217,7 +217,7 @@ export function toolHallucinations(lines, bodies) {
     const calls = callsOf(lines, bodies);
     const modelCalls = toolCallsOf(calls);
     const results = toolResultsOf(calls, lines);
-    const events = lines.map((l) => JSON.parse(l));
+    const events = envelopesOf(lines);
     const out = [];
     const push = (at, finding) => out.push({ ...finding, at });
     // the model side: each tool call against the request that produced it

package/dist/analysis/index.d.ts

@@ -20,6 +20,10 @@ export interface Finding {
         [key: string]: string | number | boolean;
     };
     detail?: string;
+    /** The numbers behind it (integers), recorded with it but not part of its identity. */
+    figures?: {
+        [key: string]: number;
+    };
 }
 export interface AnalyzeOptions {
     /** Body bytes by hash (SDK events carry their ids in the body; requests and responses are bodies). */
@@ -47,8 +51,22 @@ export interface Ev extends Envelope {
         [key: string]: Json;
     };
 }
-/** Parses the lines once, attaching SDK event bodies. */
+/** Parses the lines once, attaching SDK event bodies. On a tracked record (`Analyzer`), only the
+ * lines added since the last call are read. */
 export declare function eventsOf(lines: readonly string[], bodies: AnalyzeOptions["bodies"]): Ev[];
+/**
+ * spec/findings.md §14 (G33): the analyses over one session's growing record. Each `findings` call
+ * reads only the lines added since the last one (each line is parsed once, the calls are rebuilt
+ * from the new events only) and gives exactly what `analyze` gives over the whole record.
+ */
+export declare class Analyzer {
+    readonly lines: string[];
+    readonly bodies: AnalyzeOptions["bodies"];
+    constructor(bodies: AnalyzeOptions["bodies"]);
+    /** Appends the record's new lines (in seq order; a record only grows). */
+    push(lines: Iterable<string>): void;
+    findings(options: Omit<AnalyzeOptions, "bodies">): Finding[];
+}
 /** Every analysis, in spec order. */
 export declare function analyze(lines: readonly string[], options: AnalyzeOptions): Finding[];
 /**
@@ -94,6 +112,8 @@ export declare function toolDrifted(events: Ev[]): Finding[];
  * the call went to an MCP tool. A request refused for it (`outbound_blocked`) sent nothing.
  */
 export declare function secretSent(events: Ev[]): Finding[];
+/** spec/mcp.md §6: an MCP server asked the user for a credential through `elicitation/create`. */
+export declare function elicitationSecret(events: Ev[]): Finding[];
 /** spec/findings.md §12b: a person the agent served said an answer was wrong (👎), once per answer. */
 export declare function userDownvotes(events: Ev[]): Finding[];
 /** N6 (idea S3): the gateway refused a request that carried the session's own token. */

package/dist/analysis/index.js

@@ -8,6 +8,7 @@ import { healthFindings } from "../health/index.js";
 import { policyFindings } from "../policy/index.js";
 import { precogFindings } from "../precog/index.js";
 import { preflightFindings } from "../preflight/index.js";
+import { envelopesOf, foldState, trackRecord } from "../reconcile/record.js";
 import { canonical } from "../reconcile/shared.js";
 import { undoFindings } from "../undo/index.js";
 import { wallFindings } from "../walls/index.js";
@@ -26,27 +27,68 @@ export { checkFlightPlan, landing, } from "./landing.js";
 export { checkAgainstPacks, loadReferencePacks, packsFor, referenceContext, } from "./reference.js";
 export { OUTCOMES, rollup, waste, } from "./waste.js";
 const decoder = new TextDecoder();
-/** Parses the lines once, attaching SDK event bodies. */
+/** Parses the lines once, attaching SDK event bodies. On a tracked record (`Analyzer`), only the
+ * lines added since the last call are read. */
 export function eventsOf(lines, bodies) {
-    // N4 (idea R6): a re-sent SDK event (meta.duplicate_of) stays on the record but counts once.
-    return lines.flatMap((line) => {
-        const e = JSON.parse(line);
-        if (e.kind === "sdk.event" && e.meta.duplicate_of !== undefined)
-            return [];
-        if (e.kind === "sdk.event") {
-            const b = bodies(e.body_hash);
-            try {
-                const parsed = b === undefined ? {} : JSON.parse(decoder.decode(b));
-                e.data =
-                    typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : {};
-            }
-            catch {
-                e.data = {};
-            }
+    const fold = foldState(lines, "eventsOf", () => ({ done: 0, out: [], bodies }));
+    if (fold && fold.bodies === bodies) {
+        const all = envelopesOf(lines);
+        for (; fold.done < all.length; fold.done++) {
+            const e = withData(all[fold.done], bodies);
+            if (e)
+                fold.out.push(e);
         }
-        return [e];
+        return [...fold.out];
+    }
+    return envelopesOf(lines).flatMap((e) => {
+        const out = withData(e, bodies);
+        return out ? [out] : [];
     });
 }
+function withData(e, bodies) {
+    // N4 (idea R6): a re-sent SDK event (meta.duplicate_of) stays on the record but counts once.
+    if (e.kind === "sdk.event" && e.meta.duplicate_of !== undefined)
+        return null;
+    if (e.kind !== "sdk.event")
+        return e;
+    const b = bodies(e.body_hash);
+    let data = {};
+    try {
+        const parsed = b === undefined ? {} : JSON.parse(decoder.decode(b));
+        data = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch { }
+    return Object.isFrozen(e) ? Object.freeze({ ...e, data: deepFreezeJson(data) }) : { ...e, data };
+}
+function deepFreezeJson(value) {
+    if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const v of Object.values(value))
+            deepFreezeJson(v);
+    }
+    return value;
+}
+/**
+ * spec/findings.md §14 (G33): the analyses over one session's growing record. Each `findings` call
+ * reads only the lines added since the last one (each line is parsed once, the calls are rebuilt
+ * from the new events only) and gives exactly what `analyze` gives over the whole record.
+ */
+export class Analyzer {
+    lines = [];
+    bodies;
+    constructor(bodies) {
+        this.bodies = bodies;
+        trackRecord(this.lines);
+    }
+    /** Appends the record's new lines (in seq order; a record only grows). */
+    push(lines) {
+        for (const l of lines)
+            this.lines.push(l);
+    }
+    findings(options) {
+        return analyze(this.lines, { ...options, bodies: this.bodies });
+    }
+}
 /** Every analysis, in spec order. */
 export function analyze(lines, options) {
     const events = eventsOf(lines, options.bodies);
@@ -60,6 +102,7 @@ export function analyze(lines, options) {
         ...toolChanged(events),
         ...toolDrifted(events),
         ...secretSent(events),
+        ...elicitationSecret(events),
         ...userDownvotes(events),
         ...selfChanges(events),
         ...promptChanged(events),
@@ -473,16 +516,55 @@ export function secretSent(events) {
             n = count(e.meta.redacted);
             to = "tool";
         }
+        else if ((e.kind === "tool.elicitation" || e.kind === "tool.sampling") &&
+            e.meta.phase === "reply" &&
+            typeof e.meta.method === "string") {
+            // spec/mcp.md §6: the client's answer to a server's request went to that MCP server
+            n = count(e.meta.redacted);
+            to = "server";
+        }
         if (!to || n <= 0)
             continue;
         out.push({
             code: "SECRET_SENT",
             source: "detectors",
             severity: "warning",
-            ref: { seq: e.seq, to, count: n, ...(to === "tool" ? { tool: e.meta.tool } : {}) },
+            ref: {
+                seq: e.seq,
+                to: to === "server" ? "tool" : to,
+                count: n,
+                ...(to === "model"
+                    ? {}
+                    : { tool: (to === "tool" ? e.meta.tool : e.meta.method) }),
+            },
             detail: to === "model"
                 ? "A credential (a key, a token, a password) went to the model provider in the request."
-                : "A credential (a key, a token, a password) went to a tool in its arguments; the gateway's credential broker keeps them out of the agent's hands.",
+                : to === "tool"
+                    ? "A credential (a key, a token, a password) went to a tool in its arguments; the gateway's credential broker keeps them out of the agent's hands."
+                    : "A credential (a key, a token, a password) went to an MCP server in the client's answer to its request.",
+        });
+    }
+    return out;
+}
+/** spec/mcp.md §6: an MCP server asked the user for a credential through `elicitation/create`. */
+export function elicitationSecret(events) {
+    const out = [];
+    for (const e of events) {
+        const fields = e.meta.secret_fields;
+        if (e.kind !== "tool.elicitation" || e.meta.phase !== "request")
+            continue;
+        if (!Array.isArray(fields) || fields.length === 0)
+            continue;
+        out.push({
+            code: "ELICITATION_SECRET",
+            source: "detectors",
+            severity: "warning",
+            ref: {
+                seq: e.seq,
+                ...(typeof e.meta.server === "string" ? { server: e.meta.server } : {}),
+                fields: fields.map(String).join(","),
+            },
+            detail: "An MCP server asked the user for a credential (a password, a token, a key) through elicitation; a server should never collect one this way.",
         });
     }
     return out;

package/dist/analysis/injection.d.ts

@@ -7,7 +7,8 @@ export declare const INJECTION_RULES: ReadonlyArray<{
 export declare function hiddenText(text: string): boolean;
 /** The first rule a text breaks, or null. */
 export declare function injectionRule(text: string): string | null;
-/** spec/findings.md §1b: PROMPT_INJECTION findings over a record. */
+/** spec/findings.md §1b: PROMPT_INJECTION findings over a record. Each event is judged on its own
+ * (on a tracked record, once: G33). */
 export declare function injectionFindings(lines: readonly string[], bodies: (hash: string) => Uint8Array | undefined): {
     code: string;
     source: string;

package/dist/analysis/injection.js

@@ -4,6 +4,7 @@
 // role hijacks, exfiltration asks and hidden text, in English and Arabic. One finding per event and
 // source; the finding names the rule, never the text. Mirrors analysis/injection.py; pinned by
 // spec/vectors/injection.json.
+import { perEvent } from "../reconcile/record.js";
 const decoder = new TextDecoder();
 const MAX_TEXT = 200_000; // characters scanned per event: an injection is near the start or not worth the cost
 /** The rules, in the order they're tried. Patterns run on ASCII-lowercased, space-folded text. */
@@ -120,10 +121,10 @@ function newestTurn(body) {
     }
     return out;
 }
-/** spec/findings.md §1b: PROMPT_INJECTION findings over a record. */
+/** spec/findings.md §1b: PROMPT_INJECTION findings over a record. Each event is judged on its own
+ * (on a tracked record, once: G33). */
 export function injectionFindings(lines, bodies) {
-    const out = [];
-    const add = (seq, source, rule, tool) => out.push({
+    const found = (seq, source, rule, tool) => ({
         code: "PROMPT_INJECTION",
         source: "detectors",
         severity: "warning",
@@ -132,32 +133,31 @@ export function injectionFindings(lines, bodies) {
             ? "Text the reader can't see (hidden characters) reached the model: a classic way to smuggle instructions."
             : "Text that reached the model tries to give it new instructions: an override, a role change, or a request to send out secrets.",
     });
-    for (const l of lines) {
-        const e = JSON.parse(l);
+    return perEvent(lines, "injection", bodies, (envelope) => {
+        const e = envelope;
         if (e.kind !== "tool.result" && e.kind !== "llm.request")
-            continue;
+            return [];
         const raw = bodies(e.body_hash);
         if (!raw || raw.length === 0)
-            continue;
+            return [];
         let doc;
         try {
             doc = JSON.parse(decoder.decode(raw));
         }
         catch {
-            continue;
+            return [];
         }
         if (e.kind === "tool.result") {
             const result = doc?.result;
             if (result === undefined)
-                continue;
+                return [];
             const rule = injectionRule(textOf(result));
             const tool = typeof e.meta.tool === "string" ? e.meta.tool : undefined;
-            if (rule)
-                add(e.seq, "tool_result", rule, tool);
-            continue;
+            return rule ? [found(e.seq, "tool_result", rule, tool)] : [];
         }
         if (!doc || typeof doc !== "object" || Array.isArray(doc))
-            continue;
+            return [];
+        const out = [];
         const seen = new Set();
         for (const part of newestTurn(doc)) {
             if (seen.has(part.source))
@@ -165,9 +165,9 @@ export function injectionFindings(lines, bodies) {
             const rule = injectionRule(part.text);
             if (rule) {
                 seen.add(part.source);
-                add(e.seq, part.source, rule);
+                out.push(found(e.seq, part.source, rule));
             }
         }
-    }
-    return out;
+        return out;
+    });
 }