crewhaus 0.1.8 → 0.2.1

package/dist/security-digest.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Every kind declared by `@crewhaus/audit-log`. Kept as a local literal list
+ * (rather than importing a value — the package only exports the TYPE) so the
+ * digest can report declared kinds that produced zero records in the window.
+ *
+ * `satisfies ReadonlyArray<AuditKind>` only checks that every entry HERE is a
+ * valid `AuditKind` — it is a subset check, not an exhaustiveness check. It
+ * does NOT catch a NEW kind added to the `AuditKind` union that this list
+ * forgets to list (F7: `alert_raised`, added by the item-31 alert watchdog,
+ * compiled cleanly for a while despite being absent here). Keep this list in
+ * sync BY HAND whenever `AuditKind` gains a member.
+ */
+export declare const DECLARED_AUDIT_KINDS: readonly ["policy_decision", "model_call", "tool_classification", "gateway_request", "session_fork", "tenancy_context", "secrets_rotation", "secrets_access", "deployment_action", "egress_decision", "permission_justification_evaluated", "retention_enforcement", "governance_approval", "governance_proposal", "alert_raised", "slo_mitigation"];
+/** Thrown by `parseSinceFlag` on an unparseable `--since`. The CLI entry
+ *  file catches it and routes the message through `die()`; tests assert on
+ *  `.message` without the process exiting. */
+export declare class InvalidSinceFlagError extends Error {
+    readonly value: string;
+    readonly name = "InvalidSinceFlagError";
+    constructor(value: string);
+}
+export type SinceWindow = {
+    /** Inclusive epoch-ms lower bound on record timestamps. */
+    readonly sinceMs: number;
+    /** Human label for the report header: "7d", "30d", or the ISO value. */
+    readonly label: string;
+};
+/**
+ * Parse the `--since` flag: `<N>d` (a trailing day window, default `7d`) or
+ * an ISO date/datetime (bare dates are UTC midnight per `Date.parse`).
+ */
+export declare function parseSinceFlag(value: string | undefined, now?: () => number): SinceWindow;
+export type DeniedToolEntry = {
+    readonly toolName: string;
+    readonly denials: number;
+    /** Distinct judge identities that produced the denials. */
+    readonly judges: ReadonlyArray<string>;
+    /** Mean judge confidence over denials that carried one; null when none did. */
+    readonly meanConfidence: number | null;
+    /** The most recent denial reason, for triage at a glance. */
+    readonly lastReason?: string;
+};
+export type JudgeEntry = {
+    readonly judgeModel: string;
+    readonly evaluated: number;
+    readonly denied: number;
+};
+export type EgressSinkEntry = {
+    readonly sinkId: string;
+    readonly warned: number;
+    readonly blocked: number;
+    /** Distinct trust origins found in this sink's non-pass payloads. */
+    readonly origins: ReadonlyArray<string>;
+};
+export type CountEntry = {
+    readonly name: string;
+    readonly count: number;
+};
+export type SecurityDigest = {
+    readonly version: 1;
+    readonly generatedAt: string;
+    /** ISO instant of the window's inclusive lower bound. */
+    readonly since: string;
+    readonly windowLabel: string;
+    readonly rootDir: string;
+    readonly audit: {
+        readonly dir: string;
+        /** Records parsed from day files that could overlap the window. */
+        readonly recordsScanned: number;
+        /** Records whose ts landed inside the window (the rollup input). */
+        readonly recordsInWindow: number;
+        /** Unparseable JSONL lines — reported, never fatal (triage tool). */
+        readonly malformedLines: number;
+        readonly countsByKind: Readonly<Record<string, number>>;
+        /** Kinds @crewhaus/audit-log declares that produced 0 window records —
+         *  always includes the still-writerless kinds, plus any writerful kind
+         *  (e.g. egress_decision) that simply had no records in the window. */
+        readonly absentDeclaredKinds: ReadonlyArray<string>;
+    };
+    /** Pillar 3 intent gate — from `permission_justification_evaluated`. */
+    readonly justification: {
+        readonly evaluated: number;
+        readonly allowed: number;
+        readonly denied: number;
+        /** denied / evaluated; null when nothing was evaluated in the window. */
+        readonly denyRate: number | null;
+        readonly topDeniedTools: ReadonlyArray<DeniedToolEntry>;
+        readonly byJudge: ReadonlyArray<JudgeEntry>;
+    };
+    /** Pillar 3 sink-side — from `egress_decision` records (NO writer today;
+     *  see the module header — populated the day one lands). */
+    readonly egress: {
+        readonly decisions: number;
+        readonly passed: number;
+        readonly warned: number;
+        readonly blocked: number;
+        readonly topSinks: ReadonlyArray<EgressSinkEntry>;
+        readonly topOrigins: ReadonlyArray<CountEntry>;
+    };
+    /** From `policy_decision` (policy-engine writes deny/audit-and-allow). */
+    readonly policy: {
+        readonly decisions: number;
+        readonly denied: number;
+        readonly auditAndAllow: number;
+        readonly topDeniedTools: ReadonlyArray<CountEntry>;
+    };
+    /** Durable block-tier residue scanned out of session event logs. HEURISTIC
+     *  (best-effort) by construction: the markers live in `tool_result`
+     *  content, which any malicious tool output can forge — these counters can
+     *  be inflated (never the audit-derived ones above). Strings in here are
+     *  sanitized at parse time; see the module header's trust-boundary note. */
+    readonly sessions: {
+        readonly scanned: number;
+        readonly justificationDenials: number;
+        readonly egressBlocks: number;
+        readonly hookBlocks: number;
+        readonly injectionRedactions: number;
+        /** Rule-id hit counts parsed from redaction notices, ranked. */
+        readonly injectionRuleHits: ReadonlyArray<CountEntry>;
+    };
+};
+/**
+ * Neutralize a string parsed out of stored session/audit content before it
+ * enters the digest (adversarial-review F1). Session `tool_result` content
+ * is attacker-reachable — a malicious tool output can embed ANSI escape
+ * sequences (rewrite the operator's terminal, forge "ALL CLEAR" lines) or
+ * newlines (inject whole fake report lines) into anything the text renderer
+ * prints raw. Applied at PARSE time so text, JSON, HTML and the --notify
+ * payload all carry only sanitized values: strips C0/C1 control characters
+ * (including ESC and line breaks) and clamps the length.
+ */
+export declare function sanitizeContentString(value: string, maxLength?: number): string;
+/**
+ * Walk `<rootDir>/.crewhaus/audit` + `<rootDir>/.crewhaus/sessions` and
+ * build the windowed rollup. Missing stores yield an empty (but complete)
+ * digest — the command is a report, not a gate, so it never throws on an
+ * absent or partially-corrupt store; malformed lines are counted instead.
+ */
+export declare function buildSecurityDigest(opts: {
+    readonly rootDir: string;
+    readonly window: SinceWindow;
+    readonly now?: () => number;
+}): SecurityDigest;
+/** Prefixes the runtime writes into `tool_result` event contents on the
+ *  block tier — the durable residue the session scan keys on. Kept in one
+ *  place so the digest and its tests cite the same literals as
+ *  `@crewhaus/runtime-core`'s denial messages. */
+export declare const SESSION_DENIAL_MARKERS: {
+    readonly justification: "[justification denied]";
+    readonly egress: "[egress denied]";
+    readonly hook: "[blocked by hook]";
+};
+/** Render the digest as the CLI's indented text summary lines. */
+export declare function renderSecurityDigestText(d: SecurityDigest): ReadonlyArray<string>;
+/** Render the digest as a self-contained HTML page (no external assets). */
+export declare function renderSecurityDigestHtml(d: SecurityDigest): string;
+/** Thrown by `notifySecurityDigest` on a malformed URL or non-2xx response.
+ *  The CLI routes it through `die()` — a scheduled digest whose notification
+ *  silently failed would fabricate assurance, so it exits 1 loudly
+ *  (mirroring audit-verify's requested-but-unconsulted-anchor stance). */
+export declare class NotifyError extends Error {
+    readonly name = "NotifyError";
+}
+/**
+ * POST the JSON digest to a webhook. Plain `fetch`, no channel-adapter
+ * dependency (see module header); Slack users wrap the payload — incoming
+ * webhooks accept `{ text }`, not arbitrary JSON.
+ *
+ * A plain-http URL is allowed (local tunnels/dev receivers) but warned about
+ * on stderr (adversarial-review F3): the digest is security telemetry —
+ * denial counts, tool names, judge reasons — and posting it cleartext leaks
+ * it to every on-path observer. `warn` is injectable for tests.
+ */
+export declare function notifySecurityDigest(url: string, digest: SecurityDigest, fetchImpl?: typeof fetch, warn?: (line: string) => void): Promise<void>;