shroud-privacy 2.2.20 → 2.3.0

package/README.md

@@ -233,18 +233,78 @@ Out of the box, Shroud:
 
 > **Env var overrides:** `SHROUD_SECRET_KEY` and `SHROUD_PERSISTENT_SALT` override their respective config keys (priority: env var > plugin config > default).
 
-### Detector overrides
+### Detection rules as code (hot-reload)
 
-Disable or tune individual detection rules by name. Rule names match the built-in pattern names (e.g. `email`, `ipv4`, `phone_intl`, `cisco_enable_secret`). See `src/detectors/regex.ts` for the full list.
+Shroud auto-generates a JSONC config file on first run containing every built-in detection rule:
+
+```
+~/.shroud/shroud.config.json
+```
+
+The file is fully editable. Changes hot-reload within 2 seconds — no gateway restart needed.
+
+**Priority:** env vars > config file > plugin config > defaults.
+
+#### Override a built-in rule
+
+Change the regex, confidence, or category of any rule:
+
+```jsonc
+{
+  "rules": {
+    "email": { "pattern": "\\b[\\w.+-]+@[\\w-]+\\.[a-z]{2,}\\b", "confidence": 0.99 }
+  }
+}
+```
+
+#### Disable a rule
 
 ```jsonc
-"detectorOverrides": {
-  "phone_intl": { "enabled": false },         // disable international phone detection
-  "file_path_unix": { "confidence": 0.5 },    // lower confidence (filtered by minConfidence)
-  "snmp_community": { "confidence": 1.0 }     // boost to always match
+{
+  "rules": {
+    "phone_us": { "enabled": false },
+    "gps_coordinate": { "enabled": false }
+  }
+}
+```
+
+#### Add a custom rule
+
+```jsonc
+{
+  "rules": {
+    "internal_ticket": {
+      "pattern": "\\bTICK-\\d{6}\\b",
+      "category": "custom",
+      "confidence": 0.9
+    }
+  }
 }
 ```
 
+#### Rule format
+
+Each rule in the `rules` object supports:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `pattern` | string | Regex pattern (required for new rules, optional for overrides) |
+| `category` | string | Entity category: `email`, `ip_address`, `phone`, `hostname`, `network_credential`, `custom`, etc. |
+| `confidence` | number | Detection confidence 0.0-1.0 (filtered by `minConfidence`) |
+| `enabled` | boolean | Set to `false` to disable a rule |
+
+#### Config manager features
+
+| Feature | Detail |
+|---------|--------|
+| Format | JSONC (JSON with `//` and `/* */` comments) |
+| Auto-create | Config file generated on first run with all built-in rules |
+| Watch interval | 2 seconds |
+| History depth | 50 versions (commit/rollback via dashboard API) |
+| Restart-only fields | `secretKey`, `persistentSalt`, `dashboardEnabled`, `dashboardPort`, `maxStoreMappings` — logged as warnings, not applied until restart |
+
+> **Legacy:** `detectorOverrides` and `customPatterns` in `openclaw.json` still work. The `rules` config is the preferred way — it replaces both.
+
 ---
 
 ## URL handling

