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

package/README.md

@@ -12,7 +12,10 @@ JavaScript security middleware for LLM applications in Node.js and Next.js. Blac
 - Supports shadow mode and side-by-side policy-pack evaluation
 - Notifies webhooks or alert handlers when risky traffic appears
 - 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
@@ -74,6 +77,14 @@ console.log(guarded.report);
 
 Use `shadowMode` with `shadowPolicyPacks` or `comparePolicyPacks` to record what would have been blocked without interrupting traffic.
 
+### Provider adapters and stable wrappers
+
+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.
@@ -86,13 +97,15 @@ Use `createExpressMiddleware()`, `createLangChainCallbacks()`, or `createLlamaIn
 
 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('blackwall-llm-shield-js/providers')` for provider adapter factories.
+
 ## Core Building Blocks
 
 ### `BlackwallShield`
 
 Use it to sanitize inbound messages, mask sensitive data, score prompt-injection risk, and decide whether the request should continue to the model provider.
 
-It also exposes `protectModelCall()` and `reviewModelResponse()` so you can enforce request checks before OpenAI or Anthropic calls and review outputs before they go back to the user.
+It also exposes `protectModelCall()`, `protectWithAdapter()`, and `reviewModelResponse()` so you can enforce request checks before provider calls and review outputs before they go back to the user.
 
 ### `OutputFirewall`
 
