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

package/README.md

@@ -26,9 +26,10 @@ JavaScript security middleware for LLM applications in Node.js and Next.js. Blac
 
 ```bash
 npm install @vpdeva/blackwall-llm-shield-js
-npm install @xenova/transformers
 ```
 
+The package now ships with local Transformers support wired as a first-class dependency, so teams do not need a second install step just to enable semantic scoring.
+
 ## Fast Start
 
 ```js
@@ -89,6 +90,8 @@ The current recommendation for enterprise teams is a controlled pilot first: sta
 
 Use `summarizeOperationalTelemetry()` with emitted telemetry events when you want route-level summaries, blocked-event counts, and rollout visibility for operators.
 
+Enterprise deployments can also enrich emitted events with SSO/user context and forward flattened records to Power BI or other downstream reporting systems.
+
 ### Output grounding and tone review
 
 `OutputFirewall` can compare responses against retrieved documents and flag hallucination-style unsupported claims or unprofessional tone.
@@ -119,13 +122,15 @@ Use it after the model responds to catch leaked secrets, dangerous code patterns
 
 Use it to allowlist tools, block disallowed tools, validate arguments, and require approval for risky operations.
 
+It can also integrate with `ValueAtRiskCircuitBreaker` for high-value actions and `ShadowConsensusAuditor` for secondary logic review before sensitive tools execute.
+
 ### `RetrievalSanitizer`
 
 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.
+The 0.2.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:
 
@@ -137,11 +142,36 @@ Recommended presets:
 - `documentReview` for classification and document-review pipelines
 - `ragSearch` for search-heavy retrieval endpoints
 - `toolCalling` for routes that broker external actions
+- `governmentStrict` for highly regulated public-sector and records-sensitive workflows
+- `bankingPayments` for high-value payment and financial action routes
+- `documentIntake` for upload-heavy intake and review flows
+- `citizenServices` for identity-aware service delivery workflows
+- `internalOpsAgent` for internal operational assistants with shadow-first defaults
+
+### 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:
+
+- `DataClassificationGate` to classify traffic as `public`, `internal`, `confidential`, or `restricted`
+- `ProviderRoutingPolicy` to keep sensitive classes on approved providers
+- `ApprovalInboxModel` and `UploadQuarantineWorkflow` for quarantine and review-first intake
+- `buildComplianceEventBundle()` and `sanitizeAuditEvent()` for audit-safe event export
+- `RetrievalTrustScorer` and `OutboundCommunicationGuard` for retrieval trust and outbound checks
+- `detectOperationalDrift()` for release-over-release noise monitoring
 
 ### `AuditTrail`
 
 Use it to record signed events, summarize security activity, and power dashboards or downstream analysis.
 
+### Advanced Agent Controls
+
+- `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
+- `DigitalTwinOrchestrator` for mock tool environments and sandbox simulations
+- `PolicyLearningLoop` plus `suggestPolicyOverride()` for narrow false-positive tuning suggestions after HITL approvals
+- `AgentIdentityRegistry.issueSignedPassport()` and `issuePassportToken()` for signed agent identity exchange
+
 ## Example Workflows
 
 ### Guard a request before calling the model
@@ -201,6 +231,64 @@ function createModelShield(shield) {
 }
 ```
 
+### Add SSO-aware telemetry and Power BI export
+
+```js
+const { BlackwallShield, PowerBIExporter } = require('@vpdeva/blackwall-llm-shield-js');
+
+const shield = new BlackwallShield({
+  identityResolver: (metadata) => ({
+    userId: metadata.sso?.subject,
+    userEmail: metadata.sso?.email,
+    userName: metadata.sso?.displayName,
+    identityProvider: metadata.sso?.provider,
+    groups: metadata.sso?.groups,
+  }),
+  telemetryExporters: [
+    new PowerBIExporter({ endpointUrl: process.env.POWER_BI_PUSH_URL }),
+  ],
+});
+```
+
+### Protect high-value actions with a VaR breaker and consensus auditor
+
+```js
+const firewall = new ToolPermissionFirewall({
+  allowedTools: ['issueRefund'],
+  valueAtRiskCircuitBreaker: new ValueAtRiskCircuitBreaker({ maxValuePerWindow: 5000 }),
+  consensusAuditor: new ShadowConsensusAuditor(),
+  consensusRequiredFor: ['issueRefund'],
+});
+```
+
+### Add automatic cross-model consensus
+
+```js
+const consensus = new CrossModelConsensusWrapper({
+  auditorAdapter: geminiAuditorAdapter,
+});
+
+const firewall = new ToolPermissionFirewall({
+  allowedTools: ['issueRefund'],
+  crossModelConsensus: consensus,
+  consensusRequiredFor: ['issueRefund'],
+});
+```
+
+### Generate a digital twin for sandbox testing
+
+```js
+const twin = new DigitalTwinOrchestrator({
+  toolSchemas: [
+    { name: 'lookupOrder', mockResponse: { orderId: 'ord_1', status: 'mocked' } },
+  ],
+}).generate();
+
+await twin.simulateCall('lookupOrder', { orderId: 'ord_1' });
+```
+
+You can also derive a digital twin from `ToolPermissionFirewall` tool schemas with `DigitalTwinOrchestrator.fromToolPermissionFirewall(firewall)`.
+
 ### Protect a strict JSON workflow
 
 ```js