package/dist/config-manager.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Config-as-code manager with hot-reload.
+ *
+ * Watches a JSONC config file (`~/.shroud/shroud.config.json` by default)
+ * and merges it with the base config from `resolveConfig(pluginConfig)`.
+ *
+ * Priority: env vars > config file > plugin config > defaults.
+ *
+ * Supports:
+ * - JSONC (JSON with // and /* comments)
+ * - Keyed field-change callbacks (only fires when watched fields change)
+ * - Generic reload callbacks
+ * - Commit/rollback with 50-version history
+ * - Dashboard read/write via setFields()
+ */
+import type { ShroudConfig } from "./types.js";
+import { type ConfigIssue } from "./config.js";
+/** A versioned config snapshot. */
+export interface ConfigCommit {
+    version: number;
+    timestamp: string;
+    description: string;
+    config: Partial<ShroudConfig>;
+}
+export declare class ConfigManager {
+    private _configPath;
+    private _historyPath;
+    private _base;
+    private _fileOverrides;
+    private _effective;
+    private _fieldListeners;
+    private _reloadListeners;
+    private _history;
+    private _version;
+    private _watching;
+    constructor(configPath: string, baseConfig: ShroudConfig);
+    /** Current effective config (merged). */
+    getEffective(): ShroudConfig;
+    /** Raw overrides from the config file. */
+    getFileOverrides(): Partial<ShroudConfig>;
+    /** Path to the config file. */
+    getConfigPath(): string;
+    /** Current version number (increments on each commit). */
+    getCurrentVersion(): number;
+    /**
+     * Register a callback that fires when any of the specified fields change.
+     * The callback is deduplicated: even if multiple watched fields change in
+     * one reload, the callback fires exactly once.
+     */
+    onFieldChange(fields: string[], callback: () => void): void;
+    /** Register a callback that fires on every successful reload. */
+    onReload(callback: (config: ShroudConfig) => void): void;
+    startWatching(): void;
+    stopWatching(): void;
+    /** Merge partial config into the file and trigger reload. */
+    setFields(partial: Partial<ShroudConfig>): {
+        changedFields: string[];
+        warnings: string[];
+    };
+    /** Validate a partial config without applying it. */
+    validate(partial: Partial<ShroudConfig>): ConfigIssue[];
+    commit(description: string): ConfigCommit;
+    rollback(version: number): ConfigCommit | null;
+    getHistory(): ConfigCommit[];
+    /** Generate default config file with all built-in detection rules. */
+    private _writeDefaultConfig;
+    private _reload;
+    private _loadFile;
+    private _saveFile;
+    private _merge;
+    private _diff;
+    private _loadHistory;
+    private _saveHistory;
+}
+/**
+ * Strip // and /* comments from JSONC text.
+ * Handles strings correctly (doesn't strip inside quoted values).
+ */
+export declare function stripComments(jsonc: string): string;

package/dist/config-manager.js

@@ -0,0 +1,417 @@
+/**
+ * Config-as-code manager with hot-reload.
+ *
+ * Watches a JSONC config file (`~/.shroud/shroud.config.json` by default)
+ * and merges it with the base config from `resolveConfig(pluginConfig)`.
+ *
+ * Priority: env vars > config file > plugin config > defaults.
+ *
+ * Supports:
+ * - JSONC (JSON with // and /* comments)
+ * - Keyed field-change callbacks (only fires when watched fields change)
+ * - Generic reload callbacks
+ * - Commit/rollback with 50-version history
+ * - Dashboard read/write via setFields()
+ */
+import { readFileSync, writeFileSync, existsSync, watchFile, unwatchFile, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { validateConfig } from "./config.js";
+import { BUILTIN_PATTERNS } from "./detectors/regex.js";
+/** Fields that cannot be hot-reloaded — require gateway restart. */
+const RESTART_ONLY = new Set([
+    "secretKey",
+    "persistentSalt",
+    "dashboardEnabled",
+    "dashboardPort",
+    "maxStoreMappings",
+]);
+export class ConfigManager {
+    _configPath;
+    _historyPath;
+    _base;
+    _fileOverrides;
+    _effective;
+    _fieldListeners = [];
+    _reloadListeners = [];
+    _history = [];
+    _version = 0;
+    _watching = false;
+    constructor(configPath, baseConfig) {
+        this._configPath = configPath;
+        this._historyPath = configPath + ".history.json";
+        this._base = baseConfig;
+        // Auto-create config file with built-in rules if it doesn't exist
+        if (!existsSync(configPath)) {
+            this._writeDefaultConfig();
+        }
+        this._fileOverrides = this._loadFile();
+        this._effective = this._merge(this._base, this._fileOverrides);
+        this._loadHistory();
+    }
+    /** Current effective config (merged). */
+    getEffective() {
+        return this._effective;
+    }
+    /** Raw overrides from the config file. */
+    getFileOverrides() {
+        return { ...this._fileOverrides };
+    }
+    /** Path to the config file. */
+    getConfigPath() {
+        return this._configPath;
+    }
+    /** Current version number (increments on each commit). */
+    getCurrentVersion() {
+        return this._version;
+    }
+    // ── Subscriptions ──────────────────────────────────────
+    /**
+     * Register a callback that fires when any of the specified fields change.
+     * The callback is deduplicated: even if multiple watched fields change in
+     * one reload, the callback fires exactly once.
+     */
+    onFieldChange(fields, callback) {
+        this._fieldListeners.push({ fields: new Set(fields), callback });
+    }
+    /** Register a callback that fires on every successful reload. */
+    onReload(callback) {
+        this._reloadListeners.push(callback);
+    }
+    // ── File watching ──────────────────────────────────────
+    startWatching() {
+        if (this._watching)
+            return;
+        this._watching = true;
+        // Ensure parent directory exists so watchFile can stat the path
+        mkdirSync(dirname(this._configPath), { recursive: true });
+        watchFile(this._configPath, { interval: 2000 }, () => {
+            this._reload();
+        });
+    }
+    stopWatching() {
+        if (!this._watching)
+            return;
+        this._watching = false;
+        unwatchFile(this._configPath);
+    }
+    // ── Programmatic writes (dashboard) ────────────────────
+    /** Merge partial config into the file and trigger reload. */
+    setFields(partial) {
+        const warnings = [];
+        const cleaned = {};
+        for (const [key, value] of Object.entries(partial)) {
+            if (RESTART_ONLY.has(key)) {
+                warnings.push(`"${key}" requires gateway restart — skipped`);
+                continue;
+            }
+            cleaned[key] = value;
+        }
+        // Merge with existing file overrides
+        const merged = { ...this._fileOverrides, ...cleaned };
+        this._saveFile(merged);
+        const changedFields = this._reload();
+        return { changedFields, warnings };
+    }
+    /** Validate a partial config without applying it. */
+    validate(partial) {
+        const testConfig = this._merge(this._base, { ...this._fileOverrides, ...partial });
+        return validateConfig(testConfig);
+    }
+    // ── Commit / rollback ──────────────────────────────────
+    commit(description) {
+        this._version++;
+        const entry = {
+            version: this._version,
+            timestamp: new Date().toISOString(),
+            description,
+            config: { ...this._fileOverrides },
+        };
+        this._history.push(entry);
+        // Cap at 50
+        if (this._history.length > 50) {
+            this._history = this._history.slice(-50);
+        }
+        this._saveHistory();
+        return entry;
+    }
+    rollback(version) {
+        const entry = this._history.find(h => h.version === version);
+        if (!entry)
+            return null;
+        this._saveFile(entry.config);
+        this._reload();
+        return entry;
+    }
+    getHistory() {
+        return [...this._history];
+    }
+    // ── Internal ───────────────────────────────────────────
+    /** Generate default config file with all built-in detection rules. */
+    _writeDefaultConfig() {
+        const lines = [
+            "{",
+            "  // Shroud config-as-code — auto-generated with built-in detection rules.",
+            "  // Edit rules here. Changes hot-reload within 2 seconds (no restart needed).",
+            "  // Priority: env vars > this file > plugin config > defaults.",
+            "  //",
+            "  // Rule format:",
+            '  //   "rule_name": {',
+            '  //     "pattern": "regex string",     // override or define the detection regex',
+            '  //     "category": "email",            // entity category (email, ip_address, phone, etc.)',
+            '  //     "confidence": 0.95,             // detection confidence (0.0-1.0)',
+            '  //     "enabled": false                // set to false to disable a rule',
+            "  //   }",
+            "  //",
+            '  "rules": {',
+        ];
+        for (let i = 0; i < BUILTIN_PATTERNS.length; i++) {
+            const p = BUILTIN_PATTERNS[i];
+            const comma = i < BUILTIN_PATTERNS.length - 1 ? "," : "";
+            // Convert RegExp to source string
+            lines.push(`    "${p.name}": { "pattern": ${JSON.stringify(p.pattern.source)}, "category": "${p.category}", "confidence": ${p.confidence} }${comma}`);
+        }
+        lines.push("  }");
+        lines.push("}");
+        lines.push("");
+        try {
+            mkdirSync(dirname(this._configPath), { recursive: true });
+            writeFileSync(this._configPath, lines.join("\n"), "utf-8");
+        }
+        catch { /* non-fatal — config file is optional */ }
+    }
+    _reload() {
+        const oldEffective = this._effective;
+        try {
+            this._fileOverrides = this._loadFile();
+            this._effective = this._merge(this._base, this._fileOverrides);
+        }
+        catch {
+            // Corrupt file — keep previous config
+            return [];
+        }
+        const changed = this._diff(oldEffective, this._effective);
+        // Filter out restart-only fields — log warning but don't apply
+        const restartChanged = changed.filter(f => RESTART_ONLY.has(f));
+        if (restartChanged.length > 0) {
+            console.warn(`[shroud][config] Fields require restart (not applied): ${restartChanged.join(", ")}`);
+            // Revert restart-only fields to base values
+            for (const field of restartChanged) {
+                this._effective[field] =
+                    oldEffective[field];
+            }
+        }
+        const effectiveChanged = changed.filter(f => !RESTART_ONLY.has(f));
+        if (effectiveChanged.length > 0) {
+            // Fire field-specific listeners
+            const firedCallbacks = new Set();
+            for (const listener of this._fieldListeners) {
+                if (effectiveChanged.some(f => listener.fields.has(f)) && !firedCallbacks.has(listener.callback)) {
+                    firedCallbacks.add(listener.callback);
+                    try {
+                        listener.callback();
+                    }
+                    catch { /* non-fatal */ }
+                }
+            }
+            // Fire generic reload listeners
+            for (const cb of this._reloadListeners) {
+                try {
+                    cb(this._effective);
+                }
+                catch { /* non-fatal */ }
+            }
+        }
+        return effectiveChanged;
+    }
+    _loadFile() {
+        if (!existsSync(this._configPath))
+            return {};
+        try {
+            const raw = readFileSync(this._configPath, "utf-8");
+            const stripped = stripComments(raw);
+            return JSON.parse(stripped);
+        }
+        catch {
+            return {};
+        }
+    }
+    _saveFile(config) {
+        try {
+            mkdirSync(dirname(this._configPath), { recursive: true });
+            writeFileSync(this._configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+        }
+        catch (err) {
+            console.warn(`[shroud][config] Failed to write config file: ${err}`);
+        }
+    }
+    _merge(base, overlay) {
+        const result = { ...base };
+        for (const [key, value] of Object.entries(overlay)) {
+            if (value !== undefined) {
+                result[key] = value;
+            }
+        }
+        // Re-apply env var overrides (env always wins)
+        return applyEnvOverrides(result);
+    }
+    _diff(oldConfig, newConfig) {
+        const changed = [];
+        const allKeys = Array.from(new Set([
+            ...Object.keys(oldConfig),
+            ...Object.keys(newConfig),
+        ]));
+        for (const key of allKeys) {
+            const oldVal = oldConfig[key];
+            const newVal = newConfig[key];
+            if (JSON.stringify(oldVal) !== JSON.stringify(newVal)) {
+                changed.push(key);
+            }
+        }
+        return changed;
+    }
+    _loadHistory() {
+        if (!existsSync(this._historyPath))
+            return;
+        try {
+            const raw = readFileSync(this._historyPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed)) {
+                this._history = parsed;
+                const maxVersion = this._history.reduce((max, h) => Math.max(max, h.version), 0);
+                this._version = maxVersion;
+            }
+        }
+        catch { /* start fresh */ }
+    }
+    _saveHistory() {
+        try {
+            mkdirSync(dirname(this._historyPath), { recursive: true });
+            writeFileSync(this._historyPath, JSON.stringify(this._history, null, 2) + "\n", "utf-8");
+        }
+        catch { /* non-fatal */ }
+    }
+}
+/**
+ * Strip // and /* comments from JSONC text.
+ * Handles strings correctly (doesn't strip inside quoted values).
+ */
+export function stripComments(jsonc) {
+    let result = "";
+    let i = 0;
+    const len = jsonc.length;
+    while (i < len) {
+        // String literal — copy verbatim
+        if (jsonc[i] === '"') {
+            const start = i;
+            i++; // opening quote
+            while (i < len && jsonc[i] !== '"') {
+                if (jsonc[i] === "\\")
+                    i++; // skip escaped char
+                i++;
+            }
+            i++; // closing quote
+            result += jsonc.slice(start, i);
+            continue;
+        }
+        // Line comment
+        if (jsonc[i] === "/" && jsonc[i + 1] === "/") {
+            while (i < len && jsonc[i] !== "\n")
+                i++;
+            continue;
+        }
+        // Block comment
+        if (jsonc[i] === "/" && jsonc[i + 1] === "*") {
+            i += 2;
+            while (i < len && !(jsonc[i] === "*" && jsonc[i + 1] === "/"))
+                i++;
+            i += 2; // skip */
+            continue;
+        }
+        result += jsonc[i];
+        i++;
+    }
+    return result;
+}
+/**
+ * Re-apply environment variable overrides to a config.
+ * Env vars always win over file and plugin config.
+ */
+function applyEnvOverrides(config) {
+    const result = { ...config };
+    const env = process.env;
+    // Boolean env overrides
+    const boolOverrides = [
+        ["SHROUD_CANARY_ENABLED", "canaryEnabled"],
+        ["SHROUD_HONEYPOT_ENABLED", "honeypotEnabled"],
+        ["SHROUD_PROFILING_ENABLED", "profilingEnabled"],
+        ["SHROUD_CANARY_SYSTEM", "canarySystemInjection"],
+        ["SHROUD_CANARY_BEHAVIOURAL", "canaryBehavioural"],
+        ["SHROUD_INJECTION_SCAN_RESPONSES", "injectionScanResponses"],
+        ["SHROUD_DRIFT_ENABLED", "driftEnabled"],
+        ["SHROUD_SHADOW_EXECUTION", "shadowExecutionEnabled"],
+        ["SHROUD_DASHBOARD", "dashboardEnabled"],
+        ["SHROUD_COHERENCE_ENABLED", "coherenceEnabled"],
+        ["SHROUD_VECTOR_STORE_ENABLED", "vectorStoreEnabled"],
+        ["SHROUD_CLUSTERING_ENABLED", "clusteringEnabled"],
+        ["SHROUD_URL_CORRELATION_ENABLED", "urlCorrelationEnabled"],
+        ["SHROUD_INTENT_CHAIN_ENABLED", "intentChainEnabled"],
+        ["SHROUD_TRANSFORMER_ENABLED", "transformerEnabled"],
+    ];
+    for (const [envKey, field] of boolOverrides) {
+        if (env[envKey] === "true")
+            result[field] = true;
+        else if (env[envKey] === "false")
+            result[field] = false;
+    }
+    // Enum env overrides
+    if (env.SHROUD_INJECTION_DETECTION === "flag" || env.SHROUD_INJECTION_DETECTION === "block" || env.SHROUD_INJECTION_DETECTION === "off") {
+        result.injectionDetection = env.SHROUD_INJECTION_DETECTION;
+    }
+    if (env.SHROUD_INJECTION_MIN_SEVERITY === "low" || env.SHROUD_INJECTION_MIN_SEVERITY === "medium" || env.SHROUD_INJECTION_MIN_SEVERITY === "high") {
+        result.injectionMinSeverity = env.SHROUD_INJECTION_MIN_SEVERITY;
+    }
+    if (env.SHROUD_PROFILING_MODE === "learning" || env.SHROUD_PROFILING_MODE === "active" || env.SHROUD_PROFILING_MODE === "strict") {
+        result.profilingMode = env.SHROUD_PROFILING_MODE;
+    }
+    // String env overrides
+    const stringOverrides = [
+        ["SHROUD_SECRET_KEY", "secretKey"],
+        ["SHROUD_PERSISTENT_SALT", "persistentSalt"],
+        ["SHROUD_PROFILING_DIR", "profilingProfileDir"],
+        ["SHROUD_SIGNATURES_URL", "signaturesUrl"],
+        ["SHROUD_SIGNATURES_FILE", "signaturesFile"],
+        ["SHROUD_SIEM_WEBHOOK_URL", "siemWebhookUrl"],
+        ["SHROUD_SIEM_WEBHOOK_AUTH", "siemWebhookAuth"],
+        ["SHROUD_SIEM_JSONL_PATH", "siemJsonlPath"],
+    ];
+    for (const [envKey, field] of stringOverrides) {
+        if (env[envKey])
+            result[field] = env[envKey];
+    }
+    // Numeric env overrides
+    const numOverrides = [
+        ["SHROUD_DRIFT_THRESHOLD", "driftThreshold"],
+        ["SHROUD_DRIFT_SUDDEN_TURN", "driftSuddenTurnDelta"],
+        ["SHROUD_COHERENCE_ZSCORE", "coherenceZScore"],
+        ["SHROUD_COHERENCE_RESULT_LIMIT", "coherenceResultLimit"],
+        ["SHROUD_TRANSFORMER_THRESHOLD", "transformerThreshold"],
+        ["SHROUD_TRANSFORMER_WINDOW", "transformerWindowSize"],
+        ["SHROUD_TRANSFORMER_MIN_SESSIONS", "transformerMinSessions"],
+        ["SHROUD_TRANSFORMER_TRAIN_INTERVAL", "transformerTrainInterval"],
+        ["SHROUD_TRANSFORMER_INTENT_ATTENTION_THRESHOLD", "transformerIntentAttentionThreshold"],
+        ["SHROUD_SIGNATURES_REFRESH", "signaturesRefreshSec"],
+        ["SHROUD_DASHBOARD_PORT", "dashboardPort"],
+        ["SHROUD_VECTOR_STORE_MAX", "vectorStoreMax"],
+        ["SHROUD_DELEGATION_DRIFT_THRESHOLD", "delegationDriftThreshold"],
+        ["SHROUD_SHADOW_TIMEOUT", "shadowExecutionTimeoutMs"],
+        ["SHROUD_HONEYPOT_RATE", "honeypotRate"],
+    ];
+    for (const [envKey, field] of numOverrides) {
+        if (env[envKey]) {
+            const parsed = parseFloat(env[envKey]);
+            if (!isNaN(parsed))
+                result[field] = parsed;
+        }
+    }
+    return result;
+}

package/dist/config.js

@@ -71,6 +71,9 @@ export function resolveConfig(pluginConfig) {
         detectorOverrides: raw.detectorOverrides != null && typeof raw.detectorOverrides === "object"
             ? raw.detectorOverrides
             : {},
+        rules: raw.rules != null && typeof raw.rules === "object"
+            ? raw.rules
+            : {},
         // Tool chain depth
         maxToolDepth: typeof raw.maxToolDepth === "number" ? raw.maxToolDepth : 10,
         // Redaction level
@@ -121,5 +124,23 @@ export function validateConfig(config) {
     if (Object.keys(config.detectorOverrides).length > 0) {
         issues.push({ severity: "info", field: "detectorOverrides", message: `${Object.keys(config.detectorOverrides).length} detector override(s) configured.` });
     }
+    // Rules as code
+    if (config.rules && Object.keys(config.rules).length > 0) {
+        const ruleCount = Object.keys(config.rules).length;
+        const disabled = Object.values(config.rules).filter(r => r.enabled === false).length;
+        const custom = Object.entries(config.rules).filter(([, r]) => r.pattern && r.enabled !== false).length;
+        issues.push({ severity: "info", field: "rules", message: `${ruleCount} rule(s) configured (${custom} custom/override, ${disabled} disabled).` });
+        // Validate regex patterns
+        for (const [name, rule] of Object.entries(config.rules)) {
+            if (rule.pattern) {
+                try {
+                    new RegExp(rule.pattern);
+                }
+                catch {
+                    issues.push({ severity: "error", field: "rules", message: `Rule "${name}" has invalid regex pattern.` });
+                }
+            }
+        }
+    }
     return issues;
 }

package/dist/detectors/regex.d.ts

@@ -19,10 +19,17 @@ export type DetectorOverrides = Record<string, {
     enabled?: boolean;
     confidence?: number;
 }>;
+/** Config-as-code rule definition (pattern as string, not RegExp). */
+export type ConfigRule = {
+    enabled?: boolean;
+    pattern?: string;
+    category?: string;
+    confidence?: number;
+};
 /** Detects sensitive entities using regex patterns. */
 export declare class RegexDetector implements BaseDetector {
     readonly name = "regex";
     private patterns;
-    constructor(extraPatterns?: PatternDef[], overrides?: DetectorOverrides);
+    constructor(extraPatterns?: PatternDef[], overrides?: DetectorOverrides, configRules?: Record<string, ConfigRule>);
     detect(text: string): DetectedEntity[];
 }

package/dist/detectors/regex.js

@@ -1231,15 +1231,84 @@ class SpanTracker {
         spans.splice(lo, 0, [start, end]);
     }
 }
+/** Resolve a category string to a Category enum value. */
+function resolveCategory(name) {
+    const upper = name.toUpperCase().replace(/[^A-Z_]/g, "_");
+    if (upper in Category)
+        return Category[upper];
+    // Common aliases
+    const aliases = {
+        EMAIL: Category.EMAIL,
+        IP: Category.IP_ADDRESS,
+        IP_ADDRESS: Category.IP_ADDRESS,
+        PHONE: Category.PHONE,
+        CREDIT_CARD: Category.CREDIT_CARD,
+        SSN: Category.SSN,
+        API_KEY: Category.API_KEY,
+        URL: Category.URL,
+        FILE_PATH: Category.FILE_PATH,
+        HOSTNAME: Category.HOSTNAME,
+        MAC_ADDRESS: Category.MAC_ADDRESS,
+        NETWORK_CREDENTIAL: Category.NETWORK_CREDENTIAL,
+        CUSTOM: Category.CUSTOM,
+    };
+    return aliases[upper] ?? Category.CUSTOM;
+}
 /** Detects sensitive entities using regex patterns. */
 export class RegexDetector {
     name = "regex";
     patterns;
-    constructor(extraPatterns, overrides) {
+    constructor(extraPatterns, overrides, configRules) {
         let patterns = [...BUILTIN_PATTERNS];
         if (extraPatterns) {
             patterns.push(...extraPatterns);
         }
+        // Config-as-code rules: override built-in properties, disable, or add new
+        if (configRules) {
+            const builtinNames = new Set(patterns.map(p => p.name));
+            // Override existing rules
+            patterns = patterns.map((p) => {
+                const rule = configRules[p.name];
+                if (!rule)
+                    return p;
+                const updated = { ...p };
+                if (rule.pattern) {
+                    try {
+                        updated.pattern = new RegExp(rule.pattern, "g");
+                    }
+                    catch { /* invalid regex — keep built-in */ }
+                }
+                if (rule.confidence !== undefined)
+                    updated.confidence = rule.confidence;
+                if (rule.category)
+                    updated.category = resolveCategory(rule.category);
+                return updated;
+            });
+            // Disable rules
+            patterns = patterns.filter((p) => {
+                const rule = configRules[p.name];
+                return rule?.enabled !== false;
+            });
+            // Add new rules (names not in built-ins)
+            for (const [name, rule] of Object.entries(configRules)) {
+                if (builtinNames.has(name))
+                    continue; // already handled above
+                if (rule.enabled === false)
+                    continue;
+                if (!rule.pattern)
+                    continue; // new rules must have a pattern
+                try {
+                    patterns.push({
+                        name,
+                        pattern: new RegExp(rule.pattern, "g"),
+                        category: rule.category ? resolveCategory(rule.category) : Category.CUSTOM,
+                        confidence: rule.confidence ?? 0.9,
+                    });
+                }
+                catch { /* invalid regex — skip */ }
+            }
+        }
+        // Legacy detectorOverrides (applied after config rules for backwards compat)
         if (overrides) {
             patterns = patterns.filter((p) => {
                 const ov = overrides[p.name];

package/dist/index.js

@@ -10,6 +10,7 @@ import { join, dirname } from "node:path";
 import { resolveConfig } from "./config.js";
 import { Obfuscator } from "./obfuscator.js";
 import { registerHooks } from "./hooks.js";
+import { ConfigManager } from "./config-manager.js";
 // ---------------------------------------------------------------------------
 // Runtime prototype patch: wrap EventStream.prototype.push() with the
 // Shroud deobfuscation hook. No file reads, no file writes, no cache
@@ -115,6 +116,21 @@ export default {
         patchEventStreamPrototype(api.logger);
         const config = resolveConfig(api.pluginConfig);
         const obfuscator = new Obfuscator(config);
+        // Config-as-code: watch ~/.shroud/shroud.config.json for hot-reload.
+        // Defer startWatching so watchFile doesn't block plugin install (which
+        // loads the plugin to verify it, then expects the process to exit).
+        // Resolve config path: prefer OPENCLAW_STATE_DIR, then HOME/.shroud
+        const configDir = process.env.OPENCLAW_STATE_DIR
+            ? join(process.env.OPENCLAW_STATE_DIR, ".shroud")
+            : join(process.env.HOME || "/root", ".shroud");
+        const configPath = join(configDir, "shroud.config.json");
+        const configManager = new ConfigManager(configPath, config);
+        configManager.onReload((newConfig) => {
+            obfuscator.updateConfig(newConfig);
+            api.logger?.info("[shroud] Config hot-reloaded from " + configPath);
+        });
+        const watchTimer = setTimeout(() => configManager.startWatching(), 5000);
+        watchTimer.unref();
         registerHooks(api, obfuscator);
         // Register shroud_status tool
         api.registerTool({

package/dist/obfuscator.d.ts

@@ -7,7 +7,7 @@
 import { DetectedEntity, ObfuscationResult, ShroudConfig } from "./types.js";
 import { BaseDetector } from "./detectors/base.js";
 export declare class Obfuscator {
-    readonly config: ShroudConfig;
+    config: ShroudConfig;
     private _store;
     private _subnetMapper;
     private _mapping;
@@ -26,6 +26,13 @@ export declare class Obfuscator {
     private _toolDepth;
     constructor(config: ShroudConfig);
     private _initDetectors;
+    /**
+     * Hot-swap config at runtime (called by ConfigManager on reload).
+     * Preserves mappings, stores, and stats — only swaps behaviour flags.
+     * Fields that require restart (secretKey, persistentSalt, etc.) are
+     * already filtered by ConfigManager before this is called.
+     */
+    updateConfig(newConfig: ShroudConfig): void;
     /** Add a custom detector at runtime. */
     addDetector(detector: BaseDetector): void;
     /** Track tool call depth. */

package/dist/obfuscator.js

@@ -230,8 +230,9 @@ export class Obfuscator {
     }
     _initDetectors() {
         const overrides = this.config.detectorOverrides;
-        // Always enable the regex detector (with optional overrides)
-        const regexDetector = new RegexDetector(undefined, overrides);
+        const configRules = this.config.rules;
+        // Always enable the regex detector (with config rules + legacy overrides)
+        const regexDetector = new RegexDetector(undefined, overrides, configRules);
         // Wrap with ContextDetector for confidence boosting, proximity,
         // hostname propagation, learned entities, and frequency decay
         this._contextDetector = new ContextDetector(regexDetector);
@@ -243,6 +244,33 @@ export class Obfuscator {
         // Code-aware detector shares the same configured regex detector
         this._detectors.push(new CodeDetector(regexDetector));
     }
+    /**
+     * Hot-swap config at runtime (called by ConfigManager on reload).
+     * Preserves mappings, stores, and stats — only swaps behaviour flags.
+     * Fields that require restart (secretKey, persistentSalt, etc.) are
+     * already filtered by ConfigManager before this is called.
+     */
+    updateConfig(newConfig) {
+        this.config = newConfig;
+        // Rebuild detectors to pick up new overrides / custom patterns
+        this._detectors = [];
+        this._contextDetector = null;
+        this._initDetectors();
+        // Toggle canary
+        if (newConfig.canaryEnabled && !this._canary) {
+            this._canary = new CanaryInjector(newConfig.canaryPrefix, newConfig.secretKey);
+        }
+        else if (!newConfig.canaryEnabled) {
+            this._canary = null;
+        }
+        // Toggle audit
+        if (newConfig.auditEnabled && !this._audit) {
+            this._audit = new AuditLogger(newConfig.secretKey);
+        }
+        else if (!newConfig.auditEnabled) {
+            this._audit = null;
+        }
+    }
     /** Add a custom detector at runtime. */
     addDetector(detector) {
         this._detectors.push(detector);

package/dist/types.d.ts

@@ -90,6 +90,19 @@ export interface ShroudConfig {
         enabled?: boolean;
         confidence?: number;
     }>;
+    /**
+     * Detection rules as code. Each key is a rule name.
+     * - Override built-in rules: change pattern, confidence, or category
+     * - Disable rules: { "enabled": false }
+     * - Add new rules: { "pattern": "regex string", "category": "email", "confidence": 0.9 }
+     * Built-in rules from BUILTIN_PATTERNS are the defaults; this merges on top.
+     */
+    rules: Record<string, {
+        enabled?: boolean;
+        pattern?: string;
+        category?: string;
+        confidence?: number;
+    }>;
     /** Tool chain depth awareness — max depth before warning. */
     maxToolDepth: number;
     /** Redaction levels — 'full' | 'masked' | 'stats'. */

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "shroud-privacy",
   "name": "Shroud",
-  "version": "2.2.20",
+  "version": "2.3.0",
   "description": "Privacy obfuscation with deterministic fake values and deobfuscation — PII never reaches the LLM, tool calls still work",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shroud-privacy",
-  "version": "2.2.20",
+  "version": "2.3.0",
   "description": "Privacy and infrastructure protection for AI agents — detects sensitive data (PII, network topology, credentials, OT/SCADA) and replaces with deterministic fakes before anything reaches the LLM.",
   "type": "module",
   "main": "dist/index.js",