shroud-privacy 2.0.3 → 2.0.5

package/README.md

@@ -16,11 +16,10 @@ Privacy obfuscation plugin for [OpenClaw](https://openclaw.ai). Detects sensitiv
 | Hook | Direction | What happens |
 |------|-----------|-------------|
 | `before_prompt_build` | User → LLM | Obfuscate user prompt, prepend privacy context |
-| `before_llm_send` | User → LLM | Obfuscate all messages + install `transformResponse` |
-| `transformResponse` | LLM → User | Deobfuscate LLM output (auto-reply, WhatsApp, etc.) |
+| `before_message_write` | Any → History | Obfuscate every message written to the session transcript |
 | `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 (fallback path) |
+| `message_sending` | Agent → User | Deobfuscate outbound messages (WhatsApp, auto-reply, etc.) |
 
 ## Install
 
@@ -232,13 +231,13 @@ tail -f ~/.openclaw/logs/openclaw.log \
 You should see:
 
 ```
-[shroud][audit] OBFUSCATE req=dc5f9199cfb0d835 | entities=4 | touched=2/5 | blocks=2 | chars=1200->1218 (delta=+18) | modified=YES | byCat=email:1,ip_address:2,hostname:1
+[shroud][audit] OBFUSCATE req=dc5f9199cfb0d835 | entities=4 | chars=1200->1218 (delta=+18) | modified=YES | byCat=email:1,ip_address:2,hostname:1 | byRule=regex:email:1,regex:ipv4:2,regex:hostname:1
 ```
 
 With proof hashes enabled:
 
 ```
-[shroud][audit] OBFUSCATE req=a3f1bc9e02d4e7f1 | entities=4 | touched=2/5 | blocks=2 | chars=1200->1218 (delta=+18) | modified=YES | byCat=email:1,ip_address:2,hostname:1 | proof_in=8a3c1f0e2b4d proof_out=f7d2a1c9e084 | fakes=[jsmith@corp.net|100.64.0.12|SW-LAB-01]
+[shroud][audit] OBFUSCATE req=a3f1bc9e02d4e7f1 | entities=4 | chars=1200->1218 (delta=+18) | modified=YES | byCat=email:1,ip_address:2,hostname:1 | byRule=regex:email:1,regex:ipv4:2,regex:hostname:1 | proof_in=8a3c1f0e2b4d proof_out=f7d2a1c9e084 | fakes=[jsmith@corp.net|100.64.0.12|SW-LAB-01]
 ```
 
 ### Audit field reference
@@ -247,16 +246,14 @@ With proof hashes enabled:
 |-------|---------|
 | `req` | Random request ID (hex) — correlates obfuscate ↔ deobfuscate |
 | `entities` | Total entities detected and replaced |
-| `touched` | Messages with replacements / total messages |
-| `blocks` | Content blocks with replacements |
 | `chars` | Input → output character count |
 | `delta` | Character count change (fakes may be longer/shorter) |
 | `modified` | `YES` if text was changed, `NO` if pass-through |
 | `byCat` | Entity counts by category |
 | `byRule` | Entity counts by detector rule |
-| `proof_in` | Truncated salted SHA-256 of input text |
-| `proof_out` | Truncated salted SHA-256 of output text |
-| `fakes` | Sample of fake replacement values (never real values) |
+| `proof_in` | Truncated salted SHA-256 of input text (opt-in) |
+| `proof_out` | Truncated salted SHA-256 of output text (opt-in) |
+| `fakes` | Sample of fake replacement values (opt-in, never real values) |
 
 ### Note on log duplication
 
@@ -266,7 +263,7 @@ OpenClaw logs each plugin message twice (once under the plugin subsystem logger,
 
 ```bash
 npm install
-npm test          # run vitest (210 tests)
+npm test          # run vitest (203 tests)
 npm run build     # compile TypeScript
 npm run lint      # type-check without emitting
 ```

package/dist/hooks.d.ts

@@ -2,11 +2,11 @@
  * OpenClaw lifecycle hooks for the Shroud privacy plugin.
  *
  * Registers 5 hooks:
- * 1. before_prompt_build  (async) -- obfuscate user prompt via prependContext
- * 2. before_llm_send     (async) -- obfuscate LLM input messages + return transformResponse for deobfuscation
- * 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 (fallback)
+ * 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
  */
 import { Obfuscator } from "./obfuscator.js";
 export interface PluginApi {

package/dist/hooks.js

@@ -2,11 +2,11 @@
  * OpenClaw lifecycle hooks for the Shroud privacy plugin.
  *
  * Registers 5 hooks:
- * 1. before_prompt_build  (async) -- obfuscate user prompt via prependContext
- * 2. before_llm_send     (async) -- obfuscate LLM input messages + return transformResponse for deobfuscation
- * 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 (fallback)
+ * 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
  */
 import { createHash, randomBytes } from "node:crypto";
 import { writeFileSync } from "node:fs";
@@ -37,205 +37,77 @@ function truncateHash(hash, n) {
     return hash.slice(0, n);
 }
 // ---------------------------------------------------------------------------
-// String walking helper
+// Audit log emitter — per-message (used by before_message_write)
 // ---------------------------------------------------------------------------
-/**
- * Deep-walk an unknown message structure and obfuscate/deobfuscate all
- * string leaves.  OpenClaw message payloads can be a plain string, an
- * array of content blocks, or a nested object — this handles all three.
- */
-function walkStrings(value, fn) {
-    if (typeof value === "string")
-        return fn(value);
-    if (Array.isArray(value)) {
-        return value.map((item) => {
-            if (typeof item === "object" && item !== null && "text" in item && typeof item.text === "string") {
-                return { ...item, text: fn(item.text) };
-            }
-            return walkStrings(item, fn);
-        });
-    }
-    if (typeof value === "object" && value !== null) {
-        const out = {};
-        for (const [k, v] of Object.entries(value)) {
-            if (typeof v === "string") {
-                out[k] = fn(v);
-            }
-            else {
-                out[k] = v; // don't recurse arbitrarily into unknown objects
-            }
-        }
-        return out;
+function emitObfuscationAudit(logger, config, requestId, result, inputText, outputText) {
+    const byCat = {};
+    const byRule = {};
+    for (const e of result.entities) {
+        byCat[e.category] = (byCat[e.category] || 0) + 1;
+        byRule[e.detector] = (byRule[e.detector] || 0) + 1;
     }
-    return value;
-}
-// ---------------------------------------------------------------------------
-// obfuscateMessages (original, no stats)
-// ---------------------------------------------------------------------------
-function obfuscateMessages(messages, obfuscator) {
-    return messages.map((msg) => {
-        if (!msg || typeof msg !== "object")
-            return msg;
-        if (typeof msg.content === "string") {
-            const result = obfuscator.obfuscate(msg.content);
-            if (result.entities.length === 0)
-                return msg;
-            return { ...msg, content: result.obfuscated };
-        }
-        if (Array.isArray(msg.content)) {
-            const newContent = msg.content.map((block) => {
-                if (block && typeof block === "object" && typeof block.text === "string") {
-                    const result = obfuscator.obfuscate(block.text);
-                    if (result.entities.length === 0)
-                        return block;
-                    return { ...block, text: result.obfuscated };
-                }
-                return block;
-            });
-            return { ...msg, content: newContent };
-        }
-        return msg;
-    });
-}
-// ---------------------------------------------------------------------------
-// obfuscateMessagesWithStats (audit-aware)
-// ---------------------------------------------------------------------------
-function obfuscateMessagesWithStats(messages, obfuscator, config) {
-    const stats = {
-        totalEntities: 0,
-        byCategory: {},
-        byRule: {},
-        messagesTouched: 0,
-        blocksTouched: 0,
-        inputChars: 0,
-        outputChars: 0,
-        fakesSample: [],
-    };
-    const maxFakes = config.auditMaxFakesSample;
-    const obfuscatedMessages = messages.map((msg) => {
-        if (!msg || typeof msg !== "object")
-            return msg;
-        if (typeof msg.content === "string") {
-            const result = obfuscator.obfuscate(msg.content);
-            stats.inputChars += msg.content.length;
-            stats.outputChars += result.obfuscated.length;
-            if (result.entities.length > 0) {
-                stats.messagesTouched++;
-                stats.blocksTouched++;
-                accumulateStats(stats, result, maxFakes);
-            }
-            if (result.entities.length === 0)
-                return msg;
-            return { ...msg, content: result.obfuscated };
-        }
-        if (Array.isArray(msg.content)) {
-            let msgTouched = false;
-            const newContent = msg.content.map((block) => {
-                if (block && typeof block === "object" && typeof block.text === "string") {
-                    const result = obfuscator.obfuscate(block.text);
-                    stats.inputChars += block.text.length;
-                    stats.outputChars += result.obfuscated.length;
-                    if (result.entities.length > 0) {
-                        msgTouched = true;
-                        stats.blocksTouched++;
-                        accumulateStats(stats, result, maxFakes);
-                    }
-                    if (result.entities.length === 0)
-                        return block;
-                    return { ...block, text: result.obfuscated };
-                }
-                return block;
-            });
-            if (msgTouched)
-                stats.messagesTouched++;
-            return { ...msg, content: newContent };
-        }
-        return msg;
-    });
-    return { messages: obfuscatedMessages, stats };
-}
-function accumulateStats(stats, result, maxFakes) {
-    for (const entity of result.entities) {
-        stats.totalEntities++;
-        stats.byCategory[entity.category] = (stats.byCategory[entity.category] || 0) + 1;
-        stats.byRule[entity.detector] = (stats.byRule[entity.detector] || 0) + 1;
+    const modified = result.entities.length > 0;
+    const charDelta = outputText.length - inputText.length;
+    let proofIn = "";
+    let proofOut = "";
+    if (config.auditIncludeProofHashes) {
+        proofIn = truncateHash(safeHash(inputText, config.auditHashSalt), config.auditHashTruncate);
+        proofOut = truncateHash(safeHash(outputText, config.auditHashSalt), config.auditHashTruncate);
     }
-    // Collect fake values only (never real values)
-    if (maxFakes > 0 && stats.fakesSample.length < maxFakes) {
+    const fakesSample = [];
+    if (config.auditMaxFakesSample > 0) {
         for (const fake of Object.values(result.mappingsUsed)) {
-            if (stats.fakesSample.length >= maxFakes)
+            if (fakesSample.length >= config.auditMaxFakesSample)
                 break;
-            stats.fakesSample.push(fake);
+            fakesSample.push(fake);
         }
     }
-}
-// ---------------------------------------------------------------------------
-// Audit log emitters
-// ---------------------------------------------------------------------------
-function emitAuditLog(logger, config, requestId, stats, totalMessages, concatenatedOriginal, concatenatedObfuscated) {
-    const byCatStr = Object.entries(stats.byCategory)
-        .map(([k, v]) => `${k}:${v}`)
-        .join(",");
-    const byRuleStr = Object.entries(stats.byRule)
-        .map(([k, v]) => `${k}:${v}`)
-        .join(",");
-    const modified = stats.inputChars !== stats.outputChars || stats.totalEntities > 0;
-    const charDelta = stats.outputChars - stats.inputChars;
-    // Always compute proof hashes when proofs enabled
-    let proofHashIn = "";
-    let proofHashOut = "";
-    if (config.auditIncludeProofHashes) {
-        proofHashIn = truncateHash(safeHash(concatenatedOriginal, config.auditHashSalt), config.auditHashTruncate);
-        proofHashOut = truncateHash(safeHash(concatenatedObfuscated, config.auditHashSalt), config.auditHashTruncate);
-    }
     if (config.auditLogFormat === "json") {
         const obj = {
-            event: "shroud.audit.before_llm_send",
+            event: "shroud.audit.obfuscate",
             req: requestId,
             ts: new Date().toISOString(),
             modified,
-            totalEntities: stats.totalEntities,
-            messagesTouched: stats.messagesTouched,
-            blocksTouched: stats.blocksTouched,
-            inputChars: stats.inputChars,
-            outputChars: stats.outputChars,
+            totalEntities: result.entities.length,
+            inputChars: inputText.length,
+            outputChars: outputText.length,
             charDelta,
-            byCategory: stats.byCategory,
-            byRule: stats.byRule,
+            byCategory: byCat,
+            byRule,
         };
         if (config.auditIncludeProofHashes) {
-            obj.proofIn = proofHashIn;
-            obj.proofOut = proofHashOut;
+            obj.proofIn = proofIn;
+            obj.proofOut = proofOut;
         }
-        if (config.auditMaxFakesSample > 0 && stats.fakesSample.length > 0) {
-            obj.fakesSample = stats.fakesSample;
+        if (fakesSample.length > 0) {
+            obj.fakesSample = fakesSample;
         }
         logger?.info(JSON.stringify(obj));
     }
     else {
+        const byCatStr = Object.entries(byCat).map(([k, v]) => `${k}:${v}`).join(",");
+        const byRuleStr = Object.entries(byRule).map(([k, v]) => `${k}:${v}`).join(",");
         const parts = [
             `[shroud][audit] OBFUSCATE req=${requestId}`,
-            `entities=${stats.totalEntities}`,
-            `touched=${stats.messagesTouched}/${totalMessages}`,
-            `blocks=${stats.blocksTouched}`,
-            `chars=${stats.inputChars}->${stats.outputChars} (delta=${charDelta >= 0 ? "+" : ""}${charDelta})`,
+            `entities=${result.entities.length}`,
+            `chars=${inputText.length}->${outputText.length} (delta=${charDelta >= 0 ? "+" : ""}${charDelta})`,
             `modified=${modified ? "YES" : "NO"}`,
             `byCat=${byCatStr || "none"}`,
             `byRule=${byRuleStr || "none"}`,
         ];
         if (config.auditIncludeProofHashes) {
-            parts.push(`proof_in=${proofHashIn} proof_out=${proofHashOut}`);
+            parts.push(`proof_in=${proofIn} proof_out=${proofOut}`);
         }
-        if (config.auditMaxFakesSample > 0 && stats.fakesSample.length > 0) {
-            parts.push(`fakes=[${stats.fakesSample.join("|")}]`);
+        if (fakesSample.length > 0) {
+            parts.push(`fakes=[${fakesSample.join("|")}]`);
         }
         logger?.info(parts.join(" | "));
     }
 }
-function emitDeobfuscationAuditLog(logger, config, requestId, replacementCount) {
+function emitDeobfuscationAudit(logger, config, requestId, replacementCount) {
     if (config.auditLogFormat === "json") {
         logger?.info(JSON.stringify({
-            event: "shroud.audit.deobfuscation",
+            event: "shroud.audit.deobfuscate",
             req: requestId,
             ts: new Date().toISOString(),
             modified: replacementCount > 0,
@@ -247,6 +119,39 @@ function emitDeobfuscationAuditLog(logger, config, requestId, replacementCount)
     }
 }
 // ---------------------------------------------------------------------------
+// String walking helper
+// ---------------------------------------------------------------------------
+/**
+ * Deep-walk an unknown message structure and obfuscate/deobfuscate all
+ * string leaves.  OpenClaw message payloads can be a plain string, an
+ * array of content blocks, or a nested object — this handles all three.
+ */
+function walkStrings(value, fn) {
+    if (typeof value === "string")
+        return fn(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => {
+            if (typeof item === "object" && item !== null && "text" in item && typeof item.text === "string") {
+                return { ...item, text: fn(item.text) };
+            }
+            return walkStrings(item, fn);
+        });
+    }
+    if (typeof value === "object" && value !== null) {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (typeof v === "string") {
+                out[k] = fn(v);
+            }
+            else {
+                out[k] = v; // don't recurse arbitrarily into unknown objects
+            }
+        }
+        return out;
+    }
+    return value;
+}
+// ---------------------------------------------------------------------------
 // Hook registration
 // ---------------------------------------------------------------------------
 export function registerHooks(api, obfuscator) {
@@ -256,6 +161,11 @@ export function registerHooks(api, obfuscator) {
     // 1. before_prompt_build (async): obfuscate user prompt
     // -----------------------------------------------------------------------
     api.on("before_prompt_build", async (event) => {
+        // Reset tool depth at the start of each turn — tool calls from the
+        // previous turn are complete, so the counter should not carry over.
+        if (obfuscator.toolDepth > 0) {
+            obfuscator.resetToolDepth();
+        }
         const prompt = event?.prompt;
         if (typeof prompt !== "string" || !prompt)
             return;
@@ -276,87 +186,57 @@ export function registerHooks(api, obfuscator) {
         };
     });
     // -----------------------------------------------------------------------
-    // 2. before_llm_send (async): obfuscate LLM input + provide response deobfuscator
+    // 2. before_message_write (SYNC): obfuscate every message written to session
+    //    This ensures the LLM always sees obfuscated history, even on platforms
+    //    that don't support before_llm_send.
     // -----------------------------------------------------------------------
-    api.on("before_llm_send", async (event) => {
-        if (!Array.isArray(event?.messages))
+    api.on("before_message_write", (event) => {
+        if (!event?.message || typeof event.message !== "object")
             return;
-        // Reset tool depth at the start of each LLM turn — tool calls from the
-        // previous turn are complete, so the counter should not carry over.
-        if (obfuscator.toolDepth > 0) {
-            obfuscator.resetToolDepth();
-        }
-        const totalMessages = event.messages.length;
-        let obfuscatedMessages;
-        let requestId = "";
-        if (auditActive) {
-            requestId = randomBytes(8).toString("hex");
-            const { messages: msgs, stats } = obfuscateMessagesWithStats(event.messages, obfuscator, config);
-            obfuscatedMessages = msgs;
-            // Build concatenated texts for proof hashes
-            let concatenatedOriginal = "";
-            let concatenatedObfuscated = "";
-            if (config.auditIncludeProofHashes) {
-                for (let i = 0; i < event.messages.length; i++) {
-                    const orig = event.messages[i];
-                    const obf = obfuscatedMessages[i];
-                    if (typeof orig?.content === "string") {
-                        concatenatedOriginal += orig.content;
-                        concatenatedObfuscated += (obf?.content ?? "");
-                    }
-                    else if (Array.isArray(orig?.content)) {
-                        for (let j = 0; j < orig.content.length; j++) {
-                            const origBlock = orig.content[j];
-                            const obfBlock = obf?.content?.[j];
-                            if (typeof origBlock?.text === "string") {
-                                concatenatedOriginal += origBlock.text;
-                                concatenatedObfuscated += (obfBlock?.text ?? "");
-                            }
-                        }
-                    }
+        const msg = event.message;
+        // Obfuscate string content
+        if (typeof msg.content === "string") {
+            const result = obfuscator.obfuscate(msg.content);
+            if (result.entities.length === 0)
+                return;
+            dumpStatsFile(obfuscator);
+            if (auditActive) {
+                try {
+                    emitObfuscationAudit(api.logger, config, randomBytes(8).toString("hex"), result, msg.content, result.obfuscated);
                 }
+                catch { /* best-effort */ }
             }
-            try {
-                emitAuditLog(api.logger, config, requestId, stats, totalMessages, concatenatedOriginal, concatenatedObfuscated);
-            }
-            catch {
-                // Logging is best-effort
-            }
-        }
-        else {
-            obfuscatedMessages = obfuscateMessages(event.messages, obfuscator);
+            return { message: { ...msg, content: result.obfuscated } };
         }
-        dumpStatsFile(obfuscator);
-        api.logger?.info("[shroud] before_llm_send: obfuscated messages + installed transformResponse");
-        const capturedReqId = requestId;
-        return {
-            messages: obfuscatedMessages,
-            transformResponse: (text) => {
-                if (auditActive) {
-                    try {
-                        const { text: deobfuscated, replacementCount } = obfuscator.deobfuscateWithStats(text);
-                        if (replacementCount > 0) {
-                            try {
-                                emitDeobfuscationAuditLog(api.logger, config, capturedReqId, replacementCount);
-                            }
-                            catch {
-                                // best-effort
-                            }
-                        }
-                        dumpStatsFile(obfuscator);
-                        return deobfuscated;
+        // Obfuscate array-of-blocks content
+        if (Array.isArray(msg.content)) {
+            let changed = false;
+            const allResults = [];
+            const newContent = msg.content.map((block) => {
+                if (block && typeof block === "object" && typeof block.text === "string") {
+                    const result = obfuscator.obfuscate(block.text);
+                    if (result.entities.length > 0) {
+                        changed = true;
+                        allResults.push(result);
+                        return { ...block, text: result.obfuscated };
                     }
-                    catch {
-                        const result = obfuscator.deobfuscate(text);
-                        dumpStatsFile(obfuscator);
-                        return result;
+                }
+                return block;
+            });
+            if (!changed)
+                return;
+            dumpStatsFile(obfuscator);
+            if (auditActive) {
+                for (const result of allResults) {
+                    try {
+                        const origText = Object.keys(result.mappingsUsed).join(" ");
+                        emitObfuscationAudit(api.logger, config, randomBytes(8).toString("hex"), result, origText, result.obfuscated);
                     }
+                    catch { /* best-effort */ }
                 }
-                const result = obfuscator.deobfuscate(text);
-                dumpStatsFile(obfuscator);
-                return result;
-            },
-        };
+            }
+            return { message: { ...msg, content: newContent } };
+        }
     });
     // -----------------------------------------------------------------------
     // 3. before_tool_call (async): deobfuscate tool params + track depth
@@ -405,6 +285,17 @@ export function registerHooks(api, obfuscator) {
     api.on("message_sending", async (event) => {
         if (typeof event?.content !== "string")
             return;
+        if (auditActive) {
+            const { text: deobfuscated, replacementCount } = obfuscator.deobfuscateWithStats(event.content);
+            if (deobfuscated === event.content)
+                return;
+            try {
+                emitDeobfuscationAudit(api.logger, config, randomBytes(8).toString("hex"), replacementCount);
+            }
+            catch { /* best-effort */ }
+            dumpStatsFile(obfuscator);
+            return { content: deobfuscated };
+        }
         const deobfuscated = obfuscator.deobfuscate(event.content);
         if (deobfuscated === event.content)
             return;

package/openclaw.plugin.json

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