@aegis-scan/core 0.16.6 → 0.18.0

package/dist/runtime/chain.js

@@ -0,0 +1,156 @@
+/**
+ * Hash-chained event emitter + chain verifier.
+ *
+ * Closes APTS-AR-012 (Tamper-Evident Logging with Hash Chains) +
+ * APTS-AL-005 (Mandatory Logging + Human-Reviewable Audit Trail).
+ *
+ * Each emitted event carries:
+ *   - prev_hash: hash of the immediately-preceding event (null on first)
+ *   - this_hash: SHA-256 of this event's canonical form (excluding this_hash)
+ *
+ * Verification: re-canonicalize each event without this_hash, recompute
+ * the hash, compare against this_hash. Compare prev_hash with the
+ * previous event's this_hash. Any tamper anywhere in the chain breaks
+ * verification at that line.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { emitEvent } from './events.js';
+import { hashCanonical } from './hash.js';
+/**
+ * Stateful emitter that maintains the running prev_hash → this_hash chain.
+ * Each `emit` call pours the chain forward by one link. The current chain
+ * tail is exposed via `getTail()` so a resume operation can pick up where
+ * the prior session left off.
+ */
+export class ChainedEmitter {
+    opts;
+    prevHash;
+    constructor(opts) {
+        this.opts = opts;
+        this.prevHash = opts.initialPrevHash ?? null;
+    }
+    emit(event) {
+        // Build the chained event. Strip any caller-supplied this_hash —
+        // the emitter is the sole source of truth for the hash field.
+        const { this_hash: _ignored, ...rest } = event;
+        void _ignored;
+        const withPrev = { ...rest, prev_hash: this.prevHash };
+        // Hash without this_hash so the field can't be part of its own preimage.
+        const this_hash = hashCanonical(withPrev);
+        const final = { ...withPrev, this_hash };
+        emitEvent(final, this.opts.sink);
+        this.prevHash = this_hash;
+        return final;
+    }
+    getTail() {
+        return this.prevHash;
+    }
+}
+/**
+ * Verify the integrity of a JSONL audit-log file. Each EVENT line must:
+ *   - parse as JSON
+ *   - carry this_hash + prev_hash fields
+ *   - have a this_hash that matches the canonical hash of its other fields
+ *   - have a prev_hash that matches the previous line's this_hash (null on line 0)
+ *
+ * Snapshot lines (those with `state_version` but no `event` field) are
+ * SKIPPED — they exist alongside events in the same JSONL file (audit-fix
+ * 2026-04-27 made writeEngagementState append-not-overwrite).
+ *
+ * KNOWN SCOPE LIMIT (audit-fix-2 2026-04-27):
+ *   Snapshot lines are NOT part of the hash chain. An attacker with
+ *   write access to the state-file can post-hoc tamper with snapshot
+ *   fields (`completed_phases`, `findings_so_far`, `paused_at`,
+ *   `reason`) without breaking chain verification. The EVENT timeline
+ *   remains tamper-evident — every state transition emits an event,
+ *   so a tampered snapshot is contradicted by the unchanged event
+ *   stream. Resume-from-snapshot consumers MUST cross-check snapshot
+ *   contents against the event chain before trusting them. Closing
+ *   this gap fully would require chaining snapshot writes through
+ *   ChainedEmitter (snapshot becomes an event with prev_hash +
+ *   this_hash); deferred to a future cluster.
+ *
+ * Returns ok-with-tail-hash on success, or failure-at-line-N with reason.
+ */
+export function verifyAuditChain(path) {
+    if (!existsSync(path)) {
+        return { ok: false, error: `audit-log not found at ${path}`, broken_at: 0, total_events_processed: 0 };
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `audit-log unreadable at ${path}: ${err instanceof Error ? err.message : String(err)}`,
+            broken_at: 0,
+            total_events_processed: 0,
+        };
+    }
+    const lines = raw.split(/\r?\n/).filter((line) => line.trim().length > 0);
+    let prevExpectedHash = null;
+    let eventsProcessed = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: `line ${i}: not valid JSON (${err instanceof Error ? err.message : String(err)})`,
+                broken_at: i,
+                total_events_processed: eventsProcessed,
+            };
+        }
+        // Skip snapshot lines — they have state_version but no event.
+        if ('state_version' in parsed && !('event' in parsed)) {
+            continue;
+        }
+        const lineThisHash = parsed.this_hash;
+        const linePrevHash = parsed.prev_hash;
+        if (typeof lineThisHash !== 'string') {
+            return {
+                ok: false,
+                error: `line ${i}: missing or non-string this_hash`,
+                broken_at: i,
+                total_events_processed: eventsProcessed,
+            };
+        }
+        if (linePrevHash !== null && typeof linePrevHash !== 'string') {
+            return {
+                ok: false,
+                error: `line ${i}: prev_hash must be string or null`,
+                broken_at: i,
+                total_events_processed: eventsProcessed,
+            };
+        }
+        // Recompute the canonical hash of the event without this_hash.
+        const withoutHash = { ...parsed };
+        delete withoutHash.this_hash;
+        const recomputed = hashCanonical(withoutHash);
+        if (recomputed !== lineThisHash) {
+            return {
+                ok: false,
+                error: `line ${i}: this_hash mismatch (event tampered or canonicalization mismatch)`,
+                broken_at: i,
+                total_events_processed: eventsProcessed,
+            };
+        }
+        // Check the chain link to the previous event.
+        if ((linePrevHash ?? null) !== prevExpectedHash) {
+            return {
+                ok: false,
+                error: `line ${i}: prev_hash chain break (expected ${prevExpectedHash ?? 'null'}, got ${linePrevHash ?? 'null'})`,
+                broken_at: i,
+                total_events_processed: eventsProcessed,
+            };
+        }
+        prevExpectedHash = lineThisHash;
+        eventsProcessed += 1;
+    }
+    return { ok: true, total_events: eventsProcessed, tail_hash: prevExpectedHash };
+}
+//# sourceMappingURL=chain.js.map

