shroud-privacy 2.1.0 → 2.2.0

package/README.md

@@ -26,10 +26,11 @@
 | `before_tool_call` | LLM → Tool | Deobfuscate tool parameters + track tool chain depth |
 | `tool_result_persist` | Tool → History | Obfuscate tool results before storing |
 | `message_sending` | Agent → User | Deobfuscate outbound messages (all channels) |
+| `globalThis.__shroudDeobfuscate` | Agent → Channel | Global deobfuscation hook — called by OpenClaw before ANY channel send |
 
-> **Privacy guarantee:** Shroud intercepts ALL outbound LLM API calls (Anthropic, OpenAI, Google, any provider) at the `fetch` level and obfuscates PII in every message — including assistant history and Slack `<mailto:>` markup — before it leaves the process. No PII reaches the LLM. On the inbound side, streaming responses are deobfuscated in real-time via `EventStream.prototype.push()` — no OpenClaw file modifications needed.
+> **Privacy guarantee:** Shroud intercepts ALL outbound LLM API calls (Anthropic, OpenAI, Google, any provider) at the `fetch` level and obfuscates PII in every message — including assistant history and Slack `<mailto:>` markup — before it leaves the process. No PII reaches the LLM. On the channel delivery side, Shroud registers `globalThis.__shroudDeobfuscate` — a single function that OpenClaw calls before sending to ANY channel (Slack, WhatsApp, Signal, web, etc.). One hook, all channels, transparent no-op if Shroud isn't loaded.
 
