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

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
@@ -30,7 +32,7 @@ npm install @xenova/transformers
 ## Fast Start
 
 ```js
-const { BlackwallShield } = require('blackwall-llm-shield-js');
+const { BlackwallShield } = require('@vpdeva/blackwall-llm-shield-js');
 
 const shield = new BlackwallShield({
   blockOnPromptInjection: true,
@@ -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.
@@ -89,9 +95,9 @@ Use `createExpressMiddleware()`, `createLangChainCallbacks()`, or `createLlamaIn
 
 ### Subpath modules
 
-Use `require('blackwall-llm-shield-js/integrations')` for callback wrappers and `require('blackwall-llm-shield-js/semantic')` for optional local semantic scoring adapters.
+Use `require('@vpdeva/blackwall-llm-shield-js/integrations')` for callback wrappers and `require('@vpdeva/blackwall-llm-shield-js/semantic')` for optional local semantic scoring adapters.
 
-Use `require('blackwall-llm-shield-js/providers')` for provider adapter factories.
+Use `require('@vpdeva/blackwall-llm-shield-js/providers')` for provider adapter factories.
 
 ## Core Building Blocks
 
@@ -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.
@@ -134,7 +151,7 @@ if (!guarded.allowed) {
 ### Wrap a provider call end to end
 
 ```js
-const { BlackwallShield, createOpenAIAdapter } = require('blackwall-llm-shield-js');
+const { BlackwallShield, createOpenAIAdapter } = require('@vpdeva/blackwall-llm-shield-js');
 
 const shield = new BlackwallShield({
   preset: 'shadowFirst',
@@ -184,10 +201,53 @@ 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 { summarizeOperationalTelemetry } = require('@vpdeva/blackwall-llm-shield-js');
+const summary = summarizeOperationalTelemetry(events);
+console.log(summary.byRoute);
+console.log(summary.highestSeverity);
+```
+
+### TypeScript
+
+The package now ships first-class declaration files for the main entry point plus `integrations`, `providers`, and `semantic` subpaths, so local declaration shims should no longer be necessary in TypeScript apps.
+
 ### Inspect model output
 
 ```js
-const { OutputFirewall } = require('blackwall-llm-shield-js');
+const { OutputFirewall } = require('@vpdeva/blackwall-llm-shield-js');
 
 const firewall = new OutputFirewall({
   riskThreshold: 'high',
@@ -204,7 +264,7 @@ console.log(review.allowed);
 ### Gate tool execution
 
 ```js
-const { ToolPermissionFirewall } = require('blackwall-llm-shield-js');
+const { ToolPermissionFirewall } = require('@vpdeva/blackwall-llm-shield-js');
 
 const tools = new ToolPermissionFirewall({
   allowedTools: ['search', 'lookupCustomer'],
@@ -219,6 +279,8 @@ console.log(tools.inspectCall({ tool: 'lookupCustomer', args: { id: 'cus_123' }
 - [`examples/nextjs-app-router/app/api/chat/route.js`](/Users/vishnu/Documents/blackwall-llm-shield/blackwall-llm-shield-js/examples/nextjs-app-router/app/api/chat/route.js) shows guarded request handling in a Next.js route
 - [`examples/admin-dashboard/index.html`](/Users/vishnu/Documents/blackwall-llm-shield/blackwall-llm-shield-js/examples/admin-dashboard/index.html) shows a polished security command center demo
 
+For Next.js, the most production-real patterns are App Router route handlers, server actions for trusted internal mutations, and streaming endpoints that apply output review to assembled or final chunks instead of raw intermediate tokens.
+
 ## Release Commands
 
 - `npm run release:check` runs the JS test suite before release
@@ -227,12 +289,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/index.d.ts

@@ -0,0 +1,92 @@
+export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
+
+export interface MessagePart {
+  type: string;
+  text?: string;
+  image_url?: string;
+  file_id?: string;
+  [key: string]: unknown;
+}
+
+export interface ShieldMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string | MessagePart[] | Record<string, unknown>;
+  trusted?: boolean;
+  contentParts?: MessagePart[];
+}
+
+export interface GuardResult {
+  allowed: boolean;
+  blocked: boolean;
+  reason: string | null;
+  messages: Array<ShieldMessage & { content: string; contentParts?: MessagePart[] }>;
+  report: Record<string, unknown>;
+  vault: Record<string, string>;
+}
+
+export interface ReviewResult {
+  allowed: boolean;
+  severity: RiskLevel;
+  findings: Array<Record<string, unknown>>;
+  report: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface ProviderAdapter {
+  provider: string;
+  invoke(payload: { messages: ShieldMessage[]; metadata?: Record<string, unknown>; guard?: GuardResult }): Promise<unknown> | unknown;
+  extractOutput?(response: unknown, request?: GuardResult): unknown;
+}
+
+export interface ShieldOptions {
+  preset?: string | null;
+  policyPack?: string | null;
+  shadowMode?: boolean;
+  routePolicies?: Array<{ route: string | RegExp | ((route: string, metadata: Record<string, unknown>) => boolean); options: Record<string, unknown> }>;
+  customPromptDetectors?: Array<(payload: Record<string, unknown>) => Record<string, unknown> | Array<Record<string, unknown>> | null>;
+  onTelemetry?: (event: Record<string, unknown>) => void | Promise<void>;
+  [key: string]: unknown;
+}
+
+export class BlackwallShield {
+  constructor(options?: ShieldOptions);
+  inspectText(text: unknown): Record<string, unknown>;
+  guardModelRequest(input?: { messages?: ShieldMessage[]; metadata?: Record<string, unknown>; allowSystemMessages?: boolean; comparePolicyPacks?: string[] }): Promise<GuardResult>;
+  reviewModelResponse(input?: { output: unknown; metadata?: Record<string, unknown>; outputFirewall?: OutputFirewall | null; firewallOptions?: Record<string, unknown> }): Promise<ReviewResult>;
+  protectModelCall(input: Record<string, unknown>): Promise<Record<string, unknown>>;
+  protectWithAdapter(input: { adapter: ProviderAdapter; messages?: ShieldMessage[]; metadata?: Record<string, unknown>; allowSystemMessages?: boolean; comparePolicyPacks?: string[]; outputFirewall?: OutputFirewall | null; firewallOptions?: Record<string, unknown> }): Promise<Record<string, unknown>>;
+}
+
+export class OutputFirewall {
+  constructor(options?: Record<string, unknown>);
+  inspect(output: unknown, options?: Record<string, unknown>): ReviewResult;
+}
+
+export class ToolPermissionFirewall {
+  constructor(options?: Record<string, unknown>);
+  inspectCall(input: Record<string, unknown>): Record<string, unknown>;
+  inspectCallAsync?(input: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+
+export class RetrievalSanitizer {
+  constructor(options?: Record<string, unknown>);
+  sanitizeDocuments(documents: Array<Record<string, unknown>>): Array<Record<string, unknown>>;
+}
+
+export class AuditTrail {
+  constructor(options?: Record<string, unknown>);
+  record(event?: Record<string, unknown>): Record<string, unknown>;
+  summarize(): Record<string, unknown>;
+}
+
+export const SHIELD_PRESETS: Record<string, Record<string, unknown>>;
+export const CORE_INTERFACES: Record<string, string>;
+export const POLICY_PACKS: Record<string, Record<string, unknown>>;
+
+export function buildShieldOptions(options?: Record<string, unknown>): Record<string, unknown>;
+export function summarizeOperationalTelemetry(events?: Array<Record<string, unknown>>): Record<string, unknown>;
+
+export function createOpenAIAdapter(input: Record<string, unknown>): ProviderAdapter;
+export function createAnthropicAdapter(input: Record<string, unknown>): ProviderAdapter;
+export function createGeminiAdapter(input: Record<string, unknown>): ProviderAdapter;
+export function createOpenRouterAdapter(input: Record<string, unknown>): ProviderAdapter;

package/integrations.d.ts

@@ -0,0 +1,18 @@
+export { BlackwallShield, OutputFirewall, type ProviderAdapter } from './index';
+
+export class BlackwallLangChainCallback {
+  constructor(options?: Record<string, unknown>);
+  handleLLMStart(llm: unknown, prompts?: string[]): Promise<unknown>;
+  guardMessages(messages: unknown, metadata?: Record<string, unknown>): Promise<unknown>;
+  handleLLMEnd(output: unknown): Promise<unknown>;
+}
+
+export class BlackwallLlamaIndexCallback {
+  constructor(options?: Record<string, unknown>);
+  onEventStart(event: unknown): Promise<unknown>;
+  onEventEnd(event: unknown): Promise<unknown>;
+}
+
+export function createExpressMiddleware(options?: Record<string, unknown>): (req: unknown, res: unknown, next: () => void) => Promise<void>;
+export function createLangChainCallbacks(options?: Record<string, unknown>): Record<string, unknown>;
+export function createLlamaIndexCallback(options?: Record<string, unknown>): Record<string, unknown>;

package/package.json

@@ -1,16 +1,29 @@
 {
   "name": "@vpdeva/blackwall-llm-shield-js",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "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)",
   "type": "commonjs",
   "main": "src/index.js",
+  "types": "./index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./integrations": "./src/integrations.js",
-    "./providers": "./src/providers.js",
-    "./semantic": "./src/semantic.js"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./integrations": {
+      "types": "./integrations.d.ts",
+      "default": "./src/integrations.js"
+    },
+    "./providers": {
+      "types": "./providers.d.ts",
+      "default": "./src/providers.js"
+    },
+    "./semantic": {
+      "types": "./semantic.d.ts",
+      "default": "./src/semantic.js"
+    }
   },
   "bin": {
     "blackwall-scorecard": "src/scorecard.js"
@@ -26,6 +39,10 @@
   },
   "files": [
     "src",
+    "index.d.ts",
+    "integrations.d.ts",
+    "providers.d.ts",
+    "semantic.d.ts",
     "README.md",
     "LICENSE",
     "NOTICE"

package/providers.d.ts

@@ -0,0 +1,6 @@
+export type { ProviderAdapter } from './index';
+
+export function createOpenAIAdapter(input: Record<string, unknown>): import('./index').ProviderAdapter;
+export function createAnthropicAdapter(input: Record<string, unknown>): import('./index').ProviderAdapter;
+export function createGeminiAdapter(input: Record<string, unknown>): import('./index').ProviderAdapter;
+export function createOpenRouterAdapter(input: Record<string, unknown>): import('./index').ProviderAdapter;

package/semantic.d.ts

@@ -0,0 +1,4 @@
+export class LightweightIntentScorer {
+  constructor(options?: Record<string, unknown>);
+  score(text: unknown, options?: Record<string, unknown>): Record<string, unknown>;
+}

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,56 @@ function createTelemetryEvent(type, payload = {}) {
   };
 }
 
+function summarizeOperationalTelemetry(events = []) {
+  const summary = {
+    totalEvents: 0,
+    blockedEvents: 0,
+    shadowModeEvents: 0,
+    byType: {},
+    byRoute: {},
+    byTenant: {},
+    byModel: {},
+    byPolicyOutcome: {
+      blocked: 0,
+      shadowBlocked: 0,
+      allowed: 0,
+    },
+    topRules: {},
+    highestSeverity: 'low',
+  };
+  for (const event of Array.isArray(events) ? events : []) {
+    const type = event && event.type ? event.type : 'unknown';
+    const metadata = event && event.metadata ? event.metadata : {};
+    const route = metadata.route || metadata.path || 'unknown';
+    const tenant = metadata.tenantId || metadata.tenant_id || 'unknown';
+    const model = metadata.model || metadata.modelName || '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;
+    summary.byTenant[tenant] = (summary.byTenant[tenant] || 0) + 1;
+    summary.byModel[model] = (summary.byModel[model] || 0) + 1;
+    if (event && event.blocked) summary.blockedEvents += 1;
+    if (event && event.shadowMode) summary.shadowModeEvents += 1;
+    if (event && event.blocked) summary.byPolicyOutcome.blocked += 1;
+    else if (event && event.shadowMode) summary.byPolicyOutcome.shadowBlocked += 1;
+    else summary.byPolicyOutcome.allowed += 1;
+    const rules = event && event.report && event.report.promptInjection && Array.isArray(event.report.promptInjection.matches)
+      ? event.report.promptInjection.matches.map((item) => item.id).filter(Boolean)
+      : [];
+    rules.forEach((rule) => {
+      summary.topRules[rule] = (summary.topRules[rule] || 0) + 1;
+    });
+    if (severityWeight(severity) > severityWeight(summary.highestSeverity)) summary.highestSeverity = severity;
+  }
+  summary.topRules = Object.fromEntries(
+    Object.entries(summary.topRules).sort((a, b) => b[1] - a[1]).slice(0, 10)
+  );
+  return summary;
+}
+
 function resolveShieldPreset(name) {
   if (!name) return {};
   return SHIELD_PRESETS[name] ? { ...SHIELD_PRESETS[name] } : {};
@@ -742,11 +868,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 +886,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 +2059,7 @@ module.exports = {
   getRedTeamPromptLibrary,
   runRedTeamSuite,
   buildShieldOptions,
+  summarizeOperationalTelemetry,
   createOpenAIAdapter,
   createAnthropicAdapter,
   createGeminiAdapter,