package/dist/runtime/chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.js","sourceRoot":"","sources":["../../src/runtime/chain.ts"],"names":[],"mappings":"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"}

package/dist/runtime/events.d.ts

@@ -0,0 +1,104 @@
+import type { Finding, Severity } from '../types.js';
+export interface EngagementEventBase {
+    ts: string;
+    engagement_id: string;
+    event: string;
+    /** Hash of the previous event in the chain. null on the first event. */
+    prev_hash?: string | null;
+    /** SHA-256 of this event's canonical form (excluding this_hash itself). */
+    this_hash?: string;
+}
+export type EngagementEvent = (EngagementEventBase & {
+    event: 'engagement-start';
+    target: string;
+    roe_id: string;
+    roe_synthesized: boolean;
+    mode: string;
+}) | (EngagementEventBase & {
+    event: 'phase-transition';
+    phase: 'recon' | 'discovery' | 'exploitation' | 'reporting';
+    transition: 'enter' | 'exit';
+    duration_ms?: number;
+}) | (EngagementEventBase & {
+    event: 'finding-emitted';
+    finding_id: string;
+    severity: Severity;
+    title: string;
+    cwe?: number;
+    /** SHA-256 of the finding's canonical form (APTS-AR-010). */
+    evidence_hash?: string;
+}) | (EngagementEventBase & {
+    event: 'critical-finding';
+    finding_id: string;
+    severity: Severity;
+    title: string;
+    cwe?: number;
+    stop_action: 'halt' | 'notify-and-continue' | 'continue';
+}) | (EngagementEventBase & {
+    event: 'intervention';
+    kind: 'pause' | 'redirect' | 'kill';
+    trigger: 'signal-SIGUSR1' | 'signal-SIGTERM' | 'signal-SIGINT' | 'api';
+    reason?: string;
+}) | (EngagementEventBase & {
+    event: 'resume';
+    from_state_file: string;
+    completed_phases: string[];
+    findings_carried: number;
+}) | (EngagementEventBase & {
+    event: 'halt';
+    reason: string;
+    apts_refs?: string[];
+}) | (EngagementEventBase & {
+    event: 'kill';
+    signal: 'SIGTERM' | 'SIGINT' | 'SIGUSR2';
+    state_dump_path?: string;
+}) | (EngagementEventBase & {
+    event: 'completion';
+    duration_ms: number;
+    total_findings: number;
+    score: number;
+    grade: string;
+    blocked: boolean;
+}) | (EngagementEventBase & {
+    event: 'scope-validation';
+    target: string;
+    action: string;
+    allowed: boolean;
+    reason: string;
+    apts_refs?: string[];
+}) | (EngagementEventBase & {
+    event: 'operator-acknowledged-loopback';
+    target: string;
+    apts_refs: string[];
+    warning: string;
+});
+/**
+ * Emit an engagement event to a sink. The sink can be:
+ *   - undefined → stdout (default; siege already writes to stdout for the
+ *     human-readable spinner; emitting JSONL there is risky because the
+ *     terminal user would see noisy lines. So we only emit JSONL when an
+ *     explicit state-file path is configured.)
+ *   - a file path → append the JSON line to that file.
+ *   - a callback → in-process consumer (used by tests).
+ */
+export type EventSink = string | ((event: EngagementEvent) => void) | undefined;
+export declare function emitEvent(event: EngagementEvent, sink: EventSink): void;
+export declare function makeEvent<T extends EngagementEvent['event']>(engagementId: string, event: T, payload: Omit<Extract<EngagementEvent, {
+    event: T;
+}>, 'ts' | 'engagement_id' | 'event'>): Extract<EngagementEvent, {
+    event: T;
+}>;
+/**
+ * Helper: turn a Finding into a finding-emitted event. Caller decides
+ * whether to also emit a critical-finding event for high/critical/blocker
+ * severities. Includes evidence_hash (SHA-256 of finding's canonical form)
+ * per APTS-AR-010.
+ */
+export declare function findingEvent(engagementId: string, f: Finding): EngagementEvent;
+export declare function isCriticalSeverity(s: Severity): boolean;
+/**
+ * Initialize a state-file: ensure it's empty / not appended onto a stale
+ * run. Caller invokes this at engagement start when --state-file is set.
+ */
+export declare function initStateFile(path: string): void;
+//# sourceMappingURL=events.d.ts.map