-> **Requires OpenClaw 2026.3.24 or later.** Older versions do not call `message_sending` for Slack/WhatsApp channels, causing duplicate messages with fake tokens. Shroud 2.1+ is tested exclusively against OpenClaw 2026.3.24.
+> **Requires OpenClaw 2026.3.24 or later** with the channel delivery patch (see [OpenClaw patch](#openclaw-channel-delivery-patch) below).
 
 ## Install
 
@@ -103,38 +104,16 @@ Other methods: `reset`, `stats`, `health`, `configure`, `shutdown`.
 git clone https://github.com/walterkeating-stack/shroud.git
 cd shroud
 npm install && npm run build
-bash deploy-local.sh     # → OpenClaw (~/.openclaw/extensions/)
+openclaw plugins install --path .
+openclaw gateway restart
 ```
 
 ## Updating
 
-OpenClaw doesn't have a `plugins update` command yet, so updating requires removing the old install first. A helper script is included:
-
-```bash
-# Update to latest version (preserves your config)
-bash scripts/update-openclaw-plugin.sh
-
-# Update to a specific version
-bash scripts/update-openclaw-plugin.sh <version>
-```
-
-The script saves your plugin config from `openclaw.json`, removes the old extension, reinstalls from npm, restores your config, and restarts the gateway.
-
-### Manual update
-
-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)
+# Remove old plugin, reinstall from npm, restart
+openclaw plugins remove shroud-privacy
 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
 ```
 
@@ -261,10 +240,28 @@ Shroud uses runtime prototype patches — **no OpenClaw files are modified**:
 
 **Inbound (LLM → User):** Patches `EventStream.prototype.push()` to deobfuscate streaming responses in real-time. Fake values are replaced with real values as they stream.
 
-**Channel delivery:** On OpenClaw 2026.3.24+, the `message_sending` hook fires for ALL channels (Slack, WhatsApp, Telegram, etc.) and deobfuscates outbound messages. Older OpenClaw versions skip this hook for some channels, causing fake tokens in channel output.
+**Channel delivery:** Shroud registers `globalThis.__shroudDeobfuscate(text)` — a single global function that converts fake values back to real values. OpenClaw calls this once in its generic message delivery function, before sending to any channel. If Shroud isn't loaded, the function doesn't exist — transparent no-op. The `message_sending` hook provides a backup deobfuscation path.
 
 All patches are applied once at plugin load and are idempotent — subsequent loads detect and skip them.
 
+### OpenClaw channel delivery patch
+
+Shroud requires a one-line addition to OpenClaw's message delivery function — the single point where all outbound channel messages pass through. This covers ALL channels (Slack, WhatsApp, Signal, Telegram, web, etc.) with one change:
+
+```js
+// In OpenClaw's generic message delivery function:
+const deob = globalThis.__shroudDeobfuscate;
+if (deob && typeof text === 'string') text = deob(text);
+```
+
+**Why this works:**
+- **One change, all channels** — no per-channel hooks needed
+- **Transparent** — if Shroud isn't loaded, `globalThis.__shroudDeobfuscate` is `undefined`, the `if` is false, zero overhead
+- **All releases** — works on any OpenClaw version that sends channel messages through a common delivery path
+- **Last-moment deobfuscation** — fakes are replaced with real values at the latest possible point, just before the HTTP API call
+
+The `deploy-local.sh` script includes a post-install verification step that tests the full chain.
+
 ### Rule hit counters
 
 Shroud tracks per-rule match counts for the lifetime of the process. Counters appear in three places:
@@ -478,7 +475,7 @@ npm run lint      # type-check without emitting
 
 ```bash
 npm run build
-bash deploy-local.sh   # → OpenClaw (~/.openclaw/extensions/shroud-privacy/)
+openclaw plugins install --path .
 openclaw gateway restart
 ```
 
@@ -491,8 +488,8 @@ openclaw gateway restart
 # 2. Update CHANGELOG.md
 # 3. Commit and tag
 git add -A
-git commit -m "Release v1.x.y"
-git tag v1.x.y
+git commit -m "release: vX.Y.Z"
+git tag vX.Y.Z
 git push && git push --tags
 ```
 

package/dist/hooks.js

@@ -14,12 +14,13 @@
  *                                     providers before OpenClaw processes them
  */
 import { createHash, randomBytes } from "node:crypto";
-import { writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { BUILTIN_PATTERNS } from "./detectors/regex.js";
 const STATS_FILE = process.env.SHROUD_STATS_FILE || "/tmp/shroud-stats.json";
 function getSharedObfuscator(fallback) {
     return globalThis.__shroudObfuscator || fallback;
 }
+const MAPPINGS_FILE = process.env.SHROUD_MAPPINGS_FILE || "/tmp/shroud-mappings.json";
 function dumpStatsFile(fallback) {
     try {
         const ob = getSharedObfuscator(fallback);
@@ -32,6 +33,30 @@ function dumpStatsFile(fallback) {
     catch {
         // best-effort
     }
+    // Also dump mapping table for child process fetch intercept
+    try {
+        const ob = getSharedObfuscator(fallback);
+        const store = ob._store;
+        if (store?.allMappings) {
+            const allMap = store.allMappings();
+            const mappings = {};
+            for (const [real, fake] of allMap) {
+                mappings[real] = fake;
+            }
+            const config = ob.config;
+            writeFileSync(MAPPINGS_FILE, JSON.stringify({
+                mappings,
+                secretKey: config.secretKey,
+                persistentSalt: config.persistentSalt,
+            }) + "\n");
+        }
+    }
+    catch (e) {
+        try {
+            writeFileSync(MAPPINGS_FILE + ".error", String(e) + "\n");
+        }
+        catch { }
+    }
 }
 // ---------------------------------------------------------------------------
 // Hashing utilities (audit proof hashes)
@@ -169,6 +194,12 @@ export function registerHooks(api, obfuscator) {
     // instance while message_sending fires on another (via the delivery subsystem).
     // Without sharing, the delivery instance has an empty mapping store and
     // cannot deobfuscate CGNAT surrogates in outbound channel messages.
+    function stripSlackLinksForHook(text) {
+        text = text.replace(/<mailto:[^|>]+\|([^>]*)>/g, "$1");
+        text = text.replace(/<https?:\/\/[^|>]+\|([^>]*)>/g, "$1");
+        text = text.replace(/<(https?:\/\/[^>]+)>/g, "$1");
+        return text;
+    }
     if (process.env.NODE_ENV !== "test") {
         const g = globalThis;
         if (g.__shroudObfuscator) {
@@ -183,6 +214,16 @@ export function registerHooks(api, obfuscator) {
     const ob = () => getSharedObfuscator(obfuscator);
     const config = ob().config;
     const auditActive = config.auditEnabled || config.verboseLogging;
+    // Write initial config to mappings file so the fetch preload in child
+    // processes can create a compatible obfuscator on the first API call.
+    try {
+        writeFileSync(MAPPINGS_FILE, JSON.stringify({
+            mappings: {},
+            secretKey: config.secretKey,
+            persistentSalt: config.persistentSalt,
+        }) + "\n");
+    }
+    catch { /* best-effort */ }
     // -----------------------------------------------------------------------
     // 1. before_prompt_build (async): obfuscate user prompt
     // -----------------------------------------------------------------------
@@ -192,17 +233,46 @@ export function registerHooks(api, obfuscator) {
         if (ob().toolDepth > 0) {
             ob().resetToolDepth();
         }
+        let totalEntities = 0;
+        // Obfuscate the system prompt
         const prompt = event?.prompt;
-        if (typeof prompt !== "string" || !prompt)
-            return;
-        const result = ob().obfuscate(prompt);
-        if (result.entities.length === 0)
+        let obfuscatedPrompt;
+        if (typeof prompt === "string" && prompt) {
+            const cleaned = stripSlackLinksForHook(prompt);
+            const result = ob().obfuscate(cleaned);
+            if (result.entities.length > 0 || cleaned !== prompt) {
+                obfuscatedPrompt = result.entities.length > 0 ? result.obfuscated : cleaned;
+                totalEntities += result.entities.length;
+            }
+        }
+        // Pre-create mappings for PII in user messages WITHOUT mutating them.
+        // This ensures the fetch preload (in child process) has the mappings
+        // before the API call. The actual replacement happens in the preload.
+        api.logger?.info(`[shroud] event keys: ${Object.keys(event || {}).join(",")}`);
+        if (Array.isArray(event?.messages)) {
+            for (const msg of event.messages) {
+                const texts = [];
+                if (typeof msg.content === "string")
+                    texts.push(msg.content);
+                else if (Array.isArray(msg.content)) {
+                    for (const b of msg.content) {
+                        if (b?.type === "text" && typeof b.text === "string")
+                            texts.push(b.text);
+                    }
+                }
+                for (const text of texts) {
+                    const cleaned = stripSlackLinksForHook(text);
+                    const result = ob().obfuscate(cleaned);
+                    totalEntities += result.entities.length;
+                    // Do NOT mutate — just creating mappings in the store
+                }
+            }
+        }
+        if (totalEntities === 0)
             return;
         dumpStatsFile(obfuscator);
-        api.logger?.info(`[shroud] before_prompt_build: obfuscated ${result.entities.length} entities`);
-        return {
-            prompt: result.obfuscated,
-        };
+        api.logger?.info(`[shroud] before_prompt_build: obfuscated ${totalEntities} entities (mappings synced)`);
+        return obfuscatedPrompt ? { systemPrompt: obfuscatedPrompt } : undefined;
     });
     // -----------------------------------------------------------------------
     // 2. before_message_write (SYNC): bidirectional privacy filter
@@ -222,6 +292,30 @@ export function registerHooks(api, obfuscator) {
         const role = msg.role ?? "";
         // --- Assistant messages: DEOBFUSCATE (fakes → real values) ---
         if (role === "assistant") {
+            // Import mappings created by the fetch preload (child process) so we can
+            // deobfuscate fakes that the preload generated independently.
+            try {
+                const raw = readFileSync(MAPPINGS_FILE, "utf-8");
+                const data = JSON.parse(raw.trim());
+                const preloadMappings = data?.mappings;
+                if (preloadMappings && typeof preloadMappings === "object") {
+                    const store = ob()._store;
+                    if (store?.put) {
+                        for (const [real, fake] of Object.entries(preloadMappings)) {
+                            if (typeof fake === "string" && store.getFake(real) === undefined) {
+                                store.put(real, fake, "preload");
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                // best-effort — file may not exist yet
+            }
+            const _raw = typeof msg.content === "string" ? msg.content :
+                Array.isArray(msg.content) ? msg.content.map((b) => b?.text || "").join("") : "";
+            if (_raw.length < 500)
+                api.logger?.info(`[shroud][raw-assistant] ${_raw}`);
             if (typeof msg.content === "string") {
                 const { text: deobfuscated, replacementCount } = ob().deobfuscateWithStats(msg.content);
                 if (deobfuscated === msg.content)
@@ -368,6 +462,16 @@ export function registerHooks(api, obfuscator) {
     api.on("before_tool_call", async (event) => {
         if (!event?.params || typeof event.params !== "object")
             return;
+        // Block the message tool for send actions. The gateway auto-delivers
+        // responses — using the message tool causes duplicate messages (one
+        // deobfuscated via streaming, one with fakes from the tool call).
+        if (event.toolName === "message") {
+            api.logger?.info(`[shroud] message tool call: action=${event.params?.action}`);
+            if (event.params?.action === "send") {
+                api.logger?.info("[shroud] blocked message tool send (prevents duplicate delivery)");
+                return { block: true, blockReason: "Response is delivered automatically. Do not use the message tool to send replies." };
+            }
+        }
         // Tool chain depth tracking
         const depth = ob().enterToolCall();
         if (depth > config.maxToolDepth) {
@@ -517,6 +621,15 @@ export function registerHooks(api, obfuscator) {
     // but the final message will be correct.
     const SHROUD_BUF = Symbol("shroudStreamBuf");
     globalThis.__shroudStreamDeobfuscate = (stream, event) => {
+        // Streaming deobfuscation is DISABLED. On OpenClaw 2026.3.24+ with
+        // streaming: off, before_message_write handles all deobfuscation.
+        // The streaming buffer causes text artifacts when fake/real lengths
+        // differ — accumulated partial fakes persist in channel delivery
+        // alongside the corrected final text, producing duplicate content.
+        //
+        // The message_end handler below still runs to deobfuscate the final
+        // content blocks (partial/message), ensuring the delivered message
+        // has real values.
         const isTextDelta = event.type === "text_delta";
         const isMessageUpdateTextDelta = event.type === "message_update" &&
             event.assistantMessageEvent?.type === "text_delta";
@@ -573,8 +686,6 @@ export function registerHooks(api, obfuscator) {
             event.type === "error" || event.type === "agent_end" ||
             (event.type === "message_update" && (event.assistantMessageEvent?.type === "text_end"));
         if (isEnd) {
-            // Deobfuscate content blocks in the event's message/partial
-            // (corrects any partial fakes left from streaming)
             const targets = [
                 event.message, event.partial,
                 event.assistantMessageEvent?.partial,
@@ -585,8 +696,9 @@ export function registerHooks(api, obfuscator) {
                     for (const block of target.content) {
                         if (block?.type === "text" && typeof block.text === "string") {
                             const deob = ob().deobfuscate(block.text);
-                            if (deob !== block.text)
+                            if (deob !== block.text) {
                                 block.text = deob;
+                            }
                         }
                     }
                 }
@@ -600,7 +712,6 @@ export function registerHooks(api, obfuscator) {
                 }
                 catch { /* best-effort */ }
             }
-            // Always dump stats on message_end to capture any counter changes
             dumpStatsFile(obfuscator);
             delete stream[SHROUD_BUF];
         }
@@ -608,7 +719,24 @@ export function registerHooks(api, obfuscator) {
     };
     api.logger?.info("[shroud] Installed global streaming deobfuscation hook");
     // -----------------------------------------------------------------------
-    // 7. Outbound fetch intercept: obfuscate ALL user message content before
+    // 7. Global deobfuscation hook for OpenClaw channel delivery.
+    //    OpenClaw calls this once, in its generic message-delivery function,
+    //    before sending to ANY channel (Slack, WhatsApp, Signal, web, etc.).
+    //    Transparent: if Shroud isn't loaded the global doesn't exist — no-op.
+    //    Works on all past + present releases with a single 3-line patch:
+    //
+    //      const deob = globalThis.__shroudDeobfuscate;
+    //      if (deob && typeof text === 'string') text = deob(text);
+    //
+    // -----------------------------------------------------------------------
+    globalThis.__shroudDeobfuscate = (text) => {
+        if (typeof text !== "string")
+            return text;
+        return ob().deobfuscate(text);
+    };
+    api.logger?.info("[shroud] Registered globalThis.__shroudDeobfuscate for channel delivery");
+    // -----------------------------------------------------------------------
+    // 8. Outbound fetch intercept: obfuscate ALL user message content before
     //    it reaches any LLM API. This is the last line of defense — it works
     //    regardless of which hooks fire, which OpenClaw version is running,
     //    and which LLM provider is used (Anthropic, OpenAI, Google, etc.).
@@ -630,6 +758,7 @@ export function registerHooks(api, obfuscator) {
         "/v1/models/", // Google Vertex AI
     ];
     const originalFetch = globalThis.fetch;
+    api.logger?.info(`[shroud][fetch-guard] hasFetch=${!!originalFetch} patched=${!!globalThis.__shroudFetchPatched}`);
     if (originalFetch && !(globalThis.__shroudFetchPatched)) {
         globalThis.__shroudFetchPatched = true;
         globalThis.fetch = async function shroudFetchInterceptor(input, init) {

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "shroud-privacy",
   "name": "Shroud",
-  "version": "2.1.0",
+  "version": "2.2.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.1.0",
+  "version": "2.2.0",
   "description": "Privacy obfuscation for AI agents — detects PII and replaces with deterministic fake values before anything reaches the LLM. Works with OpenClaw (plugin) or any agent (APP protocol).",
   "type": "module",
   "main": "dist/index.js",