@connexum/ai-governance 1.0.0-beta.11

package/dist/esm/security/anomaly-self-reflection.js

@@ -0,0 +1,292 @@
+/**
+ * SelfReflectionLoopDetector -- Anomaly detection for runaway self-reflection cycles.
+ *
+ * A self-reflecting agent (Tier 1, Agent Type Coverage Strategy) inspects its own
+ * output, decides it is not good enough, regenerates, and inspects again. Without
+ * bounds this loops indefinitely, burning tokens and never converging.
+ *
+ * Detection criteria (all configurable):
+ *   1. N consecutive (output -> self-check -> regenerate) triplets within windowMs.
+ *   2. Jaccard similarity on 5-gram shingles between successive 'output' entries
+ *      >= similarityThreshold: agent is stuck, not improving (non-converging).
+ *   3. Absolute output count (PT-REFLECT-LOOP-2): any cycle exceeding maxOutputCount
+ *      text-bearing entries fires regardless of action-type label.
+ *
+ * Similarity computation:
+ *   We compare successive 'output'-kind entries only (not 'regenerate' vs 'output'
+ *   within the same triplet, which would be trivially identical). This measures
+ *   whether each new primary output differs from the previous primary output.
+ *
+ * On detection:
+ *   - Emits SELF_REFLECTION_LOOP audit event via AuditIntegrity (chained SHA-256).
+ *   - Calls CircuitBreaker.recordFailure() to escalate toward OPEN state.
+ *   - Does NOT terminate the cycle directly -- composition over duplication.
+ *
+ * Pack-binding invariant:
+ *   recordAction() throws if packBinding is empty (UnboundDataError equivalent).
+ *
+ * BUILD_PLAN V3 line 258: anomaly detection for self-reflection loops.
+ *
+ * Similarity metric: Jaccard on 5-gram character shingles.
+ *   Rationale: fast, zero external dependencies, and robust to minor surface
+ *   variation (whitespace, punctuation) that would fool simpler equality checks.
+ *   Cosine similarity requires vector embeddings -- explicitly out of scope.
+ *
+ * @connexum/ai-governance
+ */
+import * as crypto from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Detector
+// ---------------------------------------------------------------------------
+export class SelfReflectionLoopDetector {
+    tripletThreshold;
+    windowMs;
+    similarityThreshold;
+    maxOutputCount;
+    circuitBreaker;
+    auditIntegrity;
+    /**
+     * Ring buffer: cycleId -> ordered list of recent actions.
+     * Cleared by clearCycle() when the cycle ends.
+     */
+    buffer = new Map();
+    /** Detection log (capped at 500) for inspection by tests and operators. */
+    detectionLog = [];
+    constructor(config) {
+        this.circuitBreaker = config.circuitBreaker;
+        this.auditIntegrity = config.auditIntegrity;
+        this.tripletThreshold = config.tripletThreshold ?? 5;
+        this.windowMs = config.windowMs ?? 60_000;
+        this.similarityThreshold = config.similarityThreshold ?? 0.85;
+        this.maxOutputCount = config.maxOutputCount ?? this.tripletThreshold * 3;
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Record an action in a cycle's ring buffer and check for loop patterns.
+     *
+     * @throws {Error} if packBinding is empty (UnboundDataError guard).
+     */
+    recordAction(orgId, agentId, cycleId, action, packBinding) {
+        if (!packBinding || packBinding.length === 0) {
+            throw new Error(`[SelfReflectionLoopDetector] UnboundDataError: packBinding must not be empty. ` +
+                `orgId=${orgId} agentId=${agentId} cycleId=${cycleId}`);
+        }
+        const nowMs = Date.now();
+        const textHash = action.text ? hashText(action.text) : '';
+        const shingles = action.text ? computeShingles(action.text) : new Set();
+        const entry = {
+            kind: action.kind,
+            textHash,
+            shingles,
+            verdict: action.verdict,
+            timestampMs: nowMs,
+            orgId,
+            agentId,
+            packBinding,
+        };
+        // Retrieve or create ring buffer for this cycle
+        if (!this.buffer.has(cycleId)) {
+            this.buffer.set(cycleId, []);
+        }
+        const ring = this.buffer.get(cycleId);
+        ring.push(entry);
+        // Purge entries outside window
+        const cutoff = nowMs - this.windowMs;
+        while (ring.length > 0 && ring[0].timestampMs < cutoff) {
+            ring.shift();
+        }
+        // Run detection
+        return this.checkPattern(orgId, agentId, cycleId, ring, packBinding);
+    }
+    /**
+     * Release the ring buffer for a completed cycle.
+     * Call this when the cycle ends (success or failure).
+     */
+    clearCycle(cycleId) {
+        this.buffer.delete(cycleId);
+    }
+    /**
+     * Get the detection log (read-only copy).
+     */
+    getDetectionLog() {
+        return [...this.detectionLog];
+    }
+    /**
+     * Get the current ring-buffer size across all active cycles.
+     * Useful for memory leak detection tests.
+     */
+    activeBufferCount() {
+        return this.buffer.size;
+    }
+    // -------------------------------------------------------------------------
+    // Pattern detection
+    // -------------------------------------------------------------------------
+    checkPattern(orgId, agentId, cycleId, ring, packBinding) {
+        // -- Guard: PT-REFLECT-LOOP-2 absolute output count (label-spoofing) -----
+        // Count any action in the ring that has text (regardless of label).
+        const textEntries = ring.filter(e => e.textHash !== '');
+        if (textEntries.length >= this.maxOutputCount) {
+            // For similarity: prefer 'output'-kind consecutive pairs; fall back to any text pairs.
+            const similarity = computeCrossIterationSimilarity(ring);
+            return this.fireDetection(orgId, agentId, cycleId, this.tripletThreshold, similarity, packBinding);
+        }
+        // -- Primary triplet pattern: output -> self-check(regenerate) -> regenerate --
+        const tripletCount = countTriplets(ring);
+        if (tripletCount < this.tripletThreshold) {
+            return null;
+        }
+        // Compute similarity between successive 'output'-kind entries.
+        // We compare output(i-1) vs output(i) across triplet boundaries,
+        // NOT within-triplet (output(i) vs regenerate(i)) which would trivially be 1.0.
+        const similarity = computeCrossIterationSimilarity(ring);
+        return this.fireDetection(orgId, agentId, cycleId, tripletCount, similarity, packBinding);
+    }
+    fireDetection(orgId, agentId, cycleId, tripletCount, similarity, packBinding) {
+        const detectedAt = new Date().toISOString();
+        const convergenceState = similarity >= this.similarityThreshold ? 'non-converging' : 'evolving';
+        const payload = { orgId, agentId, cycleId, tripletCount, similarity, convergenceState, detectedAt, packBinding };
+        const contentHash = crypto
+            .createHash('sha256')
+            .update(JSON.stringify(payload))
+            .digest('hex');
+        const detection = { ...payload, contentHash };
+        // Append to internal log (capped)
+        this.detectionLog.push(detection);
+        if (this.detectionLog.length > 500) {
+            this.detectionLog.shift();
+        }
+        // Emit to audit chain (hash only -- never raw text)
+        this.emitAuditEvent(detection);
+        // Escalate via CircuitBreaker
+        this.circuitBreaker.recordFailure(`SELF_REFLECTION_LOOP detected: agentId=${agentId} cycleId=${cycleId} ` +
+            `triplets=${tripletCount} convergence=${convergenceState} similarity=${similarity.toFixed(3)}`);
+        process.stderr.write(`[SelfReflectionLoopDetector] SELF_REFLECTION_LOOP: orgId=${orgId} agentId=${agentId} ` +
+            `cycleId=${cycleId} triplets=${tripletCount} similarity=${similarity.toFixed(3)} ` +
+            `convergence=${convergenceState} hash=${contentHash}\n`);
+        return detection;
+    }
+    emitAuditEvent(detection) {
+        const eventData = {
+            type: 'SELF_REFLECTION_LOOP',
+            severity: 'ERROR',
+            orgId: detection.orgId,
+            agentId: detection.agentId,
+            cycleId: detection.cycleId,
+            tripletCount: detection.tripletCount,
+            similarity: detection.similarity,
+            convergenceState: detection.convergenceState,
+            packBinding: detection.packBinding,
+            contentHash: detection.contentHash,
+            timestamp: detection.detectedAt,
+            // Raw output text is NEVER logged -- only hashes are recorded
+        };
+        if (this.auditIntegrity) {
+            try {
+                this.auditIntegrity.append(eventData);
+            }
+            catch (err) {
+                process.stderr.write(`[SelfReflectionLoopDetector] Audit chain write failed: ${err.message}\n`);
+            }
+        }
+        else {
+            // Fallback: structured stderr (still captures prevHash concept via contentHash)
+            process.stderr.write(`[AUDIT] SELF_REFLECTION_LOOP ${JSON.stringify(eventData)}\n`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Triplet counting
+// ---------------------------------------------------------------------------
+/**
+ * Walk the ring left-to-right and count consecutive
+ * (output -> self-check[verdict='regenerate'] -> regenerate) triplets.
+ */
+function countTriplets(ring) {
+    let count = 0;
+    let i = 0;
+    while (i + 2 < ring.length) {
+        const a = ring[i];
+        const b = ring[i + 1];
+        const c = ring[i + 2];
+        if (a.kind === 'output' &&
+            b.kind === 'self-check' &&
+            b.verdict?.toLowerCase().includes('regenerate') &&
+            c.kind === 'regenerate') {
+            count++;
+            i += 3; // Advance past this triplet
+        }
+        else {
+            i++;
+        }
+    }
+    return count;
+}
+// ---------------------------------------------------------------------------
+// Cross-iteration similarity
+// ---------------------------------------------------------------------------
+/**
+ * Compute Jaccard similarity between the last two successive 'output'-kind entries.
+ *
+ * We specifically compare 'output' entries from adjacent triplets (not 'regenerate'
+ * within the same triplet against the prior 'output', which would trivially be 1.0
+ * if both use the same source text). This measures whether the agent's primary
+ * output is actually improving across self-check cycles.
+ *
+ * Falls back to any consecutive text-bearing pair if fewer than two 'output' entries
+ * are available.
+ */
+function computeCrossIterationSimilarity(ring) {
+    // Prefer output-kind entries (canonical primary outputs)
+    const outputEntries = ring.filter(e => e.kind === 'output' && e.textHash !== '');
+    if (outputEntries.length >= 2) {
+        return jaccardSimilarity(outputEntries[outputEntries.length - 2].shingles, outputEntries[outputEntries.length - 1].shingles);
+    }
+    // Fall back to any text-bearing entries
+    const textEntries = ring.filter(e => e.textHash !== '');
+    if (textEntries.length >= 2) {
+        return jaccardSimilarity(textEntries[textEntries.length - 2].shingles, textEntries[textEntries.length - 1].shingles);
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Jaccard similarity on 5-gram character shingles
+// ---------------------------------------------------------------------------
+const SHINGLE_SIZE = 5;
+/**
+ * Compute 5-gram character shingle set for a text string.
+ * Normalises whitespace to single spaces before shingling.
+ */
+export function computeShingles(text) {
+    // Normalise: lowercase, collapse whitespace
+    const normalised = text.toLowerCase().replace(/\s+/g, ' ').trim();
+    const shingles = new Set();
+    for (let i = 0; i <= normalised.length - SHINGLE_SIZE; i++) {
+        shingles.add(normalised.slice(i, i + SHINGLE_SIZE));
+    }
+    return shingles;
+}
+/**
+ * Compute Jaccard similarity between two shingle sets.
+ * J(A, B) = |A intersect B| / |A union B|
+ * Returns 0 when both sets are empty.
+ */
+export function jaccardSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const s of a) {
+        if (b.has(s))
+            intersection++;
+    }
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+// ---------------------------------------------------------------------------
+// SHA-256 text fingerprint (never log raw text)
+// ---------------------------------------------------------------------------
+function hashText(text) {
+    return crypto.createHash('sha256').update(text).digest('hex');
+}
+//# sourceMappingURL=anomaly-self-reflection.js.map

package/dist/esm/security/anomaly-self-reflection.js.map

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

package/dist/esm/security/built-in-llm-providers.js

@@ -0,0 +1,80 @@
+/**
+ * built-in-llm-providers.ts
+ *
+ * Canonical hostname allow-list for all LLM provider adapters shipped with
+ * @connexum/ai-governance.  The RawHttpInterceptor uses this as its default
+ * allow-list so that calls made through the official SDK adapters pass through
+ * without triggering the unknown-host policy.
+ *
+ * Rules:
+ *   - Exact domain matching.  Sub-domains must be listed separately unless
+ *     the suffix matcher is used (entries prefixed with a leading dot ".").
+ *   - A leading "." means "this domain and any sub-domain".  For example
+ *     ".amazonaws.com" matches "bedrock-runtime.us-east-1.amazonaws.com".
+ *   - Ollama runs on localhost and is intentionally excluded.  It is
+ *     registered via addAllowedOrigin() at the application level because the
+ *     base URL is user-configurable.
+ *
+ * @connexum/ai-governance
+ */
+// ---------------------------------------------------------------------------
+// Canonical list
+// ---------------------------------------------------------------------------
+/**
+ * Built-in LLM provider records derived from every adapter in
+ * src/llm-adapters/.
+ *
+ * Adapter files:
+ *   claude.ts        -> api.anthropic.com
+ *   openai.ts        -> api.openai.com
+ *   gemini.ts        -> generativelanguage.googleapis.com
+ *   google.ts        -> aiplatform.googleapis.com (Vertex AI, sub-domain per region)
+ *   azure-openai.ts  -> *.openai.azure.com (sub-domain per Azure resource)
+ *   bedrock.ts       -> bedrock-runtime.*.amazonaws.com (sub-domain per region)
+ *   ollama.ts        -> excluded (loopback, user-configurable)
+ */
+export const BUILT_IN_LLM_PROVIDERS = [
+    {
+        name: 'Anthropic (Claude)',
+        hosts: ['api.anthropic.com'],
+        adapterFile: 'claude.ts',
+    },
+    {
+        name: 'OpenAI',
+        hosts: ['api.openai.com'],
+        adapterFile: 'openai.ts',
+    },
+    {
+        name: 'Google Generative Language (Gemini)',
+        hosts: ['generativelanguage.googleapis.com'],
+        adapterFile: 'gemini.ts',
+    },
+    {
+        name: 'Google Vertex AI (aiplatform)',
+        // Regional sub-domains: <region>-aiplatform.googleapis.com
+        hosts: ['.googleapis.com'],
+        adapterFile: 'google.ts',
+    },
+    {
+        name: 'Azure OpenAI',
+        // Resource-specific sub-domains: <resource>.openai.azure.com
+        hosts: ['.openai.azure.com'],
+        adapterFile: 'azure-openai.ts',
+    },
+    {
+        name: 'AWS Bedrock',
+        // Regional sub-domains: bedrock-runtime.<region>.amazonaws.com
+        hosts: ['.amazonaws.com'],
+        adapterFile: 'bedrock.ts',
+    },
+];
+// ---------------------------------------------------------------------------
+// Flat hostname set (used internally by RawHttpInterceptor)
+// ---------------------------------------------------------------------------
+/**
+ * Flat array of all host entries across all built-in providers.
+ * Returned as-is; the interceptor applies suffix semantics for "." prefixes.
+ */
+export const BUILT_IN_LLM_HOSTNAMES = BUILT_IN_LLM_PROVIDERS
+    .flatMap((p) => p.hosts);
+//# sourceMappingURL=built-in-llm-providers.js.map

package/dist/esm/security/built-in-llm-providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"built-in-llm-providers.js","sourceRoot":"","sources":["../../../src/security/built-in-llm-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkBH,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAiC;IAClE;QACE,IAAI,EAAE,oBAAoB;QAC1B,KAAK,EAAE,CAAC,mBAAmB,CAAC;QAC5B,WAAW,EAAE,WAAW;KACzB;IACD;QACE,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,CAAC,gBAAgB,CAAC;QACzB,WAAW,EAAE,WAAW;KACzB;IACD;QACE,IAAI,EAAE,qCAAqC;QAC3C,KAAK,EAAE,CAAC,mCAAmC,CAAC;QAC5C,WAAW,EAAE,WAAW;KACzB;IACD;QACE,IAAI,EAAE,+BAA+B;QACrC,2DAA2D;QAC3D,KAAK,EAAE,CAAC,iBAAiB,CAAC;QAC1B,WAAW,EAAE,WAAW;KACzB;IACD;QACE,IAAI,EAAE,cAAc;QACpB,6DAA6D;QAC7D,KAAK,EAAE,CAAC,mBAAmB,CAAC;QAC5B,WAAW,EAAE,iBAAiB;KAC/B;IACD;QACE,IAAI,EAAE,aAAa;QACnB,+DAA+D;QAC/D,KAAK,EAAE,CAAC,gBAAgB,CAAC;QACzB,WAAW,EAAE,YAAY;KAC1B;CACO,CAAC;AAEX,8EAA8E;AAC9E,4DAA4D;AAC5D,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsB,sBAAsB;KAC5E,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAiB,CAAC,CAAC"}

package/dist/esm/security/circuit-breaker.js

@@ -0,0 +1,146 @@
+/**
+ * CircuitBreaker -- Prevents cascading agent failures.
+ * OWASP ASI08 remediation.
+ *
+ * States:
+ *   CLOSED  - Normal operation. Failures tracked but below threshold.
+ *   OPEN    - Agent suspended. All operations blocked.
+ *   HALF    - Probationary. One test cycle allowed.
+ *
+ * @connexum/ai-governance
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export class CircuitBreaker {
+    stateFile;
+    failureThreshold;
+    halfOpenAfterMs;
+    agentName;
+    constructor(config) {
+        this.agentName = config.agentName;
+        this.failureThreshold = config.failureThreshold ?? 3;
+        this.halfOpenAfterMs = config.halfOpenAfterMs ?? 10 * 60 * 1000;
+        if (!fs.existsSync(config.stateDir)) {
+            fs.mkdirSync(config.stateDir, { recursive: true });
+        }
+        this.stateFile = path.join(config.stateDir, `circuit-${config.agentName}.json`);
+    }
+    /**
+     * Check if the agent is allowed to execute.
+     */
+    allowExecution() {
+        const state = this.loadState();
+        switch (state.state) {
+            case 'CLOSED':
+                return true;
+            case 'OPEN': {
+                // Check if enough time has passed for half-open
+                if (state.openedAt) {
+                    const elapsed = Date.now() - new Date(state.openedAt).getTime();
+                    if (elapsed >= this.halfOpenAfterMs) {
+                        state.state = 'HALF_OPEN';
+                        this.saveState(state);
+                        return true;
+                    }
+                }
+                return false;
+            }
+            case 'HALF_OPEN':
+                return true;
+            default:
+                return false;
+        }
+    }
+    /**
+     * Record a successful operation.
+     */
+    recordSuccess() {
+        const state = this.loadState();
+        state.consecutiveFailures = 0;
+        state.lastSuccess = new Date().toISOString();
+        state.totalSuccesses++;
+        if (state.state === 'HALF_OPEN') {
+            state.state = 'CLOSED';
+            state.openedAt = null;
+        }
+        this.saveState(state);
+    }
+    /**
+     * Record a failed operation.
+     */
+    recordFailure(reason) {
+        const state = this.loadState();
+        state.consecutiveFailures++;
+        state.lastFailure = new Date().toISOString();
+        state.totalFailures++;
+        if (state.state === 'HALF_OPEN') {
+            // Failed during probation -- back to OPEN
+            state.state = 'OPEN';
+            state.openedAt = new Date().toISOString();
+        }
+        else if (state.consecutiveFailures >= this.failureThreshold) {
+            state.state = 'OPEN';
+            state.openedAt = new Date().toISOString();
+        }
+        this.saveState(state);
+    }
+    /**
+     * Get current state (read-only).
+     */
+    getState() {
+        return this.loadState();
+    }
+    /**
+     * Manually reset circuit breaker to CLOSED.
+     * Only for human operator use.
+     */
+    reset() {
+        const state = this.loadState();
+        state.state = 'CLOSED';
+        state.consecutiveFailures = 0;
+        state.openedAt = null;
+        this.saveState(state);
+    }
+    loadState() {
+        if (!fs.existsSync(this.stateFile)) {
+            return {
+                state: 'CLOSED',
+                consecutiveFailures: 0,
+                lastFailure: null,
+                lastSuccess: null,
+                openedAt: null,
+                totalFailures: 0,
+                totalSuccesses: 0,
+            };
+        }
+        try {
+            return JSON.parse(fs.readFileSync(this.stateFile, 'utf-8'));
+        }
+        catch {
+            return {
+                state: 'CLOSED',
+                consecutiveFailures: 0,
+                lastFailure: null,
+                lastSuccess: null,
+                openedAt: null,
+                totalFailures: 0,
+                totalSuccesses: 0,
+            };
+        }
+    }
+    saveState(state) {
+        try {
+            fs.writeFileSync(this.stateFile, JSON.stringify(state, null, 2));
+        }
+        catch (err) {
+            // State save failure is critical -- a suspended agent could resume on restart
+            process.stderr.write(`[CIRCUIT BREAKER CRITICAL] Failed to save state for ${this.agentName}: ${err.message}\n`);
+            // Fail-closed: if we can't persist the OPEN state, throw so caller knows
+            if (state.state === 'OPEN') {
+                throw new Error(`Failed to persist OPEN circuit state for ${this.agentName}. ` +
+                    `Agent may resume unsafely on restart.`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/esm/security/circuit-breaker.js.map

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