package/dist/runtime/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/runtime/events.ts"],"names":[],"mappings":"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"}

package/dist/runtime/events.js

@@ -0,0 +1,68 @@
+/**
+ * Engagement event schema (JSONL).
+ *
+ * Closes APTS-HO-002 (Real-Time Monitoring and Intervention Capability) +
+ * APTS-AR-002 (State Transition Logging — partial closure pending Cluster-3
+ * hash-chain). Each event is one JSON line, written to stdout (default) or
+ * a state-file (when --state-file is set on siege).
+ *
+ * Event types:
+ *   - engagement-start                  — emitted when siege begins (after RoE validated)
+ *   - phase-transition                  — emitted before/after each of the 4 siege phases
+ *   - finding-emitted                   — per-finding event so live monitors can react
+ *   - critical-finding                  — high-severity emission, drives stop-conditions
+ *   - intervention                      — operator pause/redirect/kill received via signal
+ *   - resume                            — engagement re-started from a serialized state file
+ *   - halt                              — engagement stopped (clean termination)
+ *   - kill                              — engagement aborted (signal-triggered)
+ *   - completion                        — engagement finished, final scoring emitted
+ *   - scope-validation                  — target in/out of scope decision (APTS-SE-015)
+ *   - operator-acknowledged-loopback    — operator opted in to loopback target (--allow-loopback)
+ */
+import { writeFileSync, appendFileSync } from 'node:fs';
+import { hashCanonical } from './hash.js';
+export function emitEvent(event, sink) {
+    if (sink === undefined)
+        return;
+    if (typeof sink === 'function') {
+        sink(event);
+        return;
+    }
+    // sink is a file path. Append JSONL — one JSON object per line.
+    appendFileSync(sink, JSON.stringify(event) + '\n');
+}
+export function makeEvent(engagementId, event, payload) {
+    return {
+        ts: new Date().toISOString(),
+        engagement_id: engagementId,
+        event,
+        ...payload,
+    };
+}
+/**
+ * Helper: turn a Finding into a finding-emitted event. Caller decides
+ * whether to also emit a critical-finding event for high/critical/blocker
+ * severities. Includes evidence_hash (SHA-256 of finding's canonical form)
+ * per APTS-AR-010.
+ */
+export function findingEvent(engagementId, f) {
+    const evidence_hash = hashCanonical(f);
+    return makeEvent(engagementId, 'finding-emitted', {
+        finding_id: f.id,
+        severity: f.severity,
+        title: f.title,
+        ...(f.cwe !== undefined ? { cwe: f.cwe } : {}),
+        evidence_hash,
+    });
+}
+export function isCriticalSeverity(s) {
+    return s === 'blocker' || s === 'critical' || s === 'high';
+}
+/**
+ * Initialize a state-file: ensure it's empty / not appended onto a stale
+ * run. Caller invokes this at engagement start when --state-file is set.
+ */
+export function initStateFile(path) {
+    writeFileSync(path, '');
+}
+//# sourceMappingURL=events.js.map

