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

package/README.md

@@ -32,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,
@@ -95,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
 
@@ -105,7 +105,7 @@ Use `require('blackwall-llm-shield-js/providers')` for provider adapter factorie
 
 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()`, `protectWithAdapter()`, and `reviewModelResponse()` so you can enforce request checks before provider calls and review outputs before they go back to the user.
+It also exposes `protectModelCall()`, `protectJsonModelCall()`, `protectWithAdapter()`, and `reviewModelResponse()` so you can enforce request checks before provider calls and review outputs before they go back to the user.
 
 ### `OutputFirewall`
 
@@ -129,6 +129,10 @@ Recommended presets:
 - `strict` for high-sensitivity routes
 - `ragSafe` for retrieval-heavy flows
 - `agentTools` for tool-calling and approval-gated agent actions
+- `agentPlanner` for JSON-heavy planner and internal ops routes
+- `documentReview` for classification and document-review pipelines
+- `ragSearch` for search-heavy retrieval endpoints
+- `toolCalling` for routes that broker external actions
 
 ### `AuditTrail`
 
@@ -151,7 +155,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',
@@ -177,6 +181,19 @@ const result = await shield.protectWithAdapter({
 console.log(result.stage, result.allowed);
 ```
 
+### Protect a strict JSON workflow
+
+```js
+const result = await shield.protectJsonModelCall({
+  messages: [{ role: 'user', content: 'Return the shipment triage plan as JSON.' }],
+  metadata: { route: '/api/planner', feature: 'planner' },
+  requiredSchema: { steps: 'object' },
+  callModel: async () => JSON.stringify({ steps: ['triage', 'notify-ops'] }),
+});
+
+console.log(result.json.parsed);
+```
+
 ### Use presets and route-level policy overrides
 
 ```js
@@ -231,18 +248,51 @@ const toolFirewall = new ToolPermissionFirewall({
 });
 ```
 
