@vpdeva/blackwall-llm-shield-js 0.1.3 → 0.1.5

package/README.md

@@ -14,6 +14,8 @@ JavaScript security middleware for LLM applications in Node.js and Next.js. Blac
 - Emits structured telemetry for prompt risk, masking volume, and output review outcomes
 - Includes first-class provider adapters for OpenAI, Anthropic, Gemini, and OpenRouter
 - Inspects model outputs for leaks, unsafe code, grounding drift, and tone violations
+- Handles mixed text, image, and file message parts more gracefully in text-first multimodal flows
+- Adds operator-friendly telemetry summaries and stronger presets for RAG and agent-tool workflows
 - Ships Express, LangChain, and LlamaIndex integration helpers
 - Enforces allowlists, denylists, validators, and approval-gated tools
 - Sanitizes RAG documents before they are injected into context
@@ -79,6 +81,10 @@ Use `shadowMode` with `shadowPolicyPacks` or `comparePolicyPacks` to record what
 
 Use `createOpenAIAdapter()`, `createAnthropicAdapter()`, `createGeminiAdapter()`, or `createOpenRouterAdapter()` with `protectWithAdapter()` when you want Blackwall to wrap the provider call end to end.
 
+### Observability and control-plane support
+
+Use `summarizeOperationalTelemetry()` with emitted telemetry events when you want route-level summaries, blocked-event counts, and rollout visibility for operators.
+
 ### Output grounding and tone review
 
 `OutputFirewall` can compare responses against retrieved documents and flag hallucination-style unsupported claims or unprofessional tone.
@@ -113,6 +119,17 @@ Use it to allowlist tools, block disallowed tools, validate arguments, and requi
 
 Use it before injecting retrieved documents into context so hostile instructions in your RAG data store do not quietly become model instructions.
 
+### Contract Stability
+
+The 0.1.x line treats `guardModelRequest()`, `protectWithAdapter()`, `reviewModelResponse()`, `ToolPermissionFirewall`, and `RetrievalSanitizer` as the long-term integration contracts. The exported `CORE_INTERFACES` map can be logged or asserted by applications that want to pin expected behavior.
+
+Recommended presets:
+
+- `shadowFirst` for low-friction rollout
+- `strict` for high-sensitivity routes
+- `ragSafe` for retrieval-heavy flows
+- `agentTools` for tool-calling and approval-gated agent actions
+
 ### `AuditTrail`
 
 Use it to record signed events, summarize security activity, and power dashboards or downstream analysis.
@@ -184,6 +201,44 @@ const shield = new BlackwallShield({
 });
 ```
 
+### Route and domain examples
+
+For RAG:
+
+```js
+const shield = new BlackwallShield({
+  preset: 'shadowFirst',
+  routePolicies: [
+    {
+      route: '/api/rag/search',
+      options: {
+        policyPack: 'government',
+        outputFirewallDefaults: {
+          retrievalDocuments: kbDocs,
+        },
+      },
+    },
+  ],
+});
+```
+
+For agent tool-calling:
+
+```js
+const toolFirewall = new ToolPermissionFirewall({
+  allowedTools: ['search', 'lookupCustomer', 'createRefund'],
+  requireHumanApprovalFor: ['createRefund'],
+});
+```
+
+### Operational telemetry summaries
+
+```js
+const summary = summarizeOperationalTelemetry(events);
+console.log(summary.byRoute);
+console.log(summary.highestSeverity);
+```
+
 ### Inspect model output
 
 ```js
