@wardnmesh/sdk-node 0.2.3 → 0.4.0

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,4 +1,4 @@
-import { ToolData, Violation, Rule, Detector, StateProvider, DetectorType } from '../types';
+import { ToolData, Violation, Rule, Detector, StateProvider, DetectorType, ThreatAction } from '../types';
 /**
  * Abstract base detector class
  *
@@ -11,8 +11,25 @@ export declare abstract class BaseDetector implements Detector {
      * Generate unique violation ID
      */
     protected generateViolationId(): string;
+    /**
+     * v0.4.0: Map 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
+     */
+    protected getRecommendedActionForSeverity(rule: Rule): ThreatAction;
+    /**
+     * v0.3.0: Determine scope description based on rule category
+     */
+    protected getScopeForCategory(category: string): string;
     /**
      * Create violation object
+     * v0.4.0: Use rule.action override for recommendedAction
      */
     protected createViolation(rule: Rule, toolData: ToolData, additionalInfo?: Record<string, unknown>): Violation;
     /**

package/dist/detectors/base.js

@@ -14,8 +14,47 @@ class BaseDetector {
         // Note: Using substring() instead of deprecated substr()
         return `violation_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
     }
+    /**
+     * v0.4.0: Map 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
+     */
+    getRecommendedActionForSeverity(rule) {
+        // Rule action override takes precedence
+        if (rule.action) {
+            return rule.action;
+        }
+        // Default severity-to-action mapping
+        switch (rule.severity) {
+            case 'critical': return 'block';
+            case 'high': return 'confirm'; // v0.4.0: Changed from 'warn' to 'confirm'
+            case 'medium': return 'warn';
+            case 'low': return 'log';
+            default: return 'block';
+        }
+    }
+    /**
+     * v0.3.0: Determine scope description based on rule category
+     */
+    getScopeForCategory(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';
+        }
+    }
     /**
      * Create violation object
+     * v0.4.0: Use rule.action override for recommendedAction
      */
     createViolation(rule, toolData, additionalInfo) {
         return {
@@ -30,7 +69,10 @@ class BaseDetector {
                 filePath: (toolData.parameters.file_path || toolData.parameters.TargetFile || toolData.parameters.AbsolutePath || toolData.parameters.path),
                 additionalInfo
             },
-            timestamp: new Date().toISOString()
+            timestamp: new Date().toISOString(),
+            // v0.4.0: Support rule.action override
+            recommendedAction: this.getRecommendedActionForSeverity(rule),
+            scope: this.getScopeForCategory(rule.category)
         };
     }
     /**

package/dist/detectors/state.js

@@ -25,7 +25,10 @@ class StateDetector extends base_1.BaseDetector {
                         additionalInfo: {
                             message: `Required state '${config.requiredState}' is '${currentState || 'undefined'}', expected '${config.targetStateValue}'.`
                         }
-                    }
+                    },
+                    // v0.4.0: Support rule.action override
+                    recommendedAction: this.getRecommendedActionForSeverity(rule),
+                    scope: this.getScopeForCategory(rule.category)
                 };
             }
             if (config.stateDerivation?.validityDurationMs) {
@@ -46,7 +49,10 @@ class StateDetector extends base_1.BaseDetector {
                                 additionalInfo: {
                                     message: `Required state '${config.requiredState}' has expired (last verified ${Math.floor(timeDiff / 1000)}s ago).`
                                 }
-                            }
+                            },
+                            // v0.4.0: Support rule.action override
+                            recommendedAction: this.getRecommendedActionForSeverity(rule),
+                            scope: this.getScopeForCategory(rule.category)
                         };
                     }
                 }

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/wardn.d.ts

@@ -33,12 +33,32 @@ 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;
+    /**
+     * v0.4.0: Map 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
+     */
+    private getRecommendedActionForSeverity;
     /** Report violation to telemetry */
     private reportViolation;
     /** Report scan completion to telemetry */

package/dist/wardn.js

@@ -175,7 +175,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" },
@@ -205,8 +205,10 @@ class Wardn {
                 }
             }
             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 +216,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 +260,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 +273,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,8 +352,41 @@ class Wardn {
                 additionalInfo: { score },
             },
             timestamp: new Date().toISOString(),
+            // v0.4.0: Set recommended action (rule.action or default severity mapping)
+            recommendedAction: this.getRecommendedActionForSeverity(rule),
+            scope: 'Semantic analysis',
         };
     }
+    /**
+     * v0.4.0: Map 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
+     */
+    getRecommendedActionForSeverity(rule) {
+        // Rule action override takes precedence
+        if (rule.action) {
+            return rule.action;
+        }
+        // Default severity-to-action mapping
+        switch (rule.severity) {
+            case 'critical':
+                return 'block';
+            case 'high':
+                return 'confirm'; // v0.4.0: Changed from 'warn' to 'confirm'
+            case 'medium':
+                return 'warn';
+            case 'low':
+                return 'log';
+            default:
+                return 'block'; // Safe default
+        }
+    }
     /** Report violation to telemetry */
     reportViolation(violation, toolData, sessionId) {
         // REDACTION: Create a safe copy for the cloud
@@ -311,7 +409,7 @@ class Wardn {
             eventType: "scan_complete",
             timestamp: new Date().toISOString(),
             data: {
-                allowed: result.allowed,
+                action: result.action,
                 latencyMs: result.latencyMs,
                 violationCount: result.violations.length,
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wardnmesh/sdk-node",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "description": "WardnMesh.AI Node.js SDK - Active Defense Middleware for AI Agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",