@zanii/blackbox 0.14.0 → 0.15.1

package/README.md

@@ -83,6 +83,12 @@ verifyAnswerCredential(credential, lines, bodies, packs); // { ok, problems }: t
 
 The same checks run offline as pure functions: `toolHallucinations`, `groundingFindings`, `factsIn`, `loadReferencePacks`, `answerRisk`, `detectorAccuracy`.
 
+## New in 0.15.0
+
+- M-of-N shares: `splitSecret` / `combineShares`, and `blackbox key-split --m 3 --n 5` / `blackbox key-combine`, so no single custodian holds the gateway's key passphrase.
+- `otlpFromProtobuf(bytes)`: OTLP/HTTP protobuf spans, read without a protobuf library (gateway v0.17 takes them on `/v1/traces`).
+- Works with gateway v0.17: the passphrase from Google Cloud KMS or Azure Key Vault, retention per tenant, closed-session summaries kept, the trace exported while a session runs.
+
 ## New in 0.14.0
 
 - Price uplifts (`uplifts` in a price table): US-only inference, regional endpoints and fast modes priced above list, per deployment (`upliftPercent`).

package/dist/cli.js

@@ -53,7 +53,9 @@ const USAGE = `usage (spec/cli.md):
   blackbox reconcile-system --connector <connector.json> --log <export.csv|jsonl> [--pack <pack.json>] <session_id>
   blackbox workspace-receipt   (a Claude Code PreToolUse / PostToolUse hook; reads the hook JSON on stdin)
   blackbox attest   (a Claude Code PostToolUse hook: spec/attestation.md §4)
-  blackbox policy-hook   (a Claude Code / Codex PreToolUse hook: asks the gateway's policy; fails closed)`;
+  blackbox policy-hook   (a Claude Code / Codex PreToolUse hook: asks the gateway's policy; fails closed)
+  blackbox key-split --m <M> --n <N> < secret   (M-of-N shares of a secret, one per line: spec/operations.md §4b)
+  blackbox key-combine <share> <share> …   (the secret back, on stdout)`;
 async function main(argv) {
     const [command, ...rest] = argv;
     if (command === "mcp")
@@ -70,6 +72,10 @@ async function main(argv) {
         return attestCommand();
     if (command === "policy-hook")
         return policyHookCommand();
+    if (command === "key-split")
+        return keySplitCommand(rest);
+    if (command === "key-combine")
+        return keyCombineCommand(rest);
     if (command === "verify")
         return verifyCommand(rest);
     if (command === "export")
@@ -218,6 +224,39 @@ async function attestCommand() {
     }
     return 0;
 }
+/** spec/operations.md §4b: the secret on stdin, as M-of-N shares on stdout, one a line. */
+async function keySplitCommand(rest) {
+    const { flags } = parse(rest, []);
+    const m = Number(flags.m);
+    const n = Number(flags.n);
+    const parts = [];
+    for await (const chunk of process.stdin)
+        parts.push(chunk);
+    const secret = Buffer.from(Buffer.concat(parts)
+        .toString("utf8")
+        .replace(/\r?\n$/, ""), "utf8");
+    try {
+        const { splitSecret } = await import("./shares/index.js");
+        process.stdout.write(`${splitSecret(secret, m, n).join("\n")}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`blackbox key-split: ${error instanceof Error ? error.message : error}\n`);
+        return 2;
+    }
+}
+/** spec/operations.md §4b: M shares (arguments) back to the secret, on stdout. */
+async function keyCombineCommand(rest) {
+    try {
+        const { combineShares } = await import("./shares/index.js");
+        process.stdout.write(`${Buffer.from(combineShares(rest)).toString("utf8")}\n`);
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`blackbox key-combine: ${error instanceof Error ? error.message : error}\n`);
+        return 2;
+    }
+}
 /** spec/policy.md §2a: a PreToolUse hook. Deny: exit 2, the reason on stderr (the agent sees it).
  * Ask: Claude Code's `permissionDecision: "ask"` on stdout. Allow: exit 0, nothing printed. Any
  * failure denies, unless BLACKBOX_HOOK_FAIL_OPEN=1. */

package/dist/index.d.ts