@@ -106,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.
@@ -127,19 +151,22 @@ if (!guarded.allowed) {
 ### Wrap a provider call end to end
 
 ```js
+const { BlackwallShield, createOpenAIAdapter } = require('blackwall-llm-shield-js');
+
 const shield = new BlackwallShield({
-  shadowMode: true,
+  preset: 'shadowFirst',
   onTelemetry: async (event) => console.log(JSON.stringify(event)),
 });
 
-const result = await shield.protectModelCall({
+const adapter = createOpenAIAdapter({
+  client: openai,
+  model: 'gpt-4.1-mini',
+});
+
+const result = await shield.protectWithAdapter({
+  adapter,
   messages: [{ role: 'user', content: 'Summarize this shipment exception.' }],
   metadata: { route: '/api/chat', tenantId: 'au-commerce', userId: 'ops-7' },
-  callModel: async ({ messages }) => openai.responses.create({
-    model: 'gpt-4.1-mini',
-    input: messages.map((msg) => `${msg.role}: ${msg.content}`).join('\n'),
-  }),
-  mapOutput: (response) => response.output_text,
   firewallOptions: {
     retrievalDocuments: [
       { id: 'kb-1', content: 'Shipment exceptions should include the parcel ID, lane, and next action.' },
@@ -150,6 +177,68 @@ const result = await shield.protectModelCall({
 console.log(result.stage, result.allowed);
 ```
 
+### Use presets and route-level policy overrides
+
+```js
+const shield = new BlackwallShield({
+  preset: 'shadowFirst',
+  routePolicies: [
+    {
+      route: '/api/admin/*',
+      options: {
+        preset: 'strict',
+        policyPack: 'finance',
+      },
+    },
+    {
+      route: '/api/health',
+      options: {
+        shadowMode: true,
+        suppressPromptRules: ['ignore_instructions'],
+      },
+    },
+  ],
+});
+```
+
+### 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
@@ -190,12 +279,21 @@ console.log(tools.inspectCall({ tool: 'lookupCustomer', args: { id: 'cus_123' }
 - `npm run release:check` runs the JS test suite before release
 - `npm run release:pack` creates the local npm tarball
 - `npm run release:publish` publishes the package to npm
+- `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 `shadowMode: true` and inspect `report.telemetry` plus `onTelemetry` events before enabling hard blocking.
+- 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.2",
+  "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)",
@@ -9,6 +9,7 @@
   "exports": {
     ".": "./src/index.js",
     "./integrations": "./src/integrations.js",
+    "./providers": "./src/providers.js",
     "./semantic": "./src/semantic.js"
   },
   "bin": {
@@ -16,6 +17,9 @@
   },
   "scripts": {
     "test": "node --test tests/*.test.js",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "changeset publish",
     "release:check": "npm test",
     "release:pack": "npm pack",
     "release:publish": "npm publish --access public --provenance"
@@ -49,5 +53,8 @@
     "enterprise",
     "nextjs",
     "node"
-  ]
+  ],
+  "devDependencies": {
+    "@changesets/cli": "^2.29.6"
+  }
 }

package/src/index.js

@@ -1,5 +1,11 @@
 const crypto = require('crypto');
 const RED_TEAM_PROMPT_LIBRARY = require('./red_team_prompts.json');
+const {
+  createOpenAIAdapter,
+  createAnthropicAdapter,
+  createGeminiAdapter,
+  createOpenRouterAdapter,
+} = require('./providers');
 
 const SENSITIVE_PATTERNS = {
   email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
@@ -100,6 +106,56 @@ const POLICY_PACKS = {
   },
 };
 
+const SHIELD_PRESETS = {
+  balanced: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'high',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: false,
+  },
+  shadowFirst: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'medium',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: true,
+  },
+  strict: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'medium',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: false,
+    allowSystemMessages: false,
+  },
+  developerFriendly: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'high',
+    notifyOnRiskLevel: 'high',
+    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';
+const CORE_INTERFACES = Object.freeze({
+  guardModelRequest: CORE_INTERFACE_VERSION,
+  reviewModelResponse: CORE_INTERFACE_VERSION,
+  protectModelCall: CORE_INTERFACE_VERSION,
+  toolPermissionFirewall: CORE_INTERFACE_VERSION,
+  retrievalSanitizer: CORE_INTERFACE_VERSION,
+});
+
 const RISK_ORDER = ['low', 'medium', 'high', 'critical'];
 const LEETSPEAK_MAP = { '0': 'o', '1': 'i', '3': 'e', '4': 'a', '5': 's', '7': 't', '@': 'a', '$': 's' };
 const TOXICITY_PATTERNS = [
@@ -165,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}]`;
 }
@@ -223,6 +343,154 @@ 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] } : {};
+}
+
+function dedupeArray(values = []) {
+  return [...new Set((Array.isArray(values) ? values : []).filter(Boolean))];
+}
+
+function routePatternMatches(pattern, route = '', metadata = {}) {
+  if (!pattern) return false;
+  if (typeof pattern === 'function') return !!pattern(route, metadata);
+  if (pattern instanceof RegExp) return pattern.test(route);
+  if (typeof pattern === 'string') {
+    if (pattern === route) return true;
+    if (pattern.includes('*')) {
+      const regex = new RegExp(`^${pattern.split('*').map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`);
+      return regex.test(route);
+    }
+  }
+  return false;
+}
+
+function resolveRoutePolicy(routePolicies = [], metadata = {}) {
+  const route = metadata.route || metadata.path || '';
+  const matched = (Array.isArray(routePolicies) ? routePolicies : []).filter((entry) => routePatternMatches(entry && entry.route, route, metadata));
+  if (!matched.length) return null;
+  return matched.reduce((acc, entry) => {
+    const options = entry && entry.options ? entry.options : {};
+    return {
+      ...acc,
+      ...options,
+      shadowPolicyPacks: dedupeArray([...(acc.shadowPolicyPacks || []), ...(options.shadowPolicyPacks || [])]),
+      entityDetectors: [...(acc.entityDetectors || []), ...(options.entityDetectors || [])],
+      customPromptDetectors: [...(acc.customPromptDetectors || []), ...(options.customPromptDetectors || [])],
+      suppressPromptRules: dedupeArray([...(acc.suppressPromptRules || []), ...(options.suppressPromptRules || [])]),
+    };
+  }, {});
+}
+
+function applyPromptRuleSuppressions(injection, suppressedIds = []) {
+  const suppressionSet = new Set(dedupeArray(suppressedIds));
+  if (!suppressionSet.size) return injection;
+  const matches = (injection.matches || []).filter((item) => !suppressionSet.has(item.id));
+  const score = Math.min(matches.reduce((sum, item) => sum + (item.score || 0), 0), 100);
+  return {
+    ...injection,
+    matches,
+    score,
+    level: riskLevelFromScore(score),
+    blockedByDefault: score >= 45,
+  };
+}
+
+function applyCustomPromptDetectors(injection, text, options = {}, metadata = {}) {
+  const detectors = Array.isArray(options.customPromptDetectors) ? options.customPromptDetectors : [];
+  if (!detectors.length) return injection;
+  const matches = [...(injection.matches || [])];
+  const seen = new Set(matches.map((item) => item.id));
+  let score = injection.score || 0;
+  for (const detector of detectors) {
+    if (typeof detector !== 'function') continue;
+    const result = detector({ text, injection, metadata, options }) || [];
+    const findings = Array.isArray(result) ? result : [result];
+    for (const finding of findings) {
+      if (!finding || !finding.id || seen.has(finding.id)) continue;
+      seen.add(finding.id);
+      matches.push({
+        id: finding.id,
+        score: Math.max(0, Math.min(finding.score || 0, 40)),
+        reason: finding.reason || 'Custom prompt detector triggered',
+        source: finding.source || 'custom',
+      });
+      score += Math.max(0, Math.min(finding.score || 0, 40));
+    }
+  }
+  const cappedScore = Math.min(score, 100);
+  return {
+    ...injection,
+    matches,
+    score: cappedScore,
+    level: riskLevelFromScore(cappedScore),
+    blockedByDefault: cappedScore >= 45,
+  };
+}
+
+function resolveEffectiveShieldOptions(baseOptions = {}, metadata = {}) {
+  const presetOptions = resolveShieldPreset(baseOptions.preset);
+  const routePolicy = resolveRoutePolicy(baseOptions.routePolicies, metadata);
+  const routePresetOptions = resolveShieldPreset(routePolicy && routePolicy.preset);
+  return {
+    ...baseOptions,
+    ...presetOptions,
+    ...routePresetOptions,
+    ...(routePolicy || {}),
+    shadowPolicyPacks: dedupeArray([
+      ...((presetOptions && presetOptions.shadowPolicyPacks) || []),
+      ...((routePresetOptions && routePresetOptions.shadowPolicyPacks) || []),
+      ...(baseOptions.shadowPolicyPacks || []),
+      ...((routePolicy && routePolicy.shadowPolicyPacks) || []),
+    ]),
+    entityDetectors: [
+      ...((presetOptions && presetOptions.entityDetectors) || []),
+      ...((routePresetOptions && routePresetOptions.entityDetectors) || []),
+      ...(baseOptions.entityDetectors || []),
+      ...((routePolicy && routePolicy.entityDetectors) || []),
+    ],
+    customPromptDetectors: [
+      ...((presetOptions && presetOptions.customPromptDetectors) || []),
+      ...((routePresetOptions && routePresetOptions.customPromptDetectors) || []),
+      ...(baseOptions.customPromptDetectors || []),
+      ...((routePolicy && routePolicy.customPromptDetectors) || []),
+    ],
+    suppressPromptRules: dedupeArray([
+      ...((presetOptions && presetOptions.suppressPromptRules) || []),
+      ...((routePresetOptions && routePresetOptions.suppressPromptRules) || []),
+      ...(baseOptions.suppressPromptRules || []),
+      ...((routePolicy && routePolicy.suppressPromptRules) || []),
+    ]),
+    routePolicy,
+  };
+}
+
 function cloneRegex(regex) {
   return new RegExp(regex.source, regex.flags);
 }
