claude-telegram-mirror 0.1.27 → 0.2.2

package/README.md

@@ -2,10 +2,11 @@
 
 [![npm version](https://img.shields.io/npm/v/claude-telegram-mirror.svg)](https://www.npmjs.com/package/claude-telegram-mirror)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![Rust](https://img.shields.io/badge/Built_with-Rust-dea584.svg)
 
 Bidirectional communication between Claude Code CLI and Telegram. Control your Claude Code sessions from your phone.
 
-**Supported platforms:** Linux, macOS
+**Supported platforms:** Linux x64, Linux arm64, macOS ARM64, macOS Intel x64
 
 ## Installation
 
@@ -14,21 +15,26 @@ npm install -g claude-telegram-mirror
 ctm setup    # Interactive setup wizard
 ```
 
-The setup wizard guides you through:
-1. Creating a Telegram bot via @BotFather
-2. Disabling privacy mode (critical for group messages)
-3. Setting up a supergroup with Topics
-4. Verifying bot permissions
-5. Installing hooks and the system service
+This installs a native Rust binary (`ctm`) via platform-specific optional packages. No Node.js runtime is needed to run the binary itself — Node.js 18+ is only required as the npm distribution mechanism.
 
 ## Features
 
 - **CLI to Telegram**: Mirror Claude's responses, tool usage, and notifications
 - **Telegram to CLI**: Send prompts from Telegram directly to Claude Code
-- **Stop/Interrupt**: Type `stop` in Telegram to send Ctrl+C and halt Claude mid-process
+- **Tool Summarizer**: Human-readable summaries for 30+ command patterns ("Running tests" instead of "Running: Bash")
+- **AskUserQuestion Rendering**: Inline buttons for Claude's interactive questions
+- **Photo & Document Upload**: Send images/files from Telegram, path injected into Claude
+- **Stop/Interrupt**: Type `stop` to send Escape, `kill` to send Ctrl-C
 - **Session Threading**: Each Claude session gets its own Forum Topic
+- **Session Rename**: `/rename` syncs with Claude Code's session title
 - **Multi-System Support**: Run separate daemons on multiple machines
 - **Compaction Notifications**: Get notified when Claude summarizes context
+- **Governor Rate Limiting**: MessageQueue with retry and exponential backoff
+- **Doctor Auto-Fix**: `ctm doctor --fix` auto-remediates common issues
+- **Token Scrubbing**: Global regex-based scrubbing prevents bot tokens from leaking to logs
+- **Atomic PID Locking**: `flock(2)` prevents duplicate daemon instances
+- **Path Traversal Protection**: Transcript paths validated and canonicalized before file access
+- **Char-Boundary Safe**: Unicode-safe message chunking and string truncation throughout
 
 ## Quick Start
 
@@ -53,6 +59,7 @@ claude
 # Setup & diagnostics
 ctm setup              # Interactive setup wizard
 ctm doctor             # Diagnose configuration issues
+ctm doctor --fix       # Auto-fix detected issues
 
 # Daemon control
 ctm start              # Start daemon (foreground mode)
@@ -61,6 +68,9 @@ ctm stop --force       # Force stop if graceful shutdown fails
 ctm restart            # Restart daemon
 ctm status             # Show daemon status, config, and hooks
 ctm config --test      # Test Telegram connection
+ctm toggle             # Toggle mirroring on/off
+ctm toggle --on        # Force mirroring ON
+ctm toggle --off       # Force mirroring OFF
 
 # Hook management
 ctm install-hooks      # Install global hooks
@@ -77,19 +87,28 @@ ctm service restart    # Restart via service manager
 ctm service status     # Show service status
 ```
 
-**Note:** The top-level `ctm stop` and `ctm restart` commands work for both direct daemon mode and OS service mode. They automatically detect how the daemon is running and use the appropriate method.
+**Note:** `ctm stop` and `ctm restart` auto-detect whether the daemon is running directly or via a system service and use the appropriate method.
 
 ## Telegram Commands
 
-Once connected, you can control Claude from Telegram:
-
 | Command | Action |
 |---------|--------|
 | Any text | Sends to Claude as input |
 | `stop` | Sends Escape to pause Claude |
 | `kill` | Sends Ctrl-C to exit Claude entirely |
-
-See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for additional command aliases.
+| `cc <cmd>` | Sends `/<cmd>` as a slash command to Claude |
+| `/status` | Show active sessions and mirroring state |
+| `/sessions` | List active sessions with age and project dir |
+| `/rename <name>` | Rename session (syncs with Claude Code) |
+| `/attach <id>` | Attach to a session for updates |
+| `/detach` | Detach from current session |
+| `/mute` / `/unmute` | Suppress/resume agent response notifications |
+| `/toggle` | Toggle mirroring on/off |
+| `/abort` | Abort the attached session |
+| `/ping` | Measure round-trip latency |
+| `/help` | Show all commands |
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for additional details and command aliases.
 
 ### Tool Approval Buttons
 
@@ -102,36 +121,32 @@ When Claude requests to use a tool that requires permission (Write, Edit, Bash w
 | **Abort** | Stop the entire Claude session |
 | **Details** | View full tool input parameters |
 
-**Note:** Approval buttons only appear when running Claude in normal mode. They do not appear when using `--dangerously-skip-permissions` mode. If you don't respond within 5 minutes, Claude will fall back to asking for approval in the CLI terminal.
+Approval buttons only appear in normal mode, not with `--dangerously-skip-permissions`. If you don't respond within 5 minutes, Claude falls back to CLI approval.
 
 ## Architecture
 
 ```
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│   Claude Code   │────▶│  Bridge Daemon  │────▶│    Telegram     │
-│      CLI        │◀────│                 │◀────│      Bot        │
+│   Claude Code   │────▶│   ctm daemon    │────▶│    Telegram     │
+│      CLI        │◀────│  (Rust binary)  │◀────│      Bot        │
 └─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │
         │ hooks                 │ Unix socket
         ▼                       ▼
 ┌─────────────────┐     ┌─────────────────┐
-│  PreToolUse:    │────▶│  Socket Server  │
-│  Node.js handler│◀────│  (bidirectional)│
-│  (with approval)│     │                 │
-├─────────────────┤     │                 │
-│  Other hooks:   │────▶│                 │
-│  Bash script    │     │                 │
-│  (fire & forget)│     │                 │
+│  ctm hook       │────▶│  Socket Server  │
+│  (same binary,  │◀────│  (bidirectional)│
+│   hook mode)    │     │                 │
 └─────────────────┘     └─────────────────┘
 ```
 
 **Flow:**
-1. Claude Code hooks capture events (prompts, responses, tool use)
-2. PreToolUse: Node.js handler sends approval request, waits for Telegram response
-3. Other hooks: Bash script sends JSON and exits immediately (faster)
-4. Bridge forwards messages to Telegram Forum Topic
+1. Claude Code hooks invoke `ctm hook`, which reads the event from stdin
+2. PreToolUse: sends approval request via socket, waits for Telegram response
+3. Other hooks: sends JSON to daemon via socket and exits immediately
+4. Daemon forwards messages to Telegram Forum Topic with summarized tool actions
 5. Telegram replies are injected into CLI via `tmux send-keys`
-6. Stop commands send `Ctrl-C` to interrupt Claude
+6. Stop/kill commands send Escape or Ctrl-C to interrupt Claude
 
 ## Multi-System Architecture
 
@@ -146,11 +161,7 @@ When running Claude Code on multiple machines, each system needs its own bot to
 ### Setup for Multiple Systems
 
 1. **Create one bot per system** via [@BotFather](https://t.me/botfather)
-   - System A: `@claude_mirror_system_a_bot`
-   - System B: `@claude_mirror_system_b_bot`
-
 2. **Add all bots to the same supergroup** with admin permissions
-
 3. **Configure each system** with its own bot token:
    ```bash
    # On System A (~/.telegram-env)
@@ -161,23 +172,20 @@ When running Claude Code on multiple machines, each system needs its own bot to
    export TELEGRAM_BOT_TOKEN="token-for-system-b-bot"
    export TELEGRAM_CHAT_ID="-100shared-group-id"  # Same group!
    ```
-
 4. **Each daemon creates topics for its sessions** - Messages route correctly because each daemon only processes topics it created.
 
 ## Prerequisites
 
-- Node.js 18+
+- Node.js 18+ (for npm installation only)
 - Claude Code CLI
 - tmux (for bidirectional communication)
-- jq (JSON processing)
-- nc (netcat, for socket communication)
 - Telegram account
 
 ## Telegram Setup
 
 ### 1. Create a Bot
 
-1. Message [@BotFather](https://t.me/botfather) → `/newbot`
+1. Message [@BotFather](https://t.me/botfather) -> `/newbot`
 2. Choose name and username (must end in `bot`)
 3. Save the API token
 
@@ -185,27 +193,23 @@ When running Claude Code on multiple machines, each system needs its own bot to
 
 1. Create a new group in Telegram
 2. Add your bot to the group
-3. Group Settings → Enable **Topics**
+3. Group Settings -> Enable **Topics**
 
 ### 3. Make Bot an Admin
 
-1. Group Settings → Administrators → Add your bot
+1. Group Settings -> Administrators -> Add your bot
 2. Enable: **Manage Topics**, **Post Messages**
 
 ### 4. Get Chat ID
 
 1. Send any message in the group
-2. Run the helper script:
-   ```bash
-   ./scripts/get-chat-id.sh YOUR_BOT_TOKEN
-   ```
-   Or manually: `https://api.telegram.org/botYOUR_TOKEN/getUpdates`
+2. Visit `https://api.telegram.org/botYOUR_TOKEN/getUpdates`
 3. Copy the chat ID (supergroups start with `-100`)
 
 ### 5. Disable Privacy Mode
 
-1. [@BotFather](https://t.me/botfather) → `/mybots` → Select bot
-2. Bot Settings → Group Privacy → **Turn off**
+1. [@BotFather](https://t.me/botfather) -> `/mybots` -> Select bot
+2. Bot Settings -> Group Privacy -> **Turn off**
 
 ## Configuration
 
@@ -248,7 +252,7 @@ Environment variables take precedence over config file values.
 
 ```bash
 ctm doctor
-# Checks: Node.js, config, hooks, socket, tmux, systemd, Telegram API
+# Checks: config, hooks, socket, tmux, systemd/launchd, Telegram API
 ```
 
 ## Project-Level Hooks
@@ -258,32 +262,35 @@ If your project has `.claude/settings.json` with custom hooks, global hooks are
 ```bash
 cd /path/to/your/project
 ctm install-hooks --project
-# or shorthand:
-ctm install-hooks -p
 ```
 
-The installer will prompt you to set up project-level hooks during installation. You can also add them later to any project.
-
 ## How Messages Flow
 
 | Direction | Event | Display |
 |-----------|-------|---------|
-| CLI → Telegram | User types | 👤 User (cli): ... |
-| CLI → Telegram | Tool starts | 🔧 Running: Bash |
-| CLI → Telegram | Claude responds | 🤖 Claude: ... |
-| CLI → Telegram | Session starts | New Forum Topic created |
-| CLI → Telegram | Context compacting | ⏳ Notification sent |
-| Telegram → CLI | User sends message | Injected via tmux |
-| Telegram → CLI | User types "stop" | Sends Ctrl+C interrupt |
+| CLI -> Telegram | User types | User (cli): ... |
+| CLI -> Telegram | Tool starts | Running tests (summarized) |
+| CLI -> Telegram | Claude responds | Claude: ... |
+| CLI -> Telegram | Session starts | New Forum Topic created |
+| CLI -> Telegram | Context compacting | Notification sent |
+| CLI -> Telegram | AskUserQuestion | Inline buttons rendered |
+| Telegram -> CLI | User sends message | Injected via tmux |
+| Telegram -> CLI | User sends photo | Downloaded, path injected |
+| Telegram -> CLI | User types "stop" | Sends Escape interrupt |
 
 ## Technical Details
 
+- **Binary**: Single native Rust executable (`ctm`), ~10 MB
 - **Session storage**: SQLite at `~/.config/claude-telegram-mirror/sessions.db`
 - **Socket path**: `~/.config/claude-telegram-mirror/bridge.sock`
+- **PID file**: `~/.config/claude-telegram-mirror/bridge.pid` (flock-guarded)
+- **Downloads**: `~/.config/claude-telegram-mirror/downloads/` (0700 permissions)
 - **Response extraction**: Reads Claude's transcript `.jsonl` on Stop event
 - **Deduplication**: Telegram-originated messages tracked to prevent echo
 - **Topic routing**: Each daemon only processes topics it created (multi-bot safe)
-- **Compaction alerts**: PreCompact hook sends notification before context summarization
+- **Rate limiting**: Governor-based with exponential backoff retry queue
+- **Token scrubbing**: All log output filtered through regex to strip bot tokens
+- **Test suite**: 512 Rust tests (unit + 10 integration test files)
 
 ## Troubleshooting
 
@@ -291,10 +298,9 @@ Run the diagnostic tool first:
 
 ```bash
 ctm doctor
+ctm doctor --fix   # Auto-fix common issues
 ```
 
-This checks all common issues and provides fix suggestions.
-
 ### Common Issues
 
 **Hooks not firing?**
@@ -305,12 +311,12 @@ This checks all common issues and provides fix suggestions.
 **409 Conflict error?**
 - Only one polling connection per bot token is allowed
 - If running multiple systems, each needs its own bot (see Multi-System Architecture)
-- Kill duplicate daemons: `pkill -f "claude-telegram-mirror"`
+- Kill duplicate daemons: `ctm stop --force`
 
 **Bridge not receiving events?**
 - Check socket: `ls -la ~/.config/claude-telegram-mirror/bridge.sock`
-- Enable debug: `export TELEGRAM_HOOK_DEBUG=1` then retry
-- Check debug log: `cat ~/.config/claude-telegram-mirror/hook-debug.log`
+- Check daemon logs for errors
+- Run `ctm status` to verify daemon is running
 
 **tmux injection not working?**
 - Verify tmux session: `tmux list-sessions`
@@ -327,46 +333,55 @@ This checks all common issues and provides fix suggestions.
 **Service not starting (macOS)?**
 - Check status: `launchctl list | grep claude`
 - View logs: `cat ~/Library/Logs/claude-telegram-mirror.*.log`
-- Check permissions: Ensure Terminal has Accessibility access
 
-## Manual Setup (for developers)
+## Build from Source
 
 <details>
-<summary>Click to expand manual installation steps</summary>
+<summary>Click to expand</summary>
 
-For developers who want to work on the source code:
+For developers who want to build from source or contribute:
 
 ```bash
 # 1. Clone and build
 git clone https://github.com/robertelee78/claude-telegram-mirror.git
-cd claude-telegram-mirror && npm install && npm run build
-
-# 2. Create a Telegram bot via @BotFather, get the token
+cd claude-telegram-mirror/rust-crates
+cargo build --release
+# Binary at: rust-crates/target/release/ctm
 
-# 3. Create a supergroup with Topics enabled, add your bot as admin
+# 2. Run tests
+cargo test
 
-# 4. Get your chat ID
-./scripts/get-chat-id.sh YOUR_BOT_TOKEN
-
-# 5. Configure environment
-cat > ~/.telegram-env << 'EOF'
-export TELEGRAM_BOT_TOKEN="your-token-here"
-export TELEGRAM_CHAT_ID="-100your-chat-id"
-export TELEGRAM_MIRROR=true
-EOF
+# 3. Use the binary directly
+./target/release/ctm setup
+./target/release/ctm start
+```
 
-# 6. Install hooks
-node dist/cli.js install-hooks                    # Global install
-# OR for projects with custom .claude/settings.json:
-cd /path/to/project && node dist/cli.js install-hooks --project
+### Project Structure (30 source files)
 
-# 7. Start daemon (choose one)
-node dist/cli.js start                            # Foreground (for testing)
-node dist/cli.js service install && \
-node dist/cli.js service start                    # As system service (recommended)
 ```
-
-**Note:** When using npm install, use `ctm` instead of `node dist/cli.js`.
+rust-crates/ctm/src/
+  main.rs           # CLI entry point (clap)
+  lib.rs            # Library re-exports
+  hook.rs           # Hook event processing
+  config.rs         # Configuration loading (env > file > defaults)
+  error.rs          # Centralized error types (thiserror)
+  types.rs          # Shared types, validation, security constants
+  session.rs        # SQLite session management
+  socket.rs         # Unix socket server/client (flock, NDJSON)
+  injector.rs       # tmux input injection
+  formatting.rs     # Message formatting, chunking, ANSI stripping
+  summarize.rs      # Tool action summarizer (30+ patterns)
+  colors.rs         # ANSI color helpers for terminal output
+  doctor.rs         # Diagnostic checks with --fix
+  installer.rs      # Hook installer
+  setup.rs          # Interactive setup wizard
+  bot/              # Telegram API client (client.rs, queue.rs, types.rs)
+  daemon/           # Bridge daemon (mod.rs, event_loop.rs, socket_handlers.rs,
+                    #   telegram_handlers.rs, callback_handlers.rs, cleanup.rs, files.rs)
+  service/          # OS service management (mod.rs, systemd.rs, launchd.rs, env.rs)
+
+rust-crates/ctm/tests/   # 10 integration test files
+```
 
 </details>
 

package/SECURITY.md

@@ -0,0 +1,228 @@
+# Security Policy
+
+## Threat Model
+
+The claude-telegram-mirror bridges a local Claude Code CLI session to a remote
+Telegram chat. The system has five trust boundaries, shown below.
+
+```mermaid
+graph TB
+    subgraph "Untrusted Network"
+        TG["Telegram Bot API<br/>(HTTPS, external)"]
+    end
+
+    subgraph "Local Machine — Same User"
+        BOT["Bot Process<br/>(reqwest long-poll)"]
+        DAEMON["Bridge Daemon"]
+        SOCK["Unix Domain Socket<br/>(bridge.sock, 0o600)"]
+        HOOKS["Hook Handler<br/>(ctm hook subcommand)"]
+        TMUX["tmux Sessions<br/>(send-keys injection)"]
+        FS["File System<br/>(~/.config/claude-telegram-mirror/)"]
+        DB["SQLite DB<br/>(sessions.db, 0o600)"]
+    end
+
+    TG -- "HTTPS poll" --> BOT
+    BOT -- "in-process" --> DAEMON
+    DAEMON -- "listen/accept" --> SOCK
+    HOOKS -- "connect/send NDJSON" --> SOCK
+    DAEMON -- "Command::new" --> TMUX
+    DAEMON -- "read/write" --> FS
+    DAEMON -- "rusqlite" --> DB
+    HOOKS -- "stdin pipe" --> HOOKS
+```
+
+### Trust boundaries
+
+| Boundary | Trust level | Threat |
+|----------|-------------|--------|
+| Telegram Bot API to Bot process | Untrusted network | Spoofed updates, message injection from unauthorized chats |
+| Unix domain socket (bridge.sock) | Same-user local IPC | Other local users or processes connecting |
+| tmux send-keys | Same-user process control | Command injection via unsanitized text |
+| File system (config dir) | Same-user file access | World-readable secrets, path traversal |
+| Hook scripts (stdin) | Subprocess execution | Oversized payloads, malformed JSON |
+
+## Security Mitigations
+
+### 1. No Shell Interpolation in tmux Injection
+
+**File:** `rust-crates/ctm/src/injector.rs`
+
+All tmux commands use `Command::new("tmux")` with `.arg()` chains. The process
+binary is the first argument and all subsequent arguments are passed directly to
+the kernel without shell interpretation. The `-l` (literal) flag on `send-keys`
+ensures tmux treats the injected string as literal keystrokes. No escaping or
+quoting is needed.
+
+Dead code for FIFO and PTY injection methods has been removed. The only
+injection method is `tmux`. See [ADR-004](docs/adr/ADR-004-tmux-only-injection.md).
+
+Slash commands (e.g., `/clear`, `/rename`) are validated against a character
+whitelist (`[a-zA-Z0-9_- /]`) before injection. Commands containing shell
+metacharacters are rejected.
+
+### 2. Bot Token Scrubbing
+
+**File:** `rust-crates/ctm/src/bot/client.rs`
+
+A `tracing` subscriber layer applies `scrub_bot_token()` to log output.
+The regex `bot\d+:[A-Za-z0-9_-]+/` matches the Telegram bot token pattern
+in API URLs and replaces it with `bot<REDACTED>`.
+
+All log output goes to stderr via the `tracing` subscriber. There is no
+file transport, so tokens cannot leak into log files on disk.
+
+The error handler in `rust-crates/ctm/src/bot/client.rs` also scrubs bot
+tokens from error messages before logging.
+
+### 3. Chat Authorization (Anti-IDOR)
+
+**File:** `rust-crates/ctm/src/daemon/telegram_handlers.rs`
+
+A chat ID check verifies `chat.id` against the configured `chat_id` on
+every incoming update. Updates from unauthorized chats receive a static
+"Unauthorized" reply and are not processed further.
+
+Approval callback handlers (`approve:`, `reject:`, `abort:`), answer
+handlers (`answer:`, `toggle:`, `submit:`), all verify the chat ID
+matches the configured `chat_id` before processing. This prevents
+IDOR attacks where a user who knows an approval ID could respond from a
+different chat.
+
+### 4. Session ID Validation
+
+**File:** `rust-crates/ctm/src/daemon/socket_handlers.rs`
+
+Session IDs from hook events are validated before any database operation:
+- Maximum length: 128 characters
+- Character set: `[a-zA-Z0-9_-]` only
+- Empty/null values are rejected
+
+Messages with invalid session IDs are dropped with a warning log.
+
+### 5. Socket Security
+
+**File:** `rust-crates/ctm/src/socket.rs`
+
+The socket server enforces three limits:
+- **NDJSON line limit:** 1 MiB (1,048,576 bytes) per line. Oversized lines
+  are dropped and logged.
+- **Connection limit:** 64 concurrent connections. New connections beyond
+  this limit are destroyed immediately.
+- **Directory permissions:** The socket directory is created with mode 0o700
+  (owner-only) and the socket file is set to 0o600 after binding.
+
+A PID file lock prevents multiple daemon instances from racing on the same
+socket.
+
+### 6. Socket Path Validation
+
+**File:** `rust-crates/ctm/src/config.rs`
+
+`validateSocketPath()` rejects socket paths that:
+- Contain `..` (directory traversal)
+- Are not absolute (do not start with `/`)
+- Exceed 256 characters
+
+Invalid paths fall back to the default socket path in the config directory.
+
+### 7. Config Directory Permissions
+
+**File:** `rust-crates/ctm/src/config.rs`
+
+`ensure_config_dir()` creates `~/.config/claude-telegram-mirror/` with mode
+0o700. If the directory already exists, it enforces 0o700 via
+`fs::set_permissions()`. All config directory creation goes through this
+single function.
+
+### 8. Database File Permissions
+
+**File:** `rust-crates/ctm/src/session.rs`
+
+Immediately after opening the SQLite database, `fs::set_permissions(db_path, 0o600)`
+is called to ensure the database file is owner-readable/writable only.
+
+### 9. Hook Stdin Size Limit
+
+**File:** `rust-crates/ctm/src/hook.rs`
+
+The hook handler reads stdin in chunks and enforces a 1 MiB
+(1,048,576 byte) limit. If the accumulated input exceeds this limit, the
+handler logs a warning and exits cleanly without processing the payload.
+
+### 10. Download File Handling
+
+**File:** `rust-crates/ctm/src/daemon/telegram_handlers.rs`
+
+Downloaded files from Telegram are handled with several protections:
+- The downloads directory is created with mode 0o700
+- Downloaded files are written with mode 0o600
+- Filenames are sanitized: path separators replaced, `..` removed, dotfile
+  prefixes neutralized, length capped at 200 characters
+- Every filename is prefixed with a UUID for uniqueness
+- Files older than 24 hours are automatically cleaned up
+- Telegram enforces a 20 MB file size limit at the API level
+
+## File Permission Summary
+
+| File/Directory | Mode | Rationale |
+|---|---|---|
+| `~/.config/claude-telegram-mirror/` | 0o700 | Contains bot token in config, session database, socket |
+| `~/.telegram-env` | 0o600 | Contains bot token and chat ID for shell sourcing |
+| `config.json` | 0o600 | Contains bot token |
+| `sessions.db` | 0o600 | Contains session metadata, approval records |
+| `bridge.sock` | 0o600 | IPC socket, same-user access only |
+| `bridge.pid` | default | PID lock file, no sensitive content |
+| `downloads/` | 0o700 | User-uploaded files from Telegram |
+| Downloaded files | 0o600 | User-uploaded content, owner-only |
+
+## Input Validation Summary
+
+| Boundary | Validation | Enforcement |
+|---|---|---|
+| Socket messages: session ID | 128 char max, `[a-zA-Z0-9_-]` | `socket_handlers.rs` — `is_valid_session_id()` |
+| Socket lines | 1 MiB max per NDJSON line | `socket.rs` — `MAX_LINE_BYTES` |
+| Socket connections | 64 concurrent max | `socket.rs` — `MAX_CONNECTIONS` |
+| Hook stdin | 1 MiB max | `hook.rs` — `MAX_STDIN_BYTES` |
+| Socket paths | No `..`, absolute only, 256 char max | `config.rs` — `validate_socket_path()` |
+| Slash commands | Character whitelist: `[a-zA-Z0-9_- /]` | `injector.rs` — `is_valid_slash_command()` |
+| Download filenames | Sanitized, UUID-prefixed, no `..`, 200 char max | `telegram_handlers.rs` — `sanitize_filename()` |
+| Download file size | 20 MB max | Telegram Bot API server-side limit |
+| Telegram chat ID | Exact match against configured `chat_id` | `telegram_handlers.rs` — chat ID check |
+
+## Security Checklist for Contributors
+
+Before modifying security-sensitive code, verify:
+
+- [ ] **No shell interpolation.** All subprocess calls use `Command::new()`
+  with `.arg()` chains, never string concatenation into a shell command.
+- [ ] **No hardcoded secrets.** Bot tokens come from environment variables or
+  the config file, never from source code.
+- [ ] **File permissions enforced.** Any new file or directory in the config
+  directory uses 0o600 (files) or 0o700 (directories).
+- [ ] **Input validated at boundary.** Any data arriving from the socket, stdin,
+  or Telegram is validated before use. Session IDs, file paths, and command
+  strings are checked against their respective whitelists.
+- [ ] **Bot token not logged.** Any error message that might contain a URL is
+  passed through `scrub_bot_token()` before logging.
+- [ ] **Chat ID checked.** Any new callback handler or message handler verifies
+  the chat ID matches the configured `chat_id`.
+- [ ] **Tests pass.** Run `cargo test` and confirm no regressions.
+- [ ] **No new file logging.** All log output goes to stderr. Do not add file
+  transports to the logger.
+- [ ] **Path traversal blocked.** Any user-controlled path component is
+  validated to reject `..` and non-absolute paths.
+
+## Responsible Disclosure
+
+If you discover a security vulnerability in claude-telegram-mirror, please
+report it responsibly:
+
+1. **Do not** open a public GitHub issue for security vulnerabilities.
+2. Email the maintainers at the address listed in `package.json`, or use
+   GitHub's private vulnerability reporting feature on the repository.
+3. Include a description of the vulnerability, steps to reproduce, and the
+   potential impact.
+4. Allow up to 90 days for a fix before public disclosure.
+
+We will acknowledge receipt within 48 hours and aim to release a fix within
+30 days of confirmation.