@vpdeva/blackwall-llm-shield-js 0.1.0 → 0.1.1

package/README.md

@@ -11,6 +11,7 @@ JavaScript security middleware for LLM applications in Node.js and Next.js. Blac
 - Blocks requests when risk exceeds policy thresholds
 - 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
 - Inspects model outputs for leaks, unsafe code, grounding drift, and tone violations
 - Ships Express, LangChain, and LlamaIndex integration helpers
 - Enforces allowlists, denylists, validators, and approval-gated tools
@@ -91,6 +92,8 @@ Use `require('blackwall-llm-shield-js/integrations')` for callback wrappers and
 
 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.
+
 ### `OutputFirewall`
 
 Use it after the model responds to catch leaked secrets, dangerous code patterns, and schema regressions before returning output to the user or agent runtime.
@@ -121,6 +124,32 @@ if (!guarded.allowed) {
 }
 ```
 
+### Wrap a provider call end to end
+
+```js
+const shield = new BlackwallShield({
+  shadowMode: true,
+  onTelemetry: async (event) => console.log(JSON.stringify(event)),
+});
+
+const result = await shield.protectModelCall({
+  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.' },
+    ],
+  },
+});
+
+console.log(result.stage, result.allowed);
+```
+
 ### Inspect model output
 
 ```js
@@ -156,12 +185,17 @@ 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
 
-## What Would Make This Production-Ready Even Faster
+## Release Commands
+
+- `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
+
+## Rollout Notes
 
-- Provider adapters for OpenAI, Anthropic, and open-source model gateways
-- OpenTelemetry spans and structured logs
-- More benchmark data for latency and false-positive rates
-- More adversarial scenarios in the red-team suite
+- Start with `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.
 
 ## Support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpdeva/blackwall-llm-shield-js",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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)",
@@ -15,7 +15,10 @@
     "blackwall-scorecard": "src/scorecard.js"
   },
   "scripts": {
-    "test": "node --test tests/*.test.js"
+    "test": "node --test tests/*.test.js",
+    "release:check": "npm test",
+    "release:pack": "npm pack",
+    "release:publish": "npm publish --access public --provenance"
   },
   "files": [
     "src",
@@ -28,11 +31,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vishnud23/blackwall-llm-shield.git"
+    "url": "git+https://github.com/vpdeva/blackwall-llm-shield-js.git"
   },
   "homepage": "https://vish.au",
   "bugs": {
-    "url": "https://github.com/vishnud23/blackwall-llm-shield/issues"
+    "url": "https://github.com/vpdeva/blackwall-llm-shield-js/issues"
   },
   "funding": {
     "type": "Buy Vish a coffee",

package/src/index.js

@@ -199,6 +199,30 @@ function mapCompliance(ids = []) {
   return [...new Set(ids.flatMap((id) => COMPLIANCE_MAP[id] || []))];
 }
 
+function countFindingsByType(findings = []) {
+  return findings.reduce((acc, finding) => {
+    const key = finding && (finding.type || finding.id || finding.category || 'unknown');
+    acc[key] = (acc[key] || 0) + 1;
+    return acc;
+  }, {});
+}
+
+function summarizeSensitiveFindings(findings = []) {
+  return findings.reduce((acc, finding) => {
+    const key = finding && finding.type ? finding.type : 'unknown';
+    acc[key] = (acc[key] || 0) + 1;
+    return acc;
+  }, {});
+}
+
+function createTelemetryEvent(type, payload = {}) {
+  return {
+    type,
+    createdAt: new Date().toISOString(),
+    ...payload,
+  };
+}
+
 function cloneRegex(regex) {
   return new RegExp(regex.source, regex.flags);
 }
@@ -733,6 +757,7 @@ class BlackwallShield {
       tokenBudgetFirewall: null,
       systemPrompt: null,
       onAlert: null,
+      onTelemetry: null,
       webhookUrl: null,
       ...options,
     };
@@ -760,6 +785,12 @@ class BlackwallShield {
     }
   }
 