@@ -227,12 +282,18 @@ console.log(tools.inspectCall({ tool: 'lookupCustomer', args: { id: 'cus_123' }
 - `npm run changeset` creates a version/changelog entry for the next release
 - `npm run version-packages` applies pending Changesets locally
 
+## Migration and Benchmarks
+
+- See [MIGRATING.md](/Users/vishnu/Documents/blackwall-llm-shield/blackwall-llm-shield-js/MIGRATING.md) for compatibility notes and stable contract guidance
+- See [BENCHMARKS.md](/Users/vishnu/Documents/blackwall-llm-shield/blackwall-llm-shield-js/BENCHMARKS.md) for baseline latency numbers and regression coverage
+
 ## Rollout Notes
 
 - Start with `preset: 'shadowFirst'` or `shadowMode: true` and inspect `report.telemetry` plus `onTelemetry` events before enabling hard blocking.
 - Use `RetrievalSanitizer` and `ToolPermissionFirewall` in front of RAG, search, admin actions, and tool-calling flows.
 - Add regression prompts for instruction overrides, prompt leaks, token leaks, and Australian PII samples so upgrades stay safe.
 - Expect some latency increase from grounding checks, output review, and custom detectors; benchmark with your real prompt and response sizes before enforcing globally.
+- For agent workflows, keep approval-gated tools and route-specific presets separate from end-user chat routes so operators can see distinct risk patterns.
 
 ## Support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpdeva/blackwall-llm-shield-js",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Open-source JavaScript enterprise LLM protection toolkit for Node.js and Next.js",
   "license": "Apache-2.0",
   "author": "Vish <hello@vish.au> (https://vish.au)",

package/src/index.js

@@ -133,6 +133,18 @@ const SHIELD_PRESETS = {
     shadowMode: true,
     allowSystemMessages: true,
   },
+  ragSafe: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'medium',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: true,
+  },
+  agentTools: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'medium',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: false,
+  },
 };
 
 const CORE_INTERFACE_VERSION = '1.0';
@@ -209,6 +221,70 @@ function sanitizeText(input, maxLength = 5000) {
     .slice(0, maxLength);
 }
 
+function stringifyMessageContent(content, maxLength = 5000) {
+  if (typeof content === 'string') return sanitizeText(content, maxLength);
+  if (Array.isArray(content)) {
+    return content
+      .map((item) => {
+        if (typeof item === 'string') return sanitizeText(item, maxLength);
+        if (item && typeof item.text === 'string') return sanitizeText(item.text, maxLength);
+        if (item && item.type === 'text' && typeof item.text === 'string') return sanitizeText(item.text, maxLength);
+        if (item && item.type === 'input_text' && typeof item.text === 'string') return sanitizeText(item.text, maxLength);
+        if (item && item.type === 'image_url') return '[IMAGE_CONTENT]';
+        if (item && item.type === 'file') return '[FILE_CONTENT]';
+        return '';
+      })
+      .filter(Boolean)
+      .join('\n');
+  }
+  if (content && typeof content === 'object') {
+    if (typeof content.text === 'string') return sanitizeText(content.text, maxLength);
+    if (Array.isArray(content.parts)) return stringifyMessageContent(content.parts, maxLength);
+    return sanitizeText(JSON.stringify(content), maxLength);
+  }
+  return sanitizeText(String(content || ''), maxLength);
+}
+
+function normalizeContentParts(content, maxLength = 5000) {
+  if (typeof content === 'string') {
+    return [{ type: 'text', text: sanitizeText(content, maxLength) }].filter((item) => item.text);
+  }
+  if (Array.isArray(content)) {
+    return content.map((item) => {
+      if (typeof item === 'string') return { type: 'text', text: sanitizeText(item, maxLength) };
+      if (!item || typeof item !== 'object') return null;
+      if ((item.type === 'text' || item.type === 'input_text') && typeof item.text === 'string') {
+        return { ...item, text: sanitizeText(item.text, maxLength) };
+      }
+      return { ...item };
+    }).filter(Boolean);
+  }
+  if (content && typeof content === 'object') {
+    if (Array.isArray(content.parts)) return normalizeContentParts(content.parts, maxLength);
+    if (typeof content.text === 'string') return [{ ...content, text: sanitizeText(content.text, maxLength) }];
+    return [{ type: 'json', value: sanitizeText(JSON.stringify(content), maxLength) }];
+  }
+  return [];
+}
+
+function maskContentParts(parts = [], options = {}) {
+  const findings = [];
+  const vault = {};
+  const maskedParts = parts.map((part) => {
+    if (!part || typeof part !== 'object') return part;
+    const textValue = typeof part.text === 'string'
+      ? part.text
+      : (part.type === 'json' && typeof part.value === 'string' ? part.value : null);
+    if (textValue == null) return { ...part };
+    const result = maskValue(textValue, options);
+    findings.push(...result.findings);
+    Object.assign(vault, result.vault);
+    if (typeof part.text === 'string') return { ...part, text: result.masked };
+    return { ...part, value: result.masked };
+  });
+  return { maskedParts, findings, vault };
+}
+
 function placeholder(type, index) {
   return `[${String(type || 'SENSITIVE').toUpperCase()}_${index}]`;
 }
