shroud-privacy 2.5.4 → 2.5.6

package/README.md

@@ -13,12 +13,15 @@
   <a href="#install">Install</a> &middot;
   <a href="#why-shroud">Why Shroud</a> &middot;
   <a href="#configure">Configure</a> &middot;
+  <a href="docs/integrations.md">Integrations</a> &middot;
   <a href="#agent-privacy-protocol-app">APP Protocol</a> &middot;
   <a href="CHANGELOG.md">Changelog</a>
 </p>
 
 > Apache 2.0 &middot; Zero runtime dependencies &middot; Anthropic + OpenAI + Google supported &middot; Prompt-caching friendly &middot; Works with [OpenClaw](https://openclaw.ai), [Hermes Agent](https://github.com/nousresearch/hermes-agent), or any agent via [APP](#agent-privacy-protocol-app)
 
+**Detailed integration reference:** [`docs/integrations.md`](docs/integrations.md)
+
 ---
 
 ## Why Shroud
@@ -78,14 +81,14 @@ Shroud does not guarantee compliance — regex-based detection has limitations (
 
 > **How it works:** Shroud intercepts ALL outbound LLM API calls (Anthropic, OpenAI, Google, any provider) at the `fetch` level and obfuscates detected entities in every message — including assistant history and Slack `<mailto:>` markup — before it leaves the process. On the response side, SSE streaming is deobfuscated per content block with buffered flushing. Every delivery path (Slack, WhatsApp, TUI, Telegram, Discord, Signal, web) gets real text automatically. Zero host patches required.
 
-> **Requires OpenClaw 2026.3.22 or later.**
+> **Requires OpenClaw 2026.3.24 or later.**
 
 ### OpenClaw support policy
 
 - **Formal minimum supported version:** `2026.3.24` (from `openclaw.plugin.json` `minOpenClawVersion`).
 - **Release validation matrix (this release):**
   - **Baseline:** `2026.3.28` (includes WhatsApp E2E path)
-  - **Latest-at-release:** `2026.4.9` (full 192-scenario E2E pass)
+  - **Latest-at-release:** `2026.4.14` (Slack E2E pass)
 - **Latest caveat:** on OpenClaw builds where WhatsApp provisioning via `channels add` is unsupported, latest-focused compat runs skip WhatsApp E2E and validate Slack E2E.
 - **Source of truth for current matrix:** `docs/ci-current-state.md` and `CHANGELOG.md`.
 
@@ -93,10 +96,10 @@ Shroud does not guarantee compliance — regex-based detection has limitations (
 
 ## Install
 
-### OpenClaw (2026.3.22+)
+### OpenClaw (2026.3.24+)
 
 ```bash
-openclaw --version    # ensure 2026.3.22+
+openclaw --version    # ensure 2026.3.24+
 openclaw plugins install shroud-privacy
 ```
 
@@ -138,7 +141,20 @@ Add to your project's `.mcp.json` or `~/.claude/.mcp.json`:
 }
 ```
 
-That's it — the MCP server auto-starts the privacy engine. Claude gains six tools: `shroud_obfuscate`, `shroud_deobfuscate`, `shroud_status`, `shroud_scan_tool`, `shroud_configure`, and `shroud_reset`.
+That's it — the MCP server auto-starts a dedicated APP daemon on `/tmp/shroud-claude-mcp.sock` and writes Claude MCP session state under `OPENCLAW_STATE_DIR` (or `~/.openclaw`) as `shroud-claude-mcp-sessions.json`. Claude gains six tools: `shroud_obfuscate`, `shroud_deobfuscate`, `shroud_status`, `shroud_scan_tool`, `shroud_configure`, and `shroud_reset`.
+
+If you want automatic tool-boundary obfuscation/deobfuscation instead of explicit MCP tools, use the shipped Claude hooks bridge in `clients/claude-code/shroud-bridge.mjs` together with `clients/claude-code/hooks.json`.
+
+### Codex
+
+```bash
+npm install shroud-privacy
+codex mcp add shroud -- node node_modules/shroud-privacy/clients/codex/shroud-mcp.mjs
+```
+
+Codex uses the same six MCP tools as Claude, but on a separate APP daemon and socket: `/tmp/shroud-codex-mcp.sock`. Its APP session file defaults to `shroud-codex-mcp-sessions.json` under `OPENCLAW_STATE_DIR` or `~/.openclaw`.
+
+The Codex MCP wrapper also auto-starts `clients/codex/shroud-bridge.mjs` on the host. That bridge watches Codex's local `~/.codex/history.jsonl` and writes `shroud-codex-cli-sessions.json` into the shared OpenClaw state dir, so Codex call/session counters stay current even when Codex is not actively invoking Shroud MCP tools. Set `SHROUD_CODEX_BRIDGE=0` only if you explicitly want to disable that behavior.
 
 ### Any agent (via APP)
 
@@ -165,6 +181,8 @@ with ShroudClient() as shroud:
 
 Copy `clients/python/shroud_client.py` into your project, or import it directly from the npm install path. Requires Node.js on the PATH.
 
+For direct APP clients such as NCG, call `identify` first if you want per-agent session counters, then `obfuscate` / `deobfuscate`, and optionally wrap tool execution with `tool_call` / `tool_result` for telemetry.
+
 **Any language:**
 
 Spawn the APP server and talk JSON-RPC over stdin/stdout:

package/app-server.mjs

@@ -13,14 +13,17 @@
  *   SHROUD_PLUGIN_CONFIG   JSON config for the engine
  *   SHROUD_STORE_FILE      Persistent store file path
  *   SHROUD_STATS_FILE      Stats dump file path
+ *   SHROUD_APP_EVENTS_FILE JSONL file for APP-side event export
+ *   SHROUD_APP_SESSIONS_FILE JSON file for APP-side agent session state
  */
 
 import { createHash, randomBytes } from "node:crypto";
 import { createInterface } from "node:readline";
 import { pathToFileURL } from "node:url";
 import { resolve, dirname } from "node:path";
-import { writeFileSync, readFileSync } from "node:fs";
+import { writeFileSync, readFileSync, unlinkSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { createServer as createNetServer } from "node:net";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const shroudDist = process.argv[2] || resolve(__dirname, "dist");
@@ -61,6 +64,8 @@ let obfuscator = new Obfuscator(config);
 
 const STATS_FILE = process.env.SHROUD_STATS_FILE || "/tmp/shroud-stats.json";
 const STORE_FILE = process.env.SHROUD_STORE_FILE || "";
+const APP_EVENTS_FILE = process.env.SHROUD_APP_EVENTS_FILE || "/tmp/shroud-app-events.jsonl";
+const APP_SESSIONS_FILE = process.env.SHROUD_APP_SESSIONS_FILE || "/tmp/shroud-app-sessions.json";
 
 // ---------------------------------------------------------------------------
 // Audit chain
@@ -116,6 +121,20 @@ function resolvePartition(params) {
 const startTime = Date.now();
 let requestCount = 0;
 let totalProcessingMs = 0;
+const toolSequence = [];
+const privacy = {
+  obfuscationCalls: 0,
+  deobfuscationCalls: 0,
+  entitiesObfuscated: 0,
+  replacementsDeobfuscated: 0,
+  categoryCounts: {},
+};
+
+let agentIdentified = false;
+let agentLabel = null;
+let agentBuildId = null;
+let agentVersion = null;
+let agentChannel = null;
 
 // ---------------------------------------------------------------------------
 // Stats dump helper
@@ -130,6 +149,36 @@ function dumpStats() {
   } catch { /* best-effort */ }
 }
 
+function dumpSessionFile() {
+  if (!agentIdentified) return;
+  try {
+    const session = {
+      agentLabel,
+      agentBuildId,
+      agentVersion,
+      channel: agentChannel,
+      source: "app-server",
+      pid: process.pid,
+      requestCount,
+      uptimeMs: Date.now() - startTime,
+      securityEvents: 0,
+      storeSize: getObfuscator().getStats().storeMappings ?? 0,
+      classification: {
+        role: "APP Agent",
+        confidencePct: 100,
+        confidence: "high",
+        colour: "#06b6d4",
+        signals: ["app-server"],
+      },
+      toolSequence: toolSequence.slice(-20),
+      privacy,
+      eventsFile: APP_EVENTS_FILE,
+      updatedAt: new Date().toISOString(),
+    };
+    writeFileSync(APP_SESSIONS_FILE, JSON.stringify(session, null, 2) + "\n");
+  } catch { /* best-effort */ }
+}
+
 // ---------------------------------------------------------------------------
 // JSON-RPC helpers
 // ---------------------------------------------------------------------------
@@ -153,6 +202,37 @@ function jsonResult(id, result) {
 // APP method handlers
 // ---------------------------------------------------------------------------
 
+function handleIdentify(id, params) {
+  if (!params || typeof params.agent !== "string" || !params.agent.trim()) {
+    return jsonError(id, ERR_BAD_PARAMS, 'Missing required param: agent (string)');
+  }
+  if (typeof params.version !== "string" || !params.version.trim()) {
+    return jsonError(id, ERR_BAD_PARAMS, 'Missing required param: version (string)');
+  }
+
+  agentLabel = params.agent.trim();
+  agentVersion = params.version.trim();
+  agentChannel = typeof params.channel === "string" && params.channel.trim() ? params.channel.trim() : "app";
+  agentBuildId = createHash("sha256")
+    .update(agentLabel + ":" + agentVersion)
+    .digest("hex")
+    .slice(0, 16);
+  agentIdentified = true;
+
+  process.stderr.write(
+    `[app-server] Agent identified: ${agentLabel} v${agentVersion} (${agentChannel}) buildId=${agentBuildId}\n`
+  );
+
+  dumpSessionFile();
+
+  return jsonResult(id, {
+    ok: true,
+    agent: agentLabel,
+    buildId: agentBuildId,
+    security: false,
+  });
+}
+
 function handleObfuscate(id, params) {
   if (!params || typeof params.text !== "string") {
     return jsonError(id, ERR_BAD_PARAMS, "Missing required param: text");
@@ -193,6 +273,12 @@ function handleObfuscate(id, params) {
   audit.fakesSample = Object.values(out.mappingsUsed || {}).slice(0, maxFakes);
   result.audit = audit;
 
+  privacy.obfuscationCalls++;
+  privacy.entitiesObfuscated += out.entities.length;
+  for (const [cat, count] of Object.entries(categories)) {
+    privacy.categoryCounts[cat] = (privacy.categoryCounts[cat] || 0) + count;
+  }
+
   dumpStats();
   return jsonResult(id, result);
 }
@@ -231,6 +317,11 @@ function handleDeobfuscate(id, params) {
   };
   result.audit = audit;
 
+  if ((deobResult.replacementCount || 0) > 0) {
+    privacy.deobfuscationCalls++;
+    privacy.replacementsDeobfuscated += deobResult.replacementCount || 0;
+  }
+
   dumpStats();
   return jsonResult(id, result);
 }
@@ -381,8 +472,53 @@ function handleConfigure(id, params) {
   return jsonResult(id, { ok: true, appliedKeys });
 }
 
+function handleSecurity(id) {
+  return jsonResult(id, {
+    enabled: false,
+    mode: "off",
+    events: 0,
+    byThreatClass: {},
+    agent: agentIdentified ? {
+      label: agentLabel,
+      buildId: agentBuildId,
+      version: agentVersion,
+      channel: agentChannel,
+      requestCount,
+    } : null,
+    recentEvents: [],
+  });
+}
+
+function handleToolCall(id, params) {
+  if (!params || typeof params.tool !== "string" || !params.tool.trim()) {
+    return jsonError(id, ERR_BAD_PARAMS, "Missing required param: tool (string)");
+  }
+
+  toolSequence.push(params.tool.trim());
+
+  return jsonResult(id, {
+    blocked: false,
+    reason: null,
+    sequenceLength: toolSequence.length,
+    events: [],
+    securityEnabled: false,
+  });
+}
+
+function handleToolResult(id, params) {
+  if (!params || typeof params.tool !== "string" || !params.tool.trim()) {
+    return jsonError(id, ERR_BAD_PARAMS, "Missing required param: tool (string)");
+  }
+
+  return jsonResult(id, {
+    ok: true,
+    recorded: true,
+  });
+}
+
 function handleShutdown(id) {
   dumpStats();
+  dumpSessionFile();
   const response = jsonResult(id, { ok: true, flushed: true });
   process.stdout.write(response + "\n");
   process.exit(0);
@@ -413,32 +549,37 @@ function handleSetPartition(id, params) {
 // ---------------------------------------------------------------------------
 
 const METHODS = {
+  identify: handleIdentify,
   obfuscate: handleObfuscate,
   deobfuscate: handleDeobfuscate,
   batch: handleBatch,
   reset: handleReset,
   stats: handleStats,
   health: handleHealth,
+  security: handleSecurity,
+  tool_call: handleToolCall,
+  tool_result: handleToolResult,
   configure: handleConfigure,
   shutdown: handleShutdown,
   setPartition: handleSetPartition,
 };
 
-function dispatch(line) {
+function dispatch(line, writeFn) {
   if (!line.trim()) return;
+  const write = writeFn || ((s) => process.stdout.write(s));
 
   let req;
   try {
     req = JSON.parse(line);
   } catch (e) {
-    process.stdout.write(jsonError(null, ERR_PARSE, `Parse error: ${e.message}`) + "\n");
+    write(jsonError(null, ERR_PARSE, `Parse error: ${e.message}`) + "\n");
     return;
   }
 
   const { id, method, params } = req;
 
   if (id === undefined || id === null || !method) {
-    process.stdout.write(
+    write(
       jsonError(id ?? null, ERR_INVALID_REQ, "Missing required field: id and method") + "\n"
     );
     return;
@@ -446,7 +587,7 @@ function dispatch(line) {
 
   const handler = METHODS[method];
   if (!handler) {
-    process.stdout.write(
+    write(
       jsonError(id, ERR_NO_METHOD, `Method not found: ${method}`) + "\n"
     );
     return;
@@ -459,10 +600,11 @@ function dispatch(line) {
     const response = handler(id, params);
     // shutdown writes its own response and exits
     if (method !== "shutdown") {
-      process.stdout.write(response + "\n");
+      write(response + "\n");
+      dumpSessionFile();
     }
   } catch (e) {
-    process.stdout.write(
+    write(
       jsonError(id, ERR_ENGINE, `Engine error: ${e.message}`) + "\n"
     );
   }
@@ -507,28 +649,103 @@ const handshake = {
   engine: "shroud",
   version: engineVersion,
   capabilities: [
+    "identify",
     "obfuscate",
     "deobfuscate",
     "batch",
     "stats",
     "health",
     "configure",
+    "security",
+    "tool_call",
+    "tool_result",
     "audit",
     "partitions",
   ],
+  security: null,
 };
 
 process.stderr.write(`[app-server] Starting APP server v${engineVersion}\n`);
-process.stdout.write(JSON.stringify(handshake) + "\n");
 
 // ---------------------------------------------------------------------------
-// Main loop
+// Socket listener mode (--listen <path>)
 // ---------------------------------------------------------------------------
 
-const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
-rl.on("line", dispatch);
-rl.on("close", () => {
-  clearInterval(heartbeatInterval);
-  dumpStats();
-  process.exit(0);
-});
+const listenFlag = process.argv.indexOf("--listen");
+const SOCKET_PATH = listenFlag !== -1 ? (process.argv[listenFlag + 1] || "/tmp/shroud-app.sock") : null;
+
+if (SOCKET_PATH) {
+  // Remove stale socket file
+  try { unlinkSync(SOCKET_PATH); } catch {}
+
+  let socketClients = 0;
+  const socketServer = createNetServer((conn) => {
+    socketClients++;
+    const clientId = socketClients;
+    process.stderr.write(`[app-server] Socket client #${clientId} connected\n`);
+
+    // Send handshake to this client
+    conn.write(JSON.stringify(handshake) + "\n");
+
+    let connected = true;
+    const connRl = createInterface({ input: conn, crlfDelay: Infinity });
+    const connWrite = (s) => { if (connected) try { conn.write(s); } catch {} };
+
+    connRl.on("line", (line) => dispatch(line, connWrite));
+    connRl.on("error", () => {});
+    conn.on("error", () => { connected = false; });
+    conn.on("close", () => {
+      connected = false;
+      process.stderr.write(`[app-server] Socket client #${clientId} disconnected\n`);
+    });
+  });
+
+  socketServer.listen(SOCKET_PATH, () => {
+    process.stderr.write(`[app-server] Listening on socket: ${SOCKET_PATH}\n`);
+  });
+
+  socketServer.on("error", (err) => {
+    process.stderr.write(`[app-server] Socket error: ${err.message}\n`);
+    process.exit(1);
+  });
+
+  // Also still serve stdin for backwards compat
+  process.stdout.write(JSON.stringify(handshake) + "\n");
+  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  rl.on("line", (line) => dispatch(line));
+  rl.on("close", () => {
+    try { unlinkSync(SOCKET_PATH); } catch {}
+    socketServer.close();
+    clearInterval(heartbeatInterval);
+    dumpStats();
+    dumpSessionFile();
+    process.exit(0);
+  });
+
+  // Cleanup socket on exit
+  for (const sig of ["SIGINT", "SIGTERM"]) {
+    process.on(sig, () => {
+      try { unlinkSync(SOCKET_PATH); } catch {}
+      socketServer.close();
+      clearInterval(heartbeatInterval);
+      dumpStats();
+      dumpSessionFile();
+      process.exit(0);
+    });
+  }
+} else {
+  // ---------------------------------------------------------------------------
+  // Default: stdin/stdout mode
+  // ---------------------------------------------------------------------------
+
+  process.stdout.write(JSON.stringify(handshake) + "\n");
+
+  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  rl.on("line", (line) => dispatch(line));
+  rl.on("close", () => {
+    clearInterval(heartbeatInterval);
+    dumpStats();
+    dumpSessionFile();
+    process.exit(0);
+  });
+}

package/clients/claude-code/hooks.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://docs.anthropic.com/schemas/claude-code-hooks.json",
+  "_comment": "Add this 'hooks' block to your .claude/settings.json or .claude/settings.local.json",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read|Bash|Grep|Glob|Write|Edit|NotebookEdit|WebFetch|WebSearch",
+        "hooks": [
+          {
+            "type": "http",
+            "url": "http://127.0.0.1:17380/pre-tool-use",
+            "timeout": 5000,
+            "statusMessage": "Shroud: scanning tool call"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read|Bash|Grep|Glob|WebFetch|WebSearch",
+        "hooks": [
+          {
+            "type": "http",
+            "url": "http://127.0.0.1:17380/post-tool-use",
+            "timeout": 5000,
+            "statusMessage": "Shroud: obfuscating output"
+          }
+        ]
+      }
+    ]
+  }
+}

package/clients/claude-code/mcp.json

@@ -0,0 +1,9 @@
+{
+  "_comment": "Copy this into your project's .mcp.json or ~/.claude/.mcp.json",
+  "mcpServers": {
+    "shroud": {
+      "command": "node",
+      "args": ["node_modules/shroud-privacy/clients/claude-code/shroud-mcp.mjs"]
+    }
+  }
+}