@wardnmesh/sdk-node 0.2.3 → 0.4.1

package/README.md

@@ -1,7 +1,20 @@
 # @wardnmesh/sdk-node
 
+> **Latest Version: v0.4.0** (Released 2026-01-17)
+
 **WardnMesh.AI** (formerly AgentGuard) is an active defense middleware for AI Agents. This SDK allows you to verify LLM inputs/outputs, block prompt injections, and prevent data exfiltration in real-time.
 
+## ✨ What's New in v0.4.0
+
+🚨 **Breaking Changes**: Action-based architecture replaces boolean `allowed` field.
+
+- ✅ **Granular Actions**: `block`, `confirm`, `warn`, `log`, `allow` instead of `true`/`false`
+- ✅ **Confirmation Support**: Native user confirmation for high-risk operations
+- ✅ **Enhanced Context**: Richer violation metadata with `recommendedAction` and `scope`
+- ✅ **Fail-Closed Security**: Defensive design defaults to `'block'` on invalid states
+
+📖 [Migration Guide](MIGRATION_v0.4.0.md) | [CHANGELOG](CHANGELOG.md)
+
 ## Features
 
 - 🛡️ **Active Defense**: Blocks prompt injections, jailbreaks, and PII leaks.
@@ -13,9 +26,68 @@
 ## Installation
 
 ```bash
-npm install @wardnmesh/sdk-node
+npm install @wardnmesh/sdk-node@0.4.0
 # or
-yarn add @wardnmesh/sdk-node
+yarn add @wardnmesh/sdk-node@0.4.0
+```
+
+## v0.4.0 API Overview
+
+The new action-based API provides fine-grained control over threat responses:
+
+```typescript
+import { Wardn } from '@wardnmesh/sdk-node';
+
+const guard = Wardn.getInstance();
+const result = await guard.scan({ prompt: userInput });
+
+// Handle different threat levels
+switch (result.action) {
+  case 'block':
+    // Critical violation - deny immediately
+    throw new Error('Security violation');
+
+  case 'confirm':
+    // High-risk - request user approval
+    const approved = await getUserConfirmation(result.confirmationDetails);
+    if (!approved) throw new Error('Operation denied');
+    break;
+
+  case 'warn':
+    // Medium-risk - log warning and allow
+    console.warn('Security warning:', result.violations);
+    break;
+
+  case 'log':
+    // Low-risk - log for monitoring
+    console.log('Security event:', result.violations);
+    break;
+
+  case 'allow':
+    // No violations - safe to proceed
+    break;
+}
+
+// Continue with your logic...
+```
+
+### Confirmation Dialog Example
+
+When `action === 'confirm'`, the SDK provides pre-formatted confirmation context:
+
+```typescript
+if (result.action === 'confirm') {
+  const { message, timeout, defaultAction } = result.confirmationDetails;
+
+  console.log(message);
+  // ⚠️ Security Alert
+  // Rule: recursive_delete
+  // Severity: HIGH
+  // Description: Detected dangerous recursive delete operation
+
+  const approved = await getUserInput(); // Your confirmation UI
+  if (!approved) throw new Error('Operation denied by user');
+}
 ```
 
 ## Quick Start

package/dist/detectors/base.d.ts