package/dist/runtime/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/runtime/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAExD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAmG1C,MAAM,UAAU,SAAS,CAAC,KAAsB,EAAE,IAAe;IAC/D,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO;IAC/B,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,CAAC;QACZ,OAAO;IACT,CAAC;IACD,gEAAgE;IAChE,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,YAAoB,EACpB,KAAQ,EACR,OAAuF;IAEvF,OAAO;QACL,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,aAAa,EAAE,YAAY;QAC3B,KAAK;QACL,GAAG,OAAO;KAC0C,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,YAAoB,EAAE,CAAU;IAC3D,MAAM,aAAa,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IACvC,OAAO,SAAS,CAAC,YAAY,EAAE,iBAAiB,EAAE;QAChD,UAAU,EAAE,CAAC,CAAC,EAAE;QAChB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,aAAa;KACd,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,CAAW;IAC5C,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,UAAU,IAAI,CAAC,KAAK,MAAM,CAAC;AAC7D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,aAAa,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAC1B,CAAC"}

package/dist/runtime/hash.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SHA-256 hash of a UTF-8 string, returned as lowercase hex.
+ */
+export declare function sha256(input: string): string;
+/**
+ * Canonicalize an arbitrary JSON-shaped value: sort keys at every depth,
+ * no whitespace, no surprising number formatting. Returns a string suitable
+ * for hashing.
+ */
+export declare function canonicalize(value: unknown): string;
+/**
+ * Hash a JSON-shaped value's canonical form. Convenience wrapper over
+ * sha256(canonicalize(value)).
+ */
+export declare function hashCanonical(value: unknown): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/runtime/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/runtime/hash.ts"],"names":[],"mappings":"AAkBA;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD"}

package/dist/runtime/hash.js

