monofence-ai 1.0.0

package/README.md

@@ -0,0 +1,276 @@
+# monofence-ai
+
+[![npm version](https://img.shields.io/npm/v/monofence-ai?color=blue&label=npm)](https://www.npmjs.com/package/monofence-ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
+
+**AI manipulation defense for LLM applications** — evasion detection, multi-turn context tracking, output scanning, and hook wiring. Sub-millisecond detection with self-learning.
+
+```
+Detection: ~0.04ms | 50+ patterns | evasion normalization | context-aware escalation
+```
+
+---
+
+## Install
+
+```bash
+npm install monofence-ai
+# or
+pnpm add monofence-ai
+```
+
+Optional — HNSW-accelerated pattern search:
+
+```bash
+npm install lancedb
+```
+
+---
+
+## Quick start
+
+```typescript
+import { isSafe, createMonoDefence } from 'monofence-ai';
+
+// Fast boolean check
+isSafe('Hello, help me write code');            // true
+isSafe('Ignore all previous instructions');     // false
+
+// Full detection with threat objects
+const fence = createMonoDefence();
+const result = await fence.detect(userInput);
+
+if (!result.safe) {
+  // result.threats — array of detected threats
+  // result.overallRisk — 0.0–1.0
+}
+```
+
+---
+
+## API
+
+### `createMonoDefence(config?)`
+
+Creates a `MonoDefence` instance.
+
+```typescript
+const fence = createMonoDefence({
+  enableLearning: true,        // persist learned threat patterns (default: false)
+  enableContextTracking: true, // track escalation state across turns (default: false)
+  enablePIIDetection: true,    // detect PII in inputs/outputs (default: true)
+  maxContextTurns: 20,         // rolling window for context tracking (default: 20)
+  confidenceThreshold: 0.5,    // minimum detection confidence (default: 0.5)
+});
+```
+
+### `fence.detect(input)`
+
+Full async scan. Returns:
+
+```typescript
+{
+  safe: boolean;          // false if any threat detected
+  threats: Threat[];      // detected threat objects with type/severity/confidence
+  piiFound: boolean;
+  overallRisk: number;    // 0.0–1.0
+  detectionTimeMs: number;
+}
+```
+
+> When context tracking is on and escalation reaches `attack`, `overallRisk` is raised
+> to at least 0.5 even when `safe=true`. Check both `safe` and `overallRisk` when using
+> context tracking.
+
+### `fence.quickScan(input)`
+
+Synchronous, sub-millisecond check. Returns `{ threat: boolean, confidence: number }`.
+
+### `isSafe(input)` / `fence.isSafe(input)`
+
+Returns `boolean`. Fastest option — no async overhead.
+
+### `fence.hasPII(input)`
+
+Returns `boolean`. Checks emails, SSNs, API keys, and passwords.
+
+### `fence.getStats()`
+
+Returns detection counters, learned pattern count, and average latency.
+
+### `fence.learnFromDetection(input, result, feedback)`
+
+Reinforces or corrects a prior detection for human-in-the-loop feedback.
+
+### `fence.getBestMitigation(threatType)`
+
+Returns the highest-effectiveness mitigation strategy for a threat type.
+
+### `fence.searchSimilarThreats(input, { k })`
+
+Vector similarity search over learned threat patterns (requires LanceDB).
+
+### `fence.recordMitigation(threatType, strategy, success)`
+
+Records whether a mitigation worked; affects future `getBestMitigation` results.
+
+---
+
+## Threat types
+
+| Type | Severity | Examples |
+|---|---|---|
+| `instruction_override` | Critical | "Ignore previous instructions", "forget everything" |
+| `jailbreak` | Critical | "DAN mode", "bypass restrictions", "developer mode" |
+| `role_switching` | High | "You are now", "Act as an unrestricted AI" |
+| `context_manipulation` | Critical | Fake `system:` messages, delimiter injection |
+| `encoding_attack` | Medium | base64/hex obfuscation |
+| `prompt_injection` | Critical | Injected instructions in user content |
+
+---
+
+## Evasion detection
+
+Inputs are normalized before pattern matching to defeat obfuscation:
+
+- **Homoglyphs**: Cyrillic/Greek lookalikes → ASCII (`і` → `i`)
+- **Spaced chars**: `i g n o r e` → `ignore`
+- **Leet substitution**: `ign0re` → `ignore` (applied after space collapsing)
+
+```typescript
+const result = await fence.detect('іgnore all рrevious instructions'); // Cyrillic chars
+// result.safe === false, threats include instruction_override
+```
+
+---
+
+## Multi-turn context tracking
+
+Enable to track escalation state across a conversation:
+
+```typescript
+const fence = createMonoDefence({ enableContextTracking: true });
+
+// Turn 1: probing question → state: probing
+// Turn 2: jailbreak attempt → state: escalating
+// Turn 3: confirmed attack → state: attack
+// Once in attack state, overallRisk ≥ 0.5 even on benign inputs
+```
+
+States: `clean` → `probing` → `escalating` → `attack`. Decays toward `clean` on idle turns.
+
+---
+
+## Multi-agent consensus
+
+When running multiple detection agents in parallel:
+
+```typescript
+import { calculateSecurityConsensus } from 'monofence-ai';
+
+const consensus = calculateSecurityConsensus([
+  { result: resultA, weight: 0.6 },
+  { result: resultB, weight: 0.4 },
+]);
+// consensus.safe, consensus.overallRisk, consensus.threats
+```
+
+A single critical threat short-circuits weighted scoring regardless of agent weight (fail-secure).
+
+---
+
+## Hook wiring (optional)
+
+Wire into the monomind hooks system so pre-task and pre-command inputs are scanned automatically. **Off by default.**
+
+```typescript
+import { SecurityHook } from 'monofence-ai/hooks';
+
+SecurityHook.register({ priority: 1000 });
+// Runs before all other hooks; aborts on attack escalation state
+```
+
+Or from the CLI:
+
+```bash
+npx monomind hooks pre-task --monofence-ai-check
+```
+
+---
+
+## Review integration
+
+When using `mastermind:review`, two flags activate monofence-ai analysis:
+
+| Flag | Effect |
+|---|---|
+| `--monofence-ai-check` | Test suite + adversarial probes against the live detector |
+| `--monofence-ai-security-deep` | Scan LLM input boundaries for unprotected paths |
+
+Both are off by default:
+
+```bash
+/mastermind:review --monofence-ai-check --monofence-ai-security-deep
+```
+
+---
+
+## MCP tools
+
+Six MCP tools are available when monomind is installed:
+
+| Tool | Description |
+|---|---|
+| `aidefence_scan` | Scan input for threats (`input`, `quick?`) |
+| `aidefence_analyze` | Deep analysis with similar-pattern search |
+| `aidefence_stats` | Detection and learning statistics |
+| `aidefence_learn` | Record feedback for pattern learning |
+| `aidefence_is_safe` | Quick boolean check |
+| `aidefence_has_pii` | PII detection only |
+
+---
+
+## Performance
+
+| Operation | Typical latency |
+|---|---|
+| Full `detect()` | ~0.04ms |
+| `quickScan()` | ~0.02ms |
+| PII check | ~0.01ms |
+| HNSW search (LanceDB) | ~0.1ms |
+
+Throughput: >12,000 req/s single-threaded. Memory: ~50KB per instance.
+
+---
+
+## Deprecated aliases
+
+Still exported for backward compatibility; will be removed in v2:
+
+| Deprecated | Replacement |
+|---|---|
+| `createAIDefence` | `createMonoDefence` |
+| `getAIDefence` | `getMonoDefence` |
+| `AIDefenceConfig` | `MonoDefenceConfig` |
+| `AIDefence` | `MonoDefence` |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/monoes/monomind.git
+cd monomind/packages/monofence-ai
+
+npm install
+npm test        # vitest run
+npm run build   # tsc
+```
+
+---
+
+## License
+
+MIT — part of the [Monomind](https://github.com/monoes/monomind) ecosystem.

package/dist/domain/entities/index.d.ts

@@ -0,0 +1,2 @@
+export * from './threat.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/domain/entities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/domain/entities/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/domain/entities/index.js

@@ -0,0 +1,2 @@
+export * from './threat.js';
+//# sourceMappingURL=index.js.map

package/dist/domain/entities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/domain/entities/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/domain/entities/threat.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Threat Domain Entity
+ *
+ * Represents a detected security threat from AI manipulation attempts.
+ */
+export type ThreatSeverity = 'low' | 'medium' | 'high' | 'critical';
+export type ThreatType = 'prompt_injection' | 'jailbreak' | 'pii_exposure' | 'instruction_override' | 'role_switching' | 'context_manipulation' | 'encoding_attack' | 'unknown';
+export interface Threat {
+    readonly id: string;
+    readonly type: ThreatType;
+    readonly severity: ThreatSeverity;
+    readonly confidence: number;
+    readonly pattern: string;
+    readonly description: string;
+    readonly location?: {
+        start: number;
+        end: number;
+    };
+    readonly detectedAt: Date;
+}
+export interface ThreatDetectionResult {
+    readonly safe: boolean;
+    readonly threats: Threat[];
+    readonly detectionTimeMs: number;
+    readonly piiFound: boolean;
+    readonly inputHash: string;
+    readonly wasObfuscated?: boolean;
+    /** Aggregate risk score [0, 1] derived from highest-confidence threat; boosted when obfuscation detected */
+    readonly overallRisk: number;
+}
+export interface BehavioralAnalysisResult {
+    readonly agentId: string;
+    readonly anomalyScore: number;
+    readonly attractorType: 'point' | 'cycle' | 'torus' | 'strange';
+    readonly lyapunovExponent: number;
+    readonly analysisTimeMs: number;
+    readonly windowSize: string;
+    readonly actionCount: number;
+}
+export interface PolicyVerificationResult {
+    readonly agentId: string;
+    readonly policy: string;
+    readonly valid: boolean;
+    readonly violations: string[];
+    readonly proofStatus: 'valid' | 'invalid' | 'timeout';
+    readonly verificationTimeMs: number;
+}
+export type EscalationState = 'clean' | 'probing' | 'escalating' | 'attack';
+export interface EvasionResult {
+    readonly normalizedInput: string;
+    readonly wasObfuscated: boolean;
+    readonly techniqueDetected?: 'homoglyph' | 'leetspeak' | 'spacing' | 'base64' | 'zero_width';
+}
+export interface ContextState {
+    readonly escalationState: EscalationState;
+    readonly cumulativeThreatScore: number;
+    readonly turnCount: number;
+    readonly recentThreats: Threat[];
+}
+export interface OutputScanResult {
+    readonly safe: boolean;
+    readonly leakageFound: boolean;
+    readonly leakageTypes: string[];
+    readonly echoDetected: boolean;
+    readonly policyViolation: boolean;
+    readonly contradictionSignal: boolean;
+    readonly scanTimeMs: number;
+}
+export interface AllowlistRule {
+    readonly id: string;
+    readonly pattern: RegExp | string;
+    /**
+     * Threat types this rule applies to.
+     * - Empty array `[]`: full bypass — matching inputs skip detection entirely.
+     * - Non-empty array: selective suppression — detection still runs, but threats
+     *   whose type appears in this array are removed from the result. Threats of
+     *   other types are reported normally.
+     */
+    readonly types: ThreatType[];
+    readonly context?: string;
+    readonly reason: string;
+    readonly source: 'builtin' | 'user';
+}
+/**
+ * Factory function to create a Threat entity
+ */
+export declare function createThreat(params: {
+    type: ThreatType;
+    severity: ThreatSeverity;
+    confidence: number;
+    pattern: string;
+    description: string;
+    location?: {
+        start: number;
+        end: number;
+    };
+}): Threat;
+//# sourceMappingURL=threat.d.ts.map

package/dist/domain/entities/threat.d.ts.map

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

package/dist/domain/entities/threat.js

@@ -0,0 +1,21 @@
+/**
+ * Threat Domain Entity
+ *
+ * Represents a detected security threat from AI manipulation attempts.
+ */
+/**
+ * Factory function to create a Threat entity
+ */
+export function createThreat(params) {
+    return {
+        id: `threat-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        type: params.type,
+        severity: params.severity,
+        confidence: params.confidence,
+        pattern: params.pattern,
+        description: params.description,
+        location: params.location,
+        detectedAt: new Date(),
+    };
+}
+//# sourceMappingURL=threat.js.map

