fix: v0.6.1 — fail-safe input coercion across public engine methods

Security checks now coerce null/non-string/garbage input instead of throwing
(found by adversarial QA pass; regression tests added). See CHANGELOG.

Author: jnMetaCode

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.6.1] - 2026-06-05
+
+### Fixed
+- **Input robustness (fail-safe)**: every public engine method (`checkCommand`, `checkInjection`, `scanData`, `checkTool`, `checkPath`, `checkResponse`, `checkAction`, `checkOutbound`, `scanToolDefinition`, `extractTextFields`) now coerces hostile/garbage input (`null`, `undefined`, numbers, objects) instead of throwing — a security check must never crash on the input it inspects. Found by an adversarial QA pass; locked in with regression tests.
+
 ## [0.6.0] - 2026-06-05
 
 ### Added

package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellward",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "mcpName": "io.github.jnMetaCode/shellward",
   "description": "AI agent security & MCP security middleware — prompt injection detection, AI firewall, runtime guardrails & data-loss prevention for LLM tool calls. 8-layer defense against data exfiltration & dangerous commands. Zero dependencies. SDK + OpenClaw plugin. Supports LangChain, AutoGPT, Claude Code, Cursor, OpenAI Agents, Hermes Agent.",
   "keywords": [

server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/jnMetaCode/shellward",
     "source": "github"
   },
-  "version": "0.6.0",
+  "version": "0.6.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "shellward",
-      "version": "0.6.0",
+      "version": "0.6.1",
       "runtime": "node",
       "transport": {
         "type": "stdio"

src/core/engine.ts

@@ -256,6 +256,7 @@ export class ShellWard {
   // ========== L2: Data Scanner ==========
 
   scanData(text: string, toolName?: string): ScanResult {
+    text = asString(text)
     const [, findings] = redactSensitive(text, this.customSensitive)
     const hasSensitiveData = findings.length > 0
     const summary = findings.map(f => `${f.name}(${f.count})`).join(', ')
@@ -282,7 +283,7 @@ export class ShellWard {
   // ========== L3: Tool & Command Checker ==========
 
   checkTool(toolName: string): CheckResult {
-    const toolLower = toolName.toLowerCase()
+    const toolLower = asString(toolName).toLowerCase()
     const enforce = this.config.mode === 'enforce'
 
     // allowedTools always wins — user-trusted tools bypass policy.
@@ -317,7 +318,7 @@ export class ShellWard {
 
   checkCommand(cmd: string, toolName?: string): CheckResult {
     const enforce = this.config.mode === 'enforce'
-    const parts = splitCommands(cmd)
+    const parts = splitCommands(asString(cmd))
 
     for (const part of parts) {
       // Normalize shell-quote obfuscation (e.g. r''m / r""m → rm) before matching.
@@ -346,6 +347,7 @@ export class ShellWard {
   }
 
   checkPath(path: string, operation: 'write' | 'delete', toolName?: string): CheckResult {
+    path = asString(path)
     const enforce = this.config.mode === 'enforce'
     const normalizedPath = normalizePath(path)
 
@@ -372,6 +374,7 @@ export class ShellWard {
   // ========== L4: Injection Detection ==========
 
   checkInjection(text: string, options?: { source?: string; threshold?: number }): InjectionResult {
+    text = asString(text)
     const threshold = options?.threshold ?? this.config.injectionThreshold
     const enforce = this.config.mode === 'enforce'
 
@@ -430,6 +433,7 @@ export class ShellWard {
   // the SDK, the MCP server, or at plugin tool-discovery time.
 
   scanToolDefinition(tool: McpToolDefinition, options?: { threshold?: number }): ToolPoisoningResult {
+    tool = (tool && typeof tool === 'object') ? tool : { name: 'unknown' }
     const threshold = options?.threshold ?? 40
     const findings: ToolPoisoningFinding[] = []
     let score = 0
@@ -507,6 +511,8 @@ export class ShellWard {
   // ========== L5: Security Gate ==========
 
   checkAction(action: string, details: string): CheckResult {
+    action = asString(action)
+    details = asString(details)
     if (action === 'exec' || action === 'shell') {
       return this.checkCommand(details)
     }
@@ -550,6 +556,7 @@ export class ShellWard {
   // ========== L6: Response Checker ==========
 
   checkResponse(content: string): ResponseCheckResult {
+    content = asString(content)
     const canaryLeak = this._canaryToken ? content.includes(this._canaryToken) : false
 
     if (canaryLeak) {
@@ -638,7 +645,8 @@ export class ShellWard {
   }
 
   checkOutbound(toolName: string, params: Record<string, any>): CheckResult {
-    const toolLower = toolName.toLowerCase()
+    params = (params && typeof params === 'object') ? params : {}
+    const toolLower = asString(toolName).toLowerCase()
     const isOutbound = this.outboundTools.has(toolLower)
     const isDualUse = DUAL_USE_TOOLS.has(toolLower)
     const enforce = this.config.mode === 'enforce'
@@ -757,6 +765,7 @@ export class ShellWard {
 
   extractTextFields(args: Record<string, any>): string[] {
     const results: string[] = []
+    if (!args || typeof args !== 'object') return results
     for (const field of TEXT_FIELDS) {
       if (typeof args[field] === 'string' && args[field].length > 0) {
         results.push(args[field])
@@ -841,6 +850,17 @@ function truncate(s: string, max: number): string {
   return s.length > max ? s.slice(0, max) + '...' : s
 }
 
+/**
+ * Defensive coercion at public API boundaries: a security check must fail safe
+ * on hostile/garbage input, never throw. null/undefined → '', everything else
+ * is stringified.
+ */
+function asString(v: unknown): string {
+  if (typeof v === 'string') return v
+  if (v == null) return ''
+  try { return String(v) } catch { return '' }
+}
+
 /**
  * Defeat shell-quote obfuscation for DETECTION (not execution): strip empty
  * quote pairs so `r''m -rf /` and `r""m -rf /` normalize to `rm -rf /`.

test-sdk.ts

@@ -295,6 +295,24 @@ console.log('\n--- 自定义规则 ---')
   test('非法自定义正则被跳过而非崩溃', constructed)
 }
 
+// === 健壮性:对垃圾输入必须 fail-safe(不抛异常)===
+console.log('\n--- 输入健壮性 ---')
+{
+  const g = new ShellWard({ locale: 'zh' })
+  const junk: any[] = [null, undefined, 0, NaN, {}, [], 12345, true]
+  let threw = false
+  for (const v of junk) {
+    try {
+      g.checkCommand(v); g.checkInjection(v); g.scanData(v); g.checkTool(v)
+      g.checkPath(v, 'delete'); g.checkResponse(v); g.checkAction(v, v)
+      g.scanToolDefinition(v); g.checkOutbound(v, v); g.extractTextFields(v)
+    } catch { threw = true }
+  }
+  test('所有公共方法对 null/非字符串输入不抛异常', !threw)
+  test('null 输入按安全默认处理(checkCommand 放行空)', g.checkCommand(null as any).allowed)
+  test('null injection 安全', g.checkInjection(null as any).safe)
+}
+
 // === Summary ===
 console.log('\n========================================')
 console.log(`  SDK 测试结果: ${passed} 通过, ${failed} 失败 (共 ${passed + failed} 项)`)