@@ -0,0 +1,70 @@
+/**
+ * Hash + canonical-serialization helpers.
+ *
+ * Closes APTS-AR-010 (Cryptographic Hashing of All Evidence) +
+ * APTS-AR-012 (Tamper-Evident Logging with Hash Chains) jointly with
+ * runtime/chain.ts.
+ *
+ * Design notes:
+ *   - SHA-256 (Node `crypto` module). FIPS 180-4 + RFC 6234.
+ *   - Canonical JSON: sorted keys recursively, no whitespace. Two
+ *     semantically-equal objects always serialize to the same string.
+ *   - The `this_hash` field is excluded from the canonical input — you
+ *     cannot include the hash in its own preimage.
+ *   - Used by both per-event chain (chain.ts) and per-finding evidence
+ *     hash (events.ts findingEvent).
+ */
+import { createHash } from 'node:crypto';
+/**
+ * SHA-256 hash of a UTF-8 string, returned as lowercase hex.
+ */
+export function sha256(input) {
+    return createHash('sha256').update(input, 'utf-8').digest('hex');
+}
+/**
+ * Canonicalize an arbitrary JSON-shaped value: sort keys at every depth,
+ * no whitespace, no surprising number formatting. Returns a string suitable
+ * for hashing.
+ */
+export function canonicalize(value) {
+    return JSON.stringify(canonicalNormalize(value));
+}
+/**
+ * Hash a JSON-shaped value's canonical form. Convenience wrapper over
+ * sha256(canonicalize(value)).
+ */
+export function hashCanonical(value) {
+    return sha256(canonicalize(value));
+}
+/**
+ * Recursively normalize an object so JSON.stringify produces a stable form.
+ * - Plain objects: keys sorted lexicographically; values recursed.
+ * - Arrays: order preserved, elements recursed.
+ * - Primitives + null: returned as-is.
+ * - Undefined values + functions are dropped (matching JSON.stringify's
+ *   own behavior, but here we make it explicit so the canonicalization
+ *   is consistent across runtimes).
+ */
+function canonicalNormalize(value) {
+    if (value === null || value === undefined)
+        return null;
+    const t = typeof value;
+    if (t === 'string' || t === 'boolean' || t === 'number')
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonicalNormalize);
+    if (t === 'object') {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        const out = {};
+        for (const k of keys) {
+            const v = obj[k];
+            if (v === undefined || typeof v === 'function')
+                continue;
+            out[k] = canonicalNormalize(v);
+        }
+        return out;
+    }
+    return null;
+}
+//# sourceMappingURL=hash.js.map

package/dist/runtime/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/runtime/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;GAEG;AACH,MAAM,UAAU,MAAM,CAAC,KAAa;IAClC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACvD,MAAM,CAAC,GAAG,OAAO,KAAK,CAAC;IACvB,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC/D,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnB,MAAM,GAAG,GAAG,KAAgC,CAAC;QAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YACrB,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;YACjB,IAAI,CAAC,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,UAAU;gBAAE,SAAS;YACzD,GAAG,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/runtime/index.d.ts

@@ -0,0 +1,7 @@
+export { emitEvent, makeEvent, findingEvent, isCriticalSeverity, initStateFile, type EngagementEvent, type EngagementEventBase, type EventSink, } from './events.js';
+export { EngagementStateSchema, writeEngagementState, loadEngagementState, newEngagementState, type EngagementState, type LoadStateResult, type LoadStateOk, type LoadStateFailure, } from './state.js';
+export { installSignalHandlers, type DumpReason, type SignalHandlerOptions, } from './signals.js';
+export { dispatchNotification, type NotificationConfig, } from './notifications.js';
+export { sha256, canonicalize, hashCanonical, } from './hash.js';
+export { ChainedEmitter, verifyAuditChain, type ChainedEmitterOpts, type ChainVerifyResult, type ChainVerifyOk, type ChainVerifyFailure, } from './chain.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,qBAAqB,EACrB,KAAK,UAAU,EACf,KAAK,oBAAoB,GAC1B,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,MAAM,EACN,YAAY,EACZ,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC"}

package/dist/runtime/index.js