+For document review and verification:
+
+```js
+const shield = new BlackwallShield({
+  preset: 'documentReview',
+  routePolicies: [
+    {
+      route: '/api/verify',
+      options: {
+        shadowMode: true,
+        outputFirewallDefaults: { requiredSchema: { verdict: 'string' } },
+      },
+    },
+  ],
+});
+```
+
+### Choose your integration path
+
+- Request-only guard: `guardModelRequest()`
+- Request + output review: `protectModelCall()`
+- Strict JSON planner/document workflows: `protectJsonModelCall()`
+- Full provider wrapper: `protectWithAdapter()`
+- Tool firewall + RAG sanitizer: `ToolPermissionFirewall` + `RetrievalSanitizer`
+
 ### Operational telemetry summaries
 
 ```js
+const { summarizeOperationalTelemetry } = require('@vpdeva/blackwall-llm-shield-js');
 const summary = summarizeOperationalTelemetry(events);
 console.log(summary.byRoute);
+console.log(summary.byFeature);
+console.log(summary.noisiestRoutes);
+console.log(summary.weeklyBlockEstimate);
 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',
@@ -259,7 +309,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'],
@@ -274,6 +324,10 @@ 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.
+
+For Gemini-heavy apps, the bundled adapter now preserves system instructions plus mixed text/image/file parts so App Router handlers can wrap direct `@google/generative-ai` calls with less translation glue.
+
 ## Release Commands
 
 - `npm run release:check` runs the JS test suite before release

package/index.d.ts

@@ -0,0 +1,104 @@
+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 JsonProtectionResult extends Record<string, unknown> {
+  allowed: boolean;
+  blocked: boolean;
+  json?: {
+    parsed: unknown;
+    schemaValid: boolean;
+    parseError?: string;
+  };
+}
+
+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>>;
+  protectJsonModelCall(input: Record<string, unknown>): Promise<JsonProtectionResult>;
+  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 parseJsonOutput(output: unknown): 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.5",
+  "version": "0.1.7",
   "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

@@ -145,6 +145,34 @@ const SHIELD_PRESETS = {
     notifyOnRiskLevel: 'medium',
     shadowMode: false,
   },
+  agentPlanner: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'medium',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: true,
+    shadowPolicyPacks: ['government'],
+  },
+  documentReview: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'high',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: true,
+    policyPack: 'healthcare',
+  },
+  ragSearch: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'medium',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: true,
+    shadowPolicyPacks: ['government'],
+  },
+  toolCalling: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'medium',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: false,
+    policyPack: 'finance',
+  },
 };
 
 const CORE_INTERFACE_VERSION = '1.0';
@@ -152,6 +180,7 @@ const CORE_INTERFACES = Object.freeze({
   guardModelRequest: CORE_INTERFACE_VERSION,
   reviewModelResponse: CORE_INTERFACE_VERSION,
   protectModelCall: CORE_INTERFACE_VERSION,
+  protectJsonModelCall: CORE_INTERFACE_VERSION,
   toolPermissionFirewall: CORE_INTERFACE_VERSION,
   retrievalSanitizer: CORE_INTERFACE_VERSION,
 });
@@ -350,24 +379,64 @@ function summarizeOperationalTelemetry(events = []) {
     shadowModeEvents: 0,
     byType: {},
     byRoute: {},
+    byFeature: {},
+    byTenant: {},
+    byModel: {},
+    byPolicyOutcome: {
+      blocked: 0,
+      shadowBlocked: 0,
+      allowed: 0,
+    },
+    topRules: {},
     highestSeverity: 'low',
+    noisiestRoutes: [],
+    weeklyBlockEstimate: 0,
   };
   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 metadata = event && event.metadata ? event.metadata : {};
+    const route = metadata.route || metadata.path || 'unknown';
+    const feature = metadata.feature || metadata.capability || route;
+    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.byFeature[feature] = (summary.byFeature[feature] || 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)
+  );
+  summary.noisiestRoutes = Object.entries(summary.byRoute)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([route, count]) => ({ route, count }));
+  summary.weeklyBlockEstimate = summary.byPolicyOutcome.blocked + summary.byPolicyOutcome.shadowBlocked;
   return summary;
 }
 
+function parseJsonOutput(output) {
+  if (typeof output === 'string') return JSON.parse(output);
+  return output;
+}
+
 function resolveShieldPreset(name) {
   if (!name) return {};
   return SHIELD_PRESETS[name] ? { ...SHIELD_PRESETS[name] } : {};
@@ -1327,6 +1396,69 @@ class BlackwallShield {
       },
     });
   }
+
+  async protectJsonModelCall({
+    messages = [],
+    metadata = {},
+    allowSystemMessages = this.options.allowSystemMessages,
+    comparePolicyPacks = [],
+    callModel,
+    mapMessages = null,
+    mapOutput = null,
+    outputFirewall = null,
+    firewallOptions = {},
+    requiredSchema = null,
+  } = {}) {
+    const result = await this.protectModelCall({
+      messages,
+      metadata,
+      allowSystemMessages,
+      comparePolicyPacks,
+      callModel,
+      mapMessages,
+      mapOutput,
+      outputFirewall,
+      firewallOptions,
+    });
+    if (result.blocked) return result;
+    try {
+      const parsed = parseJsonOutput(result.review.maskedOutput != null ? result.review.maskedOutput : result.response);
+      const schemaValid = validateRequiredSchema(parsed, requiredSchema);
+      if (!schemaValid) {
+        return {
+          ...result,
+          allowed: false,
+          blocked: true,
+          stage: 'output',
+          reason: 'Model output failed JSON schema validation',
+          json: {
+            parsed,
+            schemaValid: false,
+          },
+        };
+      }
+      return {
+        ...result,
+        json: {
+          parsed,
+          schemaValid: true,
+        },
+      };
+    } catch (error) {
+      return {
+        ...result,
+        allowed: false,
+        blocked: true,
+        stage: 'output',
+        reason: 'Model output is not valid JSON',
+        json: {
+          parsed: null,
+          schemaValid: false,
+          parseError: error.message,
+        },
+      };
+    }
+  }
 }
 
 function validateGrounding(text, documents = [], options = {}) {
@@ -2035,6 +2167,7 @@ module.exports = {
   runRedTeamSuite,
   buildShieldOptions,
   summarizeOperationalTelemetry,
+  parseJsonOutput,
   createOpenAIAdapter,
   createAnthropicAdapter,
   createGeminiAdapter,

package/src/providers.js

@@ -12,6 +12,38 @@ function stringifyContent(content) {
   return String(content || '');
 }
 
+function toGeminiPart(item) {
+  if (typeof item === 'string') return { text: item };
+  if (!item || typeof item !== 'object') return null;
+  if ((item.type === 'text' || item.type === 'input_text') && typeof item.text === 'string') {
+    return { text: item.text };
+  }
+  if (item.type === 'image_url' && typeof item.image_url === 'string') {
+    return { fileData: { fileUri: item.image_url } };
+  }
+  if (item.type === 'file') {
+    if (item.file_data && typeof item.file_data === 'object') return { inlineData: item.file_data };
+    if (typeof item.file_uri === 'string') return { fileData: { fileUri: item.file_uri } };
+    if (typeof item.file_id === 'string') return { fileData: { fileUri: item.file_id } };
+  }
+  if (item.type === 'json' && typeof item.value === 'string') {
+    return { text: item.value };
+  }
+  if (typeof item.text === 'string') return { text: item.text };
+  return null;
+}
+
+function toGeminiParts(content) {
+  if (typeof content === 'string') return [{ text: content }];
+  if (Array.isArray(content)) return content.map((item) => toGeminiPart(item)).filter(Boolean);
+  if (content && typeof content === 'object') {
+    if (Array.isArray(content.parts)) return toGeminiParts(content.parts);
+    const part = toGeminiPart(content);
+    return part ? [part] : [{ text: stringifyContent(content) }];
+  }
+  return [{ text: String(content || '') }];
+}
+
 function toOpenAIInput(messages = []) {
   return messages.map((message) => ({
     role: message.role,
@@ -101,19 +133,30 @@ function createGeminiAdapter({ client, model, request = {}, extractOutput = null
   return {
     provider: 'gemini',
     async invoke({ messages }) {
+      const systemInstruction = extractSystemPrompt(messages);
       const response = await client.models.generateContent({
         model,
-        contents: messages.map((message) => ({
-          role: message.role === 'assistant' ? 'model' : 'user',
-          parts: [{ text: stringifyContent(message.content) }],
-        })),
+        contents: messages
+          .filter((message) => message.role !== 'system')
+          .map((message) => ({
+            role: message.role === 'assistant' ? 'model' : 'user',
+            parts: toGeminiParts(message.content),
+          })),
+        ...(systemInstruction ? { systemInstruction: { parts: [{ text: systemInstruction }] } } : {}),
         ...request,
       });
-      return defaultAdapterResult(response, response && typeof response.text === 'string' ? response.text : '');
+      return defaultAdapterResult(response, this.extractOutput(response));
     },
     extractOutput(response) {
       if (typeof extractOutput === 'function') return extractOutput(response);
       if (response && typeof response.text === 'string') return response.text;
+      if (response && Array.isArray(response.candidates)) {
+        return response.candidates
+          .flatMap((candidate) => (((candidate || {}).content || {}).parts || []))
+          .map((part) => (part && typeof part.text === 'string' ? part.text : ''))
+          .filter(Boolean)
+          .join('\n');
+      }
       if (typeof response === 'string') return response;
       return '';
     },