@@ -267,6 +343,31 @@ function createTelemetryEvent(type, payload = {}) {
   };
 }
 
+function summarizeOperationalTelemetry(events = []) {
+  const summary = {
+    totalEvents: 0,
+    blockedEvents: 0,
+    shadowModeEvents: 0,
+    byType: {},
+    byRoute: {},
+    highestSeverity: 'low',
+  };
+  for (const event of Array.isArray(events) ? events : []) {
+    const type = event && event.type ? event.type : 'unknown';
+    const route = event && event.metadata && (event.metadata.route || event.metadata.path) ? (event.metadata.route || event.metadata.path) : 'unknown';
+    const severity = event && event.report && event.report.outputReview
+      ? event.report.outputReview.severity
+      : (event && event.report && event.report.promptInjection ? event.report.promptInjection.level : 'low');
+    summary.totalEvents += 1;
+    summary.byType[type] = (summary.byType[type] || 0) + 1;
+    summary.byRoute[route] = (summary.byRoute[route] || 0) + 1;
+    if (event && event.blocked) summary.blockedEvents += 1;
+    if (event && event.shadowMode) summary.shadowModeEvents += 1;
+    if (severityWeight(severity) > severityWeight(summary.highestSeverity)) summary.highestSeverity = severity;
+  }
+  return summary;
+}
+
 function resolveShieldPreset(name) {
   if (!name) return {};
   return SHIELD_PRESETS[name] ? { ...SHIELD_PRESETS[name] } : {};
@@ -742,11 +843,14 @@ function normalizeMessages(messages = [], options = {}) {
   return (Array.isArray(messages) ? messages : [])
     .slice(-maxMessages)
     .map((message) => {
-      const content = sanitizeText(String(message && message.content ? message.content : ''));
+      const originalContent = message && Object.prototype.hasOwnProperty.call(message, 'content') ? message.content : '';
+      const parts = typeof originalContent === 'string' ? [] : normalizeContentParts(originalContent, options.maxLength || 5000);
+      const content = stringifyMessageContent(originalContent, options.maxLength || 5000);
       if (!content) return null;
       return {
         role: normalizeRole(message.role, allowSystemMessages, !!message.trusted),
         content,
+        contentParts: parts.length ? parts : undefined,
       };
     })
     .filter(Boolean);
@@ -757,16 +861,25 @@ function maskMessages(messages = [], options = {}) {
   const vault = {};
   const masked = (Array.isArray(messages) ? messages : []).map((message) => {
     if (!message || typeof message !== 'object') return null;
+    const normalizedParts = Array.isArray(message.contentParts)
+      ? message.contentParts
+      : (typeof message.content === 'string' ? [] : normalizeContentParts(message.content || '', options.maxLength || 5000));
     const normalized = {
       role: message.role === 'system' ? 'system' : normalizeRole(message.role, false, false),
-      content: sanitizeText(String(message.content || ''), options.maxLength || 5000),
+      content: stringifyMessageContent(message.content || '', options.maxLength || 5000),
+      contentParts: normalizedParts.length ? normalizedParts : undefined,
     };
     if (!normalized.content) return null;
     if (normalized.role === 'system') return normalized;
     const result = maskValue(normalized.content, options);
-    findings.push(...result.findings);
-    Object.assign(vault, result.vault);
-    return { ...normalized, content: result.masked };
+    const partsResult = maskContentParts(normalized.contentParts || [], options);
+    findings.push(...result.findings, ...partsResult.findings);
+    Object.assign(vault, result.vault, partsResult.vault);
+    return {
+      ...normalized,
+      content: result.masked,
+      contentParts: partsResult.maskedParts.length ? partsResult.maskedParts : undefined,
+    };
   }).filter(Boolean);
 
   return {
@@ -1921,6 +2034,7 @@ module.exports = {
   getRedTeamPromptLibrary,
   runRedTeamSuite,
   buildShieldOptions,
+  summarizeOperationalTelemetry,
   createOpenAIAdapter,
   createAnthropicAdapter,
   createGeminiAdapter,