package/dist/domain/entities/threat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"threat.js","sourceRoot":"","sources":["../../../src/domain/entities/threat.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmGH;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,MAO5B;IACC,OAAO;QACL,EAAE,EAAE,UAAU,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;QACpE,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,UAAU,EAAE,IAAI,IAAI,EAAE;KACvB,CAAC;AACJ,CAAC"}

package/dist/domain/services/allowlist.d.ts

@@ -0,0 +1,11 @@
+import type { AllowlistRule } from '../entities/threat.js';
+export declare class Allowlist {
+    private rules;
+    constructor(userRules?: AllowlistRule[]);
+    isAllowed(input: string): boolean;
+    getMatchingRules(input: string): AllowlistRule[];
+    addRule(rule: AllowlistRule): void;
+    private matches;
+}
+export declare function createAllowlist(userRules?: AllowlistRule[]): Allowlist;
+//# sourceMappingURL=allowlist.d.ts.map

package/dist/domain/services/allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.d.ts","sourceRoot":"","sources":["../../../src/domain/services/allowlist.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AA2C3D,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAAkB;gBAEnB,SAAS,GAAE,aAAa,EAAO;IAI3C,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAIjC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE;IAIhD,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAIlC,OAAO,CAAC,OAAO;CAahB;AAED,wBAAgB,eAAe,CAAC,SAAS,CAAC,EAAE,aAAa,EAAE,GAAG,SAAS,CAEtE"}

