shroud-privacy 2.2.9 → 2.2.11

package/README.md

@@ -77,16 +77,16 @@ 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.24 or later.**
+> **Requires OpenClaw 2026.3.22 or later.**
 
 ---
 
 ## Install
 
-### OpenClaw (2026.3.24+)
+### OpenClaw (2026.3.22+)
 
 ```bash
-openclaw --version    # ensure 2026.3.24+
+openclaw --version    # ensure 2026.3.22+
 openclaw plugins install shroud-privacy
 ```
 
@@ -127,7 +127,7 @@ node node_modules/shroud-privacy/app-server.mjs node_modules/shroud-privacy/dist
 
 Handshake (server writes on startup):
 ```json
-{"app":"1.0","engine":"shroud","version":"2.2.7","capabilities":["obfuscate","deobfuscate","batch","stats","health","configure","audit","partitions"]}
+{"app":"1.0","engine":"shroud","version":"2.2.9","capabilities":["obfuscate","deobfuscate","batch","stats","health","configure","audit","partitions"]}
 ```
 
 Obfuscate:
@@ -288,7 +288,7 @@ Shroud includes a `ContextDetector` that wraps the regex engine with post-detect
 
 - **Context-aware boosting**: Text blocks containing config keywords (`interface`, `router ospf`, `hostname`) get +10% confidence for detected entities.
 - **Proximity clustering**: When a name, email, and phone appear within 200 characters, each gets a confidence boost.
