@wardnmesh/sdk-node 0.4.1 → 0.4.5

package/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog
+
+All notable changes to @wardnmesh/sdk-node will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] - 2026-01-17
+
+### 🚨 Breaking Changes
+
+**Action-Based Architecture**: Replaces boolean `allowed` field with granular action types.
+
+- **`ScanResult.allowed` → `ScanResult.action`**
+  - Type: `boolean` → `ThreatAction` (`'block'` | `'confirm'` | `'warn'` | `'log'` | `'allow'`)
+  - Provides fine-grained control over threat response
+  - Enables user confirmation for high-risk operations
+
+### Added
+
+- **Confirmation Support** (`action: 'confirm'`)
+  - New `confirmationDetails` field in `ScanResult`
+  - Pre-formatted confirmation messages with context
+  - Configurable timeout and default action
+  - Designed for user approval dialogs in CLI/UI
+
+- **Action Priority System**
+  - `determineAction()` method with priority: `block` > `confirm` > `warn` > `log` > `allow`
+  - Defensive fail-closed design: defaults to `'block'` on invalid actions
+  - Comprehensive validation with fallback safety
+
+- **Enhanced Violation Metadata**
+  - Added `recommendedAction: ThreatAction` field to `Violation`
+  - Added `scope: string` field for categorization
+  - Richer context for decision-making
+
+### Changed
+
+- **Core API**: `scan()` now returns `action` instead of `allowed`
+- **Middleware**: Callbacks now receive full `ScanResult` instead of just `violations`
+- **Error Handling**: Invalid `recommendedAction` values trigger warnings and fail-closed
+
+### Fixed
+
+- **Defensive Design**: Prevents security bypass from missing/invalid `recommendedAction`
+- **Type Safety**: All violation fields properly validated before action determination
+
+### Migration
+
+See [MIGRATION_v0.4.0.md](MIGRATION_v0.4.0.md) for detailed upgrade guide.
+
+**Quick Migration**:
+```typescript
+// Before (v0.2.3)
+if (!result.allowed) { throw new Error('Blocked'); }
+
+// After (v0.4.0)
+if (result.action === 'block') { throw new Error('Blocked'); }
+```
+
+### Testing
+
+- ✅ 17 tests passing (4 test suites)
+- ✅ All action types validated
+- ✅ Confirmation flow tested
+- ✅ Fail-closed behavior verified
+
+---
+
+## [0.2.3] - 2026-01-16
+
+### Fixed
+
+- Improved severity-to-action mapping in integrations
+- Enhanced error handling with better null checks
+
+### Documentation
+
+- Updated examples with current API patterns
+- Clarified rule configuration options
+
+---
+
+## [0.2.0] - 2026-01-15
+
+### Added
+
+- **Semantic Analysis**: ML-based threat detection using local models
+- **State Tracking**: Session-aware detection for multi-turn attacks
+- **Pattern Detectors**: Regex-based threat pattern matching
+- **Sequence Detectors**: Multi-step attack pattern recognition
+
+### Changed
+
+- Unified detector API for all detection types
+- Improved telemetry with detailed metrics
+
+### Performance
+
+- <20ms latency for most scans
+- Local-first processing (no external API calls)
+- Lazy loading for ML models
+
+---
+
+## [0.1.0] - 2026-01-10
+
+### Added
+
+- Initial release of WardnMesh SDK for Node.js
+- Core `Wardn` class with singleton pattern
+- Basic threat detection for:
+  - PII (Personal Identifiable Information)
+  - Prompt injection patterns
+  - API key leakage
+- Express middleware support
+- Next.js middleware support
+- Vercel AI SDK integration
+- Local rule management
+
+### Features
+
+- Rule-based scanning engine
+- Configurable severity levels
+- Telemetry and reporting
+- Extensible detector system
+- TypeScript support with full type definitions
+
+---
+
+## Version Compatibility
+
+| SDK Version | MCP Server | Node.js | Status |
+|-------------|------------|---------|--------|
+| 0.4.0 | 0.2.3+ | 18+ | ✅ Current |
+| 0.2.3 | 0.2.0+ | 18+ | ⚠️ Legacy |
+| 0.2.0 | 0.2.0+ | 18+ | ⚠️ Legacy |
+| 0.1.0 | 0.1.0+ | 18+ | ❌ Deprecated |
+
+---
+
+## Links
+
+- [NPM Package](https://www.npmjs.com/package/@wardnmesh/sdk-node)
+- [GitHub Repository](https://github.com/PCIRCLE-AI/wardnmesh)
+- [Documentation](https://wardnmesh.ai/docs/sdk)
+- [Migration Guides](MIGRATION_v0.4.0.md)

package/README.md

@@ -1,6 +1,6 @@
 # @wardnmesh/sdk-node
 
-> **Latest Version: v0.4.0** (Released 2026-01-17)
+> **Latest Version: v0.4.5** (Released 2026-01-19)
 
 **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.
 
@@ -26,9 +26,9 @@
 ## Installation
 
 ```bash
-npm install @wardnmesh/sdk-node@0.4.0
+npm install @wardnmesh/sdk-node@latest
 # or
-yarn add @wardnmesh/sdk-node@0.4.0
+yarn add @wardnmesh/sdk-node@latest
 ```
 
 ## v0.4.0 API Overview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wardnmesh/sdk-node",
-  "version": "0.4.1",
+  "version": "0.4.5",
   "description": "WardnMesh.AI Node.js SDK - Active Defense Middleware for AI Agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,7 +29,8 @@
     "dist",
     "bin",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -42,18 +43,23 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/PCIRCLE-AI/wardnmesh.git"
+    "url": "git+https://github.com/PCIRCLE-AI/wardnmesh-sdk-node.git"
   },
   "bugs": {
-    "url": "https://github.com/PCIRCLE-AI/wardnmesh/issues"
+    "url": "https://github.com/PCIRCLE-AI/wardnmesh-sdk-node/issues"
   },
   "homepage": "https://wardnmesh.ai",
   "author": "KT",
   "license": "Elastic-2.0",
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=9.0.0"
+  },
   "devDependencies": {
     "@types/jest": "^29.5.11",
     "@types/node": "^20.10.0",
     "jest": "^29.7.0",
+    "next": "^14.2.35",
     "ts-jest": "^29.1.1",
     "typescript": "^5.0.0"
   },

package/dist/agent-guard.d.ts

@@ -1,28 +0,0 @@
-import { AgentGuardConfig, ScanResult, AgentRequest } from "./types";
-import { SessionStateProvider } from "./state/session-manager";
-export declare class AgentGuard {
-    private static instance;
-    private config;
-    private stateProvider;
-    private telemetry;
-    private patternDetector;
-    private sequenceDetector;
-    private stateDetector;
-    private semanticDetector;
-    private constructor();
-    private initTelemetry;
-    static getInstance(): AgentGuard;
-    static init(config: AgentGuardConfig, stateProvider?: SessionStateProvider): AgentGuard;
-    /** Main entry point to scan an agent request */
-    scan(request: AgentRequest): Promise<ScanResult>;
-    /** Normalize request to ToolData format */
-    private normalizeRequest;
-    /** Run detector for a single rule */
-    private detectViolation;
-    /** Handle semantic detection */
-    private detectSemanticViolation;
-    /** Report violation to telemetry */
-    private reportViolation;
-    /** Report scan completion to telemetry */
-    private reportScanComplete;
-}

package/dist/agent-guard.js

@@ -1,206 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentGuard = void 0;
-const pattern_1 = require("./detectors/pattern");
-const sequence_1 = require("./detectors/sequence");
-const state_1 = require("./detectors/state");
-const session_manager_1 = require("./state/session-manager");
-const reporter_1 = require("./telemetry/reporter");
-const semantic_detector_1 = require("./detectors/semantic-detector");
-/** Synchronous state adapter for in-request state management */
-class SyncStateAdapter {
-    constructor(initialState, maxHistory = 50) {
-        this.maxHistory = maxHistory;
-        this.state = {
-            startTime: initialState.startTime || new Date().toISOString(),
-            toolCalls: initialState.toolCalls || [],
-            recentTools: initialState.recentTools || [],
-            detectedViolations: initialState.detectedViolations || [],
-            customState: initialState.customState || {},
-            currentFile: initialState.currentFile,
-        };
-    }
-    getRecentTools(count) {
-        const tools = this.state.recentTools || [];
-        return count ? tools.slice(-count) : tools;
-    }
-    setCustomState(key, value) {
-        this.state.customState[key] = value;
-    }
-    getCustomState(key) {
-        return this.state.customState[key];
-    }
-    addToolCall(tool) {
-        if (!this.state.recentTools)
-            this.state.recentTools = [];
-        this.state.recentTools.push(tool);
-        if (this.state.recentTools.length > this.maxHistory) {
-            this.state.recentTools.shift();
-        }
-    }
-    exportState() {
-        return this.state;
-    }
-}
-class AgentGuard {
-    constructor(config, stateProvider) {
-        this.config = config;
-        this.stateProvider = stateProvider || new session_manager_1.InMemorySessionStateProvider();
-        this.telemetry = this.initTelemetry();
-        this.patternDetector = new pattern_1.PatternDetector();
-        this.sequenceDetector = new sequence_1.SequenceDetector();
-        this.stateDetector = new state_1.StateDetector();
-        this.semanticDetector = semantic_detector_1.SemanticDetector.getInstance();
-        // Emit startup event
-        this.telemetry.emit({
-            eventType: "agent_started",
-            timestamp: new Date().toISOString(),
-            data: {
-                config: {
-                    appName: this.config.telemetry?.serviceName,
-                    ruleCount: this.config.rules.length,
-                },
-            },
-        });
-    }
-    initTelemetry() {
-        if (this.config.telemetry?.enabled && process.env.CCB_ENDPOINT) {
-            return new reporter_1.CCBReporter(process.env.CCB_ENDPOINT, process.env.CCB_API_KEY || "", this.config.telemetry.serviceName || "unknown-service");
-        }
-        return new reporter_1.ConsoleReporter();
-    }
-    static getInstance() {
-        if (!AgentGuard.instance) {
-            throw new Error("AgentGuard not initialized. Call AgentGuard.init() first.");
-        }
-        return AgentGuard.instance;
-    }
-    static init(config, stateProvider) {
-        AgentGuard.instance = new AgentGuard(config, stateProvider);
-        return AgentGuard.instance;
-    }
-    /** Main entry point to scan an agent request */
-    async scan(request) {
-        const start = Date.now();
-        const violations = [];
-        const sessionId = request.sessionId || "default";
-        try {
-            const rawState = await this.stateProvider.getState(sessionId);
-            const stateAdapter = new SyncStateAdapter(rawState, this.config.maxHistorySize);
-            const toolData = this.normalizeRequest(request);
-            stateAdapter.addToolCall(toolData);
-            // Lazy load semantic model if needed
-            if (this.config.rules.some((r) => r.detector.type === "semantic")) {
-                await this.semanticDetector.init();
-            }
-            // Run all detectors
-            for (const rule of this.config.rules) {
-                const violation = await this.detectViolation(rule, toolData, stateAdapter);
-                if (violation) {
-                    violations.push(violation);
-                    this.reportViolation(violation, toolData, sessionId);
-                }
-            }
-            await this.stateProvider.setState(sessionId, stateAdapter.exportState());
-            const result = {
-                allowed: !violations.some((v) => v.severity === "critical"),
-                violations,
-                latencyMs: Date.now() - start,
-                metadata: { analyzedRules: this.config.rules.length },
-            };
-            this.reportScanComplete(result, sessionId);
-            return result;
-        }
-        catch (error) {
-            // Fail-Open Resilience: Never crash the application
-            console.error("[AgentGuard] Scan failed, failing open:", error);
-            this.telemetry.emit({
-                eventType: "error",
-                timestamp: new Date().toISOString(),
-                data: {
-                    error: error instanceof Error ? error.message : "Unknown error",
-                    sessionId,
-                },
-            });
-            return {
-                allowed: true, // Fail-open
-                violations: [],
-                latencyMs: Date.now() - start,
-                metadata: {
-                    error: true,
-                    errorDetails: error instanceof Error ? error.message : "Unknown",
-                },
-            };
-        }
-    }
-    /** Normalize request to ToolData format */
-    normalizeRequest(request) {
-        return {
-            toolName: request.toolName || "llm_input",
-            parameters: request.parameters || { prompt: request.prompt || "" },
-            result: { success: true },
-            duration: 0,
-            timestamp: new Date().toISOString(),
-        };
-    }
-    /** Run detector for a single rule */
-    async detectViolation(rule, toolData, stateAdapter) {
-        switch (rule.detector.type) {
-            case "pattern":
-                return this.patternDetector.detect(toolData, rule, stateAdapter);
-            case "sequence":
-                return this.sequenceDetector.detect(toolData, rule, stateAdapter);
-            case "state":
-                return this.stateDetector.detect(toolData, rule, stateAdapter);
-            case "semantic":
-                return this.detectSemanticViolation(rule, toolData);
-            default:
-                return null;
-        }
-    }
-    /** Handle semantic detection */
-    async detectSemanticViolation(rule, toolData) {
-        const prompt = toolData.parameters.prompt ||
-            JSON.stringify(toolData.parameters);
-        const config = rule.detector.config;
-        const { detected, reason, score } = await this.semanticDetector.scan(prompt, config.threshold || 0.75);
-        if (!detected)
-            return null;
-        return {
-            id: crypto.randomUUID(),
-            ruleId: rule.id,
-            ruleName: rule.name,
-            severity: rule.severity,
-            description: reason || "Semantic Violation",
-            context: {
-                toolName: toolData.toolName,
-                toolData,
-                additionalInfo: { score },
-            },
-            timestamp: new Date().toISOString(),
-        };
-    }
-    /** Report violation to telemetry */
-    reportViolation(violation, toolData, sessionId) {
-        this.telemetry.emit({
-            eventType: "violation_detected",
-            timestamp: new Date().toISOString(),
-            data: { violation, toolData },
-            metadata: { sessionId },
-        });
-    }
-    /** Report scan completion to telemetry */
-    reportScanComplete(result, sessionId) {
-        this.telemetry.emit({
-            eventType: "scan_complete",
-            timestamp: new Date().toISOString(),
-            data: {
-                allowed: result.allowed,
-                latencyMs: result.latencyMs,
-                violationCount: result.violations.length,
-            },
-            metadata: { sessionId },
-        });
-    }
-}
-exports.AgentGuard = AgentGuard;