@zanii/blackbox 0.2.0 → 0.4.0

package/dist/policy/index.js

@@ -1,7 +1,57 @@
 // Tool policy (spec/policy.md): rules checked in order, the first match decides. Mirrors policy.py.
+import { createHash } from "node:crypto";
+import { hasEvidence } from "../data/index.js";
 import { callsOf } from "../reconcile/record.js";
 import { canonical } from "../reconcile/shared.js";
 import { checkCompensations } from "../undo/index.js";
+/** spec/api.md: a session's environment, e.g. `production`, `staging`, `dev`. */
+export const ENVIRONMENT = /^[a-z][a-z0-9-]{0,31}$/;
+const HINTS = ["read_only", "destructive", "idempotent", "open_world"];
+/**
+ * spec/policy.md §1: a tool's annotations (MCP `readOnlyHint`, `destructiveHint`, `idempotentHint`,
+ * `openWorldHint`) as hints. Missing ones take MCP's defaults: not read-only, destructive, not
+ * idempotent, open-world; destructive and idempotent only mean something for a tool that writes.
+ * An unknown tool gets the defaults too. Hints are the server's word, not proof.
+ */
+export function mcpToolHints(annotations) {
+    const a = (typeof annotations === "object" && annotations !== null ? annotations : {});
+    const readOnly = a.readOnlyHint === true;
+    return {
+        read_only: readOnly,
+        destructive: !readOnly && a.destructiveHint !== false,
+        idempotent: !readOnly && a.idempotentHint === true,
+        open_world: a.openWorldHint !== false,
+    };
+}
+/** The fields of an MCP tool definition that say what the tool is and does (spec/policy.md §1a). */
+const DEFINITION_FIELDS = [
+    "name",
+    "title",
+    "description",
+    "inputSchema",
+    "outputSchema",
+    "annotations",
+];
+/**
+ * spec/policy.md §1a: a tool definition's identity, `sha256:<hex>` of the canonical JSON of its
+ * name, title, description, schemas and annotations (the fields present). A changed description
+ * or schema changes it: what the agent was shown is no longer what was approved. `null` for
+ * something that isn't a named tool.
+ */
+export function toolDefinitionHash(tool) {
+    if (typeof tool !== "object" || tool === null || Array.isArray(tool))
+        return null;
+    const t = tool;
+    if (typeof t.name !== "string" || t.name.length === 0 || t.name.length > 256)
+        return null;
+    const picked = {};
+    for (const k of DEFINITION_FIELDS)
+        if (t[k] !== undefined)
+            picked[k] = t[k];
+    return `sha256:${createHash("sha256").update(canonical(picked)).digest("hex")}`;
+}
+const hintsMatch = (want, have) => want === undefined ||
+    (have !== undefined && Object.entries(want).every(([k, v]) => have[k] === v));
 const MAX_ARGS = 64 * 1024;
 /** Escapes a string for use inside a regular expression. */
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -17,8 +67,13 @@ export function loadPolicy(bytes) {
             throw new Error(`policy: rule id "${r.id}" must match ^[a-z0-9-]{1,64}$`);
         if (typeof r.tool !== "string" || r.tool === "")
             throw new Error(`policy ${r.id}: tool is required`);
-        if (r.action !== "deny" && r.action !== "allow" && r.action !== "require_approval")
-            throw new Error(`policy ${r.id}: action must be deny, allow or require_approval`);
+        if (!["deny", "allow", "require_approval", "require_proof"].includes(r.action))
+            throw new Error(`policy ${r.id}: action must be deny, allow, require_approval or require_proof`);
+        if (r.field !== undefined &&
+            (r.action !== "require_proof" ||
+                typeof r.field !== "string" ||
+                !/^[A-Za-z0-9_.-]{1,64}$/.test(r.field)))
+            throw new Error(`policy ${r.id}: field is a 1-64 character key, with require_proof only`);
         if (r.args_match !== undefined) {
             if (typeof r.args_match !== "string" || r.args_match.length > 200)
                 throw new Error(`policy ${r.id}: args_match must be a regular expression of ≤ 200 characters`);
@@ -26,6 +81,21 @@ export function loadPolicy(bytes) {
         }
         if (r.audit !== undefined && typeof r.audit !== "boolean")
             throw new Error(`policy ${r.id}: audit must be true or false`);
+        if (r.hints !== undefined) {
+            const h = r.hints;
+            if (typeof h !== "object" ||
+                h === null ||
+                Array.isArray(h) ||
+                Object.keys(h).length === 0 ||
+                !Object.entries(h).every(([k, v]) => HINTS.includes(k) && typeof v === "boolean"))
+                throw new Error(`policy ${r.id}: hints must set some of read_only, destructive, idempotent, open_world to true or false`);
+        }
+        if (r.environment !== undefined &&
+            !(Array.isArray(r.environment) &&
+                r.environment.length > 0 &&
+                r.environment.length <= 16 &&
+                r.environment.every((e) => typeof e === "string" && ENVIRONMENT.test(e))))
+            throw new Error(`policy ${r.id}: environment must be a list of 1-16 environment names (^[a-z][a-z0-9-]{0,31}$)`);
     }
     const ids = doc.rules.map((r) => r.id);
     const twice = ids.find((id, i) => ids.indexOf(id) !== i);
@@ -45,7 +115,13 @@ function checkShadowed(rules) {
             .slice(0, j)
             .find((e) => glob(e.tool).test(later.tool) &&
             (e.args_match === undefined ||
-                (e.args_match === later.args_match && !!e.ignore_case === !!later.ignore_case)));
+                (e.args_match === later.args_match && !!e.ignore_case === !!later.ignore_case)) &&
+            (e.hints === undefined ||
+                (later.hints !== undefined &&
+                    Object.entries(e.hints).every(([k, v]) => later.hints[k] === v))) &&
+            (e.environment === undefined ||
+                (later.environment !== undefined &&
+                    later.environment.every((x) => e.environment.includes(x)))));
         if (first && first.action !== later.action)
             throw new Error(`policy ${later.id}: never applies: ${first.id} matches the same calls first (${first.action})`);
     });