@@ -39,10 +39,11 @@ export { MANAGED_END, MANAGED_START, managedBlock, protectedEdit } from "./hooks
 export { type Investigation, investigation, renderInvestigation, } from "./investigate/index.ts";
 export { type McpWrapOptions, mcpWrap } from "./mcp-wrap/index.ts";
 export { commitContent, memoryChain, memoryEntry, verifyMemoryContent, verifyMemoryEntry, } from "./memory/index.ts";
-export { type AmountUnit, anthropicStatement, type Baseline, baselines, type Connector, checkConnector, checkStatement, csvStatement, customStatement, decimalToMicroUsd, fuel, modelSpend, openaiStatement, pageParams, parseXml, reconcileBilling, requestFor, resolvePath, type Statement, } from "./money/index.ts";
+export { type AmountUnit, anthropicStatement, type Baseline, baselines, type Connector, checkConnector, checkStatement, csvStatement, customStatement, decimalToMicroUsd, fuel, fxRate, fxUnit, modelSpend, openaiStatement, pageParams, parseXml, reconcileBilling, requestFor, resolvePath, type Statement, } from "./money/index.ts";
 export { deadlinesDue, filingPack, type OccurrenceFacts, type OccurrenceFramework, type OccurrenceReport, occurrenceFacts, occurrenceReport, renderOccurrence, } from "./occurrence/index.ts";
 export { ingestOcsf, type OcsfEvent, type OcsfVersion, ocsfLine, toOcsf } from "./ocsf/index.ts";
 export { fromOtlp, type OtlpEvent, toOtlp } from "./otlp/index.ts";
+export { otlpFromProtobuf } from "./otlp/protobuf.ts";
 export { checkIdentifier, checkPack, corePack, type PackEntry, packData, packFrameworks, } from "./packs/index.ts";
 export { type PolicyChange, type PolicyDelta, policyDelta } from "./policy/delta.ts";
 export { type Draft, type DraftGroup, policyDrafts } from "./policy/drafts.ts";
@@ -62,6 +63,7 @@ export { ORPHAN_TEXT, repairToolCalls } from "./replay/repair.ts";
 export { checkSearch, type SearchMatch, type SearchQuery, searchEvents } from "./search/index.ts";
 export { type DrainResult, drainSpools } from "./session/drain.ts";
 export { type AnswerCheck, BlackboxSession, checkEgress, type EgressCheck, type FlightPlan, type LlmCallIds, type SessionError, type SessionOptions, type SessionState, type SessionStats, session, stableEventId, } from "./session/index.ts";
+export { combineShares, splitSecret } from "./shares/index.ts";
 export { assembleSla, assessCompliance, buildSlaBody, signSla, slaHash, verifySla, } from "./sla/index.ts";
 export { assembleSuccession, buildSuccessionBody, type Succession, type SuccessionBody, type SuccessionReason, signSuccession, successionHash, verifyLineage, verifySuccession, } from "./succession/index.ts";
 export { type TimestampReport, timestampRequest, verifyTimestamp, } from "./timestamp/index.ts";

package/dist/index.js

@@ -41,10 +41,11 @@ export { MANAGED_END, MANAGED_START, managedBlock, protectedEdit } from "./hooks
 export { investigation, renderInvestigation, } from "./investigate/index.js";
 export { mcpWrap } from "./mcp-wrap/index.js";
 export { commitContent, memoryChain, memoryEntry, verifyMemoryContent, verifyMemoryEntry, } from "./memory/index.js";
-export { anthropicStatement, baselines, checkConnector, checkStatement, csvStatement, customStatement, decimalToMicroUsd, fuel, modelSpend, openaiStatement, pageParams, parseXml, reconcileBilling, requestFor, resolvePath, } from "./money/index.js";
+export { anthropicStatement, baselines, checkConnector, checkStatement, csvStatement, customStatement, decimalToMicroUsd, fuel, fxRate, fxUnit, modelSpend, openaiStatement, pageParams, parseXml, reconcileBilling, requestFor, resolvePath, } from "./money/index.js";
 export { deadlinesDue, filingPack, occurrenceFacts, occurrenceReport, renderOccurrence, } from "./occurrence/index.js";
 export { ingestOcsf, ocsfLine, toOcsf } from "./ocsf/index.js";
 export { fromOtlp, toOtlp } from "./otlp/index.js";
+export { otlpFromProtobuf } from "./otlp/protobuf.js";
 export { checkIdentifier, checkPack, corePack, packData, packFrameworks, } from "./packs/index.js";
 export { policyDelta } from "./policy/delta.js";
 export { policyDrafts } from "./policy/drafts.js";
