---
phase: "17"
plan: "03"
subsystem: telegram-bot
tags: [telegram, bot, commands, telego]
dependency_graph:
  requires: [engine, verifier, recon-engine, storage, providers]
  provides: [bot-command-handlers]
  affects: [serve-command]
tech_stack:
  added: [github.com/mymmrac/telego@v1.8.0]
  patterns: [telegohandler-command-predicates, context-based-handlers]
key_files:
  created: [pkg/bot/bot.go, pkg/bot/handlers.go, pkg/bot/source.go, pkg/bot/handlers_test.go]
  modified: [go.mod, go.sum]
decisions:
  - "Handler signature uses telego Context (implements context.Context) for cancellation propagation"
  - "/key command enforced private-chat-only via chat.Type check; all other commands use masked keys only"
  - "Bot wraps existing engine/verifier/recon/storage/registry via Deps struct injection"
metrics:
  duration: 5min
  completed: "2026-04-06"
---

# Phase 17 Plan 03: Bot Command Handlers Summary

Telegram bot command handlers for 8 commands using telego v1.8.0, wrapping existing scan/verify/recon/storage functionality.

## Tasks Completed

| Task | Name | Commit | Files |
|------|------|--------|-------|
| 1+2 | Bot package + 8 command handlers | 9ad5853 | pkg/bot/bot.go, pkg/bot/handlers.go, pkg/bot/source.go, go.mod, go.sum |
| 3 | Unit tests for handlers | 202473a | pkg/bot/handlers_test.go |

## Implementation Details

### Bot Package Structure

- `bot.go`: Bot struct with Deps injection (engine, verifier, recon, storage, registry, encKey), RegisterHandlers method wiring telego BotHandler
- `handlers.go`: 8 command handlers (/help, /scan, /verify, /recon, /status, /stats, /providers, /key) plus extractArg and storageToEngine helpers
- `source.go`: selectBotSource for file/directory path resolution (subset of CLI source selection)

### Command Security Model

- `/key <id>`: Private chat only. Returns full unmasked key, refuses in group/supergroup chats
- All other commands: Masked keys only. Never expose raw key material in group contexts
- Scan results capped at 20 items with overflow indicator

### Handler Registration

Commands registered via `th.CommandEqual("name")` predicates on the BotHandler. Each handler returns `error` but uses reply messages for user-facing errors rather than returning errors to telego.

## Decisions Made

1. Handler context: telego's `*th.Context` implements `context.Context`, used for timeout propagation in scan/recon operations
2. /key private-only: Enforced via `msg.Chat.Type == "private"` check, returns denial message in groups
3. Deps struct pattern: All dependencies injected via `Deps` struct to `New()` constructor, avoiding global state

## Deviations from Plan

None - plan executed exactly as written.

## Known Stubs

None. All 8 handlers are fully wired to real engine/verifier/recon/storage functionality.

## Self-Check: PASSED