shroud-privacy 2.0.12 → 2.0.14

package/README.md

@@ -164,11 +164,47 @@ Disable or tune individual detection rules by name. Rule names match the built-i
 
 Rules not listed keep their defaults. Overrides apply to both direct regex detection and code-aware detection.
 
+### Conversational tools
+
+Shroud registers tools that the LLM can call during conversations:
+
+| Tool | What it does |
+|------|-------------|
+| `shroud-stats` | Show all detection rules with status, confidence, hit counts, store size, and config summary |
+| `shroud_status` | Quick stats: entity counts, session info, audit status (JSON) |
+| `shroud_reset` | Clear all mappings and start a fresh privacy session |
+
+You can also run the stats CLI from the terminal:
+
+```bash
+node ~/.openclaw/extensions/shroud-privacy/scripts/shroud-stats.mjs           # live rule table
+node ~/.openclaw/extensions/shroud-privacy/scripts/shroud-stats.mjs --json    # JSON output
+node ~/.openclaw/extensions/shroud-privacy/scripts/shroud-stats.mjs --test "Contact john@acme.com"
+```
+
+Tip: create an alias for convenience:
+```bash
+alias shroud-stats="node ~/.openclaw/extensions/shroud-privacy/scripts/shroud-stats.mjs"
+```
+
+The CLI reads live stats from `/tmp/shroud-stats.json` (override with `SHROUD_STATS_FILE` env var). The stats file is updated by the running gateway on every obfuscation event.
+
+### Auto-patching on first install
+
+On first load, Shroud automatically patches pi-ai's `EventStream.push()` to enable streaming deobfuscation across all LLM providers and delivery channels. The patch:
+
+1. Backs up the original file (`.shroud-backup`)
+2. Injects a 4-line hook that calls `globalThis.__shroudStreamDeobfuscate`
+3. Clears the Node.js V8 compile cache
+4. Triggers a gateway restart via SIGUSR1
+
+On subsequent loads, the patch is detected and skipped. To revert: restore the `.shroud-backup` file and restart.
+
 ### Rule hit counters
 
 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 OpenClaw gateway via `/tmp/shroud-stats.json`. Use `--test "text with PII"` to test detection against sample input.