@@ -64,6 +65,7 @@ export { ORPHAN_TEXT, repairToolCalls } from "./replay/repair.js";
 export { checkSearch, searchEvents } from "./search/index.js";
 export { drainSpools } from "./session/drain.js";
 export { BlackboxSession, checkEgress, session, stableEventId, } from "./session/index.js";
+export { combineShares, splitSecret } from "./shares/index.js";
 export { assembleSla, assessCompliance, buildSlaBody, signSla, slaHash, verifySla, } from "./sla/index.js";
 export { assembleSuccession, buildSuccessionBody, signSuccession, successionHash, verifyLineage, verifySuccession, } from "./succession/index.js";
 export { timestampRequest, verifyTimestamp, } from "./timestamp/index.js";

package/dist/otlp/protobuf.d.ts

@@ -0,0 +1,4 @@
+/** spec/otlp.md §4: an ExportTraceServiceRequest's bytes as OTLP/JSON. Throws on bad bytes. */
+export declare function otlpFromProtobuf(buf: Uint8Array): {
+    resourceSpans: object[];
+};

package/dist/otlp/protobuf.js

@@ -0,0 +1,167 @@
+// OTLP/HTTP protobuf (spec/otlp.md §4): an ExportTraceServiceRequest's bytes as the OTLP/JSON
+// shape `fromOtlp` reads. A reader for just the trace messages, no protobuf library: wire types
+// varint, 64-bit, length-delimited and 32-bit; unknown fields are skipped. Mirrors
+// sdks/python/src/zanii_blackbox/otlp_protobuf.py; pinned by spec/vectors/otlp-protobuf.json.
+function fields(buf) {
+    const out = [];
+    let i = 0;
+    const varint = () => {
+        let r = 0n;
+        let s = 0n;
+        for (;;) {
+            if (i >= buf.length)
+                throw new Error("protobuf: a varint runs past the end");
+            const b = buf[i++];
+            r |= BigInt(b & 0x7f) << s;
+            if (!(b & 0x80))
+                return r;
+            s += 7n;
+            if (s > 63n)
+                throw new Error("protobuf: a varint over 64 bits");
+        }
+    };
+    const fixed = (size) => {
+        if (i + size > buf.length)
+            throw new Error("protobuf: a fixed field runs past the end");
+        let v = 0n;
+        for (let k = size - 1; k >= 0; k--)
+            v = (v << 8n) | BigInt(buf[i + k]);
+        i += size;
+        return v;
+    };
+    while (i < buf.length) {
+        const key = Number(varint());
+        const n = key >>> 3;
+        const wire = key & 7;
+        if (wire === 0)
+            out.push({ n, wire, v: varint() });
+        else if (wire === 1)
+            out.push({ n, wire, v: fixed(8) });
+        else if (wire === 5)
+            out.push({ n, wire, v: fixed(4) });
+        else if (wire === 2) {
+            const len = Number(varint());
+            if (i + len > buf.length)
+                throw new Error("protobuf: a field runs past the end");
+            out.push({ n, wire, v: buf.subarray(i, i + len) });
+            i += len;
+        }
+        else
+            throw new Error(`protobuf: wire type ${wire} isn't supported`);
+    }
+    return out;
+}
+const text = (b) => new TextDecoder().decode(b);
+const hex = (b) => Buffer.from(b).toString("hex");
+const bytes = (f) => f.v;
+const big = (f) => f.v;
+const float64 = (bits) => {
+    const view = new DataView(new ArrayBuffer(8));
+    view.setBigUint64(0, bits, true);
+    return view.getFloat64(0, true);
+};
+function anyValue(b) {
+    for (const f of fields(b)) {
+        if (f.n === 1 && f.wire === 2)
+            return { stringValue: text(bytes(f)) };
+        if (f.n === 2 && f.wire === 0)
+            return { boolValue: big(f) !== 0n };
+        if (f.n === 3 && f.wire === 0)
+            return { intValue: BigInt.asIntN(64, big(f)).toString() };
+        if (f.n === 4 && f.wire === 1)
+            return { doubleValue: float64(big(f)) };
+        if (f.n === 5 && f.wire === 2)
+            return {
+                arrayValue: {
+                    values: fields(bytes(f))
+                        .filter((x) => x.n === 1 && x.wire === 2)
+                        .map((x) => anyValue(bytes(x))),
+                },
+            };
+        if (f.n === 6 && f.wire === 2)
+            return { kvlistValue: { values: keyValues(bytes(f), 1) } };
+        if (f.n === 7 && f.wire === 2)
+            return { bytesValue: Buffer.from(bytes(f)).toString("base64") };
+    }
+    return {};
+}
+/** The repeated KeyValue at field `at` of a message. */
+function keyValues(b, at) {
+    return fields(b)
+        .filter((f) => f.n === at && f.wire === 2)
+        .map((f) => {
+        let key = "";
+        let value = {};
+        for (const g of fields(bytes(f))) {
+            if (g.n === 1 && g.wire === 2)
+                key = text(bytes(g));
+            if (g.n === 2 && g.wire === 2)
+                value = anyValue(bytes(g));
+        }
+        return { key, value };
+    });
+}
+function span(b) {
+    const out = {};
+    for (const f of fields(b)) {
+        if (f.n === 1 && f.wire === 2)
+            out.traceId = hex(bytes(f));
+        else if (f.n === 2 && f.wire === 2)
+            out.spanId = hex(bytes(f));
+        else if (f.n === 4 && f.wire === 2 && bytes(f).length)
+            out.parentSpanId = hex(bytes(f));
+        else if (f.n === 5 && f.wire === 2)
+            out.name = text(bytes(f));
+        else if (f.n === 6 && f.wire === 0)
+            out.kind = Number(big(f));
+        else if (f.n === 7 && f.wire === 1)
+            out.startTimeUnixNano = big(f).toString();
+        else if (f.n === 8 && f.wire === 1)
+            out.endTimeUnixNano = big(f).toString();
+        else if (f.n === 15 && f.wire === 2) {
+            const status = {};
+            for (const g of fields(bytes(f))) {
+                if (g.n === 2 && g.wire === 2)
+                    status.message = text(bytes(g));
+                if (g.n === 3 && g.wire === 0)
+                    status.code = Number(big(g));
+            }
+            out.status = status;
+        }
+    }
+    out.attributes = keyValues(b, 9);
+    return out;
+}
+/** spec/otlp.md §4: an ExportTraceServiceRequest's bytes as OTLP/JSON. Throws on bad bytes. */
+export function otlpFromProtobuf(buf) {
+    return {
+        resourceSpans: fields(buf)
+            .filter((f) => f.n === 1 && f.wire === 2)
+            .map((rs) => {
+            const out = { scopeSpans: [] };
+            for (const f of fields(bytes(rs))) {
+                if (f.n === 1 && f.wire === 2)
+                    out.resource = { attributes: keyValues(bytes(f), 1) };
+                if (f.n === 2 && f.wire === 2) {
+                    const ss = { spans: [] };
+                    for (const g of fields(bytes(f))) {
+                        if (g.n === 1 && g.wire === 2) {
+                            const scope = {};
+                            for (const h of fields(bytes(g))) {
+                                if (h.n === 1 && h.wire === 2)
+                                    scope.name = text(bytes(h));
+                                if (h.n === 2 && h.wire === 2)
+                                    scope.version = text(bytes(h));
+                            }
+                            ss.scope = scope;
+                        }
+                        if (g.n === 2 && g.wire === 2)
+                            ss.spans.push(span(bytes(g)));
+                    }
+                    out.scopeSpans.push(ss);
+                }
+            }
+            return out;
+        }),
+    };
+}

