@zanii/blackbox 0.3.0 → 0.5.0

package/dist/succession/index.js

@@ -0,0 +1,123 @@
+// Owner-signed succession of the gateway identity (spec/anchoring.md §7), in Zanii's format:
+// byte-identical bodies, signatures and hashes to `@zanii/succession` / `zanii.succession`
+// (vectors: spec/vectors/succession.json). The Python SDK re-exports zanii.succession.
+//
+// Succession proves continuity of authority (the owner says B follows A), not which code ran.
+// After a compromise the predecessor's signature isn't asked for (the attacker holds that key), and
+// `compromised_at` brackets the window its old receipts can be trusted in.
+import { canonicalBytes, jcsHash, publicKeyFromDid } from "@zanii/core";
+import { ed25519Sign, ed25519Verify } from "../transparency/index.js";
+const REASONS = new Set(["rotation", "compromise", "retirement"]);
+const validTs = (ts) => typeof ts === "string" && !Number.isNaN(Date.parse(ts));
+export function buildSuccessionBody(input) {
+    const { predecessor, successor, owner, reason, ts, compromised_at, note } = input;
+    if (!predecessor || !successor || !owner)
+        throw new Error("predecessor, successor, and owner are required");
+    if (predecessor === successor)
+        throw new Error("an agent cannot succeed itself");
+    if (!REASONS.has(reason))
+        throw new Error(`invalid reason '${reason}'`);
+    if (!validTs(ts))
+        throw new Error("ts must be an ISO timestamp");
+    if (reason === "compromise") {
+        if (!validTs(compromised_at))
+            throw new Error("a 'compromise' succession requires compromised_at");
+    }
+    else if (compromised_at !== undefined)
+        throw new Error("compromised_at is only meaningful with reason 'compromise'");
+    return {
+        v: 1,
+        type: "succession",
+        predecessor,
+        successor,
+        owner,
+        reason: reason,
+        ts,
+        ...(compromised_at !== undefined ? { compromised_at } : {}),
+        ...(note !== undefined ? { note } : {}),
+    };
+}
+/** Signs as the owner (required) or the predecessor (optional: a planned handover). */
+export const signSuccession = (body, did, seed) => ({
+    did,
+    sig: `ed25519:${Buffer.from(ed25519Sign(seed, canonicalBytes(body))).toString("hex")}`,
+});
+export const assembleSuccession = (body, signatures) => ({ body, signatures });
+export const successionHash = (s) => jcsHash(s);
+function sigValid(body, did, sig) {
+    const pub = publicKeyFromDid(did);
+    const m = typeof sig === "string" ? /^ed25519:([0-9a-f]{128})$/.exec(sig) : null;
+    if (!pub || !m)
+        return false;
+    return ed25519Verify(pub, canonicalBytes(body), Buffer.from(m[1], "hex"));
+}
+/** Structure sane and the owner signed; `cosigned` when the predecessor countersigned too. */
+export function verifySuccession(s) {
+    const reasons = [];
+    const e = (s ?? {});
+    const b = (e.body ?? {});
+    if (b.v !== 1 || b.type !== "succession")
+        reasons.push("not a succession (v1)");
+    const { predecessor: pred, successor: succ, owner } = b;
+    if (!pred || !succ || !owner || pred === succ)
+        reasons.push("missing/invalid parties");
+    if (!REASONS.has(String(b.reason)))
+        reasons.push("invalid reason");
+    if (b.reason === "compromise" && !validTs(b.compromised_at))
+        reasons.push("a 'compromise' succession requires a valid compromised_at");
+    if (!validTs(b.ts))
+        reasons.push("missing/invalid ts");
+    let cosigned = false;
+    if (reasons.length === 0) {
+        const sigs = Array.isArray(e.signatures) ? e.signatures : [];
+        const ownerSig = sigs.find((x) => x?.did === owner);
+        if (!ownerSig || !sigValid(b, ownerSig.did, ownerSig.sig))
+            reasons.push("missing/invalid OWNER signature");
+        const predSig = sigs.find((x) => x?.did === pred);
+        cosigned = predSig !== undefined && sigValid(b, predSig.did, predSig.sig);
+    }
+    return { ok: reasons.length === 0, reasons, cosigned };
+}
+/**
+ * Walks the successions back from `did`: every link verifies, links connect, one owner throughout
+ * (a change of owner is a sale, not a succession). `lineage` is oldest first.
+ */
+export function verifyLineage(successions, did) {
+    if (successions.length === 0)
+        return { ok: true, reasons: [], lineage: [did] };
+    const bySuccessor = new Map();
+    for (const s of successions) {
+        const check = verifySuccession(s);
+        if (!check.ok) {
+            const label = s?.body?.successor ?? "?";
+            return { ok: false, reasons: check.reasons.map((r) => `link ${label}: ${r}`), lineage: [] };
+        }
+        const link = s;
+        if (bySuccessor.has(link.body.successor))
+            return {
+                ok: false,
+                reasons: [`two successions claim successor ${link.body.successor}`],
+                lineage: [],
+            };
+        bySuccessor.set(link.body.successor, link);
+    }
+    const links = successions;
+    const owner = links[0]?.body.owner;
+    if (!links.every((s) => s.body.owner === owner))
+        return { ok: false, reasons: ["lineage spans multiple owners"], lineage: [] };
+    const lineage = [did];
+    const seen = new Set([did]);
+    let cursor = did;
+    for (let link = bySuccessor.get(cursor); link; link = bySuccessor.get(cursor)) {
+        const prev = link.body.predecessor;
+        if (seen.has(prev))
+            return { ok: false, reasons: ["succession cycle detected"], lineage: [] };
+        seen.add(prev);
+        lineage.unshift(prev);
+        cursor = prev;
+    }
+    const reasons = lineage.length === links.length + 1
+        ? []
+        : [`${links.length + 1 - lineage.length} succession(s) do not connect to ${did}'s lineage`];
+    return { ok: reasons.length === 0, reasons, lineage };
+}

