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

package/README.md

@@ -81,10 +81,16 @@ Use `shadowMode` with `shadowPolicyPacks` or `comparePolicyPacks` to record what
 
 Use `createOpenAIAdapter()`, `createAnthropicAdapter()`, `createGeminiAdapter()`, or `createOpenRouterAdapter()` with `protectWithAdapter()` when you want Blackwall to wrap the provider call end to end.
 
+### Controlled-pilot rollout
+
+The current recommendation for enterprise teams is a controlled pilot first: start in shadow mode, aggregate route-level telemetry, tune suppressions explicitly, then promote the cleanest routes to enforcement.
+
 ### Observability and control-plane support
 
 Use `summarizeOperationalTelemetry()` with emitted telemetry events when you want route-level summaries, blocked-event counts, and rollout visibility for operators.
 
+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.
@@ -115,6 +121,8 @@ 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.
@@ -138,6 +146,14 @@ Recommended presets:
 
 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
+- `DigitalTwinOrchestrator` for mock tool environments and sandbox simulations
+- `suggestPolicyOverride()` for narrow false-positive tuning suggestions after HITL approvals
+- `AgentIdentityRegistry.issueSignedPassport()` for signed agent identity exchange
+
 ## Example Workflows
 
 ### Guard a request before calling the model
@@ -181,6 +197,64 @@ const result = await shield.protectWithAdapter({
 console.log(result.stage, result.allowed);
 ```
 
+### Wrap Blackwall behind your own app adapter
+
+```js
+function createModelShield(shield) {
+  return {
+    async run({ messages, metadata, callProvider }) {
+      return shield.protectModelCall({
+        messages,
+        metadata,
+        callModel: callProvider,
+      });
+    },
+  };
+}
+```
+
+### 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'],
+});
+```
+
+### 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' });
+```
+
 ### Protect a strict JSON workflow
 
 ```js
@@ -218,6 +292,18 @@ const shield = new BlackwallShield({
 });
 ```
 
+### Next.js App Router plus Gemini pattern
+
+For App Router route handlers, the cleanest production shape is:
+
+- parse the request in `app/api/.../route.ts`
+- use `preset: 'shadowFirst'` or a route-specific preset like `agentPlanner` or `documentReview`
+- attach `route`, `feature`, and `tenantId` metadata
+- wrap the Gemini SDK call with `createGeminiAdapter()` plus `protectWithAdapter()`
+- ship `report.telemetry` and `onTelemetry` into a route-level log sink
+
+That keeps request guarding, output review, and operator reporting in one path without scattering policy logic across the route.
+
 ### Route and domain examples
 
 For RAG:
@@ -273,6 +359,13 @@ const shield = new BlackwallShield({
 - Full provider wrapper: `protectWithAdapter()`
 - Tool firewall + RAG sanitizer: `ToolPermissionFirewall` + `RetrievalSanitizer`
 
+### False-positive tuning
+
+- Start with route-level `shadowMode: true`
+- Add `suppressPromptRules` only per route, not globally, so the reason for each suppression stays obvious
+- Log `report.promptInjection.matches` and `report.telemetry.promptInjectionRuleHits` to explain why a request was flagged
+- Review `summary.noisiestRoutes`, `summary.byFeature`, and `summary.weeklyBlockEstimate` before raising enforcement
+
 ### Operational telemetry summaries
 
 ```js
@@ -280,6 +373,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);
@@ -328,6 +423,14 @@ For Next.js, the most production-real patterns are App Router route handlers, se
 
 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.
 
+## Enterprise Adoption Notes
+
+- 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
 
 - `npm run release:check` runs the JS test suite before release

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,22 @@ 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 DigitalTwinOrchestrator {
+  constructor(options?: Record<string, unknown>);
+  generate(): Record<string, unknown>;
+}
+
 export class RetrievalSanitizer {
   constructor(options?: Record<string, unknown>);
   sanitizeDocuments(documents: Array<Record<string, unknown>>): Array<Record<string, unknown>>;
@@ -97,6 +115,14 @@ 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 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.7",
+  "version": "0.2.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)",

package/src/index.js

@@ -372,6 +372,83 @@ 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;
+  }
+}
+
 function summarizeOperationalTelemetry(events = []) {
   const summary = {
     totalEvents: 0,
@@ -380,6 +457,8 @@ function summarizeOperationalTelemetry(events = []) {
     byType: {},
     byRoute: {},
     byFeature: {},
+    byUser: {},
+    byIdentityProvider: {},
     byTenant: {},
     byModel: {},
     byPolicyOutcome: {
@@ -398,6 +477,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 +487,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 +1195,8 @@ class BlackwallShield {
       outputFirewallDefaults: {},
       onAlert: null,
       onTelemetry: null,
+      telemetryExporters: [],
+      identityResolver: null,
       webhookUrl: null,
       ...options,
     };
@@ -1143,8 +1228,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 +1655,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 +1688,177 @@ 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,
+    };
+  }
+}
+
+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.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 actionValue = Math.max(0, Number(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 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,
+    };
+  }
+}
+
+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 AgenticCapabilityGater {
@@ -1737,6 +2001,9 @@ class ToolPermissionFirewall {
       validators: {},
       requireHumanApprovalFor: [],
       capabilityGater: null,
+      valueAtRiskCircuitBreaker: null,
+      consensusAuditor: null,
+      consensusRequiredFor: [],
       onApprovalRequest: null,
       approvalWebhookUrl: null,
       ...options,
@@ -1766,6 +2033,37 @@ 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 },
+        };
+      }
+    }
     const requiresApproval = this.options.requireHumanApprovalFor.includes(tool);
     return {
       allowed: !requiresApproval,
@@ -1860,11 +2158,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 +2431,18 @@ module.exports = {
   AuditTrail,
   BlackwallShield,
   CoTScanner,
+  DigitalTwinOrchestrator,
   ImageMetadataScanner,
   LightweightIntentScorer,
   MCPSecurityProxy,
   OutputFirewall,
+  PowerBIExporter,
   RetrievalSanitizer,
   SessionBuffer,
+  ShadowConsensusAuditor,
   TokenBudgetFirewall,
   ToolPermissionFirewall,
+  ValueAtRiskCircuitBreaker,
   VisualInstructionDetector,
   SENSITIVE_PATTERNS,
   PROMPT_INJECTION_RULES,
@@ -2167,6 +2472,10 @@ module.exports = {
   runRedTeamSuite,
   buildShieldOptions,
   summarizeOperationalTelemetry,
+  suggestPolicyOverride,
+  normalizeIdentityMetadata,
+  buildEnterpriseTelemetryEvent,
+  buildPowerBIRecord,
   parseJsonOutput,
   createOpenAIAdapter,
   createAnthropicAdapter,