feat(policy-loader): 8.7 — env-var deprecation warnings (v8.0.0 removal)

plugins/llm-security/scanners/lib/audit-trail.mjs

@@ -1,9 +1,12 @@
 // audit-trail.mjs — Structured JSONL audit trail writer
-// Writes SIEM-ready events to the path specified by LLM_SECURITY_AUDIT_LOG.
-// No-op when env var is not set. Zero external dependencies.
+// Resolves the audit-log path via getPolicyValueWithEnvWarn so the env-var
+// LLM_SECURITY_AUDIT_LOG and policy.json key audit.log_path stay in sync,
+// with a one-time deprecation warning when both are explicitly set.
+// No-op when neither env nor policy provides a path. Zero external dependencies.
 
 import { appendFileSync, writeFileSync, accessSync, constants } from 'node:fs';
 import { dirname } from 'node:path';
+import { getPolicyValueWithEnvWarn } from './policy-loader.mjs';
 
 let auditPath = null;
 let initialized = false;
@@ -16,19 +19,22 @@ function initAuditTrail() {
   if (initialized) return auditPath !== null;
   initialized = true;
 
-  const envPath = process.env.LLM_SECURITY_AUDIT_LOG;
-  if (!envPath) return false;
+  // D3 (v7.3.0): env still wins, deprecation warning when policy also set.
+  const resolved = getPolicyValueWithEnvWarn(
+    'audit', 'log_path', 'LLM_SECURITY_AUDIT_LOG', null
+  );
+  if (!resolved) return false;
 
   try {
     // Ensure parent directory exists and is writable
-    const dir = dirname(envPath);
+    const dir = dirname(resolved);
     accessSync(dir, constants.W_OK);
     // Touch file if it doesn't exist
-    try { accessSync(envPath); } catch { writeFileSync(envPath, ''); }
-    auditPath = envPath;
+    try { accessSync(resolved); } catch { writeFileSync(resolved, ''); }
+    auditPath = resolved;
     return true;
   } catch (err) {
-    process.stderr.write(`[llm-security] Audit trail path not writable: ${envPath} (${err.message})\n`);
+    process.stderr.write(`[llm-security] Audit trail path not writable: ${resolved} (${err.message})\n`);
     return false;
   }
 }

plugins/llm-security/scanners/lib/policy-loader.mjs

@@ -21,6 +21,7 @@ const DEFAULT_POLICY = Object.freeze({
     mode: 'warn',
     window_size: 20,
     long_horizon_window: 100,
+    escalation_window: 5,
   },
   secrets: {
     additional_patterns: [],
@@ -69,6 +70,11 @@ const DEFAULT_POLICY = Object.freeze({
 // Cache loaded policy per project root
 const cache = new Map();
 
+// Module-scoped Set of env-var names already warned about — dedupes to one
+// stderr line per env-var per process, regardless of how many call-sites
+// invoke getPolicyValueWithEnvWarn for the same name.
+const _warnedEnvVars = new Set();
+
 /**
  * Resolve project root from env or cwd.
  * @param {string} [explicitRoot]
@@ -148,6 +154,57 @@ export function getPolicyValue(section, key, defaultValue, projectRoot) {
   return defaultValue;
 }
 
+/**
+ * Resolve a policy value with an overlapping env-var, emitting a one-time
+ * stderr deprecation warning when both the env-var AND the policy.json key
+ * are explicitly set.
+ *
+ * Resolution order (env-wins is unchanged from getPolicyValue contract):
+ *   1. If LLM_SECURITY_DEPRECATION_QUIET=1, suppress warning logic entirely
+ *      and return env-value (if defined) else policy-value.
+ *   2. Otherwise, if env-var is set AND policy-value differs from
+ *      defaultValue (heuristic: user wrote the key in policy.json),
+ *      emit one stderr warning per envVarName per process.
+ *   3. Return env-value if defined, else policy-value.
+ *
+ * Why "differs from defaultValue" rather than parsing the raw policy file:
+ * loadPolicy() deep-merges DEFAULT_POLICY so `key in policy[section]` is
+ * always true. Comparing the resolved value to the caller's defaultValue
+ * is a reliable proxy for "user explicitly overrode this in policy.json"
+ * because callers pass defaults that match DEFAULT_POLICY.
+ *
+ * @param {string} section - Policy section (e.g. 'injection', 'trifecta')
+ * @param {string} key - Key within section (e.g. 'mode')
+ * @param {string} envVarName - Overlapping env-var (e.g. 'LLM_SECURITY_INJECTION_MODE')
+ * @param {*} defaultValue - Hardcoded default (must match DEFAULT_POLICY value)
+ * @param {string} [projectRoot] - Explicit root
+ * @returns {*}
+ */
+export function getPolicyValueWithEnvWarn(section, key, envVarName, defaultValue, projectRoot) {
+  const envValue = process.env[envVarName];
+
+  if (process.env.LLM_SECURITY_DEPRECATION_QUIET === '1') {
+    if (envValue !== undefined) return envValue;
+    return getPolicyValue(section, key, defaultValue, projectRoot);
+  }
+
+  const policyValue = getPolicyValue(section, key, defaultValue, projectRoot);
+
+  if (envValue !== undefined && policyValue !== defaultValue) {
+    if (!_warnedEnvVars.has(envVarName)) {
+      _warnedEnvVars.add(envVarName);
+      process.stderr.write(
+        `[llm-security] Deprecation: env-var ${envVarName} will be removed in v8.0.0; ` +
+        `policy.json key ${section}.${key} also set — env wins for now. ` +
+        `Suppress with LLM_SECURITY_DEPRECATION_QUIET=1.\n`
+      );
+    }
+  }
+
+  if (envValue !== undefined) return envValue;
+  return policyValue;
+}
+
 /**
  * Get the full default policy (for documentation/example generation).
  * @returns {object}
@@ -157,8 +214,9 @@ export function getDefaultPolicy() {
 }
 
 /**
- * Reset cache (for testing only).
+ * Reset cache and warning dedup state (for testing only).
  */
 export function _resetCacheForTest() {
   cache.clear();
+  _warnedEnvVars.clear();
 }