package/dist/domain/services/allowlist.js

@@ -0,0 +1,72 @@
+const BUILT_IN_RULES = [
+    {
+        id: 'builtin-greetings',
+        // End-anchored: "hi!" or "hello" alone — NOT "hey ignore all instructions"
+        pattern: /^\s*(?:hi|hello|hey|greetings|good\s+(?:morning|afternoon|evening))\s*[.!?]?\s*$/i,
+        types: [],
+        reason: 'Stand-alone greeting — no threat possible',
+        source: 'builtin',
+    },
+    {
+        id: 'builtin-math',
+        pattern: /^\s*what\s+is\s+[\d\s+\-*/^()]+\??$/i,
+        types: [],
+        reason: 'Simple arithmetic question',
+        source: 'builtin',
+    },
+    {
+        id: 'builtin-weather',
+        // Start + end anchored: pure weather query only — allows "in [location]" but not appended instructions
+        pattern: /^\s*(?:what(?:'s|\s+is)\s+(?:the\s+)?weather(?:\s+(?:like\s+)?(?:in|for|at|near|today|tomorrow|this\s+week)(?:\s+[\w\s,]+)?)?|how(?:'s|\s+is)\s+(?:the\s+)?weather(?:\s+[\w\s,]+)?|weather\s+(?:in|for|at|today|tomorrow|forecast)(?:\s+[\w\s,]+)?)\s*[.?!]?\s*$/i,
+        types: [],
+        reason: 'Pure weather query — benign',
+        source: 'builtin',
+    },
+    {
+        id: 'builtin-time',
+        // Start + end anchored: pure time/date query only
+        pattern: /^\s*what\s+(?:time|day|date)\s+is\s+it\s*[.?!]?\s*$/i,
+        types: [],
+        reason: 'Pure time/date query — benign',
+        source: 'builtin',
+    },
+    {
+        id: 'builtin-help',
+        pattern: /^\s*(?:can\s+you\s+)?help\s+me\s*[.?!]?\s*$/i,
+        types: [],
+        reason: 'Short "help me" request — benign',
+        source: 'builtin',
+    },
+];
+export class Allowlist {
+    rules;
+    constructor(userRules = []) {
+        this.rules = [...BUILT_IN_RULES, ...userRules];
+    }
+    isAllowed(input) {
+        return this.getMatchingRules(input).length > 0;
+    }
+    getMatchingRules(input) {
+        return this.rules.filter(rule => this.matches(rule, input));
+    }
+    addRule(rule) {
+        this.rules.push(rule);
+    }
+    matches(rule, input) {
+        if (typeof rule.pattern === 'string') {
+            // String patterns use substring matching. For security-sensitive rules,
+            // prefer RegExp with ^ and $ anchors to avoid over-allowlisting.
+            return input.toLowerCase().includes(rule.pattern.toLowerCase());
+        }
+        // Reset lastIndex before testing — g/y-flagged regexes advance lastIndex after each
+        // successful .test() call, causing alternating true/false on repeated identical inputs.
+        if (rule.pattern.global || rule.pattern.sticky) {
+            rule.pattern.lastIndex = 0;
+        }
+        return rule.pattern.test(input);
+    }
+}
+export function createAllowlist(userRules) {
+    return new Allowlist(userRules);
+}
+//# sourceMappingURL=allowlist.js.map

