@titanshield/core 0.1.0

package/src/dna.ts

@@ -0,0 +1,304 @@
+// ══════════════════════════════════════════════════════════════════════════════
+// TitanShieldAI — dna.ts
+//
+// WORLD'S FIRST: Security DNA Profiling
+//
+// Every app has a unique behavioral fingerprint — its "Security DNA."
+// Login times, request patterns, user locations, API usage rhythms.
+// TitanShield learns YOUR specific app's normal, then flags deviations.
+//
+// This is fundamentally different from generic thresholds:
+//   Generic: "3+ failed logins = suspicious" (misses slow attacks on your app)
+//   DNA:     "Your app normally has <2 failed logins/hr. This is 47. That's 23x."
+//
+// The Security DNA builds a live statistical model:
+//   - Hourly request distribution (your app's natural rhythm)
+//   - Geographic heat map (where your users normally come from)
+//   - User behavior graph (how long sessions normally run)
+//   - API access patterns (which endpoints are normally hit together)
+//   - Login success rate distribution
+//
+// Any deviation from YOUR baseline triggers an anomaly score — not a generic
+// threshold, but a deviation specific to YOUR app's unique pattern.
+// ══════════════════════════════════════════════════════════════════════════════
+
+import { createHash } from 'crypto';
+
+// ── DNA Profile Types ─────────────────────────────────────────────────────────
+export interface HourlyDistribution {
+    [hour: number]: number; // 0-23 → normalized count
+}
+
+export interface GeoProfile {
+    [countryCode: string]: number; // normalized frequency
+}
+
+export interface SecurityDNA {
+    projectId: string;
+    sampledEvents: number;
+    lastUpdatedAt: Date;
+    maturity: 'learning' | 'establishing' | 'mature';
+
+    // Behavioral baselines
+    hourlyPattern: HourlyDistribution;    // when requests normally happen
+    geoProfile: GeoProfile;               // where users normally come from
+    avgSessionDurationMs: number;          // how long normal sessions are
+    avgRequestsPerSession: number;         // typical session depth
+    loginSuccessRate: number;             // 0-1, your normal success rate
+    avgFailedLoginsPerHour: number;
+    avgApiCallsPerMinute: number;
+    typicalUserAgents: string[];          // known good browsers
+
+    // Computed anomaly thresholds (auto-calibrated to YOUR app)
+    thresholds: {
+        maxFailedLoginsPerHour: number;     // YOUR max, not generic
+        maxRequestsPerMinute: number;
+        maxNewCountriesPerDay: number;
+        minLoginSuccessRate: number;
+        maxSessionDurationMs: number;
+    };
+}
+
+export interface DNAAnomaly {
+    type: 'geo_anomaly' | 'time_anomaly' | 'frequency_anomaly' | 'session_anomaly' | 'login_rate_anomaly' | 'new_country';
+    deviationFactor: number;       // how many standard deviations from YOUR baseline
+    description: string;            // plain English, specific to YOUR app
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    suggestedAction: string;
+}
+
+export interface DNAScanResult {
+    anomalies: DNAAnomaly[];
+    overallDeviationScore: number; // 0-100
+    isNormal: boolean;
+    dnaMessage: string;            // plain English "your app story" verdict
+}
+
+// ── SecurityDNAProfiler ───────────────────────────────────────────────────────
+export class SecurityDNAProfiler {
+    private dna: SecurityDNA;
+    private readonly LEARNING_THRESHOLD = 100;   // events before DNA starts trusting its model
+    private readonly MATURE_THRESHOLD = 1000;    // events for a mature profile
+
+    constructor(projectId: string) {
+        this.dna = this.initDNA(projectId);
+    }
+
+    private initDNA(projectId: string): SecurityDNA {
+        return {
+            projectId,
+            sampledEvents: 0,
+            lastUpdatedAt: new Date(),
+            maturity: 'learning',
+            hourlyPattern: Object.fromEntries(Array.from({ length: 24 }, (_, i) => [i, 1 / 24])),
+            geoProfile: {},
+            avgSessionDurationMs: 30 * 60 * 1000, // default 30 min
+            avgRequestsPerSession: 10,
+            loginSuccessRate: 0.95,
+            avgFailedLoginsPerHour: 1,
+            avgApiCallsPerMinute: 5,
+            typicalUserAgents: [],
+            thresholds: {
+                maxFailedLoginsPerHour: 5,
+                maxRequestsPerMinute: 60,
+                maxNewCountriesPerDay: 3,
+                minLoginSuccessRate: 0.7,
+                maxSessionDurationMs: 8 * 60 * 60 * 1000,
+            },
+        };
+    }
+
+    /**
+     * Feed an event into the DNA learner.
+     * After enough samples, the DNA self-calibrates to YOUR app's unique patterns.
+     */
+    learn(event: {
+        eventType: string;
+        ip?: string;
+        country?: string;
+        userAgent?: string;
+        sessionDurationMs?: number;
+        success?: boolean;
+        timestamp?: Date;
+    }): void {
+        this.dna.sampledEvents++;
+        const n = this.dna.sampledEvents;
+
+        // Update maturity
+        if (n >= this.MATURE_THRESHOLD) this.dna.maturity = 'mature';
+        else if (n >= this.LEARNING_THRESHOLD) this.dna.maturity = 'establishing';
+        else this.dna.maturity = 'learning';
+
+        // Learn hourly pattern (exponential moving average)
+        const hour = (event.timestamp ?? new Date()).getHours();
+        this.dna.hourlyPattern[hour] = this.ema(this.dna.hourlyPattern[hour], 1, 0.05);
+        for (let h = 0; h < 24; h++) {
+            if (h !== hour) {
+                this.dna.hourlyPattern[h] = this.ema(this.dna.hourlyPattern[h], 0, 0.001);
+            }
+        }
+        this.normalizeDistribution(this.dna.hourlyPattern as Record<string | number, number>);
+
+        // Learn geo profile
+        if (event.country) {
+            this.dna.geoProfile[event.country] = (this.dna.geoProfile[event.country] ?? 0) + 1;
+            this.normalizeDistribution(this.dna.geoProfile);
+        }
+
+        // Learn session duration
+        if (event.sessionDurationMs) {
+            this.dna.avgSessionDurationMs = this.ema(this.dna.avgSessionDurationMs, event.sessionDurationMs, 0.05);
+        }
+
+        // Learn login success rate
+        if (event.eventType === 'user.login' || event.eventType === 'user.login_failed') {
+            const success = event.success !== false && event.eventType === 'user.login' ? 1 : 0;
+            this.dna.loginSuccessRate = this.ema(this.dna.loginSuccessRate, success, 0.02);
+        }
+
+        // Learn user agents
+        if (event.userAgent && !this.dna.typicalUserAgents.includes(event.userAgent)) {
+            if (this.dna.typicalUserAgents.length < 20) {
+                this.dna.typicalUserAgents.push(event.userAgent);
+            }
+        }
+
+        // Auto-calibrate thresholds to YOUR app
+        this.calibrateThresholds();
+        this.dna.lastUpdatedAt = new Date();
+    }
+
+    /**
+     * Scan a current context against YOUR Security DNA.
+     * Returns specific, app-calibrated anomaly descriptions.
+     */
+    scan(ctx: {
+        currentHour?: number;
+        country?: string;
+        failedLoginsThisHour?: number;
+        requestsPerMinute?: number;
+        loginSuccessRate?: number;
+        sessionDurationMs?: number;
+        userAgent?: string;
+        isNewCountry?: boolean;
+    }): DNAScanResult {
+        const anomalies: DNAAnomaly[] = [];
+
+        // Only scan meaningfully after some learning (avoid false positives during learning)
+        if (this.dna.maturity === 'learning') {
+            return {
+                anomalies: [],
+                overallDeviationScore: 0,
+                isNormal: true,
+                dnaMessage: `🔬 Learning your app's DNA... (${this.dna.sampledEvents}/${this.LEARNING_THRESHOLD} events seen)`,
+            };
+        }
+
+        // ── 1. Time anomaly (wrong time of day for YOUR app)
+        if (ctx.currentHour !== undefined) {
+            const expectedFreq = this.dna.hourlyPattern[ctx.currentHour] ?? (1 / 24);
+            if (expectedFreq < 0.01) { // this hour is very unusual for your app
+                anomalies.push({
+                    type: 'time_anomaly',
+                    deviationFactor: 1 / (expectedFreq * 24), // how many times rarer than average
+                    description: `📅 Request at ${ctx.currentHour}:00 — your app almost never gets traffic at this hour. ${Math.round(expectedFreq * 100)}% of your normal traffic.`,
+                    severity: expectedFreq < 0.001 ? 'high' : 'medium',
+                    suggestedAction: 'Verify if this is a legitimate request or automation',
+                });
+            }
+        }
+
+        // ── 2. Geo anomaly
+        if (ctx.isNewCountry && ctx.country) {
+            const knownFreq = this.dna.geoProfile[ctx.country] ?? 0;
+            if (knownFreq < 0.01) {
+                anomalies.push({
+                    type: 'new_country',
+                    deviationFactor: knownFreq > 0 ? 1 / knownFreq : 100,
+                    description: `🌍 First request from ${ctx.country} — your app has never (or rarely) seen users from here.`,
+                    severity: 'medium',
+                    suggestedAction: 'Consider sending a verification email to the user',
+                });
+            }
+        }
+
+        // ── 3. Login failure rate anomaly
+        if (ctx.failedLoginsThisHour !== undefined) {
+            const threshold = this.dna.thresholds.maxFailedLoginsPerHour;
+            if (ctx.failedLoginsThisHour > threshold) {
+                const factor = ctx.failedLoginsThisHour / threshold;
+                anomalies.push({
+                    type: 'login_rate_anomaly',
+                    deviationFactor: factor,
+                    description: `🔑 ${ctx.failedLoginsThisHour} failed logins this hour — ${factor.toFixed(1)}x YOUR normal max (${threshold}/hr for your app).`,
+                    severity: factor > 5 ? 'critical' : factor > 2 ? 'high' : 'medium',
+                    suggestedAction: factor > 5 ? 'Enable emergency lockout' : 'Monitor and consider adding CAPTCHA',
+                });
+            }
+        }
+
+        // ── 4. Request frequency anomaly
+        if (ctx.requestsPerMinute !== undefined) {
+            const threshold = this.dna.thresholds.maxRequestsPerMinute;
+            if (ctx.requestsPerMinute > threshold) {
+                const factor = ctx.requestsPerMinute / threshold;
+                anomalies.push({
+                    type: 'frequency_anomaly',
+                    deviationFactor: factor,
+                    description: `⚡ ${ctx.requestsPerMinute} requests/min — ${factor.toFixed(1)}x YOUR normal max. Possible DDoS or scraper.`,
+                    severity: factor > 10 ? 'critical' : factor > 3 ? 'high' : 'medium',
+                    suggestedAction: factor > 10 ? 'Enable emergency rate limiting' : 'Apply gentle rate limiting',
+                });
+            }
+        }
+
+        // ── Compute overall deviation score
+        const overallScore = Math.min(100,
+            anomalies.reduce((sum, a) => sum + Math.min(a.deviationFactor * 10, 40), 0)
+        );
+
+        const isNormal = overallScore < 20;
+        const dnaMessage = this.generateDNAVerdict(anomalies, overallScore);
+
+        return { anomalies, overallDeviationScore: overallScore, isNormal, dnaMessage };
+    }
+
+    private generateDNAVerdict(anomalies: DNAAnomaly[], score: number): string {
+        if (anomalies.length === 0) {
+            return `✅ DNA Match — everything looks exactly like YOUR app normally behaves`;
+        }
+        if (score < 30) return `⚠️ Minor DNA mismatch — ${anomalies[0].description}`;
+        if (score < 60) return `🟡 Significant DNA deviation — ${anomalies.length} unusual pattern${anomalies.length !== 1 ? 's' : ''} detected`;
+        return `🚨 Major DNA deviation — this doesn't look like your normal app at all! ${anomalies.length} critical deviations.`;
+    }
+
+    private ema(current: number, newValue: number, alpha: number): number {
+        return current * (1 - alpha) + newValue * alpha;
+    }
+
+    private normalizeDistribution(dist: Record<string | number, number>): void {
+        const total = Object.values(dist).reduce((a, b) => a + b, 0);
+        if (total === 0) return;
+        for (const key in dist) dist[key] /= total;
+    }
+
+    private calibrateThresholds(): void {
+        // Auto-calibrate to be 3x YOUR normal as the alert threshold
+        this.dna.thresholds.maxFailedLoginsPerHour = Math.max(5, this.dna.avgFailedLoginsPerHour * 3);
+        this.dna.thresholds.maxRequestsPerMinute = Math.max(60, this.dna.avgApiCallsPerMinute * 3);
+        this.dna.thresholds.minLoginSuccessRate = Math.max(0.3, this.dna.loginSuccessRate * 0.7);
+    }
+
+    getDNA(): SecurityDNA { return { ...this.dna }; }
+
+    /** Generate a shareable DNA fingerprint (safe to share publicly) */
+    getDNAFingerprint(): string {
+        const profile = JSON.stringify({
+            maturity: this.dna.maturity,
+            sampledEvents: this.dna.sampledEvents,
+            topCountries: Object.entries(this.dna.geoProfile).sort((a, b) => b[1] - a[1]).slice(0, 3).map(([k]) => k),
+            peakHour: Object.entries(this.dna.hourlyPattern).sort((a, b) => b[1] - a[1])[0]?.[0],
+        });
+        return createHash('sha256').update(profile).digest('hex').slice(0, 16);
+    }
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// @titanshield/core — Public API  v0.3
+// World's First & Best Security System — Never Built Before
+// ─────────────────────────────────────────────────────────────────────────────
+
+// ── Main class ────────────────────────────────────────────────────────────────
+export { TitanShield } from './TitanShield.js';
+
+// ── Input Validation ──────────────────────────────────────────────────────────
+export { Schemas, validate, z } from './validate.js';
+
+// ── v0.2 Prevention Engine ────────────────────────────────────────────────────
+export {
+    AccountLockout, IpReputationEngine, SessionFingerprinter,
+    CsrfProtection, securityHeaders, detectBot,
+    detectAdvancedInjection, titanPreventionMiddleware,
+} from './prevent.js';
+export type { PreventionConfig, LockoutRecord, SessionFingerprint } from './prevent.js';
+
+// ── v0.3 QUANTUM SHIELD ───────────────────────────────────────────────────────
+export { QuantumSigner, QuantumRandom, QuantumAuditChain, globalQuantumSigner, globalQuantumRandom } from './quantum.js';
+export type { QuantumKeyPair, QuantumSignature, QRNGResult, QuantumBlock } from './quantum.js';
+
+// ── v0.3 NATURAL LANGUAGE RULES ───────────────────────────────────────────────
+export { NaturalLanguageRuleParser } from './nlrules.js';
+export type { NLRule, RuleCondition, RuleEvaluationContext, RuleMatch, RuleAction } from './nlrules.js';
+
+// ── v0.3 SECURITY DNA ─────────────────────────────────────────────────────────
+export { SecurityDNAProfiler } from './dna.js';
+export type { SecurityDNA, DNAAnomaly, DNAScanResult } from './dna.js';
+
+// ── v0.3 COLLECTIVE DEFENSE NETWORK ──────────────────────────────────────────
+export { CollectiveDefenseNetwork } from './collective.js';
+export type { CollectiveThreatSignal, ThreatSignalType, CollectiveStats } from './collective.js';
+
+// ── v0.3 AI CODE SCANNER ─────────────────────────────────────────────────────
+export { AISecurityScanner } from './scanner.js';
+export type { SecurityVulnerability, ScanResult, VulnSeverity, VulnCategory } from './scanner.js';
+
+// ── v0.3 BATTLE REPORT ───────────────────────────────────────────────────────
+export { BattleReportGenerator } from './battle.js';
+export type { BattleReport, BattleReportInput } from './battle.js';
+
+// ── v0.3 GITHUB BADGE ────────────────────────────────────────────────────────
+export { generateBadgeSvg, badgeRouteHandler } from './badge.js';
+export type { BadgeConfig, BadgeResult, BadgeStyle } from './badge.js';
+
+// ── v0.3 BEHAVIORAL BIOMETRICS ───────────────────────────────────────────────
+export { BiometricAnalyzer, BIOMETRICS_CLIENT_SCRIPT } from './biometrics.js';
+export type { BiometricPayload, BiometricAnalysis, KeystrokeSample, MouseSample } from './biometrics.js';
+
+// ── Core Types ────────────────────────────────────────────────────────────────
+export type {
+    TitanConfig, AuditEvent, AuditEventType, StoredAuditEvent,
+    ThreatAlert, AnomalyScore, ValidationResult, ValidationError,
+    ComplianceScore, ComplianceStandard,
+} from './types.js';
+
+

package/src/nlrules.ts

@@ -0,0 +1,297 @@
+// ══════════════════════════════════════════════════════════════════════════════
+// TitanShieldAI — nlrules.ts
+//
+// WORLD'S FIRST: Natural Language Security Rules
+//
+// Write security rules in plain English. AI converts them to running code.
+// No other security tool on earth does this.
+//
+// Examples:
+//   "Block all logins from Russia after 10pm"
+//   "Lock any account after 3 failed attempts"
+//   "Alert me when someone exports more than 1000 records"
+//   "Require multi-factor auth for all admin users"
+//   "Block requests with more than 5 different user agents per hour"
+//
+// The AI (Gemini) parses the English, extracts structured intent,
+// compiles it to a TitanShield Rule, and starts enforcing it immediately.
+//
+// No engineers needed. No docs to read. No configuration files.
+// Just say what you want. TitanShield does it.
+// ══════════════════════════════════════════════════════════════════════════════
+
+import { GoogleGenerativeAI } from '@google/generative-ai';
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+export type RuleAction = 'block' | 'alert' | 'log' | 'lockout' | 'require_mfa' | 'rate_limit' | 'flag';
+
+export type RuleConditionType =
+    | 'geo_country'          // request from specific country
+    | 'time_window'          // specific time of day / day of week
+    | 'event_type'           // specific event (login, data.export, etc.)
+    | 'failure_count'        // N failures in window
+    | 'data_volume'          // records accessed / exported
+    | 'user_role'            // user has specific role
+    | 'ip_reputation'        // IP score threshold
+    | 'new_device'           // first time seeing this device
+    | 'rate_threshold'       // requests per minute
+    | 'user_agent_diversity' // N different UAs in window
+    | 'always';              // unconditional
+
+export interface RuleCondition {
+    type: RuleConditionType;
+    value?: string | number | string[];
+    operator?: 'gt' | 'lt' | 'eq' | 'in' | 'not_in' | 'after' | 'before' | 'between';
+    window?: number; // ms
+}
+
+export interface NLRule {
+    id: string;
+    originalText: string;       // the English the user typed
+    conditions: RuleCondition[];
+    action: RuleAction;
+    severity: 'info' | 'warning' | 'critical';
+    message: string;            // human-readable description of what this rule does
+    confidence: 'high' | 'medium' | 'low'; // AI's confidence in the interpretation
+    createdAt: Date;
+    active: boolean;
+    triggerCount: number;
+}
+
+export interface RuleEvaluationContext {
+    event: string;
+    ip?: string;
+    userId?: string;
+    userRole?: string;
+    country?: string;
+    timestamp?: number;
+    metadata?: Record<string, unknown>;
+    recentEventCount?: number;
+    dataVolumeAccessed?: number;
+    failedLoginCount?: number;
+    uniqueUserAgents?: number;
+}
+
+export interface RuleMatch {
+    rule: NLRule;
+    action: RuleAction;
+    message: string;
+    blocked: boolean;
+}
+
+// ── NaturalLanguageRuleParser ─────────────────────────────────────────────────
+export class NaturalLanguageRuleParser {
+    private ai: GoogleGenerativeAI | null = null;
+    private rules: NLRule[] = [];
+
+    constructor(geminiApiKey?: string) {
+        if (geminiApiKey) {
+            this.ai = new GoogleGenerativeAI(geminiApiKey);
+        }
+    }
+
+    /**
+     * Parse a natural language security rule into a structured TitanShield rule.
+     * Uses Gemini to understand intent, then compiles to an active rule.
+     *
+     * @example
+     * const rule = await parser.parse("Block all logins from Russia after 10pm");
+     * // → { conditions: [{type:'geo_country', value:'RU'}, {type:'time_window', value:'22:00'}], action:'block' }
+     */
+    async parse(text: string): Promise<NLRule> {
+        const id = `rule_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+
+        let parsed: Partial<NLRule>;
+
+        if (this.ai) {
+            parsed = await this.parseWithAI(text, id);
+        } else {
+            parsed = this.parseWithHeuristics(text, id);
+        }
+
+        const rule: NLRule = {
+            id,
+            originalText: text,
+            conditions: parsed.conditions ?? [{ type: 'always' }],
+            action: parsed.action ?? 'alert',
+            severity: parsed.severity ?? 'warning',
+            message: parsed.message ?? `Rule: ${text}`,
+            confidence: parsed.confidence ?? 'medium',
+            createdAt: new Date(),
+            active: true,
+            triggerCount: 0,
+        };
+
+        this.rules.push(rule);
+        console.log(`[TitanShield NL] ✅ Rule compiled: "${text}" → ${rule.action} (${rule.confidence} confidence)`);
+        return rule;
+    }
+
+    private async parseWithAI(text: string, id: string): Promise<Partial<NLRule>> {
+        const model = this.ai!.getGenerativeModel({ model: 'gemini-2.5-flash' });
+
+        const prompt = `You are a security rule compiler for TitanShieldAI.
+Parse this natural language security rule into structured JSON.
+
+Rule: "${text}"
+
+Return ONLY a valid JSON object with this exact structure:
+{
+  "conditions": [
+    {
+      "type": "geo_country|time_window|event_type|failure_count|data_volume|user_role|ip_reputation|new_device|rate_threshold|user_agent_diversity|always",
+      "value": "the value to compare (string, number, or array of strings)",
+      "operator": "gt|lt|eq|in|not_in|after|before|between",
+      "window": (optional milliseconds for time windows)
+    }
+  ],
+  "action": "block|alert|log|lockout|require_mfa|rate_limit|flag",
+  "severity": "info|warning|critical",
+  "message": "Plain English: what this rule does and why. Start with an emoji.",
+  "confidence": "high|medium|low"
+}
+
+Country codes: US, RU, CN, KP, IR, etc.
+Event types: user.login, user.login_failed, user.logout, data.export, data.read, admin.settings_changed
+Time format for time_window values: "HH:MM" in 24h format
+
+Be creative and thorough. Extract ALL conditions from the rule text.`;
+
+        try {
+            const result = await model.generateContent(prompt);
+            const raw = result.response.text().replace(/```json\n?|```/g, '').trim();
+            return JSON.parse(raw);
+        } catch {
+            return this.parseWithHeuristics(text, id);
+        }
+    }
+
+    private parseWithHeuristics(text: string, _id: string): Partial<NLRule> {
+        const lower = text.toLowerCase();
+        const conditions: RuleCondition[] = [];
+
+        // Geo detection
+        const countries: Record<string, string> = {
+            'russia': 'RU', 'china': 'CN', 'north korea': 'KP', 'iran': 'IR',
+            'nigeria': 'NG', 'usa': 'US', 'india': 'IN', 'brazil': 'BR',
+        };
+        for (const [name, code] of Object.entries(countries)) {
+            if (lower.includes(name)) {
+                conditions.push({ type: 'geo_country', value: code, operator: 'eq' });
+            }
+        }
+
+        // Time detection
+        const timeMatch = lower.match(/after\s+(\d{1,2})(pm|am)/);
+        if (timeMatch) {
+            let hour = parseInt(timeMatch[1]);
+            if (timeMatch[2] === 'pm' && hour !== 12) hour += 12;
+            conditions.push({ type: 'time_window', value: `${String(hour).padStart(2, '0')}:00`, operator: 'after' });
+        }
+
+        // Event detection
+        if (lower.includes('login')) conditions.push({ type: 'event_type', value: 'user.login' });
+        if (lower.includes('export')) conditions.push({ type: 'event_type', value: 'data.export' });
+        if (lower.includes('admin')) conditions.push({ type: 'user_role', value: 'admin', operator: 'eq' });
+
+        // Failure count
+        const failMatch = lower.match(/(\d+)\s+failed/);
+        if (failMatch) {
+            conditions.push({ type: 'failure_count', value: parseInt(failMatch[1]), operator: 'gt', window: 300_000 });
+        }
+
+        // Action detection
+        let action: RuleAction = 'alert';
+        if (lower.includes('block') || lower.includes('deny')) action = 'block';
+        else if (lower.includes('lock')) action = 'lockout';
+        else if (lower.includes('mfa') || lower.includes('multi-factor')) action = 'require_mfa';
+        else if (lower.includes('alert') || lower.includes('notify')) action = 'alert';
+
+        return {
+            conditions: conditions.length > 0 ? conditions : [{ type: 'always' }],
+            action,
+            severity: action === 'block' || action === 'lockout' ? 'critical' : 'warning',
+            message: `🛡️ NL Rule: ${text}`,
+            confidence: 'medium',
+        };
+    }
+
+    /**
+     * Evaluate all active rules against an incoming request context.
+     * Returns list of matching rules with their required actions.
+     */
+    evaluate(ctx: RuleEvaluationContext): RuleMatch[] {
+        const matches: RuleMatch[] = [];
+        const now = new Date();
+        const currentHour = now.getHours();
+        const currentMinute = now.getMinutes();
+
+        for (const rule of this.rules.filter(r => r.active)) {
+            const matched = rule.conditions.every(cond => this.evaluateCondition(cond, ctx, currentHour, currentMinute));
+
+            if (matched) {
+                rule.triggerCount++;
+                matches.push({
+                    rule,
+                    action: rule.action,
+                    message: `🛡️ Rule triggered: "${rule.originalText}" → ${rule.action.toUpperCase()}`,
+                    blocked: rule.action === 'block' || rule.action === 'lockout',
+                });
+            }
+        }
+
+        return matches;
+    }
+
+    private evaluateCondition(
+        cond: RuleCondition,
+        ctx: RuleEvaluationContext,
+        hour: number,
+        _minute: number
+    ): boolean {
+        switch (cond.type) {
+            case 'always': return true;
+            case 'geo_country':
+                return ctx.country === cond.value;
+            case 'time_window':
+                if (typeof cond.value === 'string') {
+                    const [h] = cond.value.split(':').map(Number);
+                    if (cond.operator === 'after') return hour >= h;
+                    if (cond.operator === 'before') return hour < h;
+                }
+                return false;
+            case 'event_type':
+                return ctx.event === cond.value || (Array.isArray(cond.value) && cond.value.includes(ctx.event));
+            case 'failure_count':
+                return typeof cond.value === 'number' && (ctx.failedLoginCount ?? 0) >= cond.value;
+            case 'data_volume':
+                return typeof cond.value === 'number' && (ctx.dataVolumeAccessed ?? 0) >= cond.value;
+            case 'user_role':
+                return ctx.userRole === cond.value;
+            case 'rate_threshold':
+                return typeof cond.value === 'number' && (ctx.recentEventCount ?? 0) >= cond.value;
+            case 'new_device':
+                return ctx.metadata?.newDevice === true;
+            case 'user_agent_diversity':
+                return typeof cond.value === 'number' && (ctx.uniqueUserAgents ?? 0) >= cond.value;
+            default: return false;
+        }
+    }
+
+    /** Get all active rules with their trigger counts */
+    getRules(): NLRule[] { return [...this.rules]; }
+
+    /** Enable/disable a rule by ID */
+    setActive(ruleId: string, active: boolean): boolean {
+        const rule = this.rules.find(r => r.id === ruleId);
+        if (rule) { rule.active = active; return true; }
+        return false;
+    }
+
+    /** Delete a rule by ID */
+    deleteRule(ruleId: string): boolean {
+        const idx = this.rules.findIndex(r => r.id === ruleId);
+        if (idx >= 0) { this.rules.splice(idx, 1); return true; }
+        return false;
+    }
+}