@zanii/blackbox 0.3.0 → 0.5.0

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

package/dist/session/index.d.ts

@@ -1,4 +1,5 @@
 import { type Attestation } from "../attest/index.ts";
+import { buildPayment, type screenCounterparty } from "../finance/index.ts";
 export interface SessionOptions {
     /** The gateway, e.g. http://127.0.0.1:8787 */
     url: string;
@@ -33,6 +34,11 @@ export interface SessionOptions {
     tenant?: string;
     /** spec/authority.md: `supervised` from the start (risky actions wait for a second person). */
     authority?: "agent" | "supervised";
+    /** spec/api.md: where it runs (`production`, `staging`, …); policy rules can match it. */
+    environment?: string;
+    /** spec/findings.md §13.1: hold this session's streamed answers until they're checked (`true`),
+     * or never (`false`); unset follows the server's BLACKBOX_HOLD_STREAMS. */
+    holdStreams?: boolean;
     /** spec/preflight.md: the equipment the run needs. A no-go returns a disabled session (and
      * `stats.lastError` says why); optional items that are down show in `state().degraded`. */
     preflight?: {
@@ -95,6 +101,16 @@ export interface LandingResult {
     /** How many more tries `maxAttempts` allows; at 0, stop and report. */
     attemptsLeft: number;
 }
+/** spec/findings.md §13.1: what would hold an answer, from `checkAnswer()`. */
+export interface AnswerCheck {
+    seq: number;
+    risks: Array<{
+        index: number;
+        kind: string;
+        status: "contradicted" | "ungrounded";
+    }>;
+    hold: boolean;
+}
 export interface SessionState {
     session_id: string;
     closed: boolean;
@@ -144,6 +160,10 @@ export declare class BlackboxSession {
     private timers;
     private closed;
     private landings;
+    /** spec/approvals.md §2: approved tools with arguments, until their call is reported. */
+    private approved;
+    /** spec/agents.md §4: the memory chain's tip. */
+    private memoryLast;
     /** A session that records nothing. `reason`, when opening failed, goes to `stats.lastError` (audit K1). */
     static disabled(options: SessionOptions, reason?: string): BlackboxSession;
     private readonly options;
@@ -161,6 +181,67 @@ export declare class BlackboxSession {
         };
     }): void;
     step(name: string, data?: Record<string, unknown>): void;
+    /**
+     * spec/gov.md §2: a decision about a person, under the rulebook `manifestHash`, the person named
+     * only by their subject tag. Returns the factors' nonce (keep it to disclose them in a dispute).
+     * Throws on a decision that can't be lawful evidence: no rulebook, a bad kind, no tag.
+     */
+    decision(kind: string, o: {
+        manifestHash: string;
+        outcome: Record<string, unknown>;
+        subjectTag: string;
+        factors?: Record<string, unknown>;
+        appealBy?: string;
+    }): {
+        nonce: string;
+    };
+    /** spec/health.md §2: who accessed a patient's record (an episode tag, never the seed), and why. */
+    healthAccess(o: {
+        episodeTag: string;
+        actor: string;
+        purpose: string;
+        consentRef?: string;
+        details?: Record<string, unknown>;
+    }): {
+        nonce: string;
+    };
+    /** spec/health.md §2: a model's recommendation under a protocol. `hash` is what the clinician signs. */
+    recommendation(o: {
+        episodeTag: string;
+        modelId: string;
+        manifestHash: string;
+        outcome: Record<string, unknown>;
+        runtimeHash?: string;
+        deviation?: Record<string, unknown>;
+    }): {
+        nonce: string;
+        hash: string;
+    };
+    /** spec/health.md §2: a clinician's signed confirmation (clinicianConfirmation). Throws on a bad signature. */
+    clinicianConfirmation(episodeTag: string, payload: Record<string, unknown>): void;
+    /** spec/health.md §2: an emergency access, signed by the clinician (breakGlass). Loud on purpose. */
+    breakGlass(episodeTag: string, payload: Record<string, unknown>): void;
+    private signedHealth;
+    /** spec/finance.md §2: a payment, exact (minor units), with its settlement reference. Throws on a bad amount. */
+    payment(input: Parameters<typeof buildPayment>[0]): void;
+    /** spec/finance.md §3: a counterparty screening (screenCounterparty), before paying them. */
+    screening(result: ReturnType<typeof screenCounterparty>): void;
+    /** spec/finance.md §4: a tax filing the agent prepared. It never files; a Tax Agent does. */
+    ftaPrepared(o: {
+        filingType: string;
+        period: string;
+        filingRef?: string;
+        manifestHash?: string;
+        by?: string;
+    }): void;
+    /** spec/finance.md §4: the prepared filing handed to a licensed Tax Agent. */
+    ftaHandoff(o: {
+        filingType: string;
+        period: string;
+        toTaxAgent: string;
+        filingRef?: string;
+        by?: string;
+    }): void;
     toolCall(name: string, args?: unknown): void;
     toolResult(name: string, result?: {
         ok?: boolean;
@@ -200,6 +281,15 @@ export declare class BlackboxSession {
         summary?: string;
         file_path?: string;
     }): void;
+    /** spec/findings.md §11 (H3): pin the documents the agent read, by hash; the content never leaves.
+     * Each doc is `{id, uri?, version?}` with its `content` (hashed here) or its `sha256`. */
+    retrieved(docs: ReadonlyArray<{
+        id: string;
+        uri?: string;
+        version?: string;
+        content?: string | Uint8Array;
+        sha256?: string;
+    }>): void;
     /** Stage 2 R3: the result of one of the customer's own checks (tests, a schema, a policy, a
      * partial goal), mid-run or at the end. A pass then a fail is VERIFY_REGRESSION; a success whose last
      * check failed is FALSE_SUCCESS (spec/findings.md §6). */
@@ -234,7 +324,18 @@ export declare class BlackboxSession {
         height?: number;
     }): void;
     /** spec/agents.md §1: the agent's memory store wrote, revoked or returned memories. */
-    memoryWrite(memoryId: string, summary?: string): void;
+    /** spec/agents.md §4: with `content`, the write also carries Zanii's memory entry (a salted
+     * commitment, chained after `prev`, else this session's last entry). Keep the salt it returns. */
+    memoryWrite(memoryId: string, summary?: string, opts?: {
+        content: string;
+        kind?: string;
+        prev?: Record<string, unknown>;
+        agent?: string;
+        tags?: string[];
+    }): {
+        entry: Record<string, unknown>;
+        salt: string;
+    } | undefined;
     memoryRevoke(memoryId: string, reason?: string): void;
     memoryRead(memoryIds: string[], query?: string): void;
     /** Ships what's pending now. Resolves true when everything recorded is acknowledged. With
@@ -245,6 +346,10 @@ export declare class BlackboxSession {
     /** Audit S17: the gateway's view of this session (blocked? findings?), or null if it can't be
      * read. Lets an agent react to its own block before its next model call. Never throws. */
     state(): Promise<SessionState | null>;
+    /** spec/findings.md §13.1: what in an answer (the latest, or the one at `seq`) would hold it,
+     * for an app that streams the answer by itself: `{seq, risks, hold}`. `hold` says whether the
+     * server would hold it. `null` when there's no answer yet or the gateway can't be asked. */
+    checkAnswer(seq?: number): Promise<AnswerCheck | null>;
     /** spec/approvals.md §2: asks a second person before running one of the agent's own risky tools,
      * and waits (polling) for the answer. Never throws. Only `"approved"` means go ahead; anything
      * else (`rejected`, `timeout`, or `error` when the gateway can't be asked) means don't. */