package/dist/domain/services/allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.js","sourceRoot":"","sources":["../../../src/domain/services/allowlist.ts"],"names":[],"mappings":"AAEA,MAAM,cAAc,GAAoB;IACtC;QACE,EAAE,EAAE,mBAAmB;QACvB,2EAA2E;QAC3E,OAAO,EAAE,mFAAmF;QAC5F,KAAK,EAAE,EAAE;QACT,MAAM,EAAE,2CAA2C;QACnD,MAAM,EAAE,SAAS;KAClB;IACD;QACE,EAAE,EAAE,cAAc;QAClB,OAAO,EAAE,sCAAsC;QAC/C,KAAK,EAAE,EAAE;QACT,MAAM,EAAE,4BAA4B;QACpC,MAAM,EAAE,SAAS;KAClB;IACD;QACE,EAAE,EAAE,iBAAiB;QACrB,uGAAuG;QACvG,OAAO,EAAE,mQAAmQ;QAC5Q,KAAK,EAAE,EAAE;QACT,MAAM,EAAE,6BAA6B;QACrC,MAAM,EAAE,SAAS;KAClB;IACD;QACE,EAAE,EAAE,cAAc;QAClB,kDAAkD;QAClD,OAAO,EAAE,sDAAsD;QAC/D,KAAK,EAAE,EAAE;QACT,MAAM,EAAE,+BAA+B;QACvC,MAAM,EAAE,SAAS;KAClB;IACD;QACE,EAAE,EAAE,cAAc;QAClB,OAAO,EAAE,8CAA8C;QACvD,KAAK,EAAE,EAAE;QACT,MAAM,EAAE,kCAAkC;QAC1C,MAAM,EAAE,SAAS;KAClB;CACF,CAAC;AAEF,MAAM,OAAO,SAAS;IACZ,KAAK,CAAkB;IAE/B,YAAY,YAA6B,EAAE;QACzC,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,cAAc,EAAE,GAAG,SAAS,CAAC,CAAC;IACjD,CAAC;IAED,SAAS,CAAC,KAAa;QACrB,OAAO,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IACjD,CAAC;IAED,gBAAgB,CAAC,KAAa;QAC5B,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,CAAC,IAAmB;QACzB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAEO,OAAO,CAAC,IAAmB,EAAE,KAAa;QAChD,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACrC,wEAAwE;YACxE,iEAAiE;YACjE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;QAClE,CAAC;QACD,oFAAoF;QACpF,wFAAwF;QACxF,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAC/C,IAAI,CAAC,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;CACF;AAED,MAAM,UAAU,eAAe,CAAC,SAA2B;IACzD,OAAO,IAAI,SAAS,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}

