---
phase: "17"
plan: "03"
type: implementation
autonomous: true
wave: 1
depends_on: []
requirements: [TELE-01, TELE-02, TELE-03, TELE-04, TELE-06]
---

# Phase 17 Plan 03: Bot Command Handlers

## Objective

Implement Telegram bot command handlers for /scan, /verify, /recon, /status, /stats, /providers, /help, and /key commands. The bot package wraps existing CLI functionality (scan engine, verifier, recon engine, storage queries, provider registry) and exposes it through Telegram message handlers using the telego library.

## Context

- @pkg/engine/engine.go — scan engine with Scan() method
- @pkg/verify/verifier.go — HTTPVerifier with Verify/VerifyAll
- @pkg/recon/engine.go — recon Engine with SweepAll
- @pkg/storage/queries.go — DB queries (ListFindingsFiltered, GetFinding)
- @cmd/scan.go — CLI scan flow (source selection, verification, persistence)
- @cmd/recon.go — CLI recon flow (buildReconEngine, SweepAll, persist)
- @cmd/keys.go — CLI keys management (list, show, verify)
- @cmd/providers.go — Provider listing and stats

## Tasks

### Task 1: Add telego dependency and create bot package with handler registry
type="auto"

Create `pkg/bot/` package with:
- `bot.go`: Bot struct wrapping telego.Bot, holding references to engine, verifier, recon engine, storage, providers registry, and encryption key
- `handlers.go`: Handler registration mapping commands to handler functions
- Add `github.com/mymmrac/telego` dependency

Done when: `pkg/bot/bot.go` compiles, Bot struct has all required dependencies injected

### Task 2: Implement all eight command handlers
type="auto"

Implement handlers in `pkg/bot/handlers.go`:
- `/help` — list available commands with descriptions
- `/scan <path>` — trigger scan on path, return findings (masked only, never unmasked in Telegram)
- `/verify <id>` — verify a finding by ID, return status
- `/recon [--sources=x,y]` — run recon sweep, return summary
- `/status` — show bot status (uptime, last scan time, DB stats)
- `/stats` — show provider/finding statistics
- `/providers` — list loaded providers
- `/key <id>` — show full key detail (private chat only, with unmasked key)

Security: /key must only work in private chats, never in groups. All other commands use masked keys only.

Done when: All eight handlers compile and handle errors gracefully

### Task 3: Unit tests for command handlers
type="auto"

Write tests in `pkg/bot/handlers_test.go` verifying:
- /help returns all command descriptions
- /scan with missing path returns usage error
- /key refuses to work in group chats
- /providers returns provider count
- /stats returns stats summary

Done when: `go test ./pkg/bot/...` passes

## Verification

```bash
go build ./...
go test ./pkg/bot/... -v
```

## Success Criteria

- All eight command handlers implemented in pkg/bot/handlers.go
- Bot struct accepts all required dependencies via constructor
- /key command enforced private-chat-only
- All commands use masked keys except /key in private chat
- Tests pass