-- **Hostname propagation**: `hostname FCNETR1` in one place → bare `FCNETR1` detected everywhere in the text.
+- **Hostname propagation**: `hostname CORE-RTR-01` in one place → bare `CORE-RTR-01` detected everywhere in the text.
 - **Learned entities**: Hostnames and infra identifiers seen in previous messages are remembered and detected in future messages without requiring config-line context.
 - **Documentation filtering**: RFC 3849 IPv6 doc prefix (`2001:db8::/32`), IPv6 loopback (`::1`), `example.com` emails, and well-known placeholders are automatically skipped.
 - **DNS-based URL classification**: External URLs pass through to the LLM; internal URLs are obfuscated. See [URL handling](#url-handling).
@@ -406,14 +406,36 @@ client.stop()
 
 ```bash
 npm install
-npm test          # all 3 suites: unit + harness + openclaw
-npm run test:unit      # vitest (819 tests)
-npm run test:integration  # APP harness (359 tests)
-npm run test:openclaw  # OpenClaw sandbox (14 tests)
-npm run build     # compile TypeScript
-npm run lint      # type-check without emitting
+npm run build               # compile TypeScript
+npm run lint                # type-check without emitting
+npm test                    # unit + harness (1,229 tests, no Docker)
+npm run test:docker         # Docker E2E — real OpenClaw, all channels (192 tests)
+npm run test:all            # everything (1,421 tests)
 ```
 
+### Test layers
+
+| Layer | Command | Tests | What it covers |
+|-------|---------|-------|---------------|
+| Unit | `npm run test:unit` | 870 | Obfuscator, detectors, generators, store, config |
+| APP Harness | `npm run test:integration` | 359 | 48 scenario files via mock LLM, no OpenClaw |
+| Docker E2E | `npm run test:docker` | 192 | Real OpenClaw gateway, Slack/WhatsApp/Cron/TUI channels, 153 regression scenarios |
+| Sandbox E2E | `run-compat.sh <ver> --sandbox` | +8 | Docker-in-Docker, sandboxed agent exec, tool call deobfuscation |
+
+Docker E2E runs inside an isolated container (`--internal` network, no external routing). Both OpenClaw and Shroud are installed from npm — the same path real users take. A single gateway process handles all tests via WebSocket RPC. Channel tests use mock servers with real SDK code paths (Slack via Bolt HTTP, WhatsApp via Baileys intercept).
+
+### OpenClaw compatibility matrix
+
+```bash
+bash compat/run-compat.sh latest           # test against latest OpenClaw
+bash compat/run-compat.sh latest --sandbox # include sandboxed agent exec tests
+bash compat/run-matrix.sh                  # interactive: current or current + last 3
+bash compat/run-matrix.sh --latest 3       # latest 3 versions
+bash compat/run-matrix.sh --parallel       # parallel execution
+```
+
+Supported versions are tracked in `compat/versions.json`. CI checks for new OpenClaw releases daily.
+
 ---
 
 ## Disclaimer

package/dist/agent-session.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Agent session tracking — maps LLM API calls to local agent identities.
+ *
+ * Each agent has a unique identity derived from its system prompt, plugin set,
+ * and model. This module tracks which agent is making each LLM call, enabling:
+ * - Per-agent WAF rules (different injection policies per agent)
+ * - Per-agent behavioural baselines (Track 3)
+ * - Per-agent canary attribution (Track 2)
+ * - Multi-agent session correlation
+ */
+/** A logged LLM API call. */
+export interface LlmCallRecord {
+    timestamp: number;
+    agentLabel: string;
+    url: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    cacheHitPct: number;
+    responseTimeMs: number;
+    channel: string;
+    securityEvents: number;
+    /** Why the call was made (slack message, heartbeat, cron, tool call, etc.) */
+    reason: string;
+}
+/** Agent role classification derived from name, channel, and behaviour. */
+export interface AgentClassification {
+    /** Primary role category. */
+    role: string;
+    /** Confidence percentage (0-100). */
+    confidencePct: number;
+    /** Confidence tier for display. */
+    confidence: "high" | "medium" | "low";
+    /** Colour code for dashboard rendering. */
+    colour: string;
+    /** Keywords that triggered the classification. */
+    signals: string[];
+}
+/** Agent health and behavioural compliance status. */
+export interface AgentHealth {
+    /** Overall health: "healthy", "warning", "critical". */
+    status: "healthy" | "warning" | "critical";
+    /** Health colour for dashboard. */
+    colour: string;
+    /** Is the agent behaving according to its classification? */
+    compliant: boolean;
+    /** Compliance detail messages. */
+    issues: string[];
+    /** Last active relative indicator. */
+    lastActiveAgo: string;
+    /** Security event rate per 100 calls. */
+    eventRate: number;
+}
+/** Represents a tracked agent session. */
+export interface AgentSession {
+    /** Stable identity hash: SHA256(systemPrompt + pluginList + modelId). */
+    agentBuildId: string;
+    /** Human-readable label extracted from system prompt (first 60 chars). */
+    agentLabel: string;
+    /** Session-scoped unique ID. */
+    sessionId: string;
+    /** When this session was first seen. */
+    startedAt: number;
+    /** Total LLM API calls made by this agent session. */
+    llmCallCount: number;
+    /** Total security events attributed to this agent. */
+    securityEventCount: number;
+    /** Last LLM call timestamp. */
+    lastCallAt: number;
+    /** LLM model ID detected from API calls (e.g. "claude-3-opus", "gpt-4"). */
+    detectedModel: string;
+    /** Channel source if detected (e.g. "slack:C00000001", "whatsapp:+353..."). */
+    channelSource: string;
+    /** Inferred role classification. */
+    classification: AgentClassification;
+    /** Tool names available to the agent (from body.tools). */
+    toolInventory: string[];
+    /** SOUL.md extract — agent's core identity/instructions from early messages. */
+    soulExtract: string;
+    /** Per-agent LLM cache stats. */
+    cache: AgentCacheStats;
+    /** Active channels this agent has been seen on. */
+    channels: string[];
+    /** Heartbeat tracking. */
+    heartbeat: AgentHeartbeat;
+}
+/** Per-agent heartbeat tracking. */
+export interface AgentHeartbeat {
+    /** Whether heartbeat has been detected for this agent. */
+    enabled: boolean;
+    /** Timestamps of recent heartbeats (last 10). */
+    recent: number[];
+    /** Average interval between heartbeats (ms). -1 if not enough data. */
+    avgIntervalMs: number;
+    /** Last heartbeat timestamp. */
+    lastAt: number;
+    /** Status: "alive", "stale" (2x interval missed), "dead" (5x missed). */
+    status: "alive" | "stale" | "dead" | "unknown";
+    /** Last heartbeat response (HEARTBEAT_OK or alert text). */
+    lastResponse: string;
+}
+/** Per-agent LLM cache tracking for anomaly detection. */
+export interface AgentCacheStats {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCacheRead: number;
+    totalCacheWrite: number;
+    /** Running average cache hit ratio (0-1). */
+    avgHitRatio: number;
+    /** Baseline hit ratio (from first N calls). -1 if not established. */
+    baselineHitRatio: number;
+    /** Number of calls contributing to the baseline. */
+    baselineSamples: number;
+    /** Number of calls with cache data. */
+    callsWithCache: number;
+}
+/**
+ * Tracks agent sessions and maps LLM calls to agent identities.
+ * One instance shared via globalThis across all plugin loads.
+ */
+export declare class AgentSessionTracker {
+    /** Active sessions keyed by agent label (the stable identity). */
+    private _sessions;
+    /** Current active agent label. */
+    private _currentLabel;
+    /** LLM call log (ring buffer, last 200 calls). */
+    private _callLog;
+    /** Timestamp when the current LLM call started (for response time). */
+    private _callStartTime;
+    /**
+     * Register or update an agent session from system prompt content.
+     *
+     * Identity strategy: the extracted LABEL is the primary key, not the
+     * prompt skeleton hash. System prompts contain too much dynamic content
+     * (conversation context, RAG, tool results) to produce stable hashes.
+     * The label — extracted from "- Name: X", "You are X", etc. — is the
+     * stable identity that humans recognise.
+     *
+     * The buildId is still computed for fingerprinting but is NOT used as
+     * the session key.
+     */
+    registerAgent(systemPrompt: string, pluginList?: string[], modelId?: string): AgentSession;
+    /** Update detected model from LLM API request body. */
+    updateModel(model: string): void;
+    /** Update channel source (e.g. "slack:C00000001"). */
+    updateChannel(source: string): void;
+    /**
+     * Update per-agent cache stats from an LLM response.
+     * Returns anomaly alerts if cache behaviour deviates from baseline.
+     */
+    updateCache(usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+    }): {
+        alert: string;
+        severity: "medium" | "high";
+    } | null;
+    /** Record a heartbeat for the current agent. Returns alert if missed. */
+    recordHeartbeat(response?: string): {
+        alert: string;
+        severity: "medium" | "high";
+    } | null;
+    /** Check all agents for missed heartbeats. Call periodically. */
+    checkHeartbeatHealth(): Array<{
+        agentLabel: string;
+        status: string;
+        alert: string;
+    }>;
+    /** Detect and record the channel from prompt metadata. */
+    updateChannelFromPrompt(prompt: string): string | null;
+    /** Update tool inventory from body.tools array. Only sets once (first call). */
+    updateTools(tools: string[]): void;
+    /** Update SOUL extract from early messages. Only sets once. */
+    updateSoul(soul: string): void;
+    /** Record an LLM API call for the current agent. */
+    recordLlmCall(): AgentSession | null;
+    /** Record a security event for the current agent. */
+    recordSecurityEvent(count?: number): void;
+    /** Get the current active agent session. */
+    getCurrentSession(): AgentSession | null;
+    /** Get the current agent build ID. */
+    getCurrentBuildId(): string;
+    /** Get all tracked agent sessions. */
+    getAllSessions(): AgentSession[];
+    /** Get session by build ID. */
+    getSession(buildId: string): AgentSession | null;
+    /** Get session by label (primary key). */
+    getSessionByLabel(label: string): AgentSession | null;
+    /** Mark the start of an LLM call (for response time tracking). */
+    markCallStart(): void;
+    /** Log a completed LLM call with full details. */
+    logCall(details: {
+        url: string;
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        channel: string;
+        securityEvents: number;
+        reason: string;
+    }): void;
+    /** Get the LLM call log. */
+    getCallLog(): readonly LlmCallRecord[];
+    /** Reset all session tracking. */
+    reset(): void;
+}
+/**
+ * Compute a stable agent build ID.
+ *
+ * Uses a "skeleton" of the system prompt rather than the full text.
+ * This makes the ID resilient to:
+ * - Dynamic timestamps, dates, session IDs injected into prompts
+ * - User names or account-specific context
+ * - Retrieved RAG snippets appended to the base prompt
+ * - Minor wording tweaks during prompt iteration
+ *
+ * The skeleton is: first 500 chars of the prompt with numbers, dates,
+ * emails, UUIDs, and hex strings normalized to placeholders.
+ */
+export declare function computeBuildId(systemPrompt: string, pluginList: string[], modelId: string): string;
+/**
+ * Extract a stable "skeleton" from a system prompt by normalizing
+ * dynamic content to placeholders.
+ *
+ * Normalizes: timestamps, dates, numbers >4 digits, emails, UUIDs,
+ * hex strings >8 chars, IP addresses, URLs with path components.
+ * Keeps: the structural words, role definitions, tool descriptions,
+ * behavioral instructions — the parts that define the agent's identity.
+ */
+export declare function extractPromptSkeleton(prompt: string): string;
+/**
+ * Classify an agent's role from its label and system prompt content.
+ * Uses keyword matching against a role taxonomy — no LLM call needed.
+ *
+ * Confidence scoring:
+ *   90% — role keyword in agent label (explicit naming)
+ *   70% — role keyword in SOUL.md "You are a [role]" declaration
+ *   40% — role keyword found in general prompt metadata
+ *   10% — no match, "General Agent"
+ *
+ * Multiple signal matches boost confidence by 5% each (capped at 95%).
+ */
+export declare function classifyAgent(label: string, systemPrompt: string): AgentClassification;
+/**
+ * Enhanced classifier that uses tools + SOUL.md + label.
+ * Called when new data (tools or SOUL) becomes available.
+ */
+export declare function classifyAgentWithTools(label: string, soulExtract: string, tools: string[]): AgentClassification;
+/** Detect the channel type from OpenClaw prompt metadata. */
+export declare function detectChannel(prompt: string): string | null;
+/** Check if a prompt is a heartbeat prompt. */
+export declare function isHeartbeatPrompt(prompt: string): boolean;
+/** Check if a response is a heartbeat OK response. */
+export declare function isHeartbeatOk(response: string): boolean;