+- **`shroud-stats` CLI** — see [Conversational tools](#conversational-tools) above for usage. Shows all rules with status, confidence, and hit counts from the running gateway.
 - **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.
 

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "shroud-privacy",
   "name": "Shroud",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "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,16 +1,20 @@
 {
   "name": "shroud-privacy",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "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/",
+    "scripts/shroud-stats.mjs",
     "openclaw.plugin.json",
     "LICENSE",
     "NOTICE"
   ],
+  "bin": {
+    "shroud-stats": "scripts/shroud-stats.mjs"
+  },
   "scripts": {
     "build": "tsc",
     "test": "vitest run",

package/scripts/shroud-stats.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * Shroud Stats CLI — show active rules, hit counts, store size.
+ *
+ * Usage:
+ *   node scripts/shroud-stats.mjs                    # live stats from running gateway
+ *   node scripts/shroud-stats.mjs --test "some text"  # obfuscate text then show hits
+ *
+ * Reads live stats from /tmp/shroud-stats.json (written by the Shroud plugin).
+ * Falls back to a fresh instance if no stats file exists.
+ */
+
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { readFileSync, existsSync } from "node:fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const distDir = resolve(__dirname, "..", "dist");
+
+const { resolveConfig } = await import(resolve(distDir, "config.js"));
+const { Obfuscator } = await import(resolve(distDir, "obfuscator.js"));
+const { BUILTIN_PATTERNS } = await import(resolve(distDir, "detectors", "regex.js"));
+
+// Load config from OpenClaw config file if available
+let pluginConfig = {};
+try {
+  const configPath = resolve(process.env.HOME || "~", ".openclaw", "openclaw.json");
+  const raw = JSON.parse(readFileSync(configPath, "utf-8"));
+  const entry = raw?.plugins?.entries?.["shroud-privacy"];
+  if (entry?.config) pluginConfig = entry.config;
+} catch {
+  // skip
+}
+
+const config = resolveConfig(pluginConfig);
+const overrides = config.detectorOverrides;
+
+// Try to read live stats from the bridge stats file
+const STATS_FILE = process.env.SHROUD_STATS_FILE || "/tmp/shroud-stats.json";
+let liveStats = null;
+let source = "fresh instance";
+
+if (existsSync(STATS_FILE) && !process.argv.includes("--test")) {
+  try {
+    liveStats = JSON.parse(readFileSync(STATS_FILE, "utf-8"));
+    source = `live (pid ${liveStats.pid}, updated ${liveStats.updatedAt})`;
+  } catch {
+    // fall through to fresh instance
+  }
+}
+
+// If --test flag or no live stats, use a fresh obfuscator
+let ruleHits;
+let storeMappings;
+
+if (liveStats && !process.argv.includes("--test")) {
+  ruleHits = liveStats.ruleHits || {};
+  storeMappings = liveStats.storeMappings || 0;
+} else {
+  const obf = new Obfuscator(config);
+  const testIdx = process.argv.indexOf("--test");
+  if (testIdx !== -1) {
+    const text = process.argv.slice(testIdx + 1).join(" ");
+    if (text) {
+      obf.obfuscate(text);
+      source = `test input (${text.length} chars)`;
+    }
+  }
+  const stats = obf.getStats();
+  ruleHits = stats.ruleHits;
+  storeMappings = stats.storeMappings;
+}
+
+// Build rule table
+const rules = BUILTIN_PATTERNS.map((p) => {
+  const ov = overrides[p.name];
+  const enabled = ov?.enabled !== false;
+  const confidence = ov?.confidence ?? p.confidence;
+  const hits = ruleHits[`regex:${p.name}`] ?? 0;
+  return { name: p.name, category: p.category, enabled, confidence, hits };
+});
+
+rules.sort((a, b) => b.hits - a.hits);
+
+// JSON output mode
+if (process.argv.includes("--json")) {
+  const output = {
+    source,
+    storeMappings,
+    auditEnabled: config.auditEnabled || config.verboseLogging || false,
+    overrideCount: Object.keys(overrides).length,
+    rules,
+  };
+  if (liveStats) {
+    output.pid = liveStats.pid;
+    output.updatedAt = liveStats.updatedAt;
+  }
+  process.stdout.write(JSON.stringify(output, null, 2) + "\n");
+  process.exit(0);
+}
+
+// Format table
+const maxName = Math.max(...rules.map((r) => r.name.length), 4);
+const maxCat = Math.max(...rules.map((r) => r.category.length), 8);
+
+const header = `${"Rule".padEnd(maxName)}  ${"Category".padEnd(maxCat)}  Status    Conf   Hits`;
+const sep = "─".repeat(header.length + 20);
+
+console.log(`Shroud Rule Hits (${source})`);
+console.log(sep);
+console.log(header);
+console.log(sep);
+
+for (const r of rules) {
+  const status = r.enabled ? "active" : "DISABLED";
+  const bar = r.hits > 0 ? " " + "█".repeat(Math.min(Math.ceil(Math.log2(r.hits + 1)), 16)) : "";
+  console.log(
+    `${r.name.padEnd(maxName)}  ${r.category.padEnd(maxCat)}  ${status.padEnd(8)}  ${r.confidence.toFixed(2).padStart(4)}  ${String(r.hits).padStart(5)}${bar}`
+  );
+}
+
+console.log(sep);
+console.log(`Store: ${storeMappings} active mappings`);
+console.log(`Audit: ${config.auditEnabled || config.verboseLogging ? "enabled" : "disabled"}`);
+console.log(`Config: detectorOverrides has ${Object.keys(overrides).length} override(s)`);