@@ -59,12 +135,30 @@ export function compilePolicy(policy) {
             : new RegExp(rule.args_match, rule.ignore_case ? "i" : ""),
     }));
 }
-/** The first rule that matches this call, or null (allowed). `names`: the tool's names (an MCP tool has two). */
-export function decide(compiled, names, args) {
+/** spec/api.md: the session's environment, from its `session.open` (the first line). */
+export function environmentOf(lines) {
+    const first = lines[0];
+    if (first === undefined)
+        return undefined;
+    const e = JSON.parse(first);
+    const env = e.kind === "session.open" ? e.meta?.environment : undefined;
+    return typeof env === "string" ? env : undefined;
+}
+/** A rule with `environment` holds only in a session whose environment it lists. */
+const environmentMatch = (rule, environment) => rule.environment === undefined ||
+    (environment !== undefined && rule.environment.includes(environment));
+/** The first rule that matches this call, or null (allowed). `names`: the tool's names (an MCP tool
+ * has two). `hints`: an MCP tool's annotations; a rule with `hints` never matches a call without.
+ * `environment`: the session's; a rule with `environment` never matches a session without one. */
+export function decide(compiled, names, args, hints, environment) {
     let text = null;
     for (const c of compiled) {
         if (c.rule.audit === true || !names.some((n) => c.tool.test(n)))
             continue;
+        if (!hintsMatch(c.rule.hints, hints))
+            continue;
+        if (!environmentMatch(c.rule, environment))
+            continue;
         if (c.args) {
             text ??= canonical(args ?? null).slice(0, MAX_ARGS);
             if (!c.args.test(text))
@@ -79,10 +173,12 @@ export function decide(compiled, names, args) {
     return null;
 }
 /** N3 (idea C5): every audit rule this call matches, and what it would do if it were enforced. */
-export function audited(compiled, names, args) {
+export function audited(compiled, names, args, hints, environment) {
     const text = canonical(args ?? null).slice(0, MAX_ARGS);
     return compiled
         .filter((c) => c.rule.audit === true && names.some((n) => c.tool.test(n)))
+        .filter((c) => hintsMatch(c.rule.hints, hints))
+        .filter((c) => environmentMatch(c.rule, environment))
         .filter((c) => !c.args || c.args.test(text))
         .map((c) => ({ rule: c.rule.id, would: c.rule.action }));
 }
@@ -96,6 +192,86 @@ function auditFinding(rule, would, at, tool) {
         detail: `Policy ${rule} (audit only) would ${would === "deny" ? "have refused" : "have held"} ${String(tool ?? "a tool call")}.`,
     };
 }
+/**
+ * spec/policy.md §9: each successful result of a call a `require_proof` rule decided must carry a
+ * valid tool witness (spec/data.md §9) or the rule's `field`, the touched system's own id.
+ */
+function unproven(lines, bodies, compiled) {
+    const out = [];
+    const environment = environmentOf(lines);
+    const pending = new Map();
+    const sdkPending = new Map();
+    const json = (hash) => {
+        const b = bodies(hash);
+        if (!b)
+            return undefined;
+        try {
+            return JSON.parse(new TextDecoder().decode(b));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const ruleOf = (names, args, hints) => {
+        const d = decide(compiled, names, args, hints, environment);
+        return d?.action === "require_proof"
+            ? compiled.find((c) => c.rule.id === d.rule)?.rule
+            : undefined;
+    };
+    const proven = (rule, meta, result) => meta.witness?.ok === true ||
+        (rule.field !== undefined && hasEvidence(result, rule.field));
+    const finding = (seq, rule, tool) => ({
+        code: "UNPROVEN_SIDE_EFFECT",
+        source: "policy",
+        severity: "warning",
+        ref: { seq, rule: rule.id, tool },
+        detail: `${tool} ran under policy ${rule.id}, and its result carries no witness${rule.field ? ` or ${rule.field}` : ""}.`,
+    });
+    for (const line of lines) {
+        const e = JSON.parse(line);
+        const m = e.meta;
+        if (e.kind === "tool.call" && typeof m.tool === "string" && m.via !== "broker") {
+            if (m.policy?.action === "deny")
+                continue;
+            const body = json(e.body_hash);
+            const names = [
+                m.tool,
+                ...(typeof m.server === "string" ? [`mcp__${m.server}__${m.tool}`] : []),
+            ];
+            const rule = ruleOf(names, body?.params?.arguments ?? {}, m.hints);
+            if (rule)
+                pending.set(e.seq, { rule, tool: m.tool });
+        }
+        else if (e.kind === "tool.result" && typeof m.call_seq === "number") {
+            const p = pending.get(m.call_seq);
+            if (!p)
+                continue;
+            pending.delete(m.call_seq);
+            const r = json(e.body_hash);
+            if (r === undefined || r.error !== undefined || r.result?.isError === true)
+                continue;
+            if (!proven(p.rule, m, r.result ?? r))
+                out.push(finding(e.seq, p.rule, p.tool));
+        }
+        else if (e.kind === "sdk.event" && m.type === "tool.call" && typeof m.name === "string") {
+            const d = json(e.body_hash);
+            const rule = ruleOf([m.name], d?.args ?? {});
+            if (rule)
+                sdkPending.set(m.name, [...(sdkPending.get(m.name) ?? []), { rule, tool: m.name }]);
+        }
+        else if (e.kind === "sdk.event" && m.type === "tool.result" && typeof m.name === "string") {
+            const p = sdkPending.get(m.name)?.shift();
+            if (!p)
+                continue;
+            const d = json(e.body_hash);
+            if (d === undefined || d.ok === false)
+                continue;
+            if (!proven(p.rule, m, d))
+                out.push(finding(e.seq, p.rule, p.tool));
+        }
+    }
+    return out;
+}
 /**
  * spec/policy.md §2 as findings: POLICY_DENIED for MCP calls the gateway refused (tool.call meta.policy),
  * POLICY_VIOLATION for tools a model response asked for that a deny rule matches.
@@ -118,12 +294,14 @@ export function policyFindings(lines, bodies, compiled) {
             if (typeof a.rule === "string" && a.would !== "allow")
                 out.push(auditFinding(a.rule, String(a.would), { seq: e.seq }, e.meta.tool));
     }
+    out.push(...unproven(lines, bodies, compiled));
     const calls = [...callsOf(lines, bodies)].sort((a, b) => a.endSeq - b.endSeq);
+    const environment = environmentOf(lines);
     const violation = (tool, id, args) => {
-        for (const a of audited(compiled, [tool], args))
+        for (const a of audited(compiled, [tool], args, undefined, environment))
             if (a.would !== "allow")
                 out.push(auditFinding(a.rule, a.would, { tool_use_id: id }, tool));
-        const d = decide(compiled, [tool], args);
+        const d = decide(compiled, [tool], args, undefined, environment);
         if (d?.action === "deny")
             out.push({
                 code: "POLICY_VIOLATION",

package/dist/policy/zanii.d.ts

@@ -0,0 +1,31 @@
+type OurRule = {
+    id: string;
+    tool: string;
+    action: string;
+    [key: string]: unknown;
+};
+type Skipped = {
+    id: string;
+    reason: string;
+};
+/** Zanii → Blackbox: `{policy: {version: 1, rules}, skipped}`. */
+export declare function fromZaniiPolicy(z: unknown): {
+    policy: {
+        version: 1;
+        rules: OurRule[];
+    };
+    skipped: Skipped[];
+};
+/** Blackbox → Zanii: `{policy: {default: "allow", rules}, skipped}`. */
+export declare function toZaniiPolicy(ours: unknown): {
+    policy: {
+        default: "allow";
+        rules: Array<{
+            id: string;
+            effect: string;
+            targets: string[];
+        }>;
+    };
+    skipped: Skipped[];
+};
+export {};

package/dist/policy/zanii.js

@@ -0,0 +1,87 @@
+// Zanii's policy format, in and out (spec/policy.md §8). A rule that can't be said the same way on
+// the other side is skipped and named, never loosened: dropping a condition would widen what a rule
+// denies or allows. Pure; mirrors sdks/python/src/zanii_blackbox/policy_zanii.py; pinned by
+// spec/vectors/policy-zanii.json.
+const EFFECTS = new Set(["deny", "allow", "require_approval"]);
+const idOf = (raw, n) => {
+    const s = String(raw ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+    return s || `rule-${n + 1}`;
+};
+/** A Zanii target as a Blackbox tool pattern, or null (`mcp.<server>.<tool>`, `mcp.<server>.*`, `*`). */
+function toolOf(target) {
+    if (target === "*" || target === "mcp.*")
+        return target === "*" ? "*" : "mcp__*";
+    const m = /^mcp\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_.*-]+)$/.exec(target);
+    return m ? `mcp__${m[1]}__${m[2]}` : null;
+}
+/** A Blackbox tool pattern as a Zanii target, or null (a bare tool name matches any server). */
+function targetOf(tool) {
+    if (tool === "*")
+        return "*";
+    if (tool === "mcp__*")
+        return "mcp.*";
+    const m = /^mcp__([A-Za-z0-9_-]+?)__(.+)$/.exec(tool);
+    return m ? `mcp.${m[1]}.${m[2]}` : null;
+}
+/** Zanii → Blackbox: `{policy: {version: 1, rules}, skipped}`. */
+export function fromZaniiPolicy(z) {
+    const p = (z ?? {});
+    const rules = [];
+    const skipped = [];
+    const list = Array.isArray(p.rules) ? p.rules : [];
+    for (const [n, r] of list.entries()) {
+        const id = idOf(r.id, n);
+        const skip = (reason) => skipped.push({ id, reason });
+        if (!EFFECTS.has(String(r.effect)))
+            skip(`effect ${String(r.effect)}`);
+        else if (r.where !== undefined)
+            skip("conditions on the payload (where) have no exact Blackbox form");
+        else if (r.rateLimit !== undefined)
+            skip("rate limits are not tool policy (use the session limits)");
+        else {
+            const targets = Array.isArray(r.targets) ? r.targets.map(String) : ["*"];
+            const tools = targets.map(toolOf);
+            const bad = targets.filter((_, i) => tools[i] === null);
+            if (bad.length)
+                skip(`not an MCP tool target: ${bad.join(", ")}`);
+            else
+                for (const [i, tool] of tools.entries())
+                    rules.push({
+                        id: tools.length > 1 ? `${id}-${i + 1}`.slice(0, 64) : id,
+                        tool: tool,
+                        action: String(r.effect),
+                    });
+        }
+    }
+    if (p.default === "deny")
+        rules.push({ id: "zanii-default", tool: "*", action: "deny" });
+    return { policy: { version: 1, rules }, skipped };
+}
+/** Blackbox → Zanii: `{policy: {default: "allow", rules}, skipped}`. */
+export function toZaniiPolicy(ours) {
+    const p = (ours ?? {});
+    const rules = [];
+    const skipped = [];
+    for (const r of (Array.isArray(p.rules) ? p.rules : [])) {
+        const id = String(r.id);
+        const extra = ["args_match", "hints", "environment"].filter((k) => r[k] !== undefined);
+        if (r.audit === true)
+            skipped.push({ id, reason: "an audit-only rule decides nothing" });
+        else if (r.action === "require_proof")
+            skipped.push({ id, reason: "Zanii has no require_proof effect" });
+        else if (extra.length)
+            skipped.push({ id, reason: `${extra.join(", ")} have no Zanii form` });
+        else {
+            const target = targetOf(String(r.tool));
+            if (target === null)
+                skipped.push({ id, reason: `a bare tool name matches any server: ${String(r.tool)}` });
+            else
+                rules.push({ id, effect: String(r.action), targets: [target] });
+        }
+    }
+    return { policy: { default: "allow", rules }, skipped };
+}

package/dist/pq/index.d.ts

@@ -0,0 +1,23 @@
+type Obj = Record<string, unknown>;
+export declare const PQ_ALG = "ML-DSA-65";
+/** The ML-DSA-65 seed for a gateway identity: HMAC-SHA256(its Ed25519 key, a fixed label). */
+export declare const pqSeedOf: (identityPrivateKey: Uint8Array) => Uint8Array;
+/** The raw ML-DSA-65 public key (1952 bytes) for a 32-byte seed. */
+export declare const pqPublicKey: (seed: Uint8Array) => Uint8Array;
+/** Whether this runtime has ML-DSA-65 (Node ≥ 24.6 with OpenSSL ≥ 3.5). */
+export declare function pqAvailable(): boolean;
+/** Zanii's pq.binding: both keys sign the same body, so holding one key can't forge it. */
+export declare function bindPqKey(o: {
+    did: string;
+    ts: string;
+    edPrivateKey: Uint8Array;
+    pqSeed: Uint8Array;
+}): Obj;
+/** Zanii's check: the structure, and BOTH signatures over the same body. */
+export declare function verifyPqBinding(binding: unknown): {
+    ok: boolean;
+    reasons: string[];
+};
+/** Zanii's transition payload, recorded UNSALTED: the binding as compact JSON. */
+export declare function pqTransitionPayload(binding: Obj): string;
+export {};

package/dist/pq/index.js

@@ -0,0 +1,104 @@
+// Post-quantum binding of the gateway identity (spec/anchoring.md §13): Zanii's pq.binding, an
+// ML-DSA-65 key (FIPS 204) bound to a did:key and signed by both keys, and the unsalted transition
+// payload anchored to prove the binding existed before any break of Ed25519 (@zanii/pq). Needs
+// Node ≥ 24.6 for ML-DSA. Pure; mirrors sdks/python/src/zanii_blackbox/pq.py; pinned by
+// spec/vectors/pq-binding.json.
+import { createHmac, createPrivateKey, createPublicKey, sign, verify } from "node:crypto";
+import { canonicalBytes, publicKeyFromDid } from "@zanii/core";
+import { ed25519Sign, ed25519Verify } from "../transparency/index.js";
+export const PQ_ALG = "ML-DSA-65";
+const SEED_INFO = "zanii-blackbox identity ml-dsa-65 v1";
+const PKCS8 = Buffer.from("3034020100300b060960864801650304031204228020", "hex");
+const SPKI = Buffer.from("308207b2300b0609608648016503040312038207a100", "hex");
+/** The ML-DSA-65 seed for a gateway identity: HMAC-SHA256(its Ed25519 key, a fixed label). */
+export const pqSeedOf = (identityPrivateKey) => new Uint8Array(createHmac("sha256", identityPrivateKey).update(SEED_INFO).digest());
+const privateKey = (seed) => {
+    if (seed.length !== 32)
+        throw new Error("an ML-DSA-65 seed is 32 bytes");
+    return createPrivateKey({ key: Buffer.concat([PKCS8, seed]), format: "der", type: "pkcs8" });
+};
+/** The raw ML-DSA-65 public key (1952 bytes) for a 32-byte seed. */
+export const pqPublicKey = (seed) => new Uint8Array(createPublicKey(privateKey(seed)).export({ format: "der", type: "spki" }).subarray(SPKI.length));
+/** Whether this runtime has ML-DSA-65 (Node ≥ 24.6 with OpenSSL ≥ 3.5). */
+export function pqAvailable() {
+    try {
+        pqPublicKey(new Uint8Array(32));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const validTs = (ts) => typeof ts === "string" && !Number.isNaN(Date.parse(ts));
+const hex = (b) => Buffer.from(b).toString("hex");
+/** Zanii's pq.binding: both keys sign the same body, so holding one key can't forge it. */
+export function bindPqKey(o) {
+    if (!o.did)
+        throw new Error("did is required");
+    if (!validTs(o.ts))
+        throw new Error("ts must be an ISO timestamp");
+    const unsigned = {
+        v: 1,
+        type: "pq.binding",
+        did: o.did,
+        alg: PQ_ALG,
+        pq_pub: hex(pqPublicKey(o.pqSeed)),
+        ts: o.ts,
+    };
+    const raw = canonicalBytes(unsigned);
+    return {
+        ...unsigned,
+        sig_ed: `ed25519:${hex(ed25519Sign(o.edPrivateKey, raw))}`,
+        sig_pq: `mldsa65:${hex(sign(null, raw, privateKey(o.pqSeed)))}`,
+    };
+}
+const pqVerify = (publicKey, msg, sig) => {
+    try {
+        const key = createPublicKey({
+            key: Buffer.concat([SPKI, publicKey]),
+            format: "der",
+            type: "spki",
+        });
+        return verify(null, msg, key, sig);
+    }
+    catch {
+        return false;
+    }
+};
+/** Zanii's check: the structure, and BOTH signatures over the same body. */
+export function verifyPqBinding(binding) {
+    const b = (binding ?? {});
+    const reasons = [];
+    if (b.v !== 1 || b.type !== "pq.binding")
+        reasons.push("not a pq.binding (v1)");
+    if (b.alg !== PQ_ALG)
+        reasons.push("unsupported alg (want ML-DSA-65)");
+    if (!b.did)
+        reasons.push("missing did");
+    const pqPub = typeof b.pq_pub === "string" && /^([0-9a-f]{2})+$/.test(b.pq_pub)
+        ? new Uint8Array(Buffer.from(b.pq_pub, "hex"))
+        : null;
+    if (!pqPub)
+        reasons.push("missing/invalid pq_pub");
+    if (!validTs(b.ts))
+        reasons.push("missing/invalid ts");
+    if (reasons.length > 0 || !pqPub)
+        return { ok: false, reasons };
+    const { sig_ed: sigEd, sig_pq: sigPq, ...unsigned } = b;
+    const raw = canonicalBytes(unsigned);
+    const pub = publicKeyFromDid(String(b.did));
+    const ed = typeof sigEd === "string" ? /^ed25519:([0-9a-f]{128})$/.exec(sigEd) : null;
+    if (!pub || !ed || !ed25519Verify(pub, raw, Buffer.from(ed[1], "hex")))
+        reasons.push("Ed25519 signature does not verify against the did");
+    const pq = typeof sigPq === "string" ? /^mldsa65:((?:[0-9a-f]{2})+)$/.exec(sigPq) : null;
+    if (!pq || !pqVerify(pqPub, raw, Buffer.from(pq[1], "hex")))
+        reasons.push("ML-DSA signature does not verify against pq_pub (possession not proven)");
+    return { ok: reasons.length === 0, reasons };
+}
+/** Zanii's transition payload, recorded UNSALTED: the binding as compact JSON. */
+export function pqTransitionPayload(binding) {
+    const check = verifyPqBinding(binding);
+    if (!check.ok)
+        throw new Error(`refusing to anchor an invalid binding: ${check.reasons.join("; ")}`);
+    return JSON.stringify(binding);
+}

package/dist/search/index.d.ts

@@ -0,0 +1,23 @@
+export interface SearchQuery {
+    /** An event kind, e.g. `tool.call`, `finding`, `control`. */
+    kind?: string;
+    /** A tool's name, as called: `delete_record`, `mcp__db__delete_record`, an SDK tool. */
+    tool?: string;
+    /** A finding code, e.g. `TOOL_CHANGED`. */
+    code?: string;
+    /** A person who decided an approval or a grant: their `sub`, `email` (any case) or `name`. */
+    person?: string;
+    /** The session's environment (`session.open` meta.environment). */
+    environment?: string;
+}
+export interface SearchMatch {
+    seq: number;
+    kind: string;
+    ts: string;
+    /** What matched: the tool, the code, the person, or the kind. */
+    match: string;
+}
+/** The query's fields, checked: each a 1-256 character string; `environment` alone is allowed. */
+export declare function checkSearch(q: Record<string, unknown>): string | undefined;
+/** Every event of the record that matches all of the query's fields, in seq order. */
+export declare function searchEvents(lines: readonly string[], q: SearchQuery): SearchMatch[];

package/dist/search/index.js

@@ -0,0 +1,69 @@
+// Structured search over a session's record (spec/search.md): exact matches on what the events say
+// (a tool, a fault code, a person, an event kind, the session's environment), never text inside
+// bodies. Precise by construction, and it reads nothing that was redacted. Pure; mirrors
+// sdks/python/src/zanii_blackbox/search.py; pinned by spec/vectors/search.json.
+const DECISIONS = new Set(["approval", "approval_vote", "permission"]);
+/** The query's fields, checked: each a 1-256 character string; `environment` alone is allowed. */
+export function checkSearch(q) {
+    const fields = ["kind", "tool", "code", "person", "environment"];
+    for (const k of Object.keys(q))
+        if (!fields.includes(k))
+            return `unknown search field ${JSON.stringify(k)}`;
+    for (const k of fields) {
+        const v = q[k];
+        if (v !== undefined && (typeof v !== "string" || v.length < 1 || v.length > 256))
+            return `${k} must be 1-256 characters`;
+    }
+    return fields.some((k) => q[k] !== undefined)
+        ? undefined
+        : "give kind, tool, code, person or environment";
+}
+function toolOf(e) {
+    if (e.kind === "tool.call" && typeof e.meta.tool === "string")
+        return typeof e.meta.server === "string"
+            ? [e.meta.tool, `mcp__${e.meta.server}__${e.meta.tool}`]
+            : [e.meta.tool];
+    if (e.kind === "sdk.event" && e.meta.type === "tool.call" && typeof e.meta.name === "string")
+        return [e.meta.name];
+    return [];
+}
+function personMatch(e, who) {
+    if (e.kind !== "control" || !DECISIONS.has(String(e.meta.action)))
+        return false;
+    const p = e.meta.person;
+    if (!p)
+        return false;
+    return (p.sub === who ||
+        p.name === who ||
+        (typeof p.email === "string" && p.email.toLowerCase() === who.toLowerCase()));
+}
+/** Every event of the record that matches all of the query's fields, in seq order. */
+export function searchEvents(lines, q) {
+    const events = lines.map((l) => JSON.parse(l));
+    const open = events.find((e) => e.kind === "session.open");
+    if (q.environment !== undefined && open?.meta.environment !== q.environment)
+        return [];
+    const eventWise = q.kind !== undefined || q.tool !== undefined || q.code !== undefined || q.person !== undefined;
+    if (!eventWise)
+        return open
+            ? [{ seq: open.seq, kind: open.kind, ts: open.ts, match: q.environment }]
+            : [];
+    const out = [];
+    for (const e of events) {
+        if (q.kind !== undefined && e.kind !== q.kind)
+            continue;
+        if (q.tool !== undefined && !toolOf(e).includes(q.tool))
+            continue;
+        if (q.code !== undefined && !(e.kind === "finding" && e.meta.code === q.code))
+            continue;
+        if (q.person !== undefined && !personMatch(e, q.person))
+            continue;
+        out.push({
+            seq: e.seq,
+            kind: e.kind,
+            ts: e.ts,
+            match: q.tool ?? q.code ?? q.person ?? q.kind,
+        });
+    }
+    return out;
+}