---
mode: subagent
---

<!-- SPDX-License-Identifier: MIT -->
<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->
# t1327.9: Outbound Leak Detection

## Origin

- **Created:** 2026-02-26
- **Session:** claude-code:feature/t1327.9-outbound-leak-detection
- **Created by:** ai-interactive
- **Parent task:** t1327 (SimpleX bot platform)
- **Conversation context:** Issue #2260 — implementing outbound leak scanning at the bot's send boundary to prevent accidental credential/secret exposure in chat responses.

## What

A `LeakDetector` module that scans all outbound bot messages before they are sent to SimpleX chat. If a potential leak is detected (API keys, credentials, file paths, internal IPs, database connection strings, high-entropy tokens), the message is redacted and the operator is warned via logger. The gate is at `sendMessage` and `replyToItem` — the two exit points in `SimplexAdapter`.

## Why

AI model responses and command outputs may accidentally include credentials, internal paths, or connection strings. The bot is a trust boundary — anything that passes through `sendMessage` is visible to external chat participants. This is a defense-in-depth measure: even if upstream code leaks a secret, the bot's send boundary catches it before it reaches the wire.

## How (Approach)

1. Create `src/leak-detector.ts` with:
   - Shannon entropy calculator for detecting high-entropy tokens (API keys, JWTs)
   - Regex patterns for known credential formats (AWS keys, GitHub tokens, etc.)
   - Regex patterns for internal IPs (RFC 1918), file paths, DB connection strings
   - A `scanForLeaks()` function returning detection results with match details
   - A `redactLeaks()` function that replaces detected secrets with `[REDACTED]`
2. Add `LeakDetectionResult` type to `types.ts`
3. Gate `replyToItem` and `sendMessage` in `index.ts` through the leak detector
4. Write comprehensive tests in `src/leak-detector.test.ts`

Key design decisions:
- Gate at send boundary (not at command handler level) — catches all paths
- Redact and warn, don't block — operator sees the warning in logs, user gets safe message
- Shannon entropy threshold ~4.0 for tokens >20 chars — balances false positives vs detection
- Configurable via `BotConfig.leakDetection` (enabled by default)

## Acceptance Criteria

- [ ] `leak-detector.ts` detects: AWS keys, GitHub tokens, generic API keys, JWTs, internal IPs, absolute file paths, DB connection strings, high-entropy tokens
  ```yaml
  verify:
    method: codebase
    pattern: "shannonEntropy|LEAK_PATTERNS|scanForLeaks"
    path: ".agents/scripts/simplex-bot/src/leak-detector.ts"
  ```
- [ ] `sendMessage` and `replyToItem` in `index.ts` pass text through leak detector before sending
  ```yaml
  verify:
    method: codebase
    pattern: "scanForLeaks|leakDetect"
    path: ".agents/scripts/simplex-bot/src/index.ts"
  ```
- [ ] Detected leaks are redacted with `[REDACTED]` in the outbound message
  ```yaml
  verify:
    method: bash
    run: "cd ~/Git/aidevops.feature-t1327.9-outbound-leak-detection/.agents/scripts/simplex-bot && bun test 2>&1 | grep -q 'REDACTED'"
  ```
- [ ] Operator warning logged when leak detected
  ```yaml
  verify:
    method: codebase
    pattern: "logger.warn.*leak|logger.warn.*redact"
    path: ".agents/scripts/simplex-bot/src/index.ts"
  ```
- [ ] Tests pass (`bun test`)
  ```yaml
  verify:
    method: bash
    run: "cd ~/Git/aidevops.feature-t1327.9-outbound-leak-detection/.agents/scripts/simplex-bot && bun test"
  ```
- [ ] Typecheck passes (`bun x tsc --noEmit`)
  ```yaml
  verify:
    method: bash
    run: "cd ~/Git/aidevops.feature-t1327.9-outbound-leak-detection/.agents/scripts/simplex-bot && bun x tsc --noEmit"
  ```

## Context & Decisions

- Gate at send boundary chosen over per-command gating: catches all code paths including error messages, welcome messages, and future AI model responses
- Redact-and-warn chosen over block: blocking would break user experience; redaction preserves message flow while preventing exposure
- Shannon entropy threshold of 4.0 bits/char for tokens >20 chars: empirically good balance — English text averages ~3.5, random base64 averages ~5.5
- Inspired by IronClaw's host-boundary leak scanning pattern

## Relevant Files

- `.agents/scripts/simplex-bot/src/index.ts:262` — `sendMessage` (primary gate point)
- `.agents/scripts/simplex-bot/src/index.ts:432` — `replyToItem` (secondary gate point)
- `.agents/scripts/simplex-bot/src/types.ts` — add `LeakDetectionResult` type
- `.agents/scripts/simplex-bot/src/commands.ts` — no changes needed (gated at send boundary)

## Dependencies

- **Blocked by:** t1327.4 (bot framework) — COMPLETED
- **Blocks:** t1327.10 (exec approval flow — benefits from leak detection)
- **External:** None

## Estimate Breakdown

| Phase | Time | Notes |
|-------|------|-------|
| Research/read | 15m | Understand bot send paths |
| Implementation | 1h | leak-detector.ts + index.ts gating |
| Testing | 30m | Comprehensive test suite |
| **Total** | **~2h** | |