@@ -0,0 +1,7 @@
+export { emitEvent, makeEvent, findingEvent, isCriticalSeverity, initStateFile, } from './events.js';
+export { EngagementStateSchema, writeEngagementState, loadEngagementState, newEngagementState, } from './state.js';
+export { installSignalHandlers, } from './signals.js';
+export { dispatchNotification, } from './notifications.js';
+export { sha256, canonicalize, hashCanonical, } from './hash.js';
+export { ChainedEmitter, verifyAuditChain, } from './chain.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,aAAa,GAId,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,GAKnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,qBAAqB,GAGtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,GAErB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,MAAM,EACN,YAAY,EACZ,aAAa,GACd,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,cAAc,EACd,gBAAgB,GAKjB,MAAM,YAAY,CAAC"}

package/dist/runtime/notifications.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Notification dispatcher.
+ *
+ * Closes APTS-HO-015 (Real-Time Activity Monitoring and Multi-Channel
+ * Notification — partial closure: webhook channel only; multi-channel
+ * (Slack/email/PagerDuty) is Cluster-2.5 work).
+ *
+ * Operator declares one or more webhook URLs in the RoE schema (notifications
+ * field) or via the siege --notify-webhook flag. The dispatcher fires
+ * fire-and-forget HTTP POST with the JSONL event payload. Failures are
+ * logged to the same event channel as `notification-failed` events but do
+ * not halt the engagement.
+ */
+import type { EngagementEvent, EventSink } from './events.js';
+export interface NotificationConfig {
+    /** Webhook URLs to POST events to. Operators may set multiple. */
+    webhooks: string[];
+    /** Subset of event types to forward. Defaults to high-signal events. */
+    events?: EngagementEvent['event'][];
+    /** Per-request timeout in ms. Default 5000. */
+    timeoutMs?: number;
+}
+export declare function dispatchNotification(event: EngagementEvent, config: NotificationConfig, eventSink: EventSink, fetcher?: typeof fetch): Promise<void>;
+//# sourceMappingURL=notifications.d.ts.map

package/dist/runtime/notifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/runtime/notifications.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG9D,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wEAAwE;IACxE,MAAM,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;IACpC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAWD,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,kBAAkB,EAC1B,SAAS,EAAE,SAAS,EACpB,OAAO,GAAE,OAAO,KAAa,GAC5B,OAAO,CAAC,IAAI,CAAC,CAkCf"}

package/dist/runtime/notifications.js

