@zanii/blackbox 0.23.1 → 0.23.3

package/dist/analysis/faults.js

@@ -48,6 +48,11 @@ export const FAULTS = {
         en: "The ledger rejected an anchor",
         ar: "رفض دفتر الأستاذ تثبيتًا",
     },
+    GATEWAY_BYPASS: {
+        fault: "BBX-7501",
+        en: "Network call around the gateway, dropped",
+        ar: "اتصال شبكي خارج البوابة، تم حظره",
+    },
     SDK_SILENT: {
         fault: "BBX-1201",
         en: "The SDK stopped reporting",

package/dist/analysis/taxonomy.js

@@ -43,6 +43,7 @@ export const TAXONOMY = {
     EXTRA_LOCAL: { owasp: ["ASI10"] },
     FALSE_CLAIM: { owasp: ["ASI09", "ASI10"] },
     FALSE_SUCCESS: { owasp: ["ASI09", "ASI10"] },
+    GATEWAY_BYPASS: { owasp: ["ASI10"] },
     MISSING_LOCAL: { owasp: ["ASI10"] },
     PLAN_DEVIATION: { owasp: ["ASI01", "ASI10"] },
     PLAN_VIOLATION: { owasp: ["ASI02", "ASI10"], atlas: ["AML.T0053"] },

package/dist/encryption/index.d.ts

@@ -7,3 +7,46 @@ export interface SealedSegment {
 }
 /** The body, when every segment opens, hashes to its own hash, and they join to `bodyHash`; else null. */
 export declare function openSegments(segments: readonly SealedSegment[], bodyHash: string): Uint8Array | null;
+export type ReleaseRole = "company" | "custodian";
+export interface ReleasedSegment {
+    hash: string;
+    /** base64: nonce ‖ AES-256-GCM(segment key, plaintext, aad = hash) ‖ tag. */
+    sealed: string;
+    /** base64 sealed shares (92 bytes each): company XOR custodian = the segment key. */
+    shares: {
+        company: string;
+        custodian: string;
+    };
+}
+export type RandomBytes = (n: number) => Uint8Array;
+/** The raw 32-byte X25519 public key of a raw 32-byte private key. */
+export declare function releasePublicKey(privateKey: Uint8Array): Uint8Array;
+/** Seal one 32-byte share to a recipient's X25519 public key: E ‖ nonce ‖ ciphertext ‖ tag, base64. */
+export declare function sealReleaseShare(share: Uint8Array, recipientPublicKey: Uint8Array, hash: string, role: ReleaseRole, random?: RandomBytes): string;
+/** One holder opens their own share with their private key: the 32-byte share, or null. */
+export declare function openReleaseShare(sealed: string, privateKey: Uint8Array, hash: string, role: ReleaseRole): Uint8Array | null;
+/**
+ * The gateway's side: one stored segment for a two-key release. A segment stored in the clear
+ * (`key` null) is sealed with a fresh key first, so every released segment is sealed.
+ */
+export declare function releaseSegment(segment: {
+    hash: string;
+    bytes: Uint8Array;
+    key: Uint8Array | null;
+}, recipients: {
+    company: Uint8Array;
+    custodian: Uint8Array;
+}, random?: RandomBytes): ReleasedSegment;
+/** Both holders' material: their private keys, or the shares they opened (one per segment, in order). */
+export type ReleaseHolders = {
+    company: Uint8Array;
+    custodian: Uint8Array;
+} | {
+    companyShares: readonly Uint8Array[];
+    custodianShares: readonly Uint8Array[];
+};
+/**
+ * The body of a two-key release, when both shares of every segment join into a key that opens it,
+ * each segment hashes to its own hash, and they join to `bodyHash`; else null.
+ */
+export declare function openRelease(segments: readonly ReleasedSegment[], bodyHash: string, holders: ReleaseHolders): Uint8Array | null;

package/dist/encryption/index.js

@@ -1,7 +1,7 @@
 // The auditor's side of spec/encryption.md §4: open one body from its sealed segments and their
 // keys, and check it against the hash in the chain. Pure; mirrors
 // sdks/python/src/zanii_blackbox/encryption.py; pinned by spec/vectors/body-encryption.json.
-import { createDecipheriv, createHash } from "node:crypto";
+import { createCipheriv, createDecipheriv, createHash, createPrivateKey, createPublicKey, diffieHellman, hkdfSync, randomBytes, } from "node:crypto";
 const sha256 = (b) => `sha256:${createHash("sha256").update(b).digest("hex")}`;
 function open(key, hash, sealed) {
     if (key.length !== 32 || sealed.length < 28)
@@ -29,3 +29,112 @@ export function openSegments(segments, bodyHash) {
     const body = Buffer.concat(parts);
     return sha256(body) === bodyHash ? new Uint8Array(body) : null;
 }
+const PKCS8_X25519 = Buffer.from("302e020100300506032b656e04220420", "hex");
+const SPKI_X25519 = Buffer.from("302a300506032b656e032100", "hex");
+const x25519Private = (raw) => createPrivateKey({ key: Buffer.concat([PKCS8_X25519, raw]), format: "der", type: "pkcs8" });
+const x25519Public = (raw) => createPublicKey({ key: Buffer.concat([SPKI_X25519, raw]), format: "der", type: "spki" });
+/** The raw 32-byte X25519 public key of a raw 32-byte private key. */
+export function releasePublicKey(privateKey) {
+    const der = createPublicKey(x25519Private(privateKey)).export({ format: "der", type: "spki" });
+    return new Uint8Array(der.subarray(der.length - 32));
+}
+const xor = (a, b) => new Uint8Array(32).map((_, i) => (a[i] ?? 0) ^ (b[i] ?? 0));
+const shareInfo = (role, hash) => Buffer.from(`blackbox-release-share:${role}:${hash}`, "utf8");
+function wrappingKey(z, ephemeral, recipient, info) {
+    return Buffer.from(hkdfSync("sha256", z, Buffer.concat([ephemeral, recipient]), info, 32));
+}
+function gcmSeal(key, nonce, plain, aad) {
+    const c = createCipheriv("aes-256-gcm", key, nonce);
+    c.setAAD(aad);
+    return Buffer.concat([nonce, c.update(plain), c.final(), c.getAuthTag()]);
+}
+function gcmOpen(key, sealed, aad) {
+    if (sealed.length < 28)
+        return null;
+    try {
+        const d = createDecipheriv("aes-256-gcm", key, sealed.subarray(0, 12));
+        d.setAAD(aad);
+        d.setAuthTag(sealed.subarray(sealed.length - 16));
+        return Buffer.concat([d.update(sealed.subarray(12, sealed.length - 16)), d.final()]);
+    }
+    catch {
+        return null;
+    }
+}
+/** Seal one 32-byte share to a recipient's X25519 public key: E ‖ nonce ‖ ciphertext ‖ tag, base64. */
+export function sealReleaseShare(share, recipientPublicKey, hash, role, random = randomBytes) {
+    if (share.length !== 32 || recipientPublicKey.length !== 32)
+        throw new Error("a share and a recipient key are 32 bytes each");
+    const e = random(32);
+    const ephemeral = releasePublicKey(e);
+    const z = diffieHellman({
+        privateKey: x25519Private(e),
+        publicKey: x25519Public(recipientPublicKey),
+    });
+    const info = shareInfo(role, hash);
+    const w = wrappingKey(z, ephemeral, recipientPublicKey, info);
+    return Buffer.concat([ephemeral, gcmSeal(w, random(12), share, info)]).toString("base64");
+}
+/** One holder opens their own share with their private key: the 32-byte share, or null. */
+export function openReleaseShare(sealed, privateKey, hash, role) {
+    try {
+        const bytes = Buffer.from(sealed, "base64");
+        if (bytes.length !== 92 || privateKey.length !== 32)
+            return null;
+        const ephemeral = bytes.subarray(0, 32);
+        const z = diffieHellman({
+            privateKey: x25519Private(privateKey),
+            publicKey: x25519Public(ephemeral),
+        });
+        const info = shareInfo(role, hash);
+        const share = gcmOpen(wrappingKey(z, ephemeral, releasePublicKey(privateKey), info), bytes.subarray(32), info);
+        return share && share.length === 32 ? new Uint8Array(share) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The gateway's side: one stored segment for a two-key release. A segment stored in the clear
+ * (`key` null) is sealed with a fresh key first, so every released segment is sealed.
+ */
+export function releaseSegment(segment, recipients, random = randomBytes) {
+    let key = segment.key;
+    let sealed = Buffer.from(segment.bytes);
+    if (key === null) {
+        key = random(32);
+        sealed = gcmSeal(key, random(12), segment.bytes, Buffer.from(segment.hash, "utf8"));
+    }
+    if (key.length !== 32)
+        throw new Error("a segment key is 32 bytes");
+    const a = random(32);
+    const b = xor(key, a);
+    return {
+        hash: segment.hash,
+        sealed: sealed.toString("base64"),
+        shares: {
+            company: sealReleaseShare(a, recipients.company, segment.hash, "company", random),
+            custodian: sealReleaseShare(b, recipients.custodian, segment.hash, "custodian", random),
+        },
+    };
+}
+/**
+ * The body of a two-key release, when both shares of every segment join into a key that opens it,
+ * each segment hashes to its own hash, and they join to `bodyHash`; else null.
+ */
+export function openRelease(segments, bodyHash, holders) {
+    const keys = [];
+    for (const [i, s] of segments.entries()) {
+        const a = "company" in holders
+            ? openReleaseShare(s.shares.company, holders.company, s.hash, "company")
+            : (holders.companyShares[i] ?? null);
+        const b = "custodian" in holders
+            ? openReleaseShare(s.shares.custodian, holders.custodian, s.hash, "custodian")
+            : (holders.custodianShares[i] ?? null);
+        if (!a || !b || a.length !== 32 || b.length !== 32)
+            return null;
+        const key = Buffer.from(xor(a, b));
+        keys.push({ hash: s.hash, sealed: s.sealed, key: key.toString("base64") });
+    }
+    return openSegments(keys, bodyHash);
+}

package/dist/index.d.ts

@@ -35,7 +35,7 @@ export { type Directive, type DirectiveItem, type DirectiveOptions, directives,
 export { argumentLeaves, type Disclosure, type DisclosureEnvelope, discloseFields, disclosureEnvelope, verifyDisclosure, verifyEventDisclosure, } from "./disclosure/index.ts";
 export { checkDrill, drillReport, type Fault as DrillFault } from "./drills/index.ts";
 export { checkDuty, type DutyFinding, type DutyLimits, dutyFindings } from "./duty/index.ts";
-export { openSegments, type SealedSegment } from "./encryption/index.ts";
+export { openRelease, openReleaseShare, openSegments, type ReleasedSegment, type ReleaseHolders, type ReleaseRole, releasePublicKey, releaseSegment, type SealedSegment, sealReleaseShare, } from "./encryption/index.ts";
 export { type Arm, armStats, assignArm, type CaseScore, casesFromScenarios, casesFromSessions, checkDataset, checkExperiment, checkScorer, compareRuns, datasetHash, type EvalCase, experimentResults, type Observation, parseCasesJsonl, promptResults, promptSha256, type RunSummary, runSummary, SCORERS, type Scorer, scoreCase, toMilli, } from "./evals/index.ts";
 export { type EvidencePack, type EvidencePackOptions, evidencePack, renderEvidencePack, } from "./evidence/index.ts";
 export { buildEquivocationProof, compareViews, cosignLedgerSth, cosignLedgerSthWith, verifyEquivocationProof, verifyLedgerCosignature, } from "./federation/index.ts";
@@ -49,6 +49,7 @@ export { type AgentSink, BlackboxStoppedError, blackboxAgentMiddleware, blackbox
 export { blackboxCheckpointer } from "./hooks/langgraph-checkpoint.ts";
 export { MANAGED_END, MANAGED_START, managedBlock, protectedEdit } from "./hooks/protect.ts";
 export { type Investigation, investigation, renderInvestigation, } from "./investigate/index.ts";
+export { type InvestigationVerdict, verifyInvestigationExport, } from "./investigation/index.ts";
 export { isRpcResponse, rpcIdOf, SERVER_REQUESTS, type ServerRequestKind, secretFields, serverReplyMeta, serverRequestMeta, } from "./mcp-requests/index.ts";
 export { type McpWrapOptions, mcpWrap } from "./mcp-wrap/index.ts";
 export { commitContent, memoryChain, memoryEntry, verifyMemoryContent, verifyMemoryEntry, } from "./memory/index.ts";

package/dist/index.js

@@ -38,7 +38,7 @@ export { directives, fleetDirectives, } from "./directives/index.js";
 export { argumentLeaves, discloseFields, disclosureEnvelope, verifyDisclosure, verifyEventDisclosure, } from "./disclosure/index.js";
 export { checkDrill, drillReport } from "./drills/index.js";
 export { checkDuty, dutyFindings } from "./duty/index.js";
-export { openSegments } from "./encryption/index.js";
+export { openRelease, openReleaseShare, openSegments, releasePublicKey, releaseSegment, sealReleaseShare, } from "./encryption/index.js";
 export { armStats, assignArm, casesFromScenarios, casesFromSessions, checkDataset, checkExperiment, checkScorer, compareRuns, datasetHash, experimentResults, parseCasesJsonl, promptResults, promptSha256, runSummary, SCORERS, scoreCase, toMilli, } from "./evals/index.js";
 export { evidencePack, renderEvidencePack, } from "./evidence/index.js";
 export { buildEquivocationProof, compareViews, cosignLedgerSth, cosignLedgerSthWith, verifyEquivocationProof, verifyLedgerCosignature, } from "./federation/index.js";
@@ -52,6 +52,7 @@ export { BlackboxStoppedError, blackboxAgentMiddleware, blackboxHitl, } from "./
 export { blackboxCheckpointer } from "./hooks/langgraph-checkpoint.js";
 export { MANAGED_END, MANAGED_START, managedBlock, protectedEdit } from "./hooks/protect.js";
 export { investigation, renderInvestigation, } from "./investigate/index.js";
+export { verifyInvestigationExport, } from "./investigation/index.js";
 export { isRpcResponse, rpcIdOf, SERVER_REQUESTS, secretFields, serverReplyMeta, serverRequestMeta, } from "./mcp-requests/index.js";
 export { mcpWrap } from "./mcp-wrap/index.js";
 export { commitContent, memoryChain, memoryEntry, verifyMemoryContent, verifyMemoryEntry, } from "./memory/index.js";

package/dist/investigation/index.d.ts

@@ -0,0 +1,13 @@
+export interface InvestigationVerdict {
+    ok: boolean;
+    /** The signer's DID (the gateway identity), or null when unsigned. */
+    signer: string | null;
+    sessions: number;
+    /** Every problem found, empty when ok. */
+    reasons: string[];
+}
+/**
+ * spec/data.md §7b: verifies an investigation export. `expectedGateway` pins the signer's DID;
+ * without it, check `signer` against the gateway DID you trust.
+ */
+export declare function verifyInvestigationExport(doc: unknown, expectedGateway?: string): InvestigationVerdict;

package/dist/investigation/index.js

@@ -0,0 +1,73 @@
+// Investigation export verification (spec/data.md §7b): checks a Blackbox investigation export
+// offline: the manifest's gateway signature, and every session's hash chain, bodies and anchors
+// against the head and count the manifest signed. Pure; needs nothing but the export.
+import { verifyCertificate } from "../fleet/index.js";
+import { verifyChain } from "../verify/chain.js";
+const isObj = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+/**
+ * spec/data.md §7b: verifies an investigation export. `expectedGateway` pins the signer's DID;
+ * without it, check `signer` against the gateway DID you trust.
+ */
+export function verifyInvestigationExport(doc, expectedGateway) {
+    const reasons = [];
+    const out = (signer, sessions) => ({
+        ok: reasons.length === 0,
+        signer,
+        sessions,
+        reasons,
+    });
+    if (!isObj(doc) || doc.kind !== "blackbox.investigation" || !Array.isArray(doc.sessions)) {
+        reasons.push("not an investigation export");
+        return out(null, 0);
+    }
+    const manifest = doc.manifest;
+    if (!isObj(manifest) || manifest.kind !== "blackbox.investigation-manifest") {
+        reasons.push("no manifest");
+        return out(null, 0);
+    }
+    const sig = verifyCertificate(manifest, expectedGateway);
+    if (!sig.ok)
+        reasons.push(`manifest signature: ${sig.reason}`);
+    else if (manifest.gateway !== sig.by)
+        reasons.push("manifest gateway is not its signer");
+    const heads = Array.isArray(manifest.sessions) ? manifest.sessions : [];
+    if (manifest.session_count !== doc.sessions.length || heads.length !== doc.sessions.length)
+        reasons.push("session count does not match the manifest");
+    doc.sessions.forEach((s, i) => {
+        const want = heads[i];
+        if (!isObj(s) || !Array.isArray(s.records) || !isObj(s.bodies)) {
+            reasons.push(`session ${i}: malformed`);
+            return;
+        }
+        const id = String(s.session_id);
+        if (!want || want.session_id !== id) {
+            reasons.push(`session ${id}: not in the manifest at ${i}`);
+            return;
+        }
+        const bodies = s.bodies;
+        const v = verifyChain(s.records, {
+            sessionId: id,
+            count: want.count,
+            ...(typeof want.head === "string" ? { head: want.head } : {}),
+            anchors: Array.isArray(s.anchors)
+                ? s.anchors
+                : [],
+            body: (h) => {
+                const b = bodies[h]?.base64;
+                return typeof b === "string" ? new Uint8Array(Buffer.from(b, "base64")) : undefined;
+            },
+        });
+        // the agent each session matched, signed in the manifest (absent in older exports)
+        if (want.agent !== undefined) {
+            if (s.agent !== want.agent)
+                reasons.push(`session ${id}: agent differs from the manifest`);
+            if (!Array.isArray(manifest.agents) || !manifest.agents.includes(want.agent))
+                reasons.push(`session ${id}: agent is not one the manifest names`);
+        }
+        if (!v.ok)
+            reasons.push(`session ${id}: ${v.code} ${v.message}`);
+        else if (want.head === null)
+            reasons.push(`session ${id}: the manifest signed no head`);
+    });
+    return out(sig.by, doc.sessions.length);
+}

package/dist/verify/index.d.ts

@@ -1,3 +1,4 @@
 export { ANCHOR_TARGET, anchorPayload, anchorPayloadBytes, type Bundle, type BundleAnchor, type BundleReport, verifyBundle, } from "./anchor.ts";
 export { type FailureCode, type VerifyOptions, type VerifyResult, verifyChain } from "./chain.ts";
 export { assertSafeIntegers, EncodingError, type Envelope, EVENT_KINDS, type EventKind, encodeEnvelope, GENESIS, hashBody, hashLine, type Json, } from "./envelope.ts";
+export { SEEN_BY_KIND, type Seen, seenOf } from "./seen.ts";

package/dist/verify/index.js

@@ -1,3 +1,4 @@
 export { ANCHOR_TARGET, anchorPayload, anchorPayloadBytes, verifyBundle, } from "./anchor.js";
 export { verifyChain } from "./chain.js";
 export { assertSafeIntegers, EncodingError, EVENT_KINDS, encodeEnvelope, GENESIS, hashBody, hashLine, } from "./envelope.js";
+export { SEEN_BY_KIND, seenOf } from "./seen.js";

package/dist/verify/seen.d.ts

@@ -0,0 +1,5 @@
+import type { EventKind } from "./envelope.ts";
+export type Seen = "observed" | "reported" | "inferred";
+export declare const SEEN_BY_KIND: Readonly<Record<EventKind, Seen>>;
+/** How an event was seen, from its kind (and an outcome's `by`); null for a kind this doesn't know. */
+export declare function seenOf(kind: string, meta?: Record<string, unknown> | null): Seen | null;

package/dist/verify/seen.js

@@ -0,0 +1,31 @@
+// spec/api.md §4a: how each event was seen. Pure; mirrors sdks/python/src/zanii_blackbox/verify/seen.py;
+// pinned by spec/vectors/seen.json.
+export const SEEN_BY_KIND = {
+    "session.open": "observed",
+    "session.close": "observed",
+    "session.lost_contact": "observed",
+    "llm.request": "observed",
+    "llm.chunk": "observed",
+    "llm.response": "observed",
+    "llm.incomplete": "observed",
+    "llm.realtime.client": "observed",
+    "llm.realtime.server": "observed",
+    "tool.call": "observed",
+    "tool.result": "observed",
+    "tool.notification": "observed",
+    "tool.sampling": "observed",
+    "tool.elicitation": "observed",
+    "tool.roots": "observed",
+    "workspace.receipt": "reported",
+    "sdk.event": "reported",
+    control: "observed",
+    outcome: "reported",
+    finding: "inferred",
+    "capture.gap": "observed",
+};
+/** How an event was seen, from its kind (and an outcome's `by`); null for a kind this doesn't know. */
+export function seenOf(kind, meta) {
+    if (kind === "outcome")
+        return meta?.by === "server" ? "observed" : "reported";
+    return Object.hasOwn(SEEN_BY_KIND, kind) ? SEEN_BY_KIND[kind] : null;
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.23.1";
+export declare const VERSION = "0.23.3";

package/dist/version.js

@@ -1,2 +1,2 @@
 // The SDK version, on its own so the CLI can print it without loading the whole SDK.
-export const VERSION = "0.23.1";
+export const VERSION = "0.23.3";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zanii/blackbox",
   "license": "Apache-2.0",
-  "version": "0.23.1",
+  "version": "0.23.3",
   "description": "The flight recorder for AI agents: sessions, a zero-loss spool, framework hooks, approvals, and offline verification of the gateway's hash-chained record.",
   "keywords": [
     "ai-agents",
@@ -40,19 +40,19 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@zanii/core": "^0.5.6",
-    "@zanii/sdk": "^0.5.4"
+    "@zanii/core": "^0.5.7",
+    "@zanii/sdk": "^0.6.0"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.283",
-    "@langchain/core": "1.2.13",
-    "@langchain/langgraph": "1.4.18",
-    "@mastra/core": "1.78.0",
-    "@mastra/observability": "1.20.1",
-    "@openai/agents": "0.18.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.319",
+    "@langchain/core": "1.3.5",
+    "@langchain/langgraph": "1.7.1",
+    "@mastra/core": "1.82.0",
+    "@mastra/observability": "1.23.1",
+    "@openai/agents": "0.21.0",
     "ai": "6.0.283",
-    "langchain": "1.5.14",
-    "zod": "^4.6.5"
+    "langchain": "1.6.2",
+    "zod": "^4.6.7"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",