shroud-privacy 2.5.5 → 2.5.7

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
@@ -76,7 +79,7 @@ Shroud does not guarantee compliance — regex-based detection has limitations (
 | `globalThis.__shroudStreamDeobfuscate` | LLM → Agent | Streaming event deobfuscation hook |
 | `globalThis.__shroudDeobfuscate` | Agent → Channel | Global deobfuscation hook — called by OpenClaw before ANY channel send |
 
-> **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.
+> **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, Slack `<mailto:>` markup, and OpenAI Responses / Codex `input_text` blocks — before it leaves the process. On the response side, SSE streaming is deobfuscated per content block with buffered flushing, and OpenAI Responses `output_text` blocks are treated the same as plain `text` blocks. Every delivery path (Slack, WhatsApp, TUI, Telegram, Discord, Signal, web) gets real text automatically. Zero host patches required.
 
 > **Requires OpenClaw 2026.3.24 or later.**
 
@@ -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:
@@ -202,6 +220,15 @@ openclaw plugins install --path .
 openclaw gateway restart
 ```
 
+For a local Docker-backed OpenClaw install, use the repo deploy script instead. It builds the checkout, runs the key regression tests, syncs the packaged plugin into `~/.openclaw/extensions/shroud-privacy`, clears the Node compile cache, and recreates `openclaw-primary-gateway` when `~/.openclaw/compose/docker-compose.primary.yml` is present:
+
+```bash
+git clone https://github.com/wkeything/shroud.git
+cd shroud
+npm install
+./deploy-local.sh
+```
+
 ## Updating
 
 ```bash

package/app-server.mjs

@@ -13,6 +13,8 @@
  *   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";
@@ -62,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
@@ -117,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
@@ -131,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
 // ---------------------------------------------------------------------------
@@ -154,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");
@@ -194,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);
 }
@@ -232,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);
 }
@@ -382,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);
@@ -414,12 +549,16 @@ 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,
@@ -462,6 +601,7 @@ function dispatch(line, writeFn) {
     // shutdown writes its own response and exits
     if (method !== "shutdown") {
       write(response + "\n");
+      dumpSessionFile();
     }
   } catch (e) {
     write(
@@ -509,15 +649,20 @@ 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`);
@@ -573,6 +718,7 @@ if (SOCKET_PATH) {
     socketServer.close();
     clearInterval(heartbeatInterval);
     dumpStats();
+    dumpSessionFile();
     process.exit(0);
   });
 
@@ -583,6 +729,7 @@ if (SOCKET_PATH) {
       socketServer.close();
       clearInterval(heartbeatInterval);
       dumpStats();
+      dumpSessionFile();
       process.exit(0);
     });
   }
@@ -598,6 +745,7 @@ if (SOCKET_PATH) {
   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"]
+    }
+  }
+}