@@ -0,0 +1,41 @@
+import { emitEvent, makeEvent } from './events.js';
+const DEFAULT_FORWARDED = [
+    'engagement-start',
+    'critical-finding',
+    'intervention',
+    'halt',
+    'kill',
+    'completion',
+];
+export async function dispatchNotification(event, config, eventSink, fetcher = fetch) {
+    const allowed = config.events ?? DEFAULT_FORWARDED;
+    if (!allowed.includes(event.event))
+        return;
+    const timeoutMs = config.timeoutMs ?? 5000;
+    for (const url of config.webhooks) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetcher(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(event),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                emitEvent(makeEvent(event.engagement_id, 'halt', {
+                    reason: `notification-webhook ${url} returned ${res.status} for event ${event.event} — non-fatal`,
+                }), eventSink);
+            }
+        }
+        catch (err) {
+            emitEvent(makeEvent(event.engagement_id, 'halt', {
+                reason: `notification-webhook ${url} threw for event ${event.event}: ${err instanceof Error ? err.message : String(err)} — non-fatal`,
+            }), eventSink);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=notifications.js.map

package/dist/runtime/notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../src/runtime/notifications.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAWnD,MAAM,iBAAiB,GAA+B;IACpD,kBAAkB;IAClB,kBAAkB;IAClB,cAAc;IACd,MAAM;IACN,MAAM;IACN,YAAY;CACb,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAsB,EACtB,MAA0B,EAC1B,SAAoB,EACpB,UAAwB,KAAK;IAE7B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,IAAI,iBAAiB,CAAC;IACnD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO;IAE3C,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;QAC9D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE;gBAC7B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;gBAC3B,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;gBACZ,SAAS,CACP,SAAS,CAAC,KAAK,CAAC,aAAa,EAAE,MAAM,EAAE;oBACrC,MAAM,EAAE,wBAAwB,GAAG,aAAa,GAAG,CAAC,MAAM,cAAc,KAAK,CAAC,KAAK,cAAc;iBAClG,CAAC,EACF,SAAS,CACV,CAAC;YACJ,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,CACP,SAAS,CAAC,KAAK,CAAC,aAAa,EAAE,MAAM,EAAE;gBACrC,MAAM,EAAE,wBAAwB,GAAG,oBAAoB,KAAK,CAAC,KAAK,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,cAAc;aACtI,CAAC,EACF,SAAS,CACV,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/runtime/signals.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Signal handlers for siege engagements.
+ *
+ * Closes APTS-HO-008 (Immediate Kill Switch with State Dump) +
+ * APTS-AL-012 (Kill Switch and Pause Capability) jointly with state.ts.
+ *
+ * Signal contract:
+ *   - SIGINT  (Ctrl+C)        → kill, dump state, exit code 130
+ *   - SIGTERM (kill <pid>)    → kill, dump state, exit code 143
+ *   - SIGUSR1                 → graceful pause: dump state, exit code 0
+ *                               so the operator can later --resume
+ *   - SIGUSR2                 → reserved for future redirect (no-op v0.1)
+ *
+ * Handlers are installed once per engagement and cleared on completion.
+ * In-process tests can use a synchronous shim to verify the dump-state
+ * callback fires without actually emitting OS signals.
+ */
+import type { EngagementState } from './state.js';
+import type { EventSink } from './events.js';
+import type { ChainedEmitter } from './chain.js';
+export type DumpReason = 'SIGINT' | 'SIGTERM' | 'SIGUSR1' | 'SIGUSR2';
+export interface SignalHandlerOptions {
+    /** Path to write the state-dump on signal. */
+    stateFilePath: string | null;
+    /** Provider of the current engagement state to dump. */
+    getState: () => EngagementState;
+    /** Sink to record the kill/intervention event. Same channel as the JSONL event-stream. */
+    eventSink: EventSink;
+    /** Engagement-id used by emit helpers. */
+    engagementId: string;
+    /**
+     * Optional ChainedEmitter — when provided, the kill/intervention event
+     * is appended to the same hash chain as the regular siege events so
+     * `audit-verify` continues to validate the full timeline. Without this
+     * option, the event is emitted directly via emitEvent (un-chained),
+     * which is the legacy path for back-compat.
+     */
+    chainEmitter?: ChainedEmitter;
+    /**
+     * Optional: process.exit hook (defaults to real process.exit). Tests
+     * inject a no-op to verify the cleanup path without halting the test.
+     */
+    exit?: (code: number) => void;
+    /**
+     * Optional: process.on registrar (defaults to real process.on). Tests
+     * inject an in-memory registrar to drive handler callbacks deterministically.
+     */
+    on?: (signal: string, handler: () => void) => void;
+}
+interface InstalledHandlers {
+    /** Removes all installed signal handlers. Call on engagement completion. */
+    uninstall(): void;
+}
+export declare function installSignalHandlers(opts: SignalHandlerOptions): InstalledHandlers;
+export {};
+//# sourceMappingURL=signals.d.ts.map

package/dist/runtime/signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../../src/runtime/signals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEtE,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,wDAAwD;IACxD,QAAQ,EAAE,MAAM,eAAe,CAAC;IAChC,0FAA0F;IAC1F,SAAS,EAAE,SAAS,CAAC;IACrB,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B;;;OAGG;IACH,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACpD;AAED,UAAU,iBAAiB;IACzB,4EAA4E;IAC5E,SAAS,IAAI,IAAI,CAAC;CACnB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,oBAAoB,GAAG,iBAAiB,CAuEnF"}