@vpdeva/blackwall-llm-shield-js 0.2.3 → 0.6.0

package/README.md

@@ -100,6 +100,10 @@ Enterprise deployments can also enrich emitted events with SSO/user context and
 
 Use `createExpressMiddleware()`, `createLangChainCallbacks()`, or `createLlamaIndexCallback()` to drop Blackwall into existing app and orchestration flows faster.
 
+### Example guide
+
+Use the wiki-ready examples page at [`wiki/Running-Examples.md`](/Users/vishnu/Documents/blackwall-llm-shield/blackwall-llm-shield-js/wiki/Running-Examples.md) for copy-paste setup and run commands.
+
 ### Subpath modules
 
 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.
@@ -150,7 +154,7 @@ Recommended presets:
 
 ### Global Governance Pack
 
-The 0.2.2 line also adds globally applicable enterprise controls that are useful across regulated industries, not just one country or sector:
+The 0.5.0 line also adds globally applicable enterprise controls that are useful across regulated industries, not just one country or sector:
 
 - `DataClassificationGate` to classify traffic as `public`, `internal`, `confidential`, or `restricted`
 - `ProviderRoutingPolicy` to keep sensitive classes on approved providers
@@ -158,6 +162,8 @@ The 0.2.2 line also adds globally applicable enterprise controls that are useful
 - `buildComplianceEventBundle()` and `sanitizeAuditEvent()` for audit-safe event export
 - `RetrievalTrustScorer` and `OutboundCommunicationGuard` for retrieval trust and outbound checks
 - `detectOperationalDrift()` for release-over-release noise monitoring
+- `ConversationThreatTracker`, `shield.use(plugin)`, `generateCoverageReport()`, and `unvault()` for multi-turn defense, ecosystem extensions, OWASP reporting, and reversible PII workflows
+- `AdversarialMutationEngine`, `PromptProvenanceGraph`, and `src/edge` for corpus hardening, cross-hop tracing, and edge-safe deployments
 
 ### `AuditTrail`
 
@@ -168,9 +174,12 @@ Use it to record signed events, summarize security activity, and power dashboard
 - `ValueAtRiskCircuitBreaker` for financial or high-value operational actions
 - `ShadowConsensusAuditor` for second-model or secondary-review logic conflict checks
 - `CrossModelConsensusWrapper` for automatic cross-model verification of high-impact actions
+- `QuorumApprovalEngine` for committee-based approvals and trust-score-aware multi-agent decisions
 - `DigitalTwinOrchestrator` for mock tool environments and sandbox simulations
+- `SovereignRoutingEngine` for local-vs-global provider routing based on data classification
 - `PolicyLearningLoop` plus `suggestPolicyOverride()` for narrow false-positive tuning suggestions after HITL approvals
-- `AgentIdentityRegistry.issueSignedPassport()` and `issuePassportToken()` for signed agent identity exchange
+- `buildTransparencyReport()` for explainable operator and compliance artifacts
+- `AgentIdentityRegistry.issueSignedPassport()` and `issuePassportToken()` for signed agent identity exchange with capability manifests and lineage
 
 ## Example Workflows
 
@@ -452,6 +461,7 @@ 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
+- [`wiki/Running-Examples.md`](/Users/vishnu/Documents/blackwall-llm-shield/blackwall-llm-shield-js/wiki/Running-Examples.md) shows how to run the available examples end to end
 
 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.
 

package/edge.d.ts

@@ -0,0 +1,5 @@
+export function detectPromptInjectionEdge(input?: string): Record<string, unknown>;
+export function maskTextEdge(input?: string): Record<string, unknown>;
+export class EdgeBlackwallShield {
+  guardModelRequest(input?: Record<string, unknown>): Promise<Record<string, unknown>>;
+}

package/index.d.ts