@@ -1,18 +1,33 @@
-import { ToolData, Violation, Rule, Detector, StateProvider, DetectorType } from '../types';
+import { ToolData, Violation, Rule, Detector, StateProvider, DetectorType, ThreatAction } from '../types';
 /**
- * Abstract base detector class
+ * Map rule severity to recommended action, with optional rule action override.
  *
+ * Default mapping:
+ * - critical -> block (immediate threat)
+ * - high -> confirm (needs user approval)
+ * - medium -> warn (notify but allow)
+ * - low -> log (record only)
+ *
+ * Rules can override default mapping via rule.action.
+ */
+export declare function mapSeverityToAction(rule: Rule): ThreatAction;
+/**
+ * Map rule category to scope description.
+ */
+export declare function mapCategoryToScope(category: string): string;
+/**
+ * Abstract base detector class.
  * Provides common functionality for all detectors.
  */
 export declare abstract class BaseDetector implements Detector {
     abstract detect(toolData: ToolData, rule: Rule, sessionState: StateProvider): Violation | null;
     abstract getType(): DetectorType | string;
     /**
-     * Generate unique violation ID
+     * Generate unique violation ID using cryptographically secure random.
      */
     protected generateViolationId(): string;
     /**
-     * Create violation object
+     * Create violation object with standardized structure.
      */
     protected createViolation(rule: Rule, toolData: ToolData, additionalInfo?: Record<string, unknown>): Violation;
     /**

package/dist/detectors/base.js

@@ -1,23 +1,64 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseDetector = void 0;
+exports.mapSeverityToAction = mapSeverityToAction;
+exports.mapCategoryToScope = mapCategoryToScope;
+const crypto_1 = require("crypto");
 /**
- * Abstract base detector class
+ * Map rule severity to recommended action, with optional rule action override.
  *
+ * Default mapping:
+ * - critical -> block (immediate threat)
+ * - high -> confirm (needs user approval)
+ * - medium -> warn (notify but allow)
+ * - low -> log (record only)
+ *
+ * Rules can override default mapping via rule.action.
+ */
+function mapSeverityToAction(rule) {
+    if (rule.action) {
+        return rule.action;
+    }
+    switch (rule.severity) {
+        case 'critical': return 'block';
+        case 'high': return 'confirm';
+        case 'medium': return 'warn';
+        case 'low': return 'log';
+        default: return 'block';
+    }
+}
+/**
+ * Map rule category to scope description.
+ */
+function mapCategoryToScope(category) {
+    switch (category) {
+        case 'workflow': return 'Workflow safety';
+        case 'quality': return 'Code quality';
+        case 'safety': return 'Security';
+        case 'network_boundary': return 'Network access';
+        case 'supply_chain': return 'Supply chain';
+        default: return 'Security violation';
+    }
+}
+/**
+ * Abstract base detector class.
  * Provides common functionality for all detectors.
  */
 class BaseDetector {
     /**
-     * Generate unique violation ID
+     * Generate unique violation ID using cryptographically secure random.
      */
     generateViolationId() {
-        // Note: Using substring() instead of deprecated substr()
-        return `violation_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+        return `violation_${(0, crypto_1.randomUUID)()}`;
     }
     /**
-     * Create violation object
+     * Create violation object with standardized structure.
      */
     createViolation(rule, toolData, additionalInfo) {
+        const filePath = (toolData.parameters.file_path ||
+            toolData.parameters.TargetFile ||
+            toolData.parameters.AbsolutePath ||
+            toolData.parameters.path);
         return {
             id: this.generateViolationId(),
             ruleId: rule.id,
@@ -27,10 +68,12 @@ class BaseDetector {
             context: {
                 toolName: toolData.toolName,
                 toolData,
-                filePath: (toolData.parameters.file_path || toolData.parameters.TargetFile || toolData.parameters.AbsolutePath || toolData.parameters.path),
-                additionalInfo
+                filePath,
+                additionalInfo,
             },
-            timestamp: new Date().toISOString()
+            timestamp: new Date().toISOString(),
+            recommendedAction: mapSeverityToAction(rule),
+            scope: mapCategoryToScope(rule.category),
         };
     }
     /**

package/dist/detectors/sequence.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SequenceDetector = void 0;
 const base_1 = require("./base");
+const safe_regex_1 = require("../utils/safe-regex");
 class SequenceDetector extends base_1.BaseDetector {
     getType() {
         return 'sequence';
@@ -60,7 +61,12 @@ class SequenceDetector extends base_1.BaseDetector {
                 }
                 if (step.matchesPattern) {
                     const currentValue = this.extractValue(currentTool, step.extractPath);
-                    const regex = new RegExp(step.matchesPattern);
+                    // SECURITY FIX Round 16: Use getCachedRegex for ReDoS protection
+                    const regex = (0, safe_regex_1.getCachedRegex)(step.matchesPattern);
+                    if (!regex) {
+                        // Invalid or unsafe pattern - skip this check
+                        return { matched: true };
+                    }
                     if (typeof currentValue === 'string' && !regex.test(currentValue)) {
                         return {
                             matched: false,
@@ -103,7 +109,12 @@ class SequenceDetector extends base_1.BaseDetector {
                 }
             }
             if (step.matchesPattern) {
-                const regex = new RegExp(step.matchesPattern);
+                // SECURITY FIX Round 16: Use getCachedRegex for ReDoS protection
+                const regex = (0, safe_regex_1.getCachedRegex)(step.matchesPattern);
+                if (!regex) {
+                    // Invalid or unsafe pattern - skip this tool
+                    continue;
+                }
                 if (typeof value === 'string' && !regex.test(value)) {
                     continue;
                 }
@@ -123,7 +134,13 @@ class SequenceDetector extends base_1.BaseDetector {
         }
         if (lastStep.matchesPattern) {
             const val = this.extractValue(toolData, lastStep.extractPath);
-            if (typeof val === 'string' && !new RegExp(lastStep.matchesPattern).test(val)) {
+            // SECURITY FIX Round 16: Use getCachedRegex for ReDoS protection
+            const regex = (0, safe_regex_1.getCachedRegex)(lastStep.matchesPattern);
+            if (!regex) {
+                // Invalid or unsafe pattern - skip this check (allow through)
+                return null;
+            }
+            if (typeof val === 'string' && !regex.test(val)) {
                 return null;
             }
         }

package/dist/detectors/state.d.ts

@@ -5,4 +5,5 @@ export declare class StateDetector extends BaseDetector {
     detect(toolData: ToolData, rule: Rule, sessionState: StateProvider): Violation | null;
     private isTriggerEvent;
     private updateStateFromTool;
+    private setStateWithTimestamp;
 }

package/dist/detectors/state.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StateDetector = void 0;
 const base_1 = require("./base");
+const safe_regex_1 = require("../utils/safe-regex");
 class StateDetector extends base_1.BaseDetector {
     getType() {
         return 'state';
@@ -9,78 +10,56 @@ class StateDetector extends base_1.BaseDetector {
     detect(toolData, rule, sessionState) {
         const config = rule.detector.config;
         this.updateStateFromTool(config, toolData, sessionState);
-        if (this.isTriggerEvent(config, toolData)) {
-            const currentState = sessionState.getCustomState(config.requiredState);
-            if (currentState !== config.targetStateValue) {
-                return {
-                    id: this.generateViolationId(),
-                    ruleId: rule.id,
-                    ruleName: rule.name,
-                    severity: rule.severity,
-                    timestamp: new Date().toISOString(),
-                    description: rule.description,
-                    context: {
-                        toolName: toolData.toolName,
-                        toolData: toolData,
-                        additionalInfo: {
-                            message: `Required state '${config.requiredState}' is '${currentState || 'undefined'}', expected '${config.targetStateValue}'.`
-                        }
-                    }
-                };
-            }
-            if (config.stateDerivation?.validityDurationMs) {
-                const lastUpdate = sessionState.getCustomState(`${config.requiredState}_timestamp`);
-                if (lastUpdate && typeof lastUpdate === 'string') {
-                    const timeDiff = new Date().getTime() - new Date(lastUpdate).getTime();
-                    if (timeDiff > config.stateDerivation.validityDurationMs) {
-                        return {
-                            id: this.generateViolationId(),
-                            ruleId: rule.id,
-                            ruleName: rule.name,
-                            severity: rule.severity,
-                            timestamp: new Date().toISOString(),
-                            description: rule.description,
-                            context: {
-                                toolName: toolData.toolName,
-                                toolData: toolData,
-                                additionalInfo: {
-                                    message: `Required state '${config.requiredState}' has expired (last verified ${Math.floor(timeDiff / 1000)}s ago).`
-                                }
-                            }
-                        };
-                    }
+        if (!this.isTriggerEvent(config, toolData)) {
+            return null;
+        }
+        const currentState = sessionState.getCustomState(config.requiredState);
+        if (currentState !== config.targetStateValue) {
+            const message = `Required state '${config.requiredState}' is '${currentState ?? 'undefined'}', expected '${config.targetStateValue}'.`;
+            return this.createViolation(rule, toolData, { message });
+        }
+        if (config.stateDerivation?.validityDurationMs) {
+            const lastUpdate = sessionState.getCustomState(`${config.requiredState}_timestamp`);
+            if (lastUpdate && typeof lastUpdate === 'string') {
+                const timeDiff = Date.now() - new Date(lastUpdate).getTime();
+                if (timeDiff > config.stateDerivation.validityDurationMs) {
+                    const message = `Required state '${config.requiredState}' has expired (last verified ${Math.floor(timeDiff / 1000)}s ago).`;
+                    return this.createViolation(rule, toolData, { message });
                 }
             }
         }
         return null;
     }
     isTriggerEvent(config, toolData) {
-        if (toolData.toolName !== config.trigger.tool)
+        if (toolData.toolName !== config.trigger.tool) {
+            return false;
+        }
+        if (!config.trigger.parameterMatch) {
+            return true;
+        }
+        const paramValue = this.extractValue(toolData.parameters, config.trigger.parameterMatch.key);
+        if (!paramValue || typeof paramValue !== 'string') {
             return false;
-        if (config.trigger.parameterMatch) {
-            const paramValue = this.extractValue(toolData.parameters, config.trigger.parameterMatch.key);
-            if (!paramValue || typeof paramValue !== 'string')
-                return false;
-            const regex = new RegExp(config.trigger.parameterMatch.valuePattern, 'i');
-            return regex.test(paramValue);
         }
-        return true;
+        const regex = (0, safe_regex_1.getCachedRegex)(config.trigger.parameterMatch.valuePattern, 'i');
+        return regex ? regex.test(paramValue) : false;
     }
     updateStateFromTool(config, toolData, sessionState) {
-        if (config.stateDerivation && toolData.toolName === config.stateDerivation.fromTool) {
-            // Heuristic check for 'test' in command line if it's run_command
-            if (toolData.toolName === 'run_command' && toolData.parameters.CommandLine) {
-                const commandLine = toolData.parameters.CommandLine;
-                if (commandLine.includes('test') || commandLine.includes('vitest')) {
-                    sessionState.setCustomState(config.stateDerivation.setState, config.stateDerivation.setValue);
-                    sessionState.setCustomState(`${config.stateDerivation.setState}_timestamp`, new Date().toISOString());
-                }
-            }
-            else {
-                sessionState.setCustomState(config.stateDerivation.setState, config.stateDerivation.setValue);
-                sessionState.setCustomState(`${config.stateDerivation.setState}_timestamp`, new Date().toISOString());
+        if (!config.stateDerivation || toolData.toolName !== config.stateDerivation.fromTool) {
+            return;
+        }
+        // For run_command tool, only update state if command contains test keywords
+        if (toolData.toolName === 'run_command' && toolData.parameters.CommandLine) {
+            const commandLine = toolData.parameters.CommandLine;
+            if (!commandLine.includes('test') && !commandLine.includes('vitest')) {
+                return;
             }
         }
+        this.setStateWithTimestamp(sessionState, config.stateDerivation.setState, config.stateDerivation.setValue);
+    }
+    setStateWithTimestamp(sessionState, key, value) {
+        sessionState.setCustomState(key, value);
+        sessionState.setCustomState(`${key}_timestamp`, new Date().toISOString());
     }
 }
 exports.StateDetector = StateDetector;

package/dist/integrations/vercel.js

@@ -27,7 +27,8 @@ function createWardnMiddleware(config) {
             prompt: content,
             context: { source: "vercel-ai-sdk" },
         });
-        if (!result.allowed) {
+        // v0.3.0: Check action instead of allowed
+        if (result.action === 'block') {
             throw new Error(`Security Violation: ${result.violations[0]?.description || "Blocked by Wardn"}`);
         }
     };

package/dist/middleware/express.js

@@ -29,7 +29,8 @@ function createExpressMiddleware(guard, config) {
                 return next();
             }
             const result = await guard.scan(wardnRequest);
-            if (!result.allowed) {
+            // v0.3.0: Check action instead of allowed
+            if (result.action === 'block') {
                 if (config?.onBlock) {
                     return config.onBlock(req, res, result);
                 }

package/dist/middleware/nextjs.js

@@ -28,7 +28,8 @@ function createNextMiddleware(config) {
                 ip: req.ip || req.headers.get("x-forwarded-for") || "unknown",
             },
         });
-        if (!result.allowed) {
+        // v0.3.0: Check action instead of allowed
+        if (result.action === 'block') {
             return server_1.NextResponse.json({
                 error: "Request blocked by Wardn Security Policy",
                 code: "WARDN_BLOCK",

package/dist/types.d.ts

@@ -2,8 +2,9 @@
  * Rule Schema - Core type definitions for WardnMesh rules
  */
 export type RuleCategory = "workflow" | "quality" | "safety" | "network_boundary" | "supply_chain";
-export type Severity = "critical" | "major" | "minor";
+export type Severity = "critical" | "high" | "medium" | "low";
 export type DetectorType = "sequence" | "state" | "pattern" | "content_analysis" | "semantic";
+export type ThreatAction = "allow" | "block" | "warn" | "log" | "confirm";
 export type EscalationLevel = "none" | "warning" | "critical" | "block";
 export interface SequenceDetectorConfig {
     lookback: number;
@@ -88,6 +89,7 @@ export interface Rule {
     };
     escalation: EscalationConfig;
     autofix?: AutofixConfig;
+    action?: ThreatAction;
 }
 export interface ToolData {
     toolName: string;
@@ -110,6 +112,8 @@ export interface Violation {
     description: string;
     context: ViolationContext;
     timestamp: string;
+    recommendedAction: ThreatAction;
+    scope?: string;
 }
 export interface ViolationContext {
     toolName: string;
@@ -198,9 +202,17 @@ export interface WardnRequest {
     metadata?: Record<string, unknown>;
 }
 export interface ScanResult {
-    allowed: boolean;
+    action: ThreatAction;
     violations: Violation[];
     latencyMs: number;
     metadata: Record<string, unknown>;
+    confirmationDetails?: {
+        message: string;
+        timeout: number;
+        defaultAction: 'allow' | 'block';
+        ruleId: string;
+        ruleName: string;
+        severity: Severity;
+    };
 }
 export type PatternConfig = PatternDetectorConfig;

package/dist/utils/rule-validator.js

@@ -12,7 +12,7 @@ const VALID_DETECTOR_TYPES = [
     "content_analysis",
     "semantic",
 ];
-const VALID_SEVERITIES = ["critical", "major", "minor"];
+const VALID_SEVERITIES = ["critical", "high", "medium", "low"];
 const VALID_CATEGORIES = [
     "workflow",
     "quality",

package/dist/utils/safe-regex.d.ts

@@ -51,3 +51,12 @@ export declare function safeRegexExec(regex: RegExp, content: string, maxLength?
  * Safe regex test with content length limit
  */
 export declare function safeRegexTest(regex: RegExp, content: string, maxLength?: number): boolean;
+/**
+ * Create a safe regex with validation
+ * Throws error if pattern is unsafe
+ */
+export declare function createSafeRegex(pattern: string, flags?: string): RegExp;
+/**
+ * Validate multiple regex patterns
+ */
+export declare function validateRegexPatterns(patterns: string[]): RegexValidationResult;

package/dist/utils/safe-regex.js

@@ -12,18 +12,23 @@ exports.resetPatternErrorMetrics = resetPatternErrorMetrics;
 exports.getCachedRegex = getCachedRegex;
 exports.safeRegexExec = safeRegexExec;
 exports.safeRegexTest = safeRegexTest;
+exports.createSafeRegex = createSafeRegex;
+exports.validateRegexPatterns = validateRegexPatterns;
 const logger_1 = require("./logger");
 // Patterns that are known to cause catastrophic backtracking
+// SECURITY FIX: Detect dangerous patterns in BOTH non-capturing (?...) AND capturing (...) groups
+// VULNERABILITY (v1): Required `\?` which only matched (?...) groups, missing dangerous (...) groups
+// FIX (v2): Remove `\?` requirement to catch all dangerous nested quantifiers
 const DANGEROUS_PATTERNS = [
-    /\(\?[^)]*\+[^)]*\)\+/, // Nested quantifiers with +
-    /\(\?[^)]*\*[^)]*\)\+/, // Nested quantifiers with *
-    /\(\?[^)]*\+[^)]*\)\*/, // Nested quantifiers
-    /\(\?[^)]*\*[^)]*\)\*/, // Nested quantifiers
-    /\([^)]+\)\{[0-9]+,\}/, // Unbounded repetition of groups
-    /\.\*\.\*/, // Multiple greedy wildcards
-    /\.\+\.\+/, // Multiple greedy wildcards
-    /\([^)]*\|[^)]*\)\+/, // Alternation with quantifier
-    /\([^)]*\|[^)]*\)\*/, // Alternation with quantifier
+    /\([^)]*\+[^)]*\)\+/, // Nested quantifiers: (...+...)+  or (?...+...)+
+    /\([^)]*\*[^)]*\)\+/, // Nested quantifiers: (...*...)+  or (?...*...)+
+    /\([^)]*\+[^)]*\)\*/, // Nested quantifiers: (...+...)* or (?...+...)*
+    /\([^)]*\*[^)]*\)\*/, // Nested quantifiers: (...*...)* or (?...*...)*
+    /\([^)]+\)\{[0-9]+,\}/, // Unbounded repetition of groups: (...){10,}
+    /\.\*\.\*/, // Multiple greedy wildcards: .*.*
+    /\.\+\.\+/, // Multiple greedy wildcards: .+.+
+    /\([^)]*\|[^)]*\)\+/, // Alternation with quantifier: (a|b)+
+    /\([^)]*\|[^)]*\)\*/, // Alternation with quantifier: (a|b)*
 ];
 // Maximum allowed regex pattern length
 const MAX_PATTERN_LENGTH = 1000;
@@ -166,7 +171,12 @@ function getCachedRegex(pattern, flags = "") {
     errorMetrics.totalPatternsProcessed++;
     // Convert PCRE modifiers first
     const pcreResult = convertPCREModifiers(pattern);
-    if (pcreResult.converted && pcreResult.error) {
+    // SECURITY FIX: Check for PCRE conversion errors
+    // VULNERABILITY (v1): Condition `converted && error` was always false when error exists
+    //   - When unsupported modifiers found: converted=false, error=truthy
+    //   - Condition: false && truthy = false (check skipped!)
+    // FIX (v2): Check error first, regardless of converted status
+    if (pcreResult.error) {
         // Unsupported PCRE modifiers - skip this pattern
         errorMetrics.pcreConversionFailures++;
         logger_1.logger.warn(`Skipping pattern with unsupported PCRE modifiers: ${pcreResult.error}`);
@@ -218,3 +228,26 @@ function safeRegexTest(regex, content, maxLength = 50000) {
     const safeContent = content.length > maxLength ? content.substring(0, maxLength) : content;
     return regex.test(safeContent);
 }
+/**
+ * Create a safe regex with validation
+ * Throws error if pattern is unsafe
+ */
+function createSafeRegex(pattern, flags = "") {
+    const validation = validateRegexPattern(pattern);
+    if (!validation.valid) {
+        throw new Error(validation.error || "Invalid regex pattern");
+    }
+    return new RegExp(pattern, flags);
+}
+/**
+ * Validate multiple regex patterns
+ */
+function validateRegexPatterns(patterns) {
+    for (const pattern of patterns) {
+        const result = validateRegexPattern(pattern);
+        if (!result.valid) {
+            return result;
+        }
+    }
+    return { valid: true };
+}

package/dist/wardn.d.ts

@@ -33,13 +33,21 @@ export declare class Wardn {
      * @returns ScanResult with allowed/blocked status and violations
      */
     scan(request: WardnRequest): Promise<ScanResult>;
+    /**
+     * v0.3.0: Determine final action based on all violations
+     * Priority: block > confirm > warn > log > allow
+     *
+     * Defensive design: Uses fail-closed approach - defaults to 'block' if
+     * recommendedAction is missing or invalid, ensuring security by default.
+     */
+    private determineAction;
     /** Normalize request to ToolData format */
     private normalizeRequest;
     /** Run detector for a single rule */
     private detectViolation;
     /** Handle semantic detection */
     private detectSemanticViolation;
-    /** Report violation to telemetry */
+    /** Report violation to telemetry (redacts sensitive toolData) */
     private reportViolation;
     /** Report scan completion to telemetry */
     private reportScanComplete;

package/dist/wardn.js

@@ -4,6 +4,7 @@ exports.Wardn = void 0;
 const pattern_1 = require("./detectors/pattern");
 const sequence_1 = require("./detectors/sequence");
 const state_1 = require("./detectors/state");
+const base_1 = require("./detectors/base");
 const safe_regex_1 = require("./utils/safe-regex");
 const update_checker_1 = require("./update-checker");
 const session_manager_1 = require("./state/session-manager");
@@ -175,7 +176,7 @@ class Wardn {
     async scan(request) {
         if (this.isShutdown) {
             return {
-                allowed: true,
+                action: 'allow',
                 violations: [],
                 latencyMs: 0,
                 metadata: { error: true, errorDetails: "Wardn instance is shutdown" },
@@ -201,12 +202,14 @@ class Wardn {
                 if (violation) {
                     violations.push(violation);
                     stateAdapter.addViolation(violation);
-                    this.reportViolation(violation, toolData, currentSessionId);
+                    this.reportViolation(violation, currentSessionId);
                 }
             }
             await this.stateProvider.setState(currentSessionId, stateAdapter.exportState());
+            // v0.3.0: Determine action based on violations
+            const action = this.determineAction(violations);
             const result = {
-                allowed: !violations.some((v) => v.severity === "critical"),
+                action,
                 violations,
                 latencyMs: Date.now() - startTime,
                 metadata: {
@@ -214,6 +217,35 @@ class Wardn {
                     sessionId: currentSessionId,
                 },
             };
+            // v0.4.0: Add confirmation details if action is 'confirm'
+            if (action === 'confirm') {
+                const confirmViolation = violations.find(v => v.recommendedAction === 'confirm');
+                if (confirmViolation) {
+                    // Extract metadata if available, otherwise use defaults
+                    const metadata = (confirmViolation.context.additionalInfo?.metadata || {});
+                    // Generate enhanced default message with violation context
+                    const additionalDetails = confirmViolation.context.additionalInfo?.message
+                        ? `\nDetails: ${confirmViolation.context.additionalInfo.message}`
+                        : '';
+                    const defaultMessage = `⚠️ Security Alert
+
+Rule: ${confirmViolation.ruleName}
+Severity: ${confirmViolation.severity.toUpperCase()}
+Tool: ${confirmViolation.context.toolName}
+
+Description: ${confirmViolation.description}${additionalDetails}
+
+This operation requires your approval to proceed.`;
+                    result.confirmationDetails = {
+                        message: metadata.confirmationMessage || defaultMessage,
+                        timeout: metadata.timeout || 30000,
+                        defaultAction: metadata.defaultAction || 'block',
+                        ruleId: confirmViolation.ruleId,
+                        ruleName: confirmViolation.ruleName,
+                        severity: confirmViolation.severity,
+                    };
+                }
+            }
             this.reportScanComplete(result, currentSessionId);
             return result;
         }
@@ -229,9 +261,9 @@ class Wardn {
                 },
             });
             // Configurable fail mode
-            const allowed = failMode === "open";
+            const action = failMode === "open" ? "allow" : "block";
             return {
-                allowed,
+                action,
                 violations: [],
                 latencyMs: Date.now() - startTime,
                 metadata: {
@@ -242,6 +274,40 @@ class Wardn {
             };
         }
     }
+    /**
+     * v0.3.0: Determine final action based on all violations
+     * Priority: block > confirm > warn > log > allow
+     *
+     * Defensive design: Uses fail-closed approach - defaults to 'block' if
+     * recommendedAction is missing or invalid, ensuring security by default.
+     */
+    determineAction(violations) {
+        if (violations.length === 0) {
+            return 'allow';
+        }
+        // Define action priority order
+        const actionPriority = ['block', 'confirm', 'warn', 'log', 'allow'];
+        const validActions = new Set(actionPriority);
+        // Find highest priority action from all violations
+        for (const action of actionPriority) {
+            const hasAction = violations.some(v => {
+                // Defensive: validate recommendedAction exists and is valid
+                const recommended = v.recommendedAction;
+                if (!recommended || !validActions.has(recommended)) {
+                    // Fail-closed: log warning and treat as 'block'
+                    logger_1.logger.warn(`Invalid recommendedAction '${recommended}' in violation ${v.id}, defaulting to 'block'`);
+                    return action === 'block';
+                }
+                return recommended === action;
+            });
+            if (hasAction) {
+                return action;
+            }
+        }
+        // Fallback: should never reach here, but fail-closed for safety
+        logger_1.logger.warn('determineAction fallback: no valid action found, defaulting to block');
+        return 'block';
+    }
     /** Normalize request to ToolData format */
     normalizeRequest(request) {
         return {
@@ -287,17 +353,17 @@ class Wardn {
                 additionalInfo: { score },
             },
             timestamp: new Date().toISOString(),
+            recommendedAction: (0, base_1.mapSeverityToAction)(rule),
+            scope: 'Semantic analysis',
         };
     }
-    /** Report violation to telemetry */
-    reportViolation(violation, toolData, sessionId) {
-        // REDACTION: Create a safe copy for the cloud
-        const safeViolation = { ...violation };
-        if (safeViolation.context) {
-            // Remove raw toolData (prompts) from the cloud payload
-            const { toolData: _removed, ...safeContext } = safeViolation.context;
-            safeViolation.context = safeContext;
-        }
+    /** Report violation to telemetry (redacts sensitive toolData) */
+    reportViolation(violation, sessionId) {
+        const { toolData: _redacted, ...safeContext } = violation.context;
+        const safeViolation = {
+            ...violation,
+            context: safeContext,
+        };
         this.telemetry.emit({
             eventType: "violation_detected",
             timestamp: new Date().toISOString(),
@@ -311,7 +377,7 @@ class Wardn {
             eventType: "scan_complete",
             timestamp: new Date().toISOString(),
             data: {
-                allowed: result.allowed,
+                action: result.action,
                 latencyMs: result.latencyMs,
                 violationCount: result.violations.length,
             },
@@ -393,14 +459,12 @@ class Wardn {
     async pollRemoteRules() {
         if (!this.config.remoteRulesUrl || this.isShutdown)
             return;
-        const FETCH_TIMEOUT_MS = 10000; // 10 second timeout
         const poll = async () => {
             if (this.isShutdown)
                 return;
             try {
-                // Create AbortController for timeout
                 const controller = new AbortController();
-                const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+                const timeoutId = setTimeout(() => controller.abort(), security_limits_1.SECURITY_LIMITS.FETCH_TIMEOUT_MS);
                 const response = await fetch(this.config.remoteRulesUrl, {
                     headers: {
                         "Accept": "application/json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wardnmesh/sdk-node",
-  "version": "0.2.3",
+  "version": "0.4.1",
   "description": "WardnMesh.AI Node.js SDK - Active Defense Middleware for AI Agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -68,4 +68,4 @@
   "dependencies": {
     "@xenova/transformers": "^2.17.2"
   }
-}
+}