shroud-privacy 2.0.5 → 2.0.7

package/README.md

@@ -17,6 +17,7 @@ Privacy obfuscation plugin for [OpenClaw](https://openclaw.ai). Detects sensitiv
 |------|-----------|-------------|
 | `before_prompt_build` | User → LLM | Obfuscate user prompt, prepend privacy context |
 | `before_message_write` | Any → History | Obfuscate every message written to the session transcript |
+| `before_llm_send` | Context → LLM | Obfuscate LLM messages + install `transformResponse` for deobfuscation (>=2026.3.14) |
 | `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 (WhatsApp, auto-reply, etc.) |
@@ -263,7 +264,7 @@ OpenClaw logs each plugin message twice (once under the plugin subsystem logger,
 
 ```bash
 npm install
-npm test          # run vitest (203 tests)
+npm test          # run vitest (215 tests)
 npm run build     # compile TypeScript
 npm run lint      # type-check without emitting
 ```

package/dist/hooks.d.ts

@@ -1,12 +1,21 @@
 /**
  * OpenClaw lifecycle hooks for the Shroud privacy plugin.
  *
- * Registers 5 hooks:
+ * Registers 6 hooks + 1 transport interceptor (version-adaptive):
  * 1. before_prompt_build   (async) -- obfuscate user prompt via prependContext
  * 2. before_message_write  (SYNC)  -- obfuscate every message written to the session transcript
- * 3. before_tool_call      (async) -- deobfuscate tool params (+ depth tracking)
- * 4. tool_result_persist   (SYNC)  -- obfuscate tool result message
- * 5. message_sending       (async) -- deobfuscate outbound message content
+ * 3. before_llm_send       (async) -- obfuscate LLM messages + install transformResponse (>=2026.3.14)
+ * 4. before_tool_call      (async) -- deobfuscate tool params (+ depth tracking)
+ * 5. tool_result_persist   (SYNC)  -- obfuscate tool result message
+ * 6. message_sending       (async) -- deobfuscate outbound message content
+ * 7. Transport interceptor         -- wraps Slack WebClient.apiCall for universal deobfuscation
+ *
+ * The transport interceptor is the universal fallback: it deobfuscates Slack
+ * messages at the API-call level, independent of which OpenClaw hooks fire.
+ * On >=2026.3.14, transformResponse handles deobfuscation first (for ALL
+ * channels); the transport interceptor is a no-op since the text is already
+ * deobfuscated.  On older versions where message_sending doesn't fire for
+ * Slack, the interceptor catches it.
  */
 import { Obfuscator } from "./obfuscator.js";
 export interface PluginApi {

package/dist/hooks.js

@@ -1,14 +1,24 @@
 /**
  * OpenClaw lifecycle hooks for the Shroud privacy plugin.
  *
- * Registers 5 hooks:
+ * Registers 6 hooks + 1 transport interceptor (version-adaptive):
  * 1. before_prompt_build   (async) -- obfuscate user prompt via prependContext
  * 2. before_message_write  (SYNC)  -- obfuscate every message written to the session transcript
- * 3. before_tool_call      (async) -- deobfuscate tool params (+ depth tracking)
- * 4. tool_result_persist   (SYNC)  -- obfuscate tool result message
- * 5. message_sending       (async) -- deobfuscate outbound message content
+ * 3. before_llm_send       (async) -- obfuscate LLM messages + install transformResponse (>=2026.3.14)
+ * 4. before_tool_call      (async) -- deobfuscate tool params (+ depth tracking)
+ * 5. tool_result_persist   (SYNC)  -- obfuscate tool result message
+ * 6. message_sending       (async) -- deobfuscate outbound message content
+ * 7. Transport interceptor         -- wraps Slack WebClient.apiCall for universal deobfuscation
+ *
+ * The transport interceptor is the universal fallback: it deobfuscates Slack
+ * messages at the API-call level, independent of which OpenClaw hooks fire.
+ * On >=2026.3.14, transformResponse handles deobfuscation first (for ALL
+ * channels); the transport interceptor is a no-op since the text is already
+ * deobfuscated.  On older versions where message_sending doesn't fire for
+ * Slack, the interceptor catches it.
  */
 import { createHash, randomBytes } from "node:crypto";
+import { createRequire } from "node:module";
 import { writeFileSync } from "node:fs";
 import { BUILTIN_PATTERNS } from "./detectors/regex.js";
 const STATS_FILE = process.env.SHROUD_STATS_FILE || "/tmp/shroud-stats.json";
@@ -152,6 +162,74 @@ function walkStrings(value, fn) {
     return value;
 }
 // ---------------------------------------------------------------------------
+// Transport-level deobfuscation interceptor (fallback for all versions)
+// ---------------------------------------------------------------------------
+/**
+ * Wraps the Slack WebClient.prototype.apiCall to deobfuscate outbound message
+ * text before it hits the Slack API.  This is the universal fallback that works
+ * on ANY OpenClaw version — it doesn't depend on hook dispatch at all.
+ *
+ * The @slack/web-api package is CJS and already loaded by OpenClaw, so it lives
+ * in require.cache.  We find it there, wrap the prototype once, done.
+ */
+function installTransportInterceptor(obfuscator, logger) {
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const cache = esmRequire.cache;
+        if (!cache)
+            return;
+        for (const key of Object.keys(cache)) {
+            if (!key.includes("@slack/web-api"))
+                continue;
+            const mod = cache[key];
+            const WebClient = mod?.exports?.WebClient;
+            if (typeof WebClient !== "function")
+                continue;
+            const proto = WebClient.prototype;
+            if (typeof proto.apiCall !== "function")
+                continue;
+            if (proto.__shroudPatched)
+                return; // already wrapped
+            const origApiCall = proto.apiCall;
+            proto.apiCall = async function shroudApiCall(method, options) {
+                if ((method === "chat.postMessage" || method === "chat.update") &&
+                    options) {
+                    // Deobfuscate the plain-text fallback
+                    if (typeof options.text === "string") {
+                        const original = options.text;
+                        const deobfuscated = obfuscator.deobfuscate(original);
+                        if (deobfuscated !== original) {
+                            options = { ...options, text: deobfuscated };
+                            logger?.info(`[shroud][transport] deobfuscated Slack ${method}`);
+                        }
+                    }
+                    // Deobfuscate blocks (rich text) — walk all text elements
+                    if (Array.isArray(options.blocks)) {
+                        const json = JSON.stringify(options.blocks);
+                        const deobJson = obfuscator.deobfuscate(json);
+                        if (deobJson !== json) {
+                            try {
+                                options = { ...options, blocks: JSON.parse(deobJson) };
+                            }
+                            catch {
+                                // If JSON parse fails, leave blocks unchanged
+                            }
+                        }
+                    }
+                }
+                return origApiCall.call(this, method, options);
+            };
+            proto.__shroudPatched = true;
+            logger?.info("[shroud] Installed Slack transport interceptor (universal deobfuscation fallback)");
+            return;
+        }
+        logger?.info("[shroud] Slack WebClient not found in require.cache — transport interceptor not installed (hooks-only mode)");
+    }
+    catch (err) {
+        logger?.warn(`[shroud] Failed to install transport interceptor: ${String(err)}`);
+    }
+}
+// ---------------------------------------------------------------------------
 // Hook registration
 // ---------------------------------------------------------------------------
 export function registerHooks(api, obfuscator) {
@@ -239,7 +317,57 @@ export function registerHooks(api, obfuscator) {
         }
     });
     // -----------------------------------------------------------------------
-    // 3. before_tool_call (async): deobfuscate tool params + track depth
+    // 3. before_llm_send (async): obfuscate LLM context + install transformResponse
+    //    Available on OpenClaw >=2026.3.14. Silently ignored on older versions.
+    //    This is the most reliable deobfuscation path — transformResponse catches
+    //    ALL LLM output text including streaming deltas.
+    // -----------------------------------------------------------------------
+    api.on("before_llm_send", async (event) => {
+        const messages = event?.messages;
+        if (!Array.isArray(messages))
+            return;
+        // Obfuscate all string content in the message array
+        let totalEntities = 0;
+        const obfuscatedMessages = messages.map((msg) => {
+            if (!msg || typeof msg !== "object")
+                return msg;
+            const walked = walkStrings(msg.content, (s) => {
+                const result = obfuscator.obfuscate(s);
+                totalEntities += result.entities.length;
+                return result.obfuscated;
+            });
+            if (walked === msg.content)
+                return msg;
+            return { ...msg, content: walked };
+        });
+        if (totalEntities > 0) {
+            dumpStatsFile(obfuscator);
+            api.logger?.info(`[shroud] before_llm_send: obfuscated ${totalEntities} entities in ${messages.length} messages`);
+        }
+        // Install transformResponse — this deobfuscates LLM output text.
+        // It's a synchronous function called on every response chunk.
+        const requestId = randomBytes(8).toString("hex");
+        const transformResponse = (text) => {
+            if (auditActive) {
+                const { text: deobfuscated, replacementCount } = obfuscator.deobfuscateWithStats(text);
+                if (deobfuscated !== text) {
+                    try {
+                        emitDeobfuscationAudit(api.logger, config, requestId, replacementCount);
+                    }
+                    catch { /* best-effort */ }
+                    dumpStatsFile(obfuscator);
+                }
+                return deobfuscated;
+            }
+            return obfuscator.deobfuscate(text);
+        };
+        return {
+            messages: totalEntities > 0 ? obfuscatedMessages : undefined,
+            transformResponse,
+        };
+    });
+    // -----------------------------------------------------------------------
+    // 4. before_tool_call (async): deobfuscate tool params + track depth
     // -----------------------------------------------------------------------
     api.on("before_tool_call", async (event) => {
         if (!event?.params || typeof event.params !== "object")
@@ -265,7 +393,7 @@ export function registerHooks(api, obfuscator) {
         }
     });
     // -----------------------------------------------------------------------
-    // 4. tool_result_persist (SYNC): obfuscate tool result message
+    // 5. tool_result_persist (SYNC): obfuscate tool result message
     // -----------------------------------------------------------------------
     api.on("tool_result_persist", (event) => {
         if (!event?.message)
@@ -280,7 +408,8 @@ export function registerHooks(api, obfuscator) {
         return { message: obfuscated };
     });
     // -----------------------------------------------------------------------
-    // 5. message_sending (async): deobfuscate outbound message content
+    // 6. message_sending (async): deobfuscate outbound message content
+    //    Fallback for versions without before_llm_send/transformResponse.
     // -----------------------------------------------------------------------
     api.on("message_sending", async (event) => {
         if (typeof event?.content !== "string")
@@ -345,4 +474,10 @@ export function registerHooks(api, obfuscator) {
             return { content: [{ type: "text", text: lines.join("\n") }] };
         },
     });
+    // -----------------------------------------------------------------------
+    // 7. Transport interceptor: universal deobfuscation fallback
+    //    Wraps Slack WebClient.apiCall so outbound messages are deobfuscated
+    //    regardless of which OpenClaw hooks fire (or don't).
+    // -----------------------------------------------------------------------
+    installTransportInterceptor(obfuscator, api.logger);
 }

package/dist/obfuscator.js

@@ -78,6 +78,21 @@ function compressIPv6(addr) {
     }
     return groups.join(":");
 }
+/**
+ * Strip Slack/chat mrkdwn link formatting to recover plain text.
+ * Slack wraps emails as `<mailto:X|DISPLAY>` and URLs as `<URL|DISPLAY>`,
+ * which splits entities across tag boundaries and breaks regex detection.
+ * This converts display-text links back to their visible form.
+ */
+function stripSlackLinks(text) {
+    // <mailto:X|DISPLAY> → DISPLAY  (email links)
+    text = text.replace(/<mailto:[^|>]+\|([^>]*)>/g, "$1");
+    // <URL|DISPLAY> → DISPLAY       (URL links with display text)
+    text = text.replace(/<https?:\/\/[^|>]+\|([^>]*)>/g, "$1");
+    // <URL> → URL                    (bare URL links, no display text)
+    text = text.replace(/<(https?:\/\/[^>]+)>/g, "$1");
+    return text;
+}
 /**
  * Build a single combined regex from an array of literal strings.
  * Strings are escaped and joined with alternation (|), sorted longest-first
@@ -197,6 +212,10 @@ export class Obfuscator {
      */
     obfuscate(text, context) {
         const startTime = Date.now();
+        // 0. Strip Slack/chat mrkdwn link formatting so detection sees clean text.
+        //    Slack wraps emails as <mailto:X|DISPLAY> and URLs as <URL|DISPLAY>,
+        //    which splits entities across tag boundaries and breaks regex matching.
+        text = stripSlackLinks(text);
         // 1. Learn subnet context from CIDR notation and masks in text
         this._subnetMapper.learnSubnetsFromText(text);
         // 2. Detect all entities from all detectors

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "shroud-privacy",
   "name": "Shroud",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "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.0.5",
+  "version": "2.0.7",
   "description": "Privacy obfuscation plugin for OpenClaw — detects sensitive data and replaces with deterministic fake values",
   "type": "module",
   "main": "dist/index.js",