package/dist/shares/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Splits `secret` into `n` shares, any `m` of which rebuild it: `zks1-<m>-<x>-<check>-<hex>`,
+ * where `check` (8 hex of the secret's SHA-256) catches a share from another secret. `random`
+ * gives the polynomial's coefficients (the tests pass fixed ones; never do that for real).
+ */
+export declare function splitSecret(secret: Uint8Array, m: number, n: number, random?: (count: number) => Uint8Array): string[];
+/** Rebuilds a secret from at least `m` of its shares; throws if they're too few or don't fit. */
+export declare function combineShares(shares: readonly string[]): Uint8Array;

package/dist/shares/index.js

@@ -0,0 +1,84 @@
+// M-of-N secret shares (spec/operations.md §4b): Shamir's scheme over GF(256), byte by byte, so any
+// M of N custodians can rebuild a secret (the key passphrase) and fewer learn nothing about it.
+// Mirrors sdks/python/src/zanii_blackbox/shares.py; pinned by spec/vectors/shares.json.
+import { createHash, randomBytes } from "node:crypto";
+// GF(256) with the AES polynomial x^8 + x^4 + x^3 + x + 1, generator 3
+const EXP = new Uint8Array(512);
+const LOG = new Uint8Array(256);
+{
+    let x = 1;
+    for (let i = 0; i < 255; i++) {
+        EXP[i] = x;
+        LOG[x] = i;
+        x ^= (x << 1) ^ (x & 0x80 ? 0x11b : 0);
+        x &= 0xff;
+    }
+    for (let i = 255; i < 512; i++)
+        EXP[i] = EXP[i - 255];
+}
+const mul = (a, b) => a === 0 || b === 0 ? 0 : EXP[LOG[a] + LOG[b]];
+const div = (a, b) => a === 0 ? 0 : EXP[LOG[a] + 255 - LOG[b]];
+const check = (secret) => createHash("sha256").update(secret).digest("hex").slice(0, 8);
+/**
+ * Splits `secret` into `n` shares, any `m` of which rebuild it: `zks1-<m>-<x>-<check>-<hex>`,
+ * where `check` (8 hex of the secret's SHA-256) catches a share from another secret. `random`
+ * gives the polynomial's coefficients (the tests pass fixed ones; never do that for real).
+ */
+export function splitSecret(secret, m, n, random = (count) => new Uint8Array(randomBytes(count))) {
+    if (!Number.isInteger(m) || !Number.isInteger(n) || m < 2 || n < m || n > 255)
+        throw new Error("shares need 2 ≤ m ≤ n ≤ 255");
+    if (secret.length < 1 || secret.length > 4096)
+        throw new Error("a secret is 1-4096 bytes");
+    const ys = Array.from({ length: n }, () => new Uint8Array(secret.length));
+    for (let i = 0; i < secret.length; i++) {
+        const coefficients = [secret[i], ...random(m - 1)];
+        for (let x = 1; x <= n; x++) {
+            let y = 0;
+            for (let k = coefficients.length - 1; k >= 0; k--)
+                y = mul(y, x) ^ coefficients[k]; // Horner, in GF(256)
+            ys[x - 1][i] = y;
+        }
+    }
+    const c = check(secret);
+    return ys.map((y, i) => `zks1-${m}-${i + 1}-${c}-${Buffer.from(y).toString("hex")}`);
+}
+/** Rebuilds a secret from at least `m` of its shares; throws if they're too few or don't fit. */
+export function combineShares(shares) {
+    const parsed = shares.map((s) => {
+        const p = /^zks1-(\d{1,3})-(\d{1,3})-([0-9a-f]{8})-((?:[0-9a-f]{2})+)$/.exec(s.trim());
+        if (!p)
+            throw new Error("not a share (zks1-<m>-<x>-<check>-<hex>)");
+        return {
+            m: Number(p[1]),
+            x: Number(p[2]),
+            check: p[3],
+            y: Buffer.from(p[4], "hex"),
+        };
+    });
+    const first = parsed[0];
+    if (!first)
+        throw new Error("no shares");
+    if (parsed.some((p) => p.m !== first.m || p.check !== first.check || p.y.length !== first.y.length))
+        throw new Error("the shares aren't of one secret");
+    const unique = [...new Map(parsed.map((p) => [p.x, p])).values()];
+    if (unique.some((p) => p.x < 1 || p.x > 255))
+        throw new Error("a share's index is out of range");
+    if (unique.length < first.m)
+        throw new Error(`${first.m} shares are needed, ${unique.length} given`);
+    const use = unique.slice(0, first.m);
+    const secret = new Uint8Array(first.y.length);
+    for (let i = 0; i < secret.length; i++) {
+        let s = 0;
+        for (const [j, pj] of use.entries()) {
+            let l = 1; // the Lagrange basis at 0
+            for (const [k, pk] of use.entries())
+                if (k !== j)
+                    l = mul(l, div(pk.x, pk.x ^ pj.x));
+            s ^= mul(pj.y[i], l);
+        }
+        secret[i] = s;
+    }
+    if (check(secret) !== first.check)
+        throw new Error("the shares don't fit together");
+    return secret;
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.14.0";
+export declare const VERSION = "0.15.1";

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.14.0";
+export const VERSION = "0.15.1";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zanii/blackbox",
   "license": "Apache-2.0",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "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",