@@ -319,6 +407,8 @@ const { summarizeOperationalTelemetry } = require('@vpdeva/blackwall-llm-shield-
 const summary = summarizeOperationalTelemetry(events);
 console.log(summary.byRoute);
 console.log(summary.byFeature);
+console.log(summary.byUser);
+console.log(summary.byIdentityProvider);
 console.log(summary.noisiestRoutes);
 console.log(summary.weeklyBlockEstimate);
 console.log(summary.highestSeverity);
@@ -372,6 +462,8 @@ For Gemini-heavy apps, the bundled adapter now preserves system instructions plu
 - A controlled pilot is a good fit today when you want shadow-mode prompt and output protection without forcing hard blocking on every route immediately.
 - If you prefer not to depend on Blackwall directly everywhere, wrap it behind your own internal model-security abstraction and expose only the contract your app teams need.
 - For broader approval, focus rollout reviews on false-positive rates, noisiest routes, and latency budgets alongside jailbreak coverage.
+- For executive or staff-facing workflows, always attach authenticated identity metadata so telemetry can answer which user triggered which risky request or output event.
+- For high-impact agentic workflows, combine tool approval, VaR limits, digital-twin tests, and signed agent passports instead of relying on a single detector.
 
 ## Release Commands
 

package/index.d.ts

@@ -55,6 +55,8 @@ export interface ShieldOptions {
   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>;
+  telemetryExporters?: Array<{ send(events: Array<Record<string, unknown>>): unknown }>;
+  identityResolver?: (metadata: Record<string, unknown>) => Record<string, unknown> | null;
   [key: string]: unknown;
 }
 
@@ -79,6 +81,66 @@ export class ToolPermissionFirewall {
   inspectCallAsync?(input: Record<string, unknown>): Promise<Record<string, unknown>>;
 }
 
+export class ValueAtRiskCircuitBreaker {
+  constructor(options?: Record<string, unknown>);
+  inspect(input?: Record<string, unknown>): Record<string, unknown>;
+  revokeSession(sessionId: string, durationMs?: number): Record<string, unknown> | null;
+}
+
+export class ShadowConsensusAuditor {
+  constructor(options?: Record<string, unknown>);
+  inspect(input?: Record<string, unknown>): Record<string, unknown>;
+}
+
+export class CrossModelConsensusWrapper {
+  constructor(options?: Record<string, unknown>);
+  evaluate(input?: Record<string, unknown>): Promise<Record<string, unknown>> | Record<string, unknown>;
+}
+
+export class DigitalTwinOrchestrator {
+  constructor(options?: Record<string, unknown>);
+  generate(): Record<string, unknown>;
+  static fromToolPermissionFirewall(firewall: unknown): DigitalTwinOrchestrator;
+}
+
+export class DataClassificationGate {
+  constructor(options?: Record<string, unknown>);
+  classify(input?: Record<string, unknown>): string;
+  inspect(input?: Record<string, unknown>): Record<string, unknown>;
+}
+
+export class ProviderRoutingPolicy {
+  constructor(options?: Record<string, unknown>);
+  choose(input?: Record<string, unknown>): Record<string, unknown>;
+}
+
+export class ApprovalInboxModel {
+  constructor(options?: Record<string, unknown>);
+  createRequest(input?: Record<string, unknown>): Record<string, unknown>;
+  approve(id: string, approver: string): Record<string, unknown> | null;
+  summarize(): Record<string, unknown>;
+}
+
+export class RetrievalTrustScorer {
+  score(documents?: Array<Record<string, unknown>>): Array<Record<string, unknown>>;
+}
+
+export class OutboundCommunicationGuard {
+  constructor(options?: Record<string, unknown>);
+  inspect(input?: Record<string, unknown>): Record<string, unknown>;
+}
+
+export class UploadQuarantineWorkflow {
+  constructor(options?: Record<string, unknown>);
+  inspectUpload(input?: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+
+export class PolicyLearningLoop {
+  constructor();
+  recordDecision(input?: Record<string, unknown>): Record<string, unknown> | null;
+  suggestOverrides(): Array<Record<string, unknown>>;
+}
+
 export class RetrievalSanitizer {
   constructor(options?: Record<string, unknown>);
   sanitizeDocuments(documents: Array<Record<string, unknown>>): Array<Record<string, unknown>>;
@@ -97,6 +159,17 @@ 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 normalizeIdentityMetadata(metadata?: Record<string, unknown>, resolver?: ((metadata: Record<string, unknown>) => Record<string, unknown> | null) | null): Record<string, unknown>;
+export function buildEnterpriseTelemetryEvent(event?: Record<string, unknown>, resolver?: ((metadata: Record<string, unknown>) => Record<string, unknown> | null) | null): Record<string, unknown>;
+export function buildPowerBIRecord(event?: Record<string, unknown>): Record<string, unknown>;
+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 suggestPolicyOverride(input?: Record<string, unknown>): Record<string, unknown> | null;
+export class PowerBIExporter {
+  constructor(options?: Record<string, unknown>);
+  send(events?: Array<Record<string, unknown>> | Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
+}
 
 export function createOpenAIAdapter(input: Record<string, unknown>): ProviderAdapter;
 export function createAnthropicAdapter(input: Record<string, unknown>): ProviderAdapter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpdeva/blackwall-llm-shield-js",
-  "version": "0.1.8",
+  "version": "0.2.3",
   "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)",
@@ -71,6 +71,9 @@
     "nextjs",
     "node"
   ],
+  "dependencies": {
+    "@xenova/transformers": "^2.17.2"
+  },
   "devDependencies": {
     "@changesets/cli": "^2.29.6"
   }

package/src/index.js

@@ -173,6 +173,41 @@ const SHIELD_PRESETS = {
     shadowMode: false,
     policyPack: 'finance',
   },
+  governmentStrict: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'medium',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: false,
+    policyPack: 'government',
+  },
+  bankingPayments: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'medium',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: false,
+    policyPack: 'finance',
+  },
+  documentIntake: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'high',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: true,
+    policyPack: 'government',
+  },
+  citizenServices: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'medium',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: true,
+    policyPack: 'government',
+  },
+  internalOpsAgent: {
+    blockOnPromptInjection: true,
+    promptInjectionThreshold: 'medium',
+    notifyOnRiskLevel: 'medium',
+    shadowMode: true,
+    policyPack: 'finance',
+  },
 };
 
 const CORE_INTERFACE_VERSION = '1.0';
