@zanii/blackbox 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export { type Invoice, type InvoiceLine, invoice, loadPlans, type Plan, type Pla
 export { BlackboxApiError, type Client, type ClientOptions, client, type SessionQuery, } from "./client/index.ts";
 export { complianceFacts, complianceReport, type Facts, type Framework, type Report as ComplianceReport, renderReport, } from "./compliance/index.ts";
 export { type CallCost, type CostReport, callMicroUsd, effectivePrice, formatAed, type LoadedPrices, loadPrices, type ModelPrice, type PriceTable, priceCall, priceFor, promptTokens, requestsOf, sessionCost, type Tokens, toAedFils, tokensOf, } from "./cost/index.ts";
+export { type AuditRow, CORE_EVIDENCE, CORE_IDENTIFIERS, type Connector as AuditConnector, canaryIdentifier, checkAuditConnector, type DataFinding, type DataRules, dataClasses, dataFindings, dataFingerprint, dataMeta, dataScan, dataTopology, hasEvidence, type Identifier, type Lineage, lineage, luhn, normalizeValue, parseAuditLog, parseCsv, reconcileSystem, type SystemReport, type Topology, toolWitness, unevidenced, verifyToolWitness, witnessOf, } from "./data/index.ts";
 export { type Directive, type DirectiveItem, type DirectiveOptions, directives, fleetDirectives, } from "./directives/index.ts";
 export { checkDrill, drillReport, type Fault as DrillFault } from "./drills/index.ts";
 export { checkDuty, type DutyFinding, type DutyLimits, dutyFindings } from "./duty/index.ts";
@@ -24,7 +25,7 @@ export { type AmountUnit, anthropicStatement, type Baseline, baselines, type Con
 export { 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 { toOtlp } from "./otlp/index.ts";
-export { checkPack, corePack, type PackEntry, packFrameworks } from "./packs/index.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";
 export { audited, type CompiledPolicy, compilePolicy, type Decision, decide, loadPolicy, type Policy, policyFindings, type Rule, } from "./policy/index.ts";
@@ -37,7 +38,7 @@ export { type Finding, type FindingCode, type Harness, loadLocal, type Reconcile
 export { cassette, requestKey, type Take } from "./replay/index.ts";
 export { ORPHAN_TEXT, repairToolCalls } from "./replay/repair.ts";
 export { type DrainResult, drainSpools } from "./session/drain.ts";
-export { BlackboxSession, type FlightPlan, type LlmCallIds, type SessionError, type SessionOptions, type SessionState, type SessionStats, session, stableEventId, } from "./session/index.ts";
+export { BlackboxSession, checkEgress, type EgressCheck, type FlightPlan, type LlmCallIds, type SessionError, type SessionOptions, type SessionState, type SessionStats, session, stableEventId, } from "./session/index.ts";
 export { type Compensation, checkCompensations, runUndo, type UndoFinding, type UndoStatus, type UndoStep, undoFindings, undoPlan, } from "./undo/index.ts";
 export * from "./verify/index.ts";
 export { VERSION } from "./version.ts";

package/dist/index.js

@@ -12,6 +12,7 @@ export { invoice, loadPlans, renderTaxInvoice, stripeSignatureOk, taxInvoice, }
 export { BlackboxApiError, client, } from "./client/index.js";
 export { complianceFacts, complianceReport, renderReport, } from "./compliance/index.js";
 export { callMicroUsd, effectivePrice, formatAed, loadPrices, priceCall, priceFor, promptTokens, requestsOf, sessionCost, toAedFils, tokensOf, } from "./cost/index.js";
+export { CORE_EVIDENCE, CORE_IDENTIFIERS, canaryIdentifier, checkAuditConnector, dataClasses, dataFindings, dataFingerprint, dataMeta, dataScan, dataTopology, hasEvidence, lineage, luhn, normalizeValue, parseAuditLog, parseCsv, reconcileSystem, toolWitness, unevidenced, verifyToolWitness, witnessOf, } from "./data/index.js";
 export { directives, fleetDirectives, } from "./directives/index.js";
 export { checkDrill, drillReport } from "./drills/index.js";
 export { checkDuty, dutyFindings } from "./duty/index.js";
@@ -26,7 +27,7 @@ export { anthropicStatement, baselines, checkConnector, checkStatement, csvState
 export { filingPack, occurrenceFacts, occurrenceReport, renderOccurrence, } from "./occurrence/index.js";
 export { ingestOcsf, ocsfLine, toOcsf } from "./ocsf/index.js";
 export { toOtlp } from "./otlp/index.js";
-export { checkPack, corePack, packFrameworks } from "./packs/index.js";
+export { checkIdentifier, checkPack, corePack, packData, packFrameworks, } from "./packs/index.js";
 export { policyDelta } from "./policy/delta.js";
 export { policyDrafts } from "./policy/drafts.js";
 export { audited, compilePolicy, decide, loadPolicy, policyFindings, } from "./policy/index.js";
@@ -39,7 +40,7 @@ export { loadLocal, RecordNotVerified, reconcile, } from "./reconcile/index.js";
 export { cassette, requestKey } from "./replay/index.js";
 export { ORPHAN_TEXT, repairToolCalls } from "./replay/repair.js";
 export { drainSpools } from "./session/drain.js";
-export { BlackboxSession, session, stableEventId, } from "./session/index.js";
+export { BlackboxSession, checkEgress, session, stableEventId, } from "./session/index.js";
 export { checkCompensations, runUndo, undoFindings, undoPlan, } from "./undo/index.js";
 export * from "./verify/index.js";
 export { VERSION } from "./version.js";

package/dist/packs/index.d.ts

@@ -1,3 +1,4 @@
+import { type DataRules } from "../data/index.ts";
 type Obj = Record<string, unknown>;
 export interface PackEntry {
     pack: string;
@@ -9,6 +10,13 @@ export interface PackEntry {
 }
 /** spec/packs.md §1: why a pack is invalid, or undefined. */
 export declare function checkPack(value: unknown): string | undefined;
+/** spec/data.md §1: why an identifier is invalid, or undefined. */
+export declare function checkIdentifier(v: unknown, at: string): string | undefined;
+/**
+ * spec/data.md §4: the data rules of packs merged in order, then the core. Pack identifiers come
+ * before the core ones; throws on an invalid pack or an identifier id in two packs.
+ */
+export declare function packData(packs: readonly unknown[]): DataRules;
 /** spec/packs.md §2: the core pack, from the built-in frameworks files. */
 export declare function corePack(compliance: {
     notes: string;

package/dist/packs/index.js

@@ -1,6 +1,7 @@
 // Framework packs (spec/packs.md): compliance and occurrence frameworks as data a deployment
 // switches on. Pure; mirrors sdks/python/src/zanii_blackbox/packs.py; pinned by
-// spec/vectors/packs.json.
+// spec/vectors/packs.json. The `data` part is spec/data.md §4.
+import { CORE_EVIDENCE, CORE_IDENTIFIERS } from "../data/index.js";
 const FACTS = new Set([
     "sessions",
     "events",
@@ -130,7 +131,9 @@ function checkArabic(ar, fw, at) {
 export function checkPack(value) {
     if (!isObj(value))
         return "a pack must be an object";
+    // `data` came later (spec/data.md §4); the pinned messages below name the v1 keys only.
     if (!only(value, [
+        "data",
         "v",
         "id",
         "title",
@@ -154,7 +157,7 @@ export function checkPack(value) {
             typeof value.reviewed_at !== "string" ||
             !DATE.test(value.reviewed_at)))
         return "a reviewed pack needs reviewed_by and reviewed_at (YYYY-MM-DD)";
-    if (value.compliance === undefined && value.occurrence === undefined)
+    if (value.compliance === undefined && value.occurrence === undefined && value.data === undefined)
         return "a pack needs compliance, occurrence or both";
     for (const kind of ["compliance", "occurrence"])
         if (value[kind] !== undefined) {
@@ -162,8 +165,131 @@ export function checkPack(value) {
             if (bad)
                 return bad;
         }
+    return value.data === undefined ? undefined : checkData(value.data);
+}
+const IDENTIFIER_ID = /^[a-z0-9_]{1,64}$/;
+const NORMALIZE = new Set(["digits", "lower", "upper", "exact"]);
+// Escapes Python reads over Unicode and JavaScript over ASCII (spec/data.md §1).
+const UNPORTABLE = /\\[dDwWbBsS]/;
+const ALLOW = /^(?:region|model|tool|api):(?:[A-Za-z0-9._-]{1,128}\*?|\*)$/;
+const TOOL = /^[A-Za-z0-9._-]{1,128}$/;
+const FIELD = /^[A-Za-z0-9_.-]{1,64}$/;
+const compiles = (pattern) => {
+    try {
+        new RegExp(pattern);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** spec/data.md §1: why an identifier is invalid, or undefined. */
+export function checkIdentifier(v, at) {
+    if (!isObj(v) ||
+        !only(v, ["id", "title", "pattern", "normalize", "keep_last", "check", "personal"]))
+        return `${at} may only have id, title, pattern, normalize, keep_last, check, personal`;
+    if (typeof v.id !== "string" || !IDENTIFIER_ID.test(v.id))
+        return `${at}.id must be 1-64 of a-z 0-9 _`;
+    if (!text(v.title, 200))
+        return `${at}.title must be 1-200 characters`;
+    if (typeof v.pattern !== "string" || !text(v.pattern, 500) || !compiles(v.pattern))
+        return `${at}.pattern must be a regular expression of 1-500 characters`;
+    if (UNPORTABLE.test(v.pattern))
+        return `${at}.pattern must not use \\d \\w \\b or \\s`;
+    if (!NORMALIZE.has(v.normalize))
+        return `${at}.normalize must be digits, lower, upper or exact`;
+    if (v.keep_last !== undefined &&
+        (!Number.isInteger(v.keep_last) || v.keep_last < 1 || v.keep_last > 30))
+        return `${at}.keep_last must be 1-30`;
+    if (v.check !== undefined && v.check !== "luhn")
+        return `${at}.check must be luhn`;
+    if (typeof v.personal !== "boolean")
+        return `${at}.personal must be true or false`;
+    return undefined;
+}
+function checkData(part) {
+    if (!isObj(part) || !only(part, ["notes", "identifiers", "residency", "restricted", "evidence"]))
+        return "data may only have notes, identifiers, residency, restricted, evidence";
+    if (!text(part.notes, 2000))
+        return "data.notes must be 1-2000 characters";
+    const ids = part.identifiers ?? [];
+    if (!Array.isArray(ids) || ids.length > 50)
+        return "data.identifiers must hold 0-50 identifiers";
+    const seen = new Set(CORE_IDENTIFIERS.map((i) => i.id));
+    for (const [i, v] of ids.entries()) {
+        const bad = checkIdentifier(v, `data.identifiers[${i}]`);
+        if (bad)
+            return bad;
+        const id = v.id;
+        if (seen.has(id))
+            return `data.identifiers[${i}].id ${id} is already defined`;
+        seen.add(id);
+    }
+    if (part.residency !== undefined && typeof part.residency !== "boolean")
+        return "data.residency must be true or false";
+    const rules = part.restricted ?? [];
+    if (!Array.isArray(rules) || rules.length > 50)
+        return "data.restricted must hold 0-50 rules";
+    for (const [i, r] of rules.entries()) {
+        const at = `data.restricted[${i}]`;
+        if (!isObj(r) || !only(r, ["identifiers", "allow"]))
+            return `${at} must be {identifiers, allow}`;
+        if (!Array.isArray(r.identifiers) ||
+            r.identifiers.length < 1 ||
+            r.identifiers.length > 50 ||
+            !r.identifiers.every((x) => typeof x === "string" && seen.has(x)))
+            return `${at}.identifiers must hold 1-50 known identifier ids`;
+        if (!Array.isArray(r.allow) ||
+            r.allow.length < 1 ||
+            r.allow.length > 20 ||
+            !r.allow.every((x) => typeof x === "string" && ALLOW.test(x)))
+            return `${at}.allow must hold 1-20 of region:, model:, tool:, api:`;
+    }
+    const evidence = part.evidence ?? [];
+    if (!Array.isArray(evidence) || evidence.length > 200)
+        return "data.evidence must hold 0-200 rules";
+    for (const [i, e] of evidence.entries())
+        if (!isObj(e) ||
+            !only(e, ["tool", "field"]) ||
+            typeof e.tool !== "string" ||
+            !TOOL.test(e.tool) ||
+            typeof e.field !== "string" ||
+            !FIELD.test(e.field))
+            return `data.evidence[${i}] must be {tool, field}`;
     return undefined;
 }
+/**
+ * spec/data.md §4: the data rules of packs merged in order, then the core. Pack identifiers come
+ * before the core ones; throws on an invalid pack or an identifier id in two packs.
+ */
+export function packData(packs) {
+    const identifiers = [];
+    const restricted = [];
+    const evidence = [];
+    const owner = new Map();
+    let residency = false;
+    for (const p of packs) {
+        const bad = checkPack(p);
+        const id = isObj(p) && typeof p.id === "string" ? p.id : "?";
+        if (bad)
+            throw new Error(`pack ${id}: ${bad}`);
+        const data = p.data;
+        if (!data)
+            continue;
+        for (const ident of data.identifiers ?? []) {
+            const had = owner.get(ident.id);
+            if (had)
+                throw new Error(`identifier ${ident.id} is in packs ${had} and ${id}`);
+            owner.set(ident.id, id);
+            identifiers.push(ident);
+        }
+        residency ||= data.residency === true;
+        restricted.push(...(data.restricted ?? []));
+        evidence.push(...(data.evidence ?? []));
+    }
+    identifiers.push(...CORE_IDENTIFIERS);
+    return { identifiers, residency, restricted, evidence: [...evidence, ...CORE_EVIDENCE] };
+}
 /** spec/packs.md §2: the core pack, from the built-in frameworks files. */
 export function corePack(compliance, occurrence) {
     return {

package/dist/session/index.d.ts

@@ -76,6 +76,16 @@ export interface FlightPlan {
 }
 /** Audit S17: what the gateway says about this session right now (GET /v1/sessions/:id/state). */
 /** What `land()` found (spec/findings.md §5). */
+export interface EgressCheck {
+    url: string;
+    /** The request got any answer: the agent can reach the internet around the gateway. */
+    open: boolean;
+}
+/** spec/data.md §6: a direct HTTPS request to `url` (default https://example.com). Never throws. */
+export declare function checkEgress(options?: {
+    url?: string;
+    timeoutMs?: number;
+}): Promise<EgressCheck>;
 export interface LandingResult {
     /** Only a `satisfied` verdict lands: `unverified` never counts as a pass. */
     landed: boolean;
@@ -149,6 +159,15 @@ export declare class BlackboxSession {
         ok?: boolean;
         [key: string]: unknown;
     }): void;
+    /** spec/data.md §7: a subject's consent for a purpose. The subject is fingerprinted at capture,
+     *  so it must be an identifier the deployment knows (an e-mail, an Emirates ID, a pack's own). */
+    consent(subject: string, purpose: string, granted: boolean): void;
+    /** spec/data.md §6: tries the internet directly, outside the gateway, and records the answer.
+     *  `open: true` means the gateway isn't the only way out (EGRESS_OPEN). */
+    egressCheck(options?: {
+        url?: string;
+        timeoutMs?: number;
+    }): Promise<EgressCheck>;
     llmCall(ids: LlmCallIds): void;
     note(text: string): void;
     /** Files the flight plan (spec/findings.md §5), unless one was filed when the session opened. */

package/dist/session/index.js

@@ -7,6 +7,17 @@ import { request as httpsRequest } from "node:https";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { attest, isReadOnly } from "../attest/index.js";
+/** spec/data.md §6: a direct HTTPS request to `url` (default https://example.com). Never throws. */
+export async function checkEgress(options = {}) {
+    const url = options.url ?? "https://example.com";
+    try {
+        await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(options.timeoutMs ?? 5000) });
+        return { url, open: true };
+    }
+    catch {
+        return { url, open: false };
+    }
+}
 const TYPE = /^[a-z][a-z0-9_.]{0,63}$/;
 /** N4 (idea R6): a caller's logical id for an event, so a re-sent one is recorded as a duplicate. */
 const EVENT_ID = /^[A-Za-z0-9._:-]{1,128}$/;
@@ -181,6 +192,18 @@ export class BlackboxSession {
     toolResult(name, result) {
         this.event("tool.result", name, result);
     }
+    /** spec/data.md §7: a subject's consent for a purpose. The subject is fingerprinted at capture,
+     *  so it must be an identifier the deployment knows (an e-mail, an Emirates ID, a pack's own). */
+    consent(subject, purpose, granted) {
+        this.event("consent", granted ? "granted" : "withdrawn", { subject, purpose });
+    }
+    /** spec/data.md §6: tries the internet directly, outside the gateway, and records the answer.
+     *  `open: true` means the gateway isn't the only way out (EGRESS_OPEN). */
+    async egressCheck(options = {}) {
+        const result = await checkEgress(options);
+        this.event("egress_check", result.open ? "open" : "closed", { url: result.url });
+        return result;
+    }
     llmCall(ids) {
         this.event("llm.call", ids.provider, { ...ids });
     }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.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.1.0";
+export const VERSION = "0.2.0";

package/package.json

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