shroud-privacy 2.0.0 → 2.0.2

package/README.md

@@ -2,7 +2,7 @@
 
 Privacy obfuscation plugin for [OpenClaw](https://openclaw.ai). Detects sensitive data (PII, network infrastructure, credentials) and replaces it with deterministic fake values before anything reaches the LLM. Tool calls still work because Shroud deobfuscates on the way back.
 
-> **Open-source Community Edition** — free to use under MIT license. [Enterprise Edition](#enterprise-edition) available with additional features for teams.
+> **Open-source Community Edition** — free to use under Apache 2.0 license. [Enterprise Edition](#enterprise-edition) available with additional features for teams.
 
 ## What it does
 
@@ -32,33 +32,50 @@ openclaw plugins install shroud-privacy
 
 That's it. Configure in `~/.openclaw/openclaw.json` under `plugins.entries."shroud-privacy".config`.
 
-### NCG Agent
+### From source (development)
 
 ```bash
-python agent.py plugin install shroud-privacy
+git clone https://github.com/walterkeating-stack/shroud.git
+cd shroud
+npm install && npm run build
+bash deploy-local.sh     # → OpenClaw (~/.openclaw/extensions/)
 ```
 
-Configure in `~/.ncg/ncg.json` under `plugins.entries."shroud-privacy".config`.
+## Updating
 
-### From source (development)
+OpenClaw doesn't have a `plugins update` command yet, so updating requires removing the old install first. A helper script is included:
 
 ```bash
-git clone https://github.com/walterkeating-stack/shroud.git
-cd shroud
-npm install && npm run build
+# Update to latest version (preserves your config)
+bash scripts/update-openclaw-plugin.sh
 
-bash deploy-local.sh     # → OpenClaw (~/.openclaw/extensions/)
-bash deploy-ncg.sh       # → NCG (~/.ncg/extensions/)
+# Update to a specific version
+bash scripts/update-openclaw-plugin.sh 2.0.1
 ```
 
-## Configure
+The script saves your plugin config from `openclaw.json`, removes the old extension, reinstalls from npm, restores your config, and restarts the gateway.
 
-Both OpenClaw and NCG store Shroud config in the same structure — only the file path differs:
+### Manual update
 
-| Platform | Config file | Config path |
-|----------|-------------|-------------|
-| OpenClaw | `~/.openclaw/openclaw.json` | `plugins.entries."shroud-privacy".config` |
-| NCG | `~/.ncg/ncg.json` | `plugins.entries."shroud-privacy".config` |
+If you prefer to do it manually:
+
+```bash
+# 1. Remove old plugin files
+rm -rf ~/.openclaw/extensions/shroud-privacy
+
+# 2. Reinstall (this resets your plugin config to defaults)
+openclaw plugins install shroud-privacy
+
+# 3. Re-apply your config in ~/.openclaw/openclaw.json
+#    (under plugins.entries."shroud-privacy".config)
+
+# 4. Restart
+openclaw gateway restart
+```
+
+## Configure
+
+Edit `~/.openclaw/openclaw.json` under `plugins.entries."shroud-privacy".config`:
 
 ```jsonc
 "shroud-privacy": {
@@ -80,8 +97,7 @@ Both OpenClaw and NCG store Shroud config in the same structure — only the fil
 Restart the gateway after config changes:
 
 ```bash
-openclaw gateway restart                    # OpenClaw
-sudo systemctl restart ncg-gateway.service  # NCG
+openclaw gateway restart
 ```
 
 ### Safe defaults
@@ -91,7 +107,6 @@ Out of the box, Shroud:
 - Detects all entity categories at confidence >= 0.0
 - Logs audit lines (counts + categories) but **not** proof hashes or fake samples
 - Never logs raw values, real→fake mappings, or original text
-- All enterprise features are opt-in and disabled by default
 
 To enable proof hashes and fake samples for deeper audit:
 
@@ -127,56 +142,12 @@ To enable proof hashes and fake samples for deeper audit:
 | `logMappings` | boolean | `false` | Log mapping table (debug only) |
 | `customPatterns` | array | `[]` | User-defined regex detection patterns |
 | `detectorOverrides` | object | `{}` | Override built-in rules: disable or change confidence per rule name |
-
-### Enterprise settings
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `tenantId` | string | `""` | Multi-tenant isolation: tenant ID for HMAC keying |
-| `lockedCategories` | string[] | `[]` | Compliance mode: categories that MUST be detected |
 | `maxToolDepth` | number | `10` | Max nested tool call depth before warning |
-| `exposureWindow` | number | `60000` | Sliding window (ms) for exposure rate tracking |
-| `exposureThresholds` | object | `{}` | Per-category max detections per window |
-| `exposureGlobalThreshold` | number | `100` | Global max detections per window |
-| `policyFile` | string | `""` | Path to external JSON policy file (allowlist/denylist with glob/regex) |
 | `redactionLevel` | `"full"` \| `"masked"` \| `"stats"` | `"full"` | Output mode: fake values, partial masking, or category placeholders |
-| `sharedStorePath` | string | `""` | File path for cross-agent shared mapping store |
-| `sharedStoreTtlMs` | number | `5000` | Cache TTL for shared store reads (ms) |
-| `provenanceTagging` | boolean | `false` | Embed `«shroud:category:hash»` markers in output |
-| `sessionHandoff` | boolean | `false` | Enable session export/import tools |
-
-### Key rotation settings
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `keys` | array | `[]` | Versioned keys: `[{version, key, createdAt?, expiresAt?, retired?}]` |
-| `activeKeyVersion` | number | `0` | Which key version to use (0 = highest non-expired) |
-
-### SIEM integration settings
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `siemWebhooks` | array | `[]` | Webhook endpoints: `[{url, authHeader?, headers?, eventTypes?}]` |
-| `siemBatchSize` | number | `100` | Max events before auto-flush |
-| `siemFlushIntervalMs` | number | `30000` | Flush interval (ms) |
-| `siemMaxRetries` | number | `3` | Max retry attempts per flush |
-| `siemRetryBackoffMs` | number | `1000` | Initial retry backoff (doubles each retry) |
-| `siemEventFormat` | `"json"` \| `"cef"` | `"json"` | Output format for SIEM events |
+| `dryRun` | boolean | `false` | Detect entities but don't replace (testing mode) |
+| `maxStoreMappings` | number | `0` | Max mapping store size with LRU eviction (0 = unlimited) |
 
-### Hot-reload, session isolation, and monitoring settings
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `hotReload` | boolean | `false` | Watch config files and reload detection rules on change |
-| `customPatternsFile` | string | `""` | Path to custom patterns JSON file to watch |
-| `hotReloadDebounceMs` | number | `1000` | Debounce interval for file change events |
-| `sessionIsolation` | boolean | `false` | Per-session isolated stores and mapping engines |
-| `monitorEnabled` | boolean | `false` | Active monitoring and alerting pipeline |
-| `monitorRateWindowMs` | number | `60000` | Rolling window for rate baseline |
-| `monitorSpikeMultiplier` | number | `3.0` | Alert when rate exceeds baseline × multiplier |
-| `monitorMaxAlerts` | number | `500` | Max alerts to keep in memory |
-
-> **Env var overrides:** `SHROUD_SECRET_KEY`, `SHROUD_PERSISTENT_SALT`, `SHROUD_TENANT_ID`, `SHROUD_SHARED_STORE`, `SHROUD_SIEM_WEBHOOK_URL`, `SHROUD_SIEM_WEBHOOK_AUTH`, and `SHROUD_KEYS` (JSON array) override their respective config keys (priority: env var > plugin config > default).
+> **Env var overrides:** `SHROUD_SECRET_KEY` and `SHROUD_PERSISTENT_SALT` override their respective config keys (priority: env var > plugin config > default).
 
 ### Detector overrides
 
@@ -196,7 +167,7 @@ Rules not listed keep their defaults. Overrides apply to both direct regex detec
 
 Shroud tracks per-rule match counts for the lifetime of the process. Counters appear in three places:
 
-- **`shroud-stats` CLI** — run `node scripts/shroud-stats.mjs` to see all rules with status, confidence, and hit counts. Shows live cumulative stats from the running gateway (NCG or OpenClaw) via `/tmp/shroud-stats.json`. Use `--test "text with PII"` to test detection against sample input.
+- **`shroud-stats` CLI** — run `node scripts/shroud-stats.mjs` to see all rules with status, confidence, and hit counts. Shows live cumulative stats from the running OpenClaw gateway via `/tmp/shroud-stats.json`. Use `--test "text with PII"` to test detection against sample input.
 - **Audit log lines** — `byRule=regex:email:3,regex:ipv4:2,...` alongside the existing `byCat` field.
 - **`getStats()`** — the `ruleHits` object in the stats response, useful for programmatic access.
 
@@ -270,12 +241,6 @@ With proof hashes enabled:
 [shroud][audit] OBFUSCATE req=a3f1bc9e02d4e7f1 | entities=4 | touched=2/5 | blocks=2 | chars=1200->1218 (delta=+18) | modified=YES | byCat=email:1,ip_address:2,hostname:1 | proof_in=8a3c1f0e2b4d proof_out=f7d2a1c9e084 | fakes=[jsmith@corp.net|100.64.0.12|SW-LAB-01]
 ```
 
-With compliance locking:
-
-```
-[shroud][audit] OBFUSCATE req=... | ... | COMPLIANCE_WARN=missing:[credit_card]
-```
-
 ### Audit field reference
 
 | Field | Meaning |
@@ -292,7 +257,6 @@ With compliance locking:
 | `proof_in` | Truncated salted SHA-256 of input text |
 | `proof_out` | Truncated salted SHA-256 of output text |
 | `fakes` | Sample of fake replacement values (never real values) |
-| `COMPLIANCE_WARN` | Missing locked categories (if compliance mode enabled) |
 
 ### Note on log duplication
 
@@ -302,7 +266,7 @@ OpenClaw logs each plugin message twice (once under the plugin subsystem logger,
 
 ```bash
 npm install
-npm test          # run vitest (303 tests)
+npm test          # run vitest (210 tests)
 npm run build     # compile TypeScript
 npm run lint      # type-check without emitting
 ```
@@ -312,10 +276,7 @@ npm run lint      # type-check without emitting
 ```bash
 npm run build
 bash deploy-local.sh   # → OpenClaw (~/.openclaw/extensions/shroud-privacy/)
-bash deploy-ncg.sh     # → NCG (~/.ncg/extensions/shroud-privacy/)
-
-openclaw gateway restart                    # restart OpenClaw
-sudo systemctl restart ncg-gateway.service  # restart NCG
+openclaw gateway restart
 ```
 
 ## Release workflow
@@ -334,9 +295,7 @@ git push && git push --tags
 
 Then create a GitHub Release from the tag (attach the changelog entry as notes).
 
-### npm publish (not published yet — maintainers only)
-
-This package is **not published to npm**. The `package.json` is pre-configured so publishing is a single command when the time comes. Do not publish without maintainer approval.
+### npm publish (maintainers only)
 
 ```bash
 # Pre-flight (always run before publishing)
@@ -366,4 +325,4 @@ The repo includes `.github/workflows/ci.yml` which runs lint + test + build on e
 
 ## License
 
-[MIT](LICENSE)
+[Apache 2.0](LICENSE)

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "shroud-privacy",
   "name": "Shroud",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Privacy obfuscation with deterministic fake values and deobfuscation — PII never reaches the LLM, tool calls still work",
   "configSchema": {
     "type": "object",
@@ -61,11 +61,6 @@
     "canaryEnabled": { "label": "Enable Canary Tokens", "help": "Inject tracking tokens to detect PII leakage" },
     "auditEnabled": { "label": "Enable Audit Log", "help": "Tamper-evident obfuscation event tracking" }
   },
-  "ncg": {
-    "adapter": "ncg_adapter.py",
-    "adapterClass": "ShroudPlugin",
-    "bridge": "shroud_bridge.mjs"
-  },
   "compatibility": {
     "minOpenClawVersion": "2026.3.0"
   }

package/package.json

@@ -1,15 +1,13 @@
 {
   "name": "shroud-privacy",
-  "version": "2.0.0",
-  "description": "Privacy obfuscation plugin for OpenClaw and NCG — deterministic fake values with deobfuscation",
+  "version": "2.0.2",
+  "description": "Privacy obfuscation plugin for OpenClaw — detects sensitive data and replaces with deterministic fake values",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist/",
     "openclaw.plugin.json",
-    "ncg_adapter.py",
-    "shroud_bridge.mjs",
     "LICENSE",
     "NOTICE"
   ],
@@ -23,7 +21,6 @@
   "keywords": [
     "openclaw",
     "openclaw-plugin",
-    "ncg",
     "privacy",
     "pii",
     "obfuscation",

package/ncg_adapter.py

@@ -1,530 +0,0 @@
-"""Shroud plugin adapter for NCG Agent.
-
-Bridges NCG's Python agent to the Shroud TypeScript obfuscation engine
-(running as a Node.js subprocess) via JSON-RPC over stdin/stdout.
-
-This mirrors how OpenClaw integrates with Shroud:
-- Obfuscate text before sending to the LLM
-- Deobfuscate text received from the LLM
-- Deobfuscate tool parameters before execution
-- Obfuscate tool results before persisting to history
-
-Usage (via PluginManager):
-    plugin = ShroudPlugin.from_config(plugin_dir, config)
-    plugin.start()
-    safe   = plugin.sanitize(real_text)      # before LLM
-    real   = plugin.desanitize(safe_text)     # after LLM
-    plugin.stop()
-
-Legacy usage (direct, for testing):
-    plugin = ShroudPlugin.from_config()       # loads config/shroud.yaml
-    plugin.start()
-
-The plugin can be activated/deactivated at runtime, and its config
-can be hot-reloaded without restarting the agent.
-"""
-
-import json
-import logging
-import os
-import re
-import subprocess
-import threading
-import time
-from pathlib import Path
-
-from plugins.base import NCGPlugin
-
-log = logging.getLogger("ncg.shroud")
-
-# Legacy defaults — used only for backward-compat direct instantiation
-_DEFAULT_SHROUD_PATH = str(Path(__file__).resolve().parent / "dist")
-_LEGACY_BRIDGE_SCRIPT = Path(__file__).parent / "shroud_bridge.mjs"
-_LEGACY_CONFIG_FILE = Path(__file__).resolve().parent.parent / "config" / "shroud.yaml"
-
-# CGNAT range used by Shroud for fake IPv4 addresses
-_CGNAT_RE = re.compile(r'\b100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.\d{1,3}\.\d{1,3}\b')
-# ULA range used by Shroud for fake IPv6 addresses (fd00::/8)
-_ULA_RE = re.compile(r'\bfd00:[0-9a-fA-F:]{2,39}\b')
-
-
-def _fmt_audit_obfuscate(audit):
-    """Format obfuscation audit data as a single human-readable line.
-
-    Proves: text was modified, what categories were found, char delta,
-    truncated proof hashes (no raw values), fake samples, chain hash.
-    """
-    cats = ",".join(f"{k}:{v}" for k, v in audit.get("byCategory", {}).items()) or "none"
-    fakes = "|".join(audit.get("fakesSample", []))
-    parts = [
-        f"[shroud][audit] OBFUSCATE req={audit.get('req', '?')}",
-        f"entities={audit.get('totalEntities', 0)}",
-        f"chars={audit.get('inputChars', 0)}->{audit.get('outputChars', 0)} (delta={audit.get('charDelta', 0):+d})",
-        f"modified={'YES' if audit.get('modified') else 'NO'}",
-        f"byCat={cats}",
-        f"proof_in={audit.get('proofIn', '?')} proof_out={audit.get('proofOut', '?')}",
-        f"chain={audit.get('chainHash', '?')}",
-    ]
-    if fakes:
-        parts.append(f"fakes=[{fakes}]")
-    return " | ".join(parts)
-
-
-def _fmt_audit_deobfuscate(audit, req_id=None):
-    """Format deobfuscation audit data as a single human-readable line."""
-    parts = [
-        f"[shroud][audit] DEOBFUSCATE",
-    ]
-    if req_id:
-        parts[0] += f" req={req_id}"
-    parts += [
-        f"replacements={audit.get('replacementCount', 0)}",
-        f"chars={audit.get('inputChars', 0)}->{audit.get('outputChars', 0)}",
-        f"modified={'YES' if audit.get('modified') else 'NO'}",
-        f"proof_in={audit.get('proofIn', '?')} proof_out={audit.get('proofOut', '?')}",
-        f"chain={audit.get('chainHash', '?')}",
-    ]
-    return " | ".join(parts)
-
-
-class ShroudPlugin(NCGPlugin):
-    """Python adapter for the Shroud obfuscation engine.
-
-    Manages a long-lived Node.js child process that runs the shroud
-    bridge script. Communication is newline-delimited JSON over
-    stdin/stdout (same pattern OpenClaw uses for plugin IPC).
-    """
-
-    def __init__(self, *, enabled=True, shroud_path=None, bridge_script=None,
-                 config=None, plugin_dir=None):
-        self.enabled = enabled
-        self.plugin_dir = plugin_dir
-        self.shroud_path = shroud_path or _DEFAULT_SHROUD_PATH
-        self.bridge_script = bridge_script or _LEGACY_BRIDGE_SCRIPT
-        self.config = config or {}
-        self._proc = None
-        self._lock = threading.Lock()
-        self._req_id = 0
-        self._started = False
-        self._version = None
-        self._audit_logger = None  # set by agent for file-based audit log
-        self._last_obf_req = None  # track request ID for deobfuscation correlation
-
-    # ── Factory ─────────────────────────────────────────────────────
-
-    @classmethod
-    def from_config(cls, plugin_dir: Path = None, config: dict = None,
-                    enabled: bool = True):
-        """Create a ShroudPlugin from a plugin directory and config dict.
-
-        When called by PluginManager:
-            ShroudPlugin.from_config(plugin_dir=..., config={...}, enabled=True)
-
-        Legacy usage (direct, loads config/shroud.yaml):
-            ShroudPlugin.from_config()
-        """
-        if plugin_dir is not None:
-            # PluginManager path: derive paths from plugin_dir
-            shroud_path = str(plugin_dir / "dist")
-            bridge_script = plugin_dir / "shroud_bridge.mjs"
-            return cls(enabled=enabled, shroud_path=shroud_path,
-                       bridge_script=bridge_script, config=config or {},
-                       plugin_dir=plugin_dir)
-
-        # Legacy path: read from config/shroud.yaml
-        path = _LEGACY_CONFIG_FILE
-        file_config = {}
-        shroud_path = _DEFAULT_SHROUD_PATH
-
-        if path.exists():
-            try:
-                import yaml
-                raw = yaml.safe_load(path.read_text()) or {}
-                shroud_path = raw.get("shroud_path", shroud_path)
-                if shroud_path.startswith("$"):
-                    shroud_path = os.path.expandvars(shroud_path)
-                file_config = raw.get("plugin_config", {})
-                if raw.get("enabled") is False:
-                    enabled = False
-                log.info("[shroud] Config loaded from %s", path)
-            except Exception as e:
-                log.warning("[shroud] Failed to load config %s: %s", path, e)
-        else:
-            log.info("[shroud] No config at %s — using defaults", path)
-
-        return cls(enabled=enabled, shroud_path=shroud_path, config=file_config)
-
-    def set_audit_logger(self, audit_logger):
-        """Attach the agent's audit file logger so shroud events appear in session logs."""
-        self._audit_logger = audit_logger
-
-    # ── Lifecycle ───────────────────────────────────────────────────
-
-    def start(self):
-        """Spawn the Node.js bridge subprocess."""
-        if not self.enabled:
-            log.info("[shroud] Plugin disabled — skipping start")
-            return False
-
-        if self._started:
-            log.warning("[shroud] Already started")
-            return True
-
-        # Verify shroud dist exists
-        dist = Path(self.shroud_path)
-        if not dist.exists() or not (dist / "obfuscator.js").exists():
-            log.error("[shroud] Shroud dist not found at %s", self.shroud_path)
-            self.enabled = False
-            return False
-
-        # Verify bridge script exists
-        if not self.bridge_script.exists():
-            log.error("[shroud] Bridge script not found at %s", self.bridge_script)
-            self.enabled = False
-            return False
-
-        env = os.environ.copy()
-        if self.config:
-            env["SHROUD_PLUGIN_CONFIG"] = json.dumps(self.config)
-
-        try:
-            self._proc = subprocess.Popen(
-                ["node", str(self.bridge_script), self.shroud_path],
-                stdin=subprocess.PIPE,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE,
-                env=env,
-                text=True,
-                bufsize=1,  # line-buffered
-            )
-
-            # Start stderr reader thread for bridge logs
-            self._stderr_thread = threading.Thread(
-                target=self._read_stderr, daemon=True, name="shroud-stderr"
-            )
-            self._stderr_thread.start()
-
-            # Wait for ready signal
-            ready_line = self._proc.stdout.readline()
-            if not ready_line:
-                raise RuntimeError("Bridge process died immediately")
-
-            ready = json.loads(ready_line)
-            if not ready.get("ready"):
-                raise RuntimeError(f"Unexpected ready signal: {ready}")
-
-            self._version = ready.get("version", "?")
-            self._started = True
-            log.info("[shroud] Plugin started (v%s, pid=%d)",
-                     self._version, self._proc.pid)
-            return True
-
-        except Exception as e:
-            log.error("[shroud] Failed to start: %s", e)
-            self._cleanup()
-            self.enabled = False
-            return False
-
-    def stop(self):
-        """Shut down the bridge subprocess."""
-        if self._proc:
-            log.info("[shroud] Stopping plugin (pid=%d)", self._proc.pid)
-            self._cleanup()
-            self._started = False
-            log.info("[shroud] Plugin stopped")
-
-    def _cleanup(self):
-        if self._proc:
-            try:
-                self._proc.stdin.close()
-            except Exception:
-                pass
-            try:
-                self._proc.terminate()
-                self._proc.wait(timeout=5)
-            except Exception:
-                try:
-                    self._proc.kill()
-                except Exception:
-                    pass
-            self._proc = None
-
-    def _restart(self):
-        """Attempt to restart the bridge subprocess after a crash.
-
-        NOTE: mappings from the previous bridge process are lost.
-        This is a best-effort recovery — new obfuscations will create fresh mappings.
-        """
-        self._cleanup()
-        self._started = False
-        try:
-            return self.start()
-        except Exception as e:
-            log.error("[shroud] Restart failed: %s", e)
-            return False
-
-    def _read_stderr(self):
-        """Read bridge stderr and forward to Python logging."""
-        try:
-            for line in self._proc.stderr:
-                line = line.rstrip()
-                if line:
-                    log.debug("[shroud-bridge] %s", line)
-        except Exception:
-            pass
-
-    # ── JSON-RPC communication ──────────────────────────────────────
-
-    def _call(self, method, params=None):
-        """Send a JSON-RPC request and return the result."""
-        if not self._started or not self._proc or self._proc.poll() is not None:
-            if self._started:
-                log.error("[shroud] Bridge process died (exit=%s) — attempting restart",
-                          self._proc.returncode if self._proc else "?")
-                self._started = False
-                # Auto-restart instead of disabling
-                if self._restart():
-                    log.info("[shroud] Bridge restarted successfully")
-                else:
-                    log.error("[shroud] Bridge restart failed — disabling")
-                    self.enabled = False
-                    return None
-            else:
-                return None
-
-        with self._lock:
-            self._req_id += 1
-            req_id = self._req_id
-            req = {"id": req_id, "method": method}
-            if params:
-                req["params"] = params
-
-            try:
-                start_t = time.monotonic()
-                self._proc.stdin.write(json.dumps(req) + "\n")
-                self._proc.stdin.flush()
-
-                resp_line = self._proc.stdout.readline()
-                elapsed_ms = (time.monotonic() - start_t) * 1000
-
-                if not resp_line:
-                    log.error("[shroud] Bridge EOF on method=%s", method)
-                    self._started = False
-                    self.enabled = False
-                    return None
-
-                resp = json.loads(resp_line)
-
-                if resp.get("error"):
-                    log.warning("[shroud] %s error: %s", method, resp["error"])
-                    return None
-
-                if elapsed_ms > 100:
-                    log.debug("[shroud] %s took %.1fms", method, elapsed_ms)
-
-                return resp.get("result")
-
-            except (BrokenPipeError, OSError) as e:
-                log.error("[shroud] Bridge pipe error on %s: %s — attempting restart", method, e)
-                self._started = False
-                if self._restart():
-                    log.warning("[shroud] Bridge restarted after pipe error (mappings lost)")
-                else:
-                    self.enabled = False
-                return None
-            except json.JSONDecodeError as e:
-                log.error("[shroud] Bad JSON from bridge on %s: %s", method, e)
-                return None
-
-    # ── Audit logging ───────────────────────────────────────────────
-
-    def _log_audit(self, message):
-        """Write audit line to both console logger and agent audit file."""
-        log.info("%s", message)
-        if self._audit_logger:
-            try:
-                self._audit_logger.info("%s", message)
-            except Exception:
-                pass  # best-effort
-
-    # ── Public API (matches NCG Sanitizer interface) ────────────────
-
-    def sanitize(self, text):
-        """Obfuscate real values → fake values (before sending to LLM).
-
-        Drop-in replacement for Sanitizer.sanitize().
-        """
-        if not self.enabled or not text:
-            return text
-
-        result = self._call("obfuscate", {"text": text})
-        if result is None:
-            return text  # fallback: pass-through on error
-
-        entity_count = result.get("entityCount", 0)
-        if entity_count > 0:
-            cats = result.get("categories", {})
-            log.debug("[shroud] obfuscate: %d entities %s", entity_count, cats)
-
-        # Audit logging
-        audit = result.get("audit")
-        if audit:
-            self._last_obf_req = audit.get("req")
-            self._log_audit(_fmt_audit_obfuscate(audit))
-
-        return result.get("obfuscated", text)
-
-    def desanitize(self, text):
-        """Deobfuscate fake values → real values (after receiving from LLM).
-
-        Drop-in replacement for Sanitizer.desanitize().
-        """
-        if not self.enabled or not text:
-            return text
-
-        result = self._call("deobfuscate", {"text": text})
-        if result is None:
-            log.warning("[shroud] desanitize: bridge returned None — fakes may leak through! "
-                        "text_len=%d", len(text))
-            return text  # fallback: pass-through on error
-
-        deobfuscated = result.get("text", text)
-        replacement_count = result.get("replacementCount", 0)
-        store_size = result.get("storeSize", -1)
-
-        # Audit logging
-        audit = result.get("audit")
-        if audit:
-            self._log_audit(_fmt_audit_deobfuscate(audit, self._last_obf_req))
-
-        # Residual fake detection: scan for CGNAT IPv4 and ULA IPv6 that survived deobfuscation
-        residual_v4 = _CGNAT_RE.findall(deobfuscated)
-        residual_v6 = _ULA_RE.findall(deobfuscated)
-        residual = residual_v4 + residual_v6
-        if residual:
-            unique_residual = set(residual)
-            label = "CGNAT/ULA" if residual_v6 else "CGNAT"
-            log.warning(
-                "[shroud] RESIDUAL FAKES DETECTED after deobfuscation: %d occurrences "
-                "(%d unique) of %s IPs in output | store_size=%d | replacements=%d | "
-                "residual_ips=%s",
-                len(residual), len(unique_residual), label, store_size, replacement_count,
-                ",".join(sorted(unique_residual)[:10]),
-            )
-            if self._audit_logger:
-                self._audit_logger.warning(
-                    "[shroud][LEAK] Residual %s IPs: %s (store=%d, replacements=%d)",
-                    label, ",".join(sorted(unique_residual)[:10]), store_size, replacement_count,
-                )
-
-        if store_size == 0 and replacement_count == 0 and len(text) > 100:
-            log.warning("[shroud] desanitize: store is EMPTY — no mappings available for "
-                        "deobfuscation (bridge may have restarted)")
-
-        return deobfuscated
-
-    def reset(self):
-        """Clear all mappings and start a fresh session."""
-        result = self._call("reset")
-        if result and result.get("ok"):
-            log.info("[shroud] Session reset — all mappings cleared")
-            self._last_obf_req = None
-        return result
-
-    def get_stats(self):
-        """Return obfuscation statistics."""
-        result = self._call("getStats")
-        if result is None:
-            return {"enabled": self.enabled, "error": "bridge not running"}
-        result["enabled"] = self.enabled
-        result["bridge_pid"] = self._proc.pid if self._proc else None
-        result["version"] = self._version
-        return result
-
-    # ── Runtime control ─────────────────────────────────────────────
-
-    def activate(self):
-        """Enable the plugin at runtime."""
-        if self.enabled and self._started:
-            log.info("[shroud] Already active")
-            return True
-        self.enabled = True
-        ok = self.start()
-        if ok:
-            log.info("[shroud] Activated")
-        return ok
-
-    def deactivate(self):
-        """Disable the plugin at runtime (pass-through mode)."""
-        self.enabled = False
-        self.stop()
-        log.info("[shroud] Deactivated — obfuscation disabled")
-
-    def update_config(self, new_config):
-        """Hot-reload shroud config without restarting the agent."""
-        result = self._call("reconfigure", {"config": new_config})
-        if result and result.get("ok"):
-            self.config = new_config
-            log.info("[shroud] Config updated and reloaded")
-            return True
-        log.warning("[shroud] Config update failed")
-        return False
-
-    def reload_from_file(self):
-        """Re-read config file and hot-reload."""
-        config_file = _LEGACY_CONFIG_FILE
-        if config_file.exists():
-            try:
-                import yaml
-                raw = yaml.safe_load(config_file.read_text()) or {}
-                new_config = raw.get("plugin_config", {})
-                return self.update_config(new_config)
-            except Exception as e:
-                log.error("[shroud] Failed to reload config: %s", e)
-                return False
-        log.warning("[shroud] Config file not found: %s", config_file)
-        return False
-
-    # ── Tool registration (NCGPlugin interface) ──────────────────────
-
-    def get_tool_definitions(self) -> list[dict]:
-        """Return shroud tool definitions for the agent."""
-        return [
-            {"name": "shroud_status",
-             "description": "Show Shroud privacy plugin stats: entity counts, session info, audit status, version.",
-             "input_schema": {"type": "object", "properties": {}}},
-            {"name": "shroud_reset",
-             "description": "Clear all Shroud obfuscation mappings and start a fresh privacy session.",
-             "input_schema": {"type": "object", "properties": {}}},
-            {"name": "shroud_activate",
-             "description": "Enable the Shroud privacy plugin (starts obfuscation of data sent to LLM).",
-             "input_schema": {"type": "object", "properties": {}}},
-            {"name": "shroud_deactivate",
-             "description": "Disable the Shroud privacy plugin (data sent to LLM without obfuscation).",
-             "input_schema": {"type": "object", "properties": {}}},
-        ]
-
-    def get_tool_handlers(self) -> dict:
-        """Return {tool_name: handler_fn} for shroud tools."""
-        return {
-            "shroud_status": lambda _: self.get_stats(),
-            "shroud_reset": lambda _: (
-                {"ok": True, "message": "Shroud session reset. All mappings cleared."}
-                if self.reset() else {"error": "Reset failed"}),
-            "shroud_activate": lambda _: (
-                {"ok": True, "message": "Shroud activated"} if self.activate()
-                else {"ok": False, "message": "Activation failed"}),
-            "shroud_deactivate": lambda _: (
-                self.deactivate() or
-                {"ok": True, "message": "Shroud deactivated — obfuscation disabled"}),
-        }
-
-    @property
-    def is_running(self):
-        """Check if the bridge subprocess is alive."""
-        return (self._started and self._proc is not None
-                and self._proc.poll() is None)
-
-    def __repr__(self):
-        state = "active" if self.is_running else ("disabled" if not self.enabled else "stopped")
-        return f"<ShroudPlugin state={state} version={self._version}>"

package/shroud_bridge.mjs

@@ -1,225 +0,0 @@
-#!/usr/bin/env node
-/**
- * Shroud Bridge — JSON-RPC server over stdin/stdout.
- *
- * Loads the shroud Obfuscator from a configurable dist path and exposes
- * obfuscate / deobfuscate / reset / getStats / configure via newline-
- * delimited JSON messages.
- *
- * Protocol:
- *   → {"id":1,"method":"obfuscate","params":{"text":"..."}}
- *   ← {"id":1,"result":{"obfuscated":"...","entityCount":3,"audit":{...}}}
- *
- *   → {"id":2,"method":"deobfuscate","params":{"text":"..."}}
- *   ← {"id":2,"result":{"text":"...","replacementCount":2,"audit":{...}}}
- *
- *   → {"id":3,"method":"reset"}
- *   ← {"id":3,"result":{"ok":true}}
- *
- *   → {"id":4,"method":"getStats"}
- *   ← {"id":4,"result":{...}}
- *
- *   → {"id":5,"method":"ping"}
- *   ← {"id":5,"result":{"ok":true,"version":"1.3.0"}}
- */
-
-import { createHash, randomBytes } from "node:crypto";
-import { createInterface } from "node:readline";
-import { pathToFileURL } from "node:url";
-import { resolve } from "node:path";
-import { writeFileSync } from "node:fs";
-
-// Shroud dist path passed as first CLI arg (default: ./dist relative to this script)
-import { dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const shroudDist = process.argv[2] || resolve(__dirname, "dist");
-
-// Dynamically import the Obfuscator and config resolver
-const { Obfuscator } = await import(
-  pathToFileURL(resolve(shroudDist, "obfuscator.js")).href
-);
-const { resolveConfig } = await import(
-  pathToFileURL(resolve(shroudDist, "config.js")).href
-);
-
-// Read plugin config from env var (JSON) or use defaults
-let pluginConfig = {};
-if (process.env.SHROUD_PLUGIN_CONFIG) {
-  try {
-    pluginConfig = JSON.parse(process.env.SHROUD_PLUGIN_CONFIG);
-  } catch (e) {
-    process.stderr.write(`[shroud-bridge] Bad SHROUD_PLUGIN_CONFIG: ${e.message}\n`);
-  }
-}
-
-const config = resolveConfig(pluginConfig);
-let obfuscator = new Obfuscator(config);
-
-// Hash chain: each audit entry includes hash of previous entry for tamper evidence
-let chainHash = "0000000000000000";
-
-function advanceChain(data) {
-  const payload = chainHash + JSON.stringify(data);
-  chainHash = createHash("sha256").update(payload).digest("hex").slice(0, 16);
-  return chainHash;
-}
-
-function proofHash(text) {
-  const salt = config.auditHashSalt || "";
-  const truncate = config.auditHashTruncate || 12;
-  return createHash("sha256")
-    .update(salt + text)
-    .digest("hex")
-    .slice(0, truncate);
-}
-
-const STATS_FILE = process.env.SHROUD_STATS_FILE || "/tmp/shroud-stats.json";
-
-function dumpStats() {
-  try {
-    const stats = obfuscator.getStats();
-    stats.updatedAt = new Date().toISOString();
-    stats.pid = process.pid;
-    writeFileSync(STATS_FILE, JSON.stringify(stats, null, 2) + "\n");
-  } catch {
-    // best-effort
-  }
-}
-
-process.stderr.write("[shroud-bridge] Ready.\n");
-
-// Signal readiness to parent process
-process.stdout.write(JSON.stringify({ ready: true, version: "1.3.0" }) + "\n");
-
-const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
-
-rl.on("line", (line) => {
-  if (!line.trim()) return;
-  let req;
-  try {
-    req = JSON.parse(line);
-  } catch (e) {
-    process.stdout.write(
-      JSON.stringify({ id: null, error: `Parse error: ${e.message}` }) + "\n"
-    );
-    return;
-  }
-
-  const { id, method, params } = req;
-  let result;
-  try {
-    switch (method) {
-      case "ping":
-        result = { ok: true, version: "1.3.0" };
-        break;
-
-      case "obfuscate": {
-        const text = params?.text ?? "";
-        const out = obfuscator.obfuscate(text);
-        const categories = {};
-        for (const e of out.entities) {
-          categories[e.category] = (categories[e.category] || 0) + 1;
-        }
-        result = {
-          obfuscated: out.obfuscated,
-          entityCount: out.entities.length,
-          categories,
-        };
-
-        // Always include audit data in response — Python side decides what to log
-        if (config.auditEnabled || config.verboseLogging) {
-          const reqId = randomBytes(8).toString("hex");
-          const audit = {
-            req: reqId,
-            totalEntities: out.entities.length,
-            inputChars: text.length,
-            outputChars: out.obfuscated.length,
-            charDelta: out.obfuscated.length - text.length,
-            byCategory: categories,
-            modified: out.obfuscated !== text,
-            proofIn: proofHash(text),
-            proofOut: proofHash(out.obfuscated),
-          };
-
-          // Fake samples (only fake values, never real)
-          const maxFakes = config.auditMaxFakesSample || 3;
-          audit.fakesSample = Object.values(out.mappingsUsed).slice(0, maxFakes);
-
-          // Advance tamper-evident hash chain
-          audit.chainHash = advanceChain(audit);
-
-          result.audit = audit;
-        }
-        dumpStats();
-        break;
-      }
-
-      case "deobfuscate": {
-        const text = params?.text ?? "";
-        const deobResult = obfuscator.deobfuscateWithStats
-          ? obfuscator.deobfuscateWithStats(text)
-          : { text: obfuscator.deobfuscate(text), replacementCount: 0 };
-
-        // Always include store size for diagnostics
-        const stats = obfuscator.getStats();
-        result = {
-          text: deobResult.text,
-          replacementCount: deobResult.replacementCount,
-          storeSize: stats.storeMappings ?? 0,
-        };
-
-        if (config.auditEnabled || config.verboseLogging) {
-          const audit = {
-            replacementCount: deobResult.replacementCount,
-            storeSize: stats.storeMappings ?? 0,
-            inputChars: text.length,
-            outputChars: deobResult.text.length,
-            modified: deobResult.text !== text,
-            proofIn: proofHash(text),
-            proofOut: proofHash(deobResult.text),
-          };
-          // Correlate with request via chain
-          audit.chainHash = advanceChain(audit);
-          result.audit = audit;
-        }
-        dumpStats();
-        break;
-      }
-
-      case "reset":
-        obfuscator.reset();
-        chainHash = "0000000000000000";
-        dumpStats();
-        result = { ok: true };
-        break;
-
-      case "getStats":
-        result = obfuscator.getStats();
-        result.chainHash = chainHash;
-        break;
-
-      case "reconfigure": {
-        // Hot-reload config without restarting the process
-        const newConfig = resolveConfig(params?.config ?? {});
-        obfuscator = new Obfuscator(newConfig);
-        result = { ok: true, config: newConfig };
-        break;
-      }
-
-      default:
-        result = undefined;
-        process.stdout.write(
-          JSON.stringify({ id, error: `Unknown method: ${method}` }) + "\n"
-        );
-        return;
-    }
-    process.stdout.write(JSON.stringify({ id, result }) + "\n");
-  } catch (e) {
-    process.stdout.write(
-      JSON.stringify({ id, error: `${method} failed: ${e.message}` }) + "\n"
-    );
-  }
-});
-
-rl.on("close", () => process.exit(0));