+  async emitTelemetry(event) {
+    if (typeof this.options.onTelemetry === 'function') {
+      await this.options.onTelemetry(event);
+    }
+  }
+
   async guardModelRequest({ messages = [], metadata = {}, allowSystemMessages = this.options.allowSystemMessages, comparePolicyPacks = [] } = {}) {
     const normalizedMessages = normalizeMessages(messages, {
       maxMessages: this.options.maxMessages,
@@ -815,8 +846,25 @@ class BlackwallShield {
       policyPack: primaryPolicy ? primaryPolicy.name : null,
       policyComparisons,
       tokenBudget: budgetResult,
+      telemetry: {
+        eventType: 'llm_request_reviewed',
+        promptInjectionRuleHits: countFindingsByType(injection.matches),
+        maskedEntityCounts: summarizeSensitiveFindings(masked.findings),
+        promptTokenEstimate: budgetResult.estimatedTokens,
+        complianceMap: mapCompliance([
+          ...injection.matches.map((item) => item.id),
+          ...(budgetResult.allowed ? [] : ['token_budget_exceeded']),
+        ]),
+      },
     };
 
+    await this.emitTelemetry(createTelemetryEvent('llm_request_reviewed', {
+      metadata,
+      blocked: shouldBlock || !budgetResult.allowed,
+      shadowMode: this.options.shadowMode,
+      report,
+    }));
+
     if (shouldNotify || wouldBlock) {
       await this.notify({
         type: shouldBlock ? 'llm_request_blocked' : (wouldBlock ? 'llm_request_shadow_blocked' : 'llm_request_risky'),
@@ -836,6 +884,110 @@ class BlackwallShield {
       vault: masked.vault,
     };
   }
+
+  async reviewModelResponse({ output, metadata = {}, outputFirewall = null, firewallOptions = {} } = {}) {
+    const primaryPolicy = resolvePolicyPack(this.options.policyPack);
+    const firewall = outputFirewall || new OutputFirewall({
+      riskThreshold: (primaryPolicy && primaryPolicy.outputRiskThreshold) || 'high',
+      systemPrompt: this.options.systemPrompt,
+      ...firewallOptions,
+    });
+    const review = firewall.inspect(output, {
+      systemPrompt: this.options.systemPrompt,
+      ...firewallOptions,
+    });
+    const report = {
+      package: 'blackwall-llm-shield-js',
+      createdAt: new Date().toISOString(),
+      metadata,
+      outputReview: {
+        ...review,
+        telemetry: {
+          eventType: 'llm_output_reviewed',
+          findingCounts: countFindingsByType(review.findings),
+          piiEntityCounts: summarizeSensitiveFindings(review.piiFindings),
+          complianceMap: mapCompliance(review.findings.map((item) => item.id)),
+        },
+      },
+    };
+
+    await this.emitTelemetry(createTelemetryEvent('llm_output_reviewed', {
+      metadata,
+      blocked: !review.allowed,
+      report,
+    }));
+
+    if (!review.allowed || compareRisk(review.severity, 'high')) {
+      await this.notify({
+        type: !review.allowed ? 'llm_output_blocked' : 'llm_output_risky',
+        severity: review.severity,
+        reason: !review.allowed ? 'Model output failed Blackwall review' : 'Model output triggered Blackwall findings',
+        report,
+      });
+    }
+
+    return {
+      ...review,
+      report,
+    };
+  }
+
+  async protectModelCall({
+    messages = [],
+    metadata = {},
+    allowSystemMessages = this.options.allowSystemMessages,
+    comparePolicyPacks = [],
+    callModel,
+    mapMessages = null,
+    mapOutput = null,
+    outputFirewall = null,
+    firewallOptions = {},
+  } = {}) {
+    if (typeof callModel !== 'function') {
+      throw new TypeError('callModel must be a function');
+    }
+    const request = await this.guardModelRequest({
+      messages,
+      metadata,
+      allowSystemMessages,
+      comparePolicyPacks,
+    });
+    if (!request.allowed) {
+      return {
+        allowed: false,
+        blocked: true,
+        stage: 'request',
+        reason: request.reason,
+        request,
+        response: null,
+        review: null,
+      };
+    }
+    const guardedMessages = typeof mapMessages === 'function'
+      ? await mapMessages(request.messages, request)
+      : request.messages;
+    const response = await callModel({
+      messages: guardedMessages,
+      metadata,
+      guard: request,
+    });
+    const output = typeof mapOutput === 'function' ? await mapOutput(response, request) : response;
+    const review = await this.reviewModelResponse({
+      output,
+      metadata,
+      outputFirewall,
+      firewallOptions,
+    });
+    return {
+      allowed: review.allowed,
+      blocked: !review.allowed,
+      stage: review.allowed ? 'complete' : 'output',
+      reason: review.allowed ? null : 'Model output failed Blackwall review',
+      request,
+      response,
+      review,
+    };
+  }
 }
 
 function validateGrounding(text, documents = [], options = {}) {
@@ -1101,6 +1253,7 @@ class OutputFirewall {
       grounding,
       tone,
       cot,
+      complianceMap: mapCompliance(findings.map((item) => item.id)),
     };
   }
 }

package/src/integrations.js

@@ -35,7 +35,9 @@ class BlackwallLangChainCallback {
     const text = Array.isArray(generations) && generations[0] && generations[0][0]
       ? (generations[0][0].text || generations[0][0].message?.content || '')
       : '';
-    const review = this.outputFirewall.inspect(text);
+    const review = this.options.shield && typeof this.options.shield.reviewModelResponse === 'function'
+      ? await this.options.shield.reviewModelResponse({ output: text, outputFirewall: this.outputFirewall })
+      : this.outputFirewall.inspect(text);
     this.lastOutputReview = review;
     if (review && review.allowed === false) throw new Error('Blackwall blocked model output');
     return review;
@@ -62,7 +64,9 @@ class BlackwallLlamaIndexCallback {
     if (!this.outputFirewall || typeof this.outputFirewall.inspect !== 'function') return null;
     const payload = event && event.payload ? event.payload : {};
     const text = payload.response || payload.output || '';
-    const review = this.outputFirewall.inspect(text);
+    const review = this.options.shield && typeof this.options.shield.reviewModelResponse === 'function'
+      ? await this.options.shield.reviewModelResponse({ output: text, outputFirewall: this.outputFirewall })
+      : this.outputFirewall.inspect(text);
     this.lastOutputReview = review;
     if (review && review.allowed === false) throw new Error('Blackwall blocked model output');
     return review;