@@ -372,6 +407,250 @@ function createTelemetryEvent(type, payload = {}) {
   };
 }
 
+function normalizeIdentityMetadata(metadata = {}, resolver = null) {
+  const resolved = typeof resolver === 'function' ? resolver(metadata) || {} : {};
+  const source = { ...metadata, ...resolved };
+  const groups = Array.isArray(source.groups)
+    ? source.groups
+    : (Array.isArray(source.ssoGroups) ? source.ssoGroups : (typeof source.groups === 'string' ? source.groups.split(',').map((item) => item.trim()).filter(Boolean) : []));
+  return {
+    userId: source.userId || source.user_id || source.subject || source.sub || 'anonymous',
+    userEmail: source.userEmail || source.user_email || source.email || source.upn || null,
+    userName: source.userName || source.user_name || source.displayName || source.display_name || source.name || null,
+    tenantId: source.tenantId || source.tenant_id || source.orgId || source.org_id || 'default',
+    identityProvider: source.identityProvider || source.identity_provider || source.ssoProvider || source.sso_provider || source.idp || null,
+    authMethod: source.authMethod || source.auth_method || source.authType || source.auth_type || null,
+    sessionId: source.sessionId || source.session_id || null,
+    groups,
+  };
+}
+
+function buildEnterpriseTelemetryEvent(event = {}, resolver = null) {
+  const metadata = event && event.metadata ? event.metadata : {};
+  const actor = normalizeIdentityMetadata(metadata, resolver);
+  return {
+    ...event,
+    actor,
+    metadata: {
+      ...metadata,
+      userId: metadata.userId || metadata.user_id || actor.userId,
+      tenantId: metadata.tenantId || metadata.tenant_id || actor.tenantId,
+      identityProvider: metadata.identityProvider || metadata.identity_provider || actor.identityProvider,
+      sessionId: metadata.sessionId || metadata.session_id || actor.sessionId,
+    },
+  };
+}
+
+function buildPowerBIRecord(event = {}) {
+  const actor = event.actor || normalizeIdentityMetadata(event.metadata || {});
+  const metadata = event.metadata || {};
+  return {
+    eventType: event.type || 'unknown',
+    createdAt: event.createdAt || new Date().toISOString(),
+    route: metadata.route || metadata.path || 'unknown',
+    feature: metadata.feature || metadata.capability || metadata.route || 'unknown',
+    model: metadata.model || metadata.modelName || 'unknown',
+    tenantId: actor.tenantId || 'default',
+    userId: actor.userId || 'anonymous',
+    userEmail: actor.userEmail || null,
+    userName: actor.userName || null,
+    identityProvider: actor.identityProvider || null,
+    authMethod: actor.authMethod || null,
+    sessionId: actor.sessionId || null,
+    blocked: !!event.blocked,
+    shadowMode: !!event.shadowMode,
+    severity: (event.report && event.report.outputReview && event.report.outputReview.severity)
+      || (event.report && event.report.promptInjection && event.report.promptInjection.level)
+      || 'low',
+    topRule: (event.report && event.report.promptInjection && Array.isArray(event.report.promptInjection.matches) && event.report.promptInjection.matches[0] && event.report.promptInjection.matches[0].id) || null,
+  };
+}
+
+class PowerBIExporter {
+  constructor(options = {}) {
+    this.endpointUrl = options.endpointUrl || options.webhookUrl || null;
+    this.fetchImpl = options.fetchImpl || (typeof fetch === 'function' ? fetch : null);
+  }
+
+  async send(events = []) {
+    const records = (Array.isArray(events) ? events : [events]).filter(Boolean).map((event) => buildPowerBIRecord(event));
+    if (!this.endpointUrl || !this.fetchImpl) return records;
+    await this.fetchImpl(this.endpointUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(records),
+    });
+    return records;
+  }
+}
+
+class DataClassificationGate {
+  constructor(options = {}) {
+    this.defaultLevel = options.defaultLevel || 'internal';
+    this.providerAllowMap = options.providerAllowMap || {};
+    this.levelOrder = ['public', 'internal', 'confidential', 'restricted'];
+  }
+
+  classify({ metadata = {}, findings = [], messages = [] } = {}) {
+    if (metadata.classification) return metadata.classification;
+    const types = findings.map((item) => item.type).filter(Boolean);
+    if (types.some((type) => ['creditCard', 'tfn', 'passport', 'license', 'apiKey', 'jwt', 'bearerToken'].includes(type))) return 'restricted';
+    if (types.length) return 'confidential';
+    const text = JSON.stringify(messages || []).toLowerCase();
+    if (/\bconfidential|restricted|secret\b/.test(text)) return 'confidential';
+    return this.defaultLevel;
+  }
+
+  inspect({ metadata = {}, findings = [], messages = [], provider = null } = {}) {
+    const classification = this.classify({ metadata, findings, messages });
+    const allowedProviders = this.providerAllowMap[classification] || null;
+    const allowed = !provider || !allowedProviders || allowedProviders.includes(provider);
+    return {
+      allowed,
+      classification,
+      provider,
+      allowedProviders,
+      reason: allowed ? null : `Provider ${provider} is not allowed for ${classification} data`,
+    };
+  }
+}
+
+class ProviderRoutingPolicy {
+  constructor(options = {}) {
+    this.routes = options.routes || {};
+    this.fallbackProvider = options.fallbackProvider || null;
+  }
+
+  choose({ route = '', classification = 'internal', requestedProvider = null, candidates = [] } = {}) {
+    const routeConfig = this.routes[route] || this.routes.default || {};
+    const preferred = routeConfig[classification] || routeConfig.default || requestedProvider || this.fallbackProvider || candidates[0] || null;
+    const allowedCandidates = candidates.length ? candidates : [preferred].filter(Boolean);
+    const chosen = allowedCandidates.includes(preferred) ? preferred : allowedCandidates[0] || null;
+    return { provider: chosen, route, classification, requestedProvider, candidates: allowedCandidates };
+  }
+}
+
+class ApprovalInboxModel {
+  constructor(options = {}) {
+    this.requests = [];
+    this.requiredApprovers = options.requiredApprovers || 1;
+  }
+
+  createRequest(request = {}) {
+    const id = request.id || `apr_${crypto.randomBytes(6).toString('hex')}`;
+    const record = {
+      id,
+      status: 'pending',
+      requiredApprovers: request.requiredApprovers || this.requiredApprovers,
+      approvals: [],
+      createdAt: new Date().toISOString(),
+      ...request,
+    };
+    this.requests.push(record);
+    return record;
+  }
+
+  approve(id, approver) {
+    const request = this.requests.find((item) => item.id === id);
+    if (!request) return null;
+    if (!request.approvals.includes(approver)) request.approvals.push(approver);
+    request.status = request.approvals.length >= request.requiredApprovers ? 'approved' : 'pending';
+    return request;
+  }
+
+  summarize() {
+    return {
+      total: this.requests.length,
+      pending: this.requests.filter((item) => item.status === 'pending').length,
+      approved: this.requests.filter((item) => item.status === 'approved').length,
+    };
+  }
+}
+
+function buildComplianceEventBundle(event = {}) {
+  const payload = JSON.stringify(event);
+  const evidenceHash = crypto.createHash('sha256').update(payload).digest('hex');
+  return {
+    schemaVersion: '1.0',
+    generatedAt: new Date().toISOString(),
+    evidenceHash,
+    event,
+  };
+}
+
+function sanitizeAuditEvent(event = {}, options = {}) {
+  const keepEvidence = !!options.keepEvidence;
+  const clone = JSON.parse(JSON.stringify(event || {}));
+  if (!keepEvidence && clone.report && clone.report.sensitiveData) {
+    clone.report.sensitiveData.findings = (clone.report.sensitiveData.findings || []).map((finding) => ({ type: finding.type }));
+  }
+  return clone;
+}
+
+class RetrievalTrustScorer {
+  score(documents = []) {
+    return (documents || []).map((doc, index) => {
+      const metadata = doc && doc.metadata ? doc.metadata : {};
+      const sourceTrust = metadata.approved ? 0.4 : 0.1;
+      const freshness = metadata.fresh ? 0.3 : 0.1;
+      const origin = metadata.origin === 'trusted' ? 0.3 : 0.1;
+      const score = Number(Math.min(1, sourceTrust + freshness + origin).toFixed(2));
+      return {
+        id: doc && doc.id ? doc.id : `doc_${index + 1}`,
+        trustScore: score,
+        trusted: score >= 0.7,
+        metadata,
+      };
+    });
+  }
+}
+
+class OutboundCommunicationGuard {
+  constructor(options = {}) {
+    this.outputFirewall = options.outputFirewall || new OutputFirewall({ riskThreshold: 'high', enforceProfessionalTone: true });
+  }
+
+  inspect({ message, metadata = {} } = {}) {
+    const review = this.outputFirewall.inspect(message, {});
+    return {
+      allowed: review.allowed,
+      review,
+      channel: metadata.channel || 'outbound',
+      recipient: metadata.recipient || null,
+    };
+  }
+}
+
+class UploadQuarantineWorkflow {
+  constructor(options = {}) {
+    this.shield = options.shield || new BlackwallShield({ preset: 'documentIntake' });
+    this.inbox = options.approvalInbox || new ApprovalInboxModel({ requiredApprovers: 1 });
+  }
+
+  async inspectUpload({ content, metadata = {} } = {}) {
+    const guarded = await this.shield.guardModelRequest({
+      messages: [{ role: 'user', content }],
+      metadata: { ...metadata, feature: metadata.feature || 'upload_intake' },
+    });
+    const quarantined = !guarded.allowed || guarded.report.sensitiveData.hasSensitiveData;
+    const approvalRequest = quarantined ? this.inbox.createRequest({ route: metadata.route || '/uploads', reason: guarded.reason || 'Upload requires review', metadata }) : null;
+    return { quarantined, approvalRequest, guard: guarded };
+  }
+}
+
+function detectOperationalDrift(previousSummary = {}, currentSummary = {}) {
+  const previousBlocked = previousSummary.weeklyBlockEstimate || 0;
+  const currentBlocked = currentSummary.weeklyBlockEstimate || 0;
+  const delta = currentBlocked - previousBlocked;
+  return {
+    driftDetected: Math.abs(delta) > 0,
+    blockedDelta: delta,
+    previousBlocked,
+    currentBlocked,
+    severity: delta > 10 ? 'high' : delta > 0 ? 'medium' : 'low',
+  };
+}
+
 function summarizeOperationalTelemetry(events = []) {
   const summary = {
     totalEvents: 0,
@@ -380,6 +659,8 @@ function summarizeOperationalTelemetry(events = []) {
     byType: {},
     byRoute: {},
     byFeature: {},
+    byUser: {},
+    byIdentityProvider: {},
     byTenant: {},
     byModel: {},
     byPolicyOutcome: {
@@ -398,6 +679,8 @@ function summarizeOperationalTelemetry(events = []) {
     const route = metadata.route || metadata.path || 'unknown';
     const feature = metadata.feature || metadata.capability || route;
     const tenant = metadata.tenantId || metadata.tenant_id || 'unknown';
+    const user = metadata.userId || metadata.user_id || (event.actor && event.actor.userId) || 'unknown';
+    const idp = metadata.identityProvider || metadata.identity_provider || (event.actor && event.actor.identityProvider) || 'unknown';
     const model = metadata.model || metadata.modelName || 'unknown';
     const severity = event && event.report && event.report.outputReview
       ? event.report.outputReview.severity
@@ -406,6 +689,8 @@ function summarizeOperationalTelemetry(events = []) {
     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.byUser[user] = (summary.byUser[user] || 0) + 1;
+    summary.byIdentityProvider[idp] = (summary.byIdentityProvider[idp] || 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;
@@ -1112,6 +1397,8 @@ class BlackwallShield {
       outputFirewallDefaults: {},
       onAlert: null,
       onTelemetry: null,
+      telemetryExporters: [],
+      identityResolver: null,
       webhookUrl: null,
       ...options,
     };
@@ -1143,8 +1430,15 @@ class BlackwallShield {
   }
 
   async emitTelemetry(event) {
+    const enriched = buildEnterpriseTelemetryEvent(event, this.options.identityResolver);
     if (typeof this.options.onTelemetry === 'function') {
-      await this.options.onTelemetry(event);
+      await this.options.onTelemetry(enriched);
+    }
+    const exporters = Array.isArray(this.options.telemetryExporters) ? this.options.telemetryExporters : [];
+    for (const exporter of exporters) {
+      if (exporter && typeof exporter.send === 'function') {
+        await exporter.send([enriched]);
+      }
     }
   }
 
@@ -1563,9 +1857,10 @@ class CoTScanner {
 }
 
 class AgentIdentityRegistry {
-  constructor() {
+  constructor(options = {}) {
     this.identities = new Map();
     this.ephemeralTokens = new Map();
+    this.secret = options.secret || 'blackwall-agent-passport-secret';
   }
 
   register(agentId, profile = {}) {
@@ -1595,6 +1890,256 @@ class AgentIdentityRegistry {
     }
     return { valid: true, agentId: record.agentId };
   }
+
+  issueSignedPassport(agentId, options = {}) {
+    const identity = this.get(agentId) || this.register(agentId, options.profile || {});
+    const securityScore = options.securityScore != null
+      ? options.securityScore
+      : Math.max(0, 100 - (Object.values(identity.capabilities || {}).filter(Boolean).length * 10));
+    const passport = {
+      agentId,
+      issuedAt: new Date().toISOString(),
+      issuer: options.issuer || 'blackwall-llm-shield-js',
+      blackwallProtected: options.blackwallProtected !== false,
+      securityScore,
+      scopes: identity.scopes || [],
+      persona: identity.persona || 'default',
+      environment: options.environment || 'production',
+    };
+    const signature = crypto.createHmac('sha256', this.secret).update(JSON.stringify(passport)).digest('hex');
+    return { ...passport, signature };
+  }
+
+  verifySignedPassport(passport = {}) {
+    const { signature, ...unsigned } = passport || {};
+    if (!signature) return { valid: false, reason: 'Passport signature is required' };
+    const expected = crypto.createHmac('sha256', this.secret).update(JSON.stringify(unsigned)).digest('hex');
+    return {
+      valid: crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)),
+      agentId: unsigned.agentId || null,
+      securityScore: unsigned.securityScore || null,
+      blackwallProtected: !!unsigned.blackwallProtected,
+    };
+  }
+
+  issuePassportToken(agentId, options = {}) {
+    const passport = this.issueSignedPassport(agentId, options);
+    const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+    const payload = Buffer.from(JSON.stringify(passport)).toString('base64url');
+    const signature = crypto.createHmac('sha256', this.secret).update(`${header}.${payload}`).digest('base64url');
+    return `${header}.${payload}.${signature}`;
+  }
+
+  verifyPassportToken(token) {
+    if (!token || typeof token !== 'string' || token.split('.').length !== 3) {
+      return { valid: false, reason: 'Malformed passport token' };
+    }
+    const [header, payload, signature] = token.split('.');
+    const expected = crypto.createHmac('sha256', this.secret).update(`${header}.${payload}`).digest('base64url');
+    if (signature !== expected) return { valid: false, reason: 'Invalid passport token signature' };
+    const passport = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+    return { valid: true, passport, ...this.verifySignedPassport(passport) };
+  }
+}
+
+class ValueAtRiskCircuitBreaker {
+  constructor(options = {}) {
+    this.maxValuePerWindow = options.maxValuePerWindow || 5000;
+    this.windowMs = options.windowMs || (60 * 60 * 1000);
+    this.revocationMs = options.revocationMs || (30 * 60 * 1000);
+    this.valueExtractor = options.valueExtractor || ((args = {}, context = {}) => Number(context.actionValue != null ? context.actionValue : (args.amount != null ? args.amount : 0)));
+    this.toolSchemas = options.toolSchemas || [];
+    this.entries = [];
+    this.revocations = new Map();
+  }
+
+  revokeSession(sessionId, durationMs = this.revocationMs) {
+    if (!sessionId) return null;
+    const expiresAt = Date.now() + durationMs;
+    this.revocations.set(sessionId, expiresAt);
+    return { sessionId, revokedUntil: new Date(expiresAt).toISOString() };
+  }
+
+  inspect({ tool, args = {}, context = {} } = {}) {
+    const sessionId = context.sessionId || context.session_id || null;
+    const now = Date.now();
+    const revokedUntil = sessionId ? this.revocations.get(sessionId) : null;
+    if (revokedUntil && revokedUntil > now) {
+      return {
+        allowed: false,
+        triggered: true,
+        requiresMfa: true,
+        reason: 'Session is revoked until MFA or human review completes',
+        revokedSession: sessionId,
+        revokedUntil: new Date(revokedUntil).toISOString(),
+        riskWindowValue: null,
+      };
+    }
+    this.entries = this.entries.filter((entry) => (now - entry.at) <= this.windowMs);
+    const schema = this.toolSchemas.find((item) => item && item.name === tool) || {};
+    const field = schema.monetaryValueField || schema.valueField || null;
+    const schemaValue = field ? Number(args && args[field]) : 0;
+    const actionValue = Math.max(0, Number((schemaValue || this.valueExtractor(args, context)) || 0));
+    const key = sessionId || context.agentId || context.agent_id || context.userId || context.user_id || 'default';
+    const relevant = this.entries.filter((entry) => entry.key === key);
+    const riskWindowValue = relevant.reduce((sum, entry) => sum + entry.value, 0) + actionValue;
+    const triggered = riskWindowValue > this.maxValuePerWindow;
+    if (triggered) {
+      const revocation = this.revokeSession(sessionId);
+      return {
+        allowed: false,
+        triggered: true,
+        requiresMfa: true,
+        reason: `Value-at-risk threshold exceeded for ${tool || 'action'}`,
+        riskWindowValue,
+        threshold: this.maxValuePerWindow,
+        actionValue,
+        revokedSession: revocation && revocation.sessionId,
+        revokedUntil: revocation && revocation.revokedUntil,
+      };
+    }
+    this.entries.push({ key, tool: tool || 'unknown', value: actionValue, at: now });
+    return {
+      allowed: true,
+      triggered: false,
+      requiresMfa: false,
+      riskWindowValue,
+      threshold: this.maxValuePerWindow,
+      actionValue,
+    };
+  }
+}
+
+class ShadowConsensusAuditor {
+  constructor(options = {}) {
+    this.review = options.review || ((payload = {}) => {
+      const text = JSON.stringify({ tool: payload.tool, args: payload.args, sessionContext: payload.sessionContext || '' }).toLowerCase();
+      const disagreement = /\b(ignore previous|bypass|override|secret|reveal)\b/i.test(text);
+      return {
+        agreed: !disagreement,
+        disagreement,
+        reason: disagreement ? 'Logic Conflict: shadow auditor found risky reasoning drift' : null,
+      };
+    });
+  }
+
+  inspect(payload = {}) {
+    const result = this.review(payload) || {};
+    return {
+      agreed: result.agreed !== false,
+      disagreement: !!result.disagreement || result.agreed === false,
+      reason: result.reason || (result.agreed === false ? 'Logic Conflict detected by shadow auditor' : null),
+      auditor: result.auditor || 'shadow',
+    };
+  }
+}
+
+class CrossModelConsensusWrapper {
+  constructor(options = {}) {
+    this.primaryAdapter = options.primaryAdapter || null;
+    this.auditorAdapter = options.auditorAdapter || null;
+    this.decisionParser = options.decisionParser || ((output) => {
+      const text = typeof output === 'string' ? output : JSON.stringify(output || '');
+      if (/\b(block|unsafe|deny|disagree)\b/i.test(text)) return 'block';
+      return 'allow';
+    });
+  }
+
+  async evaluate({ messages = [], metadata = {}, primaryResult = null } = {}) {
+    if (!this.auditorAdapter || typeof this.auditorAdapter.invoke !== 'function') {
+      return { agreed: true, disagreement: false, reason: null, primaryDecision: 'allow', auditorDecision: 'allow' };
+    }
+    const primaryDecision = primaryResult && primaryResult.blocked ? 'block' : 'allow';
+    const response = await this.auditorAdapter.invoke({ messages, metadata, primaryResult });
+    const output = typeof this.auditorAdapter.extractOutput === 'function'
+      ? this.auditorAdapter.extractOutput(response && Object.prototype.hasOwnProperty.call(response, 'response') ? response.response : response)
+      : (response && response.output) || response;
+    const auditorDecision = this.decisionParser(output);
+    const disagreement = auditorDecision !== primaryDecision;
+    return {
+      agreed: !disagreement,
+      disagreement,
+      primaryDecision,
+      auditorDecision,
+      reason: disagreement ? 'Logic Conflict: cross-model auditor disagreed with the primary decision' : null,
+      auditorResponse: response,
+      auditorOutput: output,
+    };
+  }
+}
+
+class DigitalTwinOrchestrator {
+  constructor(options = {}) {
+    this.toolSchemas = options.toolSchemas || [];
+    this.invocations = [];
+  }
+
+  generate() {
+    const handlers = {};
+    for (const schema of this.toolSchemas) {
+      if (!schema || !schema.name) continue;
+      handlers[schema.name] = async (args = {}) => {
+        const response = schema.mockResponse || schema.sampleResponse || { ok: true, tool: schema.name, args };
+        this.invocations.push({ tool: schema.name, args, response, at: new Date().toISOString() });
+        return response;
+      };
+    }
+    return {
+      handlers,
+      simulateCall: async (tool, args = {}) => {
+        if (!handlers[tool]) throw new Error(`No digital twin registered for ${tool}`);
+        return handlers[tool](args);
+      },
+      invocations: this.invocations,
+    };
+  }
+
+  static fromToolPermissionFirewall(firewall) {
+    const schemas = Array.isArray(firewall && firewall.options && firewall.options.toolSchemas)
+      ? firewall.options.toolSchemas
+      : [];
+    return new DigitalTwinOrchestrator({ toolSchemas: schemas });
+  }
+}
+
+function suggestPolicyOverride({ route = null, approval = null, guardResult = null, toolDecision = null } = {}) {
+  if (approval !== true) return null;
+  if (guardResult && guardResult.report && guardResult.report.promptInjection) {
+    const rules = (guardResult.report.promptInjection.matches || []).map((item) => item.id).filter(Boolean);
+    return {
+      route: route || (guardResult.report.metadata && (guardResult.report.metadata.route || guardResult.report.metadata.path)) || '*',
+      options: {
+        shadowMode: true,
+        suppressPromptRules: [...new Set(rules)],
+      },
+      rationale: 'Suggested from approved false positive',
+    };
+  }
+  if (toolDecision && toolDecision.approvalRequest) {
+    return {
+      route: route || ((toolDecision.approvalRequest.context || {}).route) || '*',
+      options: {
+        requireHumanApprovalFor: [toolDecision.approvalRequest.tool],
+      },
+      rationale: 'Suggested from approved high-impact tool action',
+    };
+  }
+  return null;
+}
+
+class PolicyLearningLoop {
+  constructor() {
+    this.decisions = [];
+  }
+
+  recordDecision(input = {}) {
+    this.decisions.push({ ...input, recordedAt: new Date().toISOString() });
+    return suggestPolicyOverride(input);
+  }
+
+  suggestOverrides() {
+    return this.decisions.map((entry) => suggestPolicyOverride(entry)).filter(Boolean);
+  }
 }
 
 class AgenticCapabilityGater {
@@ -1735,8 +2280,13 @@ class ToolPermissionFirewall {
       allowedTools: [],
       blockedTools: [],
       validators: {},
+      toolSchemas: [],
       requireHumanApprovalFor: [],
       capabilityGater: null,
+      valueAtRiskCircuitBreaker: null,
+      consensusAuditor: null,
+      crossModelConsensus: null,
+      consensusRequiredFor: [],
       onApprovalRequest: null,
       approvalWebhookUrl: null,
       ...options,
@@ -1766,6 +2316,46 @@ class ToolPermissionFirewall {
         return { allowed: false, reason: gate.reason, requiresApproval: false, agentGate: gate };
       }
     }
+    if (this.options.valueAtRiskCircuitBreaker) {
+      const breaker = this.options.valueAtRiskCircuitBreaker.inspect({ tool, args, context });
+      if (!breaker.allowed) {
+        return {
+          allowed: false,
+          reason: breaker.reason,
+          requiresApproval: true,
+          requiresMfa: !!breaker.requiresMfa,
+          circuitBreaker: breaker,
+          approvalRequest: { tool, args, context, breaker },
+        };
+      }
+    }
+    if (this.options.consensusAuditor && (context.highImpact || this.options.consensusRequiredFor.includes(tool))) {
+      const consensus = this.options.consensusAuditor.inspect({
+        tool,
+        args,
+        context,
+        sessionContext: context.sessionContext || context.session_buffer || null,
+      });
+      if (consensus.disagreement) {
+        return {
+          allowed: false,
+          reason: consensus.reason || 'Logic Conflict detected by shadow auditor',
+          requiresApproval: true,
+          logicConflict: true,
+          consensus,
+          approvalRequest: { tool, args, context, consensus },
+        };
+      }
+    }
+    if (this.options.crossModelConsensus && (context.highImpact || this.options.consensusRequiredFor.includes(tool))) {
+      return {
+        allowed: false,
+        reason: 'Cross-model consensus requires async inspection',
+        requiresApproval: true,
+        requiresAsyncConsensus: true,
+        approvalRequest: { tool, args, context },
+      };
+    }
     const requiresApproval = this.options.requireHumanApprovalFor.includes(tool);
     return {
       allowed: !requiresApproval,
@@ -1777,6 +2367,24 @@ class ToolPermissionFirewall {
 
   async inspectCallAsync(input = {}) {
     const result = this.inspectCall(input);
+    if (result.requiresAsyncConsensus && this.options.crossModelConsensus) {
+      const consensus = await this.options.crossModelConsensus.evaluate({
+        messages: input.context && input.context.consensusMessages ? input.context.consensusMessages : [{ role: 'user', content: JSON.stringify({ tool: input.tool, args: input.args, context: input.context }) }],
+        metadata: input.context || {},
+        primaryResult: result,
+      });
+      if (consensus.disagreement) {
+        return {
+          allowed: false,
+          reason: consensus.reason,
+          requiresApproval: true,
+          logicConflict: true,
+          consensus,
+          approvalRequest: { tool: input.tool, args: input.args || {}, context: input.context || {}, consensus },
+        };
+      }
+      return { allowed: true, reason: null, requiresApproval: false, consensus };
+    }
     if (result.requiresApproval) {
       if (typeof this.options.onApprovalRequest === 'function') {
         await this.options.onApprovalRequest(result.approvalRequest);
@@ -1860,11 +2468,14 @@ class AuditTrail {
   constructor(options = {}) {
     this.secret = options.secret || 'blackwall-default-secret';
     this.events = [];
+    this.identityResolver = options.identityResolver || null;
   }
 
   record(event = {}) {
+    const actor = event.actor || normalizeIdentityMetadata(event.metadata || event, this.identityResolver);
     const payload = {
       ...event,
+      actor,
       complianceMap: event.complianceMap || mapCompliance([
         ...(event.ruleIds || []),
         event.type === 'retrieval_poisoning_detected' ? 'retrieval_poisoning' : null,
@@ -2130,14 +2741,20 @@ module.exports = {
   AuditTrail,
   BlackwallShield,
   CoTScanner,
+  CrossModelConsensusWrapper,
+  DigitalTwinOrchestrator,
   ImageMetadataScanner,
   LightweightIntentScorer,
   MCPSecurityProxy,
   OutputFirewall,
+  PowerBIExporter,
+  PolicyLearningLoop,
   RetrievalSanitizer,
   SessionBuffer,
+  ShadowConsensusAuditor,
   TokenBudgetFirewall,
   ToolPermissionFirewall,
+  ValueAtRiskCircuitBreaker,
   VisualInstructionDetector,
   SENSITIVE_PATTERNS,
   PROMPT_INJECTION_RULES,
@@ -2167,6 +2784,19 @@ module.exports = {
   runRedTeamSuite,
   buildShieldOptions,
   summarizeOperationalTelemetry,
+  suggestPolicyOverride,
+  normalizeIdentityMetadata,
+  buildEnterpriseTelemetryEvent,
+  buildPowerBIRecord,
+  buildComplianceEventBundle,
+  sanitizeAuditEvent,
+  detectOperationalDrift,
+  DataClassificationGate,
+  ProviderRoutingPolicy,
+  ApprovalInboxModel,
+  RetrievalTrustScorer,
+  OutboundCommunicationGuard,
+  UploadQuarantineWorkflow,
   parseJsonOutput,
   createOpenAIAdapter,
   createAnthropicAdapter,