@@ -62,12 +62,15 @@ export interface ShieldOptions {
 
 export class BlackwallShield {
   constructor(options?: ShieldOptions);
+  use(plugin: Record<string, unknown>): this;
   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>>;
+  protectZeroTrustModelCall(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>>;
+  generateCoverageReport(options?: Record<string, unknown>): Record<string, unknown>;
 }
 
 export class OutputFirewall {
@@ -81,6 +84,25 @@ export class ToolPermissionFirewall {
   inspectCallAsync?(input: Record<string, unknown>): Promise<Record<string, unknown>>;
 }
 
+export class AgentIdentityRegistry {
+  constructor(options?: Record<string, unknown>);
+  register(agentId: string, profile?: Record<string, unknown>): Record<string, unknown>;
+  get(agentId: string): Record<string, unknown> | null;
+  issueEphemeralToken(agentId: string, options?: Record<string, unknown>): Record<string, unknown>;
+  verifyEphemeralToken(token: string): Record<string, unknown>;
+  recordSecurityEvent(agentId: string, event?: Record<string, unknown>): Record<string, unknown>;
+  getTrustScore(agentId: string): number | null;
+  issueSignedPassport(agentId: string, options?: Record<string, unknown>): Record<string, unknown>;
+  verifySignedPassport(passport?: Record<string, unknown>): Record<string, unknown>;
+  issuePassportToken(agentId: string, options?: Record<string, unknown>): string;
+  verifyPassportToken(token: string): Record<string, unknown>;
+}
+
+export class AgenticCapabilityGater {
+  constructor(options?: Record<string, unknown>);
+  evaluate(agentId: string, capabilities?: Record<string, unknown>): Record<string, unknown>;
+}
+
 export class ValueAtRiskCircuitBreaker {
   constructor(options?: Record<string, unknown>);
   inspect(input?: Record<string, unknown>): Record<string, unknown>;
@@ -97,12 +119,35 @@ export class CrossModelConsensusWrapper {
   evaluate(input?: Record<string, unknown>): Promise<Record<string, unknown>> | Record<string, unknown>;
 }
 
+export class QuorumApprovalEngine {
+  constructor(options?: Record<string, unknown>);
+  evaluate(input?: Record<string, unknown>): Promise<Record<string, unknown>> | Record<string, unknown>;
+}
+
+export class ConversationThreatTracker {
+  constructor(options?: Record<string, unknown>);
+  record(sessionId: string, injection?: Record<string, unknown>): Record<string, unknown> | null;
+  summarize(sessionId: string): Record<string, unknown>;
+  clear(sessionId: string): void;
+}
+
 export class DigitalTwinOrchestrator {
   constructor(options?: Record<string, unknown>);
   generate(): Record<string, unknown>;
   static fromToolPermissionFirewall(firewall: unknown): DigitalTwinOrchestrator;
 }
 
+export class AdversarialMutationEngine {
+  mutate(prompt?: string): Array<Record<string, unknown>>;
+  hardenCorpus(input?: Record<string, unknown>): Record<string, unknown>;
+}
+
+export class PromptProvenanceGraph {
+  constructor();
+  append(input?: Record<string, unknown>): Record<string, unknown>;
+  summarize(): Record<string, unknown>;
+}
+
 export class DataClassificationGate {
   constructor(options?: Record<string, unknown>);
   classify(input?: Record<string, unknown>): string;
@@ -114,6 +159,11 @@ export class ProviderRoutingPolicy {
   choose(input?: Record<string, unknown>): Record<string, unknown>;
 }
 
+export class SovereignRoutingEngine {
+  constructor(options?: Record<string, unknown>);
+  route(input?: Record<string, unknown>): Record<string, unknown>;
+}
+
 export class ApprovalInboxModel {
   constructor(options?: Record<string, unknown>);
   createRequest(input?: Record<string, unknown>): Record<string, unknown>;
@@ -139,6 +189,7 @@ export class PolicyLearningLoop {
   constructor();
   recordDecision(input?: Record<string, unknown>): Record<string, unknown> | null;
   suggestOverrides(): Array<Record<string, unknown>>;
+  buildTransparencyReport(input?: Record<string, unknown>): Record<string, unknown>;
 }
 
 export class RetrievalSanitizer {
@@ -165,7 +216,10 @@ export function buildPowerBIRecord(event?: Record<string, unknown>): Record<stri
 export function buildComplianceEventBundle(event?: Record<string, unknown>): Record<string, unknown>;
 export function sanitizeAuditEvent(event?: Record<string, unknown>, options?: Record<string, unknown>): Record<string, unknown>;
 export function detectOperationalDrift(previousSummary?: Record<string, unknown>, currentSummary?: Record<string, unknown>): Record<string, unknown>;
+export function buildTransparencyReport(input?: Record<string, unknown>): Record<string, unknown>;
+export function generateCoverageReport(options?: Record<string, unknown>): Record<string, unknown>;
 export function suggestPolicyOverride(input?: Record<string, unknown>): Record<string, unknown> | null;
+export function unvault(output?: unknown, vault?: Record<string, string>): string;
 export class PowerBIExporter {
   constructor(options?: Record<string, unknown>);
   send(events?: Array<Record<string, unknown>> | Record<string, unknown>): Promise<Array<Record<string, unknown>>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpdeva/blackwall-llm-shield-js",
-  "version": "0.2.3",
+  "version": "0.6.0",
   "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)",
@@ -20,6 +20,10 @@
       "types": "./providers.d.ts",
       "default": "./src/providers.js"
     },
+    "./edge": {
+      "types": "./edge.d.ts",
+      "default": "./src/edge.js"
+    },
     "./semantic": {
       "types": "./semantic.d.ts",
       "default": "./src/semantic.js"
@@ -39,6 +43,7 @@
   },
   "files": [
     "src",
+    "edge.d.ts",
     "index.d.ts",
     "integrations.d.ts",
     "providers.d.ts",

package/src/edge.js

@@ -0,0 +1,71 @@
+const EDGE_PROMPT_PATTERNS = [
+  { id: 'ignore_instructions', score: 25, regex: /\bignore\b.{0,40}\b(instructions?|policy|guardrails?|safety)\b/i },
+  { id: 'secret_exfiltration', score: 25, regex: /\b(reveal|dump|print|show)\b.{0,40}\b(secret|token|system prompt|hidden instructions?)\b/i },
+  { id: 'tool_override', score: 20, regex: /\b(bypass|override|disable)\b.{0,40}\b(tool|policy|guardrail|safety)\b/i },
+];
+
+function edgeRiskLevel(score) {
+  if (score >= 70) return 'critical';
+  if (score >= 45) return 'high';
+  if (score >= 20) return 'medium';
+  return 'low';
+}
+
+function detectPromptInjectionEdge(input = '') {
+  const text = String(input || '');
+  const matches = EDGE_PROMPT_PATTERNS.filter((rule) => rule.regex.test(text)).map((rule) => ({
+    id: rule.id,
+    score: rule.score,
+    reason: `Edge rule matched ${rule.id}`,
+  }));
+  const score = Math.min(matches.reduce((sum, item) => sum + item.score, 0), 100);
+  return {
+    score,
+    level: edgeRiskLevel(score),
+    matches,
+    blockedByDefault: score >= 45,
+  };
+}
+
+function maskTextEdge(text = '') {
+  let masked = String(text || '');
+  const vault = {};
+  const patterns = [
+    ['EMAIL', /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g],
+    ['CREDIT_CARD', /\b(?:\d{4}[\s-]?){3}\d{4}\b/g],
+    ['API_KEY', /\b(?:sk|rk|pk|api)[-_][A-Za-z0-9_-]{8,}\b/g],
+    ['JWT', /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9._-]+\.[A-Za-z0-9._-]+\b/g],
+    ['BEARER', /\bBearer\s+[A-Za-z0-9\-._~+/]+=*\b/gi],
+    ['PHONE', /(\+?\d{1,3}[\s-]?)?(\(0\d\)|0\d|\(?\d{2,4}\)?)[\s-]?\d{3,4}[\s-]?\d{3,4}\b/g],
+  ];
+  for (const [label, pattern] of patterns) {
+    masked = masked.replace(pattern, (match) => {
+      const token = `[${label}_${Object.keys(vault).length + 1}]`;
+      vault[token] = match;
+      return token;
+    });
+  }
+  return { masked, vault, hasSensitiveData: Object.keys(vault).length > 0 };
+}
+
+class EdgeBlackwallShield {
+  async guardModelRequest({ messages = [], metadata = {} } = {}) {
+    const text = (Array.isArray(messages) ? messages : []).map((item) => String(item.content || '')).join('\n');
+    const masked = maskTextEdge(text);
+    const injection = detectPromptInjectionEdge(text);
+    return {
+      allowed: !injection.blockedByDefault,
+      blocked: injection.blockedByDefault,
+      reason: injection.blockedByDefault ? 'Prompt injection risk exceeded edge threshold' : null,
+      messages,
+      report: { metadata, promptInjection: injection, sensitiveData: masked },
+      vault: masked.vault,
+    };
+  }
+}
+
+module.exports = {
+  EdgeBlackwallShield,
+  detectPromptInjectionEdge,
+  maskTextEdge,
+};