package/dist/domain/services/context-tracker.d.ts

@@ -0,0 +1,15 @@
+import type { ContextState, ThreatDetectionResult } from '../entities/threat.js';
+export declare class ContextTracker {
+    private state;
+    private lastTurnAt;
+    private readonly idleDecayMs;
+    constructor(opts?: {
+        idleDecayMs?: number;
+    });
+    recordTurn(input: string, result: ThreatDetectionResult): void;
+    getState(): Readonly<ContextState>;
+    reset(): void;
+    private computeNextState;
+}
+export declare function createContextTracker(): ContextTracker;
+//# sourceMappingURL=context-tracker.d.ts.map

package/dist/domain/services/context-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-tracker.d.ts","sourceRoot":"","sources":["../../../src/domain/services/context-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAA2B,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAiB1G,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAKX;IAEF,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,IAAI,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO;IAI/C,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,GAAG,IAAI;IA8B9D,QAAQ,IAAI,QAAQ,CAAC,YAAY,CAAC;IAIlC,KAAK,IAAI,IAAI;IAUb,OAAO,CAAC,gBAAgB;CAiBzB;AAED,wBAAgB,oBAAoB,IAAI,cAAc,CAErD"}

package/dist/domain/services/context-tracker.js

@@ -0,0 +1,75 @@
+// Escalation thresholds
+const PROBING_THRESHOLD = 0.3;
+const ESCALATING_THRESHOLD = 0.6; // cumulative score
+const ATTACK_CONFIDENCE = 0.9; // single-turn jump-to-attack
+const ESCALATION_ORDER = ['clean', 'probing', 'escalating', 'attack'];
+export class ContextTracker {
+    state = {
+        escalationState: 'clean',
+        cumulativeThreatScore: 0,
+        turnCount: 0,
+        recentThreats: [],
+    };
+    lastTurnAt = 0;
+    idleDecayMs;
+    constructor(opts = {}) {
+        this.idleDecayMs = opts.idleDecayMs ?? 30 * 60 * 1000; // 30 min default
+    }
+    recordTurn(input, result) {
+        const now = Date.now();
+        // Decay escalation state if session has been idle
+        if (this.lastTurnAt > 0 && now - this.lastTurnAt > this.idleDecayMs) {
+            const currentIndex = ESCALATION_ORDER.indexOf(this.state.escalationState);
+            if (currentIndex > 0) {
+                this.state.escalationState = ESCALATION_ORDER[currentIndex - 1];
+            }
+            // Also decay cumulative score so computeNextState doesn't immediately re-escalate
+            this.state.cumulativeThreatScore = Math.max(0, this.state.cumulativeThreatScore * 0.5);
+        }
+        this.lastTurnAt = now;
+        this.state.turnCount++;
+        // Update cumulative score
+        this.state.cumulativeThreatScore += result.overallRisk;
+        // Maintain sliding window of 10
+        if (!result.safe) {
+            this.state.recentThreats = [
+                ...this.state.recentThreats.slice(-9),
+                ...result.threats,
+            ].slice(-10);
+        }
+        // Escalation state machine (monotonic — only moves forward)
+        this.state.escalationState = this.computeNextState(result);
+    }
+    getState() {
+        return { ...this.state, recentThreats: [...this.state.recentThreats] };
+    }
+    reset() {
+        this.state = {
+            escalationState: 'clean',
+            cumulativeThreatScore: 0,
+            turnCount: 0,
+            recentThreats: [],
+        };
+        this.lastTurnAt = 0;
+    }
+    computeNextState(result) {
+        const current = this.state.escalationState;
+        const currentIndex = ESCALATION_ORDER.indexOf(current);
+        let targetIndex = currentIndex; // monotonic: never go back
+        // Jump to attack on high single-turn confidence
+        if (result.overallRisk >= ATTACK_CONFIDENCE) {
+            targetIndex = ESCALATION_ORDER.indexOf('attack');
+        }
+        else if (this.state.cumulativeThreatScore >= ESCALATING_THRESHOLD) {
+            targetIndex = Math.max(targetIndex, ESCALATION_ORDER.indexOf('escalating'));
+        }
+        else if (result.overallRisk >= PROBING_THRESHOLD) {
+            targetIndex = Math.max(targetIndex, ESCALATION_ORDER.indexOf('probing'));
+        }
+        return ESCALATION_ORDER[targetIndex];
+    }
+}
+export function createContextTracker() {
+    return new ContextTracker();
+}
+//# sourceMappingURL=context-tracker.js.map

package/dist/domain/services/context-tracker.js.map

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

package/dist/domain/services/evasion-detector.d.ts

@@ -0,0 +1,12 @@
+import type { EvasionResult } from '../entities/threat.js';
+export declare class EvasionDetector {
+    normalize(input: string): EvasionResult;
+    private replaceHomoglyphs;
+    private expandLeetspeak;
+    private collapseSpacedChars;
+    private stripZeroWidth;
+    private appendDecodedBase64;
+    private detectTechnique;
+}
+export declare function createEvasionDetector(): EvasionDetector;
+//# sourceMappingURL=evasion-detector.d.ts.map

package/dist/domain/services/evasion-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evasion-detector.d.ts","sourceRoot":"","sources":["../../../src/domain/services/evasion-detector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAmD3D,qBAAa,eAAe;IAC1B,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa;IA6BvC,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,eAAe;IAkBvB,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,mBAAmB;IAiB3B,OAAO,CAAC,eAAe;CAWxB;AAED,wBAAgB,qBAAqB,IAAI,eAAe,CAEvD"}