package/dist/tokens/index.d.ts

@@ -0,0 +1,6 @@
+/** The token for one value: `<kind_tok:base64url(nonce ‖ AES-256-GCM(value, aad=kind))>`. */
+export declare function tokenFor(kind: string, value: string, key: Uint8Array): string;
+/** A token's value, or null when it isn't one, or isn't this key's. */
+export declare function resolveToken(token: string, key: Uint8Array): string | null;
+/** Every token in `text` this key resolves, put back; any other is left as it is. */
+export declare function resolveTokens(text: string, key: Uint8Array): string;

package/dist/tokens/index.js

@@ -0,0 +1,46 @@
+// Keyed redaction tokens (spec/data.md §12, L9): a redacted value as `<kind_tok:…>`, AES-256-GCM
+// under the deployment's token key, so a tool that holds the key resolves it and nothing in between
+// (the model, the gateway's memory) has the value. Deterministic: the nonce is an HMAC of the kind
+// and value, so the same value always reads the same. Mirrors sdks/python/src/zanii_blackbox/
+// tokens.py; pinned by spec/vectors/tokens.json.
+import { createCipheriv, createDecipheriv, createHmac } from "node:crypto";
+const TOKEN = /<([a-z_]{1,32})_tok:([A-Za-z0-9_-]{24,4096})>/g;
+const check = (key) => {
+    if (key.length !== 32)
+        throw new Error("a token key is 32 bytes");
+};
+/** The token for one value: `<kind_tok:base64url(nonce ‖ AES-256-GCM(value, aad=kind))>`. */
+export function tokenFor(kind, value, key) {
+    check(key);
+    if (!/^[a-z_]{1,32}$/.test(kind))
+        throw new Error("kind must be 1-32 of a-z _");
+    const nonce = createHmac("sha256", key).update(`${kind}\0${value}`).digest().subarray(0, 12);
+    const cipher = createCipheriv("aes-256-gcm", key, nonce);
+    cipher.setAAD(Buffer.from(kind));
+    const sealed = Buffer.concat([cipher.update(value, "utf8"), cipher.final(), cipher.getAuthTag()]);
+    return `<${kind}_tok:${Buffer.concat([nonce, sealed]).toString("base64url")}>`;
+}
+/** A token's value, or null when it isn't one, or isn't this key's. */
+export function resolveToken(token, key) {
+    check(key);
+    const m = new RegExp(`^${TOKEN.source}$`).exec(token);
+    if (!m)
+        return null;
+    try {
+        const raw = Buffer.from(m[2], "base64url");
+        if (raw.length < 12 + 16)
+            return null;
+        const d = createDecipheriv("aes-256-gcm", key, raw.subarray(0, 12));
+        d.setAAD(Buffer.from(m[1]));
+        d.setAuthTag(raw.subarray(raw.length - 16));
+        return Buffer.concat([d.update(raw.subarray(12, raw.length - 16)), d.final()]).toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Every token in `text` this key resolves, put back; any other is left as it is. */
+export function resolveTokens(text, key) {
+    check(key);
+    return text.replace(TOKEN, (t) => resolveToken(t, key) ?? t);
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.3.0";
+export declare const VERSION = "0.5.0";

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

package/dist/walls/index.d.ts

@@ -0,0 +1,31 @@
+export interface Wall {
+    id: string;
+    regulator: string;
+    scopes: string[];
+    denies: string[];
+    forbidden: string[];
+    note: string;
+}
+export declare const WALLS: Readonly<Record<string, Wall>>;
+/** Zanii's wall manifest hash: the id and its sorted scopes and denies (order-independent). */
+export declare const wallManifestHash: (w: Wall) => string;
+/** Zanii's heuristic: an output crosses the wall when it holds a forbidden phrase. */
+export declare function checkOutput(w: Wall, text: string): {
+    ok: boolean;
+    violations: string[];
+};
+/**
+ * spec/governance.md §5: WALL_CROSSED for each model response that holds a phrase one of the
+ * walls forbids; one finding per response and wall, naming the first phrase.
+ */
+export declare function wallFindings(lines: readonly string[], bodies: (hash: string) => Uint8Array | undefined, wallIds: readonly string[]): {
+    code: string;
+    source: string;
+    severity: "warning";
+    ref: {
+        seq: number;
+        wall: string;
+        phrase: string;
+    };
+    detail: string;
+}[];

package/dist/walls/index.js

@@ -0,0 +1,119 @@
+// Zanii's UAE vertical walls (spec/governance.md §5): the table from spec/walls/v1.json, embedded
+// (a test checks it matches), and the output check. Mirrors sdks/python/src/zanii_blackbox/walls.py.
+import { jcsHash } from "@zanii/core";
+export const WALLS = {
+    "sca-trading": {
+        id: "sca-trading",
+        regulator: "SCA",
+        scopes: ["trading.education.*", "market.read.*"],
+        denies: ["trading.execute.*", "trading.advise.*", "trading.recommend.*"],
+        forbidden: [
+            "buy this",
+            "sell this",
+            "you should buy",
+            "you should sell",
+            "i recommend buying",
+            "i recommend selling",
+            "guaranteed return",
+            "guaranteed profit",
+            "this will go up",
+            "will moon",
+        ],
+        note: 'education only; NEVER "buy this" — investment advice/execution is a licensed SCA activity',
+    },
+    "rera-realty": {
+        id: "rera-realty",
+        regulator: "RERA/DLD",
+        scopes: ["realty.inform.*", "realty.read.*"],
+        denies: ["realty.broker.*", "realty.list.*"],
+        forbidden: ["i can broker", "i will list", "sign the deal"],
+        note: "informs; never brokers or lists unpermitted properties",
+    },
+    "tdra-messaging": {
+        id: "tdra-messaging",
+        regulator: "TDRA",
+        scopes: ["messaging.send.optin.*"],
+        denies: ["messaging.send.bulk.*", "messaging.send.nonoptin.*"],
+        forbidden: [],
+        note: "opt-in only; must announce it is a bot",
+    },
+    "legal-drafting": {
+        id: "legal-drafting",
+        regulator: "Legal Affairs",
+        scopes: ["legal.draft.*", "legal.read.*"],
+        denies: ["legal.opine.*", "legal.advise.*"],
+        forbidden: ["my legal opinion is", "you should sue", "this is legally binding advice"],
+        note: "drafts; never gives legal opinions",
+    },
+    "consumer-due": {
+        id: "consumer-due",
+        regulator: "Consumer Protection / Central Bank",
+        scopes: ["collections.remind.*"],
+        denies: ["collections.threaten.*"],
+        forbidden: ["we will sue you", "legal action today", "you will be arrested"],
+        note: "reminds; never threatens; frequency limits",
+    },
+    "difc-dp": {
+        id: "difc-dp",
+        regulator: "DIFC (DP Law 2020)",
+        scopes: ["data.process.difc.*"],
+        denies: ["data.export.nonadequate.*"],
+        forbidden: [],
+        note: "DIFC free-zone data protection; select per deployment (not federal PDPL)",
+    },
+    "adgm-dp": {
+        id: "adgm-dp",
+        regulator: "ADGM (DP Regs 2021)",
+        scopes: ["data.process.adgm.*"],
+        denies: ["data.export.nonadequate.*"],
+        forbidden: [],
+        note: "ADGM free-zone data protection; select per deployment (not federal PDPL)",
+    },
+};
+/** Zanii's wall manifest hash: the id and its sorted scopes and denies (order-independent). */
+export const wallManifestHash = (w) => jcsHash({ id: w.id, scopes: [...w.scopes].sort(), denies: [...w.denies].sort() });
+/** Zanii's heuristic: an output crosses the wall when it holds a forbidden phrase. */
+export function checkOutput(w, text) {
+    const lower = text.toLowerCase();
+    const violations = w.forbidden.filter((p) => lower.includes(p));
+    return { ok: violations.length === 0, violations };
+}
+const decoder = new TextDecoder();
+/**
+ * spec/governance.md §5: WALL_CROSSED for each model response that holds a phrase one of the
+ * walls forbids; one finding per response and wall, naming the first phrase.
+ */
+export function wallFindings(lines, bodies, wallIds) {
+    const walls = wallIds.map((id) => WALLS[id]).filter((w) => w !== undefined);
+    const out = [];
+    if (walls.length === 0)
+        return out;
+    // a response's bytes are its chunks' bodies, joined in order (spec/api.md: llm.chunk)
+    const chunks = new Map();
+    for (const l of lines) {
+        const e = JSON.parse(l);
+        if (e.kind === "llm.chunk") {
+            const body = bodies(e.body_hash);
+            const list = chunks.get(e.meta.request_seq) ?? [];
+            list.push(body ? decoder.decode(body) : "");
+            chunks.set(e.meta.request_seq, list);
+        }
+        if (e.kind !== "llm.response")
+            continue;
+        const text = (chunks.get(e.meta.request_seq) ?? []).join("");
+        if (!text)
+            continue;
+        for (const w of walls) {
+            const check = checkOutput(w, text);
+            if (!check.ok)
+                out.push({
+                    code: "WALL_CROSSED",
+                    source: "detectors",
+                    severity: "warning",
+                    ref: { seq: e.seq, wall: w.id, phrase: check.violations[0] },
+                    detail: `The model's answer crossed the ${w.regulator} wall: ${w.note}`,
+                });
+        }
+    }
+    return out;
+}

package/package.json

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