@@ -575,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);
@@ -590,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 {
@@ -748,14 +1028,19 @@ class BlackwallShield {
       maxLength: 5000,
       allowSystemMessages: false,
       shadowMode: false,
+      preset: null,
       policyPack: null,
       shadowPolicyPacks: [],
       entityDetectors: [],
+      customPromptDetectors: [],
+      suppressPromptRules: [],
+      routePolicies: [],
       detectNamedEntities: false,
       semanticScorer: null,
       sessionBuffer: null,
       tokenBudgetFirewall: null,
       systemPrompt: null,
+      outputFirewallDefaults: {},
       onAlert: null,
       onTelemetry: null,
       webhookUrl: null,
@@ -764,10 +1049,13 @@ class BlackwallShield {
   }
 
   inspectText(text) {
-    const pii = maskValue(text, this.options);
-    const injection = detectPromptInjection(text, this.options);
+    const effectiveOptions = resolveEffectiveShieldOptions(this.options);
+    const pii = maskValue(text, effectiveOptions);
+    let injection = detectPromptInjection(text, effectiveOptions);
+    injection = applyCustomPromptDetectors(injection, String(text || ''), effectiveOptions, {});
+    injection = applyPromptRuleSuppressions(injection, effectiveOptions.suppressPromptRules);
     return {
-      sanitized: pii.original || sanitizeText(text, this.options.maxLength),
+      sanitized: pii.original || sanitizeText(text, effectiveOptions.maxLength),
       promptInjection: injection,
       sensitiveData: {
         findings: pii.findings,
@@ -792,35 +1080,43 @@ class BlackwallShield {
   }
 
   async guardModelRequest({ messages = [], metadata = {}, allowSystemMessages = this.options.allowSystemMessages, comparePolicyPacks = [] } = {}) {
+    const effectiveOptions = resolveEffectiveShieldOptions(this.options, metadata);
+    const effectiveAllowSystemMessages = allowSystemMessages === this.options.allowSystemMessages
+      ? effectiveOptions.allowSystemMessages
+      : allowSystemMessages;
     const normalizedMessages = normalizeMessages(messages, {
-      maxMessages: this.options.maxMessages,
-      allowSystemMessages,
+      maxMessages: effectiveOptions.maxMessages,
+      allowSystemMessages: effectiveAllowSystemMessages,
     });
     const masked = maskMessages(normalizedMessages, {
-      includeOriginals: this.options.includeOriginals,
-      syntheticReplacement: this.options.syntheticReplacement,
-      maxLength: this.options.maxLength,
-      allowSystemMessages,
+      includeOriginals: effectiveOptions.includeOriginals,
+      syntheticReplacement: effectiveOptions.syntheticReplacement,
+      maxLength: effectiveOptions.maxLength,
+      allowSystemMessages: effectiveAllowSystemMessages,
+      entityDetectors: effectiveOptions.entityDetectors,
+      detectNamedEntities: effectiveOptions.detectNamedEntities,
     });
     const promptCandidate = normalizedMessages.filter((msg) => msg.role !== 'assistant');
-    const sessionBuffer = this.options.sessionBuffer;
+    const sessionBuffer = effectiveOptions.sessionBuffer;
     if (sessionBuffer && typeof sessionBuffer.record === 'function') {
       promptCandidate.forEach((msg) => sessionBuffer.record(msg.content));
     }
     const sessionContext = sessionBuffer && typeof sessionBuffer.render === 'function'
       ? sessionBuffer.render()
       : promptCandidate;
-    const injection = detectPromptInjection(sessionContext, this.options);
-
-    const primaryPolicy = resolvePolicyPack(this.options.policyPack);
-    const threshold = (primaryPolicy && primaryPolicy.promptInjectionThreshold) || this.options.promptInjectionThreshold;
-    const wouldBlock = this.options.blockOnPromptInjection && compareRisk(injection.level, threshold);
-    const shouldBlock = this.options.shadowMode ? false : wouldBlock;
-    const shouldNotify = compareRisk(injection.level, this.options.notifyOnRiskLevel);
-    const policyNames = [...new Set([...(this.options.shadowPolicyPacks || []), ...comparePolicyPacks].filter(Boolean))];
-    const policyComparisons = policyNames.map((name) => evaluatePolicyPack(injection, name, this.options.promptInjectionThreshold));
-    const budgetResult = this.options.tokenBudgetFirewall && typeof this.options.tokenBudgetFirewall.inspect === 'function'
-      ? this.options.tokenBudgetFirewall.inspect({
+    let injection = detectPromptInjection(sessionContext, effectiveOptions);
+    injection = applyCustomPromptDetectors(injection, Array.isArray(sessionContext) ? JSON.stringify(sessionContext) : String(sessionContext || ''), effectiveOptions, metadata);
+    injection = applyPromptRuleSuppressions(injection, effectiveOptions.suppressPromptRules);
+
+    const primaryPolicy = resolvePolicyPack(effectiveOptions.policyPack);
+    const threshold = (primaryPolicy && primaryPolicy.promptInjectionThreshold) || effectiveOptions.promptInjectionThreshold;
+    const wouldBlock = effectiveOptions.blockOnPromptInjection && compareRisk(injection.level, threshold);
+    const shouldBlock = effectiveOptions.shadowMode ? false : wouldBlock;
+    const shouldNotify = compareRisk(injection.level, effectiveOptions.notifyOnRiskLevel);
+    const policyNames = [...new Set([...(effectiveOptions.shadowPolicyPacks || []), ...comparePolicyPacks].filter(Boolean))];
+    const policyComparisons = policyNames.map((name) => evaluatePolicyPack(injection, name, effectiveOptions.promptInjectionThreshold));
+    const budgetResult = effectiveOptions.tokenBudgetFirewall && typeof effectiveOptions.tokenBudgetFirewall.inspect === 'function'
+      ? effectiveOptions.tokenBudgetFirewall.inspect({
         userId: metadata.userId || metadata.user_id || 'anonymous',
         tenantId: metadata.tenantId || metadata.tenant_id || 'default',
         messages: normalizedMessages,
@@ -838,7 +1134,7 @@ class BlackwallShield {
         hasSensitiveData: masked.hasSensitiveData,
       },
       enforcement: {
-        shadowMode: this.options.shadowMode,
+        shadowMode: effectiveOptions.shadowMode,
         wouldBlock: wouldBlock || !budgetResult.allowed,
         blocked: shouldBlock || !budgetResult.allowed,
         threshold,
@@ -846,6 +1142,13 @@ class BlackwallShield {
       policyPack: primaryPolicy ? primaryPolicy.name : null,
       policyComparisons,
       tokenBudget: budgetResult,
+      coreInterfaces: CORE_INTERFACES,
+      routePolicy: effectiveOptions.routePolicy ? {
+        route: metadata.route || metadata.path || null,
+        suppressPromptRules: effectiveOptions.routePolicy.suppressPromptRules || [],
+        policyPack: effectiveOptions.routePolicy.policyPack || null,
+        preset: effectiveOptions.routePolicy.preset || null,
+      } : null,
       telemetry: {
         eventType: 'llm_request_reviewed',
         promptInjectionRuleHits: countFindingsByType(injection.matches),
@@ -861,7 +1164,7 @@ class BlackwallShield {
     await this.emitTelemetry(createTelemetryEvent('llm_request_reviewed', {
       metadata,
       blocked: shouldBlock || !budgetResult.allowed,
-      shadowMode: this.options.shadowMode,
+      shadowMode: effectiveOptions.shadowMode,
       report,
     }));
 
@@ -886,14 +1189,17 @@ class BlackwallShield {
   }
 
   async reviewModelResponse({ output, metadata = {}, outputFirewall = null, firewallOptions = {} } = {}) {
-    const primaryPolicy = resolvePolicyPack(this.options.policyPack);
+    const effectiveOptions = resolveEffectiveShieldOptions(this.options, metadata);
+    const primaryPolicy = resolvePolicyPack(effectiveOptions.policyPack);
     const firewall = outputFirewall || new OutputFirewall({
       riskThreshold: (primaryPolicy && primaryPolicy.outputRiskThreshold) || 'high',
-      systemPrompt: this.options.systemPrompt,
+      systemPrompt: effectiveOptions.systemPrompt,
+      ...effectiveOptions.outputFirewallDefaults,
       ...firewallOptions,
     });
     const review = firewall.inspect(output, {
-      systemPrompt: this.options.systemPrompt,
+      systemPrompt: effectiveOptions.systemPrompt,
+      ...(effectiveOptions.outputFirewallDefaults || {}),
       ...firewallOptions,
     });
     const report = {
@@ -902,6 +1208,7 @@ class BlackwallShield {
       metadata,
       outputReview: {
         ...review,
+        coreInterfaces: CORE_INTERFACES,
         telemetry: {
           eventType: 'llm_output_reviewed',
           findingCounts: countFindingsByType(review.findings),
@@ -988,6 +1295,38 @@ class BlackwallShield {
       review,
     };
   }
+
+  async protectWithAdapter({
+    adapter,
+    messages = [],
+    metadata = {},
+    allowSystemMessages = this.options.allowSystemMessages,
+    comparePolicyPacks = [],
+    outputFirewall = null,
+    firewallOptions = {},
+  } = {}) {
+    if (!adapter || typeof adapter.invoke !== 'function') {
+      throw new TypeError('adapter.invoke must be a function');
+    }
+    return this.protectModelCall({
+      messages,
+      metadata,
+      allowSystemMessages,
+      comparePolicyPacks,
+      outputFirewall,
+      firewallOptions,
+      callModel: async (payload) => {
+        const result = await adapter.invoke(payload);
+        return result && Object.prototype.hasOwnProperty.call(result, 'response') ? result.response : result;
+      },
+      mapOutput: async (response, request) => {
+        if (typeof adapter.extractOutput === 'function') {
+          return adapter.extractOutput(response, request);
+        }
+        return response && Object.prototype.hasOwnProperty.call(response, 'output') ? response.output : response;
+      },
+    });
+  }
 }
 
 function validateGrounding(text, documents = [], options = {}) {
@@ -1641,6 +1980,18 @@ function createLlamaIndexCallback({ shield, metadata = {} } = {}) {
   };
 }
 
+function buildShieldOptions(options = {}) {
+  const presetOptions = resolveShieldPreset(options.preset);
+  return {
+    ...presetOptions,
+    ...options,
+    shadowPolicyPacks: dedupeArray([
+      ...(presetOptions.shadowPolicyPacks || []),
+      ...(options.shadowPolicyPacks || []),
+    ]),
+  };
+}
+
 module.exports = {
   AgenticCapabilityGater,
   AgentIdentityRegistry,
@@ -1659,6 +2010,8 @@ module.exports = {
   SENSITIVE_PATTERNS,
   PROMPT_INJECTION_RULES,
   POLICY_PACKS,
+  SHIELD_PRESETS,
+  CORE_INTERFACES,
   sanitizeText,
   deobfuscateText,
   maskText,
@@ -1680,6 +2033,12 @@ module.exports = {
   buildAdminDashboardModel,
   getRedTeamPromptLibrary,
   runRedTeamSuite,
+  buildShieldOptions,
+  summarizeOperationalTelemetry,
+  createOpenAIAdapter,
+  createAnthropicAdapter,
+  createGeminiAdapter,
+  createOpenRouterAdapter,
   createExpressMiddleware,
   createLangChainCallbacks,
   createLlamaIndexCallback,

package/src/providers.js

@@ -0,0 +1,152 @@
+function stringifyContent(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content.map((item) => {
+      if (typeof item === 'string') return item;
+      if (item && typeof item.text === 'string') return item.text;
+      if (item && item.type === 'text' && typeof item.text === 'string') return item.text;
+      return '';
+    }).filter(Boolean).join('\n');
+  }
+  if (content && typeof content.text === 'string') return content.text;
+  return String(content || '');
+}
+
+function toOpenAIInput(messages = []) {
+  return messages.map((message) => ({
+    role: message.role,
+    content: stringifyContent(message.content),
+  }));
+}
+
+function toAnthropicMessages(messages = []) {
+  return messages
+    .filter((message) => message.role !== 'system')
+    .map((message) => ({
+      role: message.role === 'assistant' ? 'assistant' : 'user',
+      content: stringifyContent(message.content),
+    }));
+}
+
+function extractSystemPrompt(messages = []) {
+  return messages.filter((message) => message.role === 'system').map((message) => stringifyContent(message.content)).join('\n\n');
+}
+
+function defaultAdapterResult(response, output) {
+  return { response, output };
+}
+
+function createOpenAIAdapter({ client, model, request = {}, method = 'responses', extractOutput = null } = {}) {
+  if (!client) throw new TypeError('client is required');
+  return {
+    provider: 'openai',
+    async invoke({ messages, metadata = {} }) {
+      if (method === 'chat.completions') {
+        const response = await client.chat.completions.create({
+          model,
+          messages: toOpenAIInput(messages),
+          metadata,
+          ...request,
+        });
+        return defaultAdapterResult(response, response && response.choices && response.choices[0] && response.choices[0].message
+          ? stringifyContent(response.choices[0].message.content)
+          : '');
+      }
+      const response = await client.responses.create({
+        model,
+        input: toOpenAIInput(messages),
+        metadata,
+        ...request,
+      });
+      return defaultAdapterResult(response, response && typeof response.output_text === 'string' ? response.output_text : '');
+    },
+    extractOutput(response) {
+      if (typeof extractOutput === 'function') return extractOutput(response);
+      if (response && typeof response.output_text === 'string') return response.output_text;
+      return response && response.choices && response.choices[0] && response.choices[0].message
+        ? stringifyContent(response.choices[0].message.content)
+        : '';
+    },
+  };
+}
+
+function createAnthropicAdapter({ client, model, request = {}, extractOutput = null } = {}) {
+  if (!client) throw new TypeError('client is required');
+  return {
+    provider: 'anthropic',
+    async invoke({ messages, metadata = {} }) {
+      const response = await client.messages.create({
+        model,
+        system: extractSystemPrompt(messages) || undefined,
+        messages: toAnthropicMessages(messages),
+        metadata,
+        ...request,
+      });
+      const output = Array.isArray(response && response.content)
+        ? response.content.map((item) => stringifyContent(item)).filter(Boolean).join('\n')
+        : '';
+      return defaultAdapterResult(response, output);
+    },
+    extractOutput(response) {
+      if (typeof extractOutput === 'function') return extractOutput(response);
+      return Array.isArray(response && response.content)
+        ? response.content.map((item) => stringifyContent(item)).filter(Boolean).join('\n')
+        : '';
+    },
+  };
+}
+
+function createGeminiAdapter({ client, model, request = {}, extractOutput = null } = {}) {
+  if (!client) throw new TypeError('client is required');
+  return {
+    provider: 'gemini',
+    async invoke({ messages }) {
+      const response = await client.models.generateContent({
+        model,
+        contents: messages.map((message) => ({
+          role: message.role === 'assistant' ? 'model' : 'user',
+          parts: [{ text: stringifyContent(message.content) }],
+        })),
+        ...request,
+      });
+      return defaultAdapterResult(response, response && typeof response.text === 'string' ? response.text : '');
+    },
+    extractOutput(response) {
+      if (typeof extractOutput === 'function') return extractOutput(response);
+      if (response && typeof response.text === 'string') return response.text;
+      if (typeof response === 'string') return response;
+      return '';
+    },
+  };
+}
+
+function createOpenRouterAdapter({ client, model, request = {}, extractOutput = null } = {}) {
+  if (!client) throw new TypeError('client is required');
+  return {
+    provider: 'openrouter',
+    async invoke({ messages }) {
+      const response = await client.chat.completions.create({
+        model,
+        messages: toOpenAIInput(messages),
+        ...request,
+      });
+      const output = response && response.choices && response.choices[0] && response.choices[0].message
+        ? stringifyContent(response.choices[0].message.content)
+        : '';
+      return defaultAdapterResult(response, output);
+    },
+    extractOutput(response) {
+      if (typeof extractOutput === 'function') return extractOutput(response);
+      return response && response.choices && response.choices[0] && response.choices[0].message
+        ? stringifyContent(response.choices[0].message.content)
+        : '';
+    },
+  };
+}
+
+module.exports = {
+  createOpenAIAdapter,
+  createAnthropicAdapter,
+  createGeminiAdapter,
+  createOpenRouterAdapter,
+};