diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 8252aa2..c0cf4f5 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -232,12 +232,12 @@ Requirements for initial release. Each maps to roadmap phases. ### Telegram Bot -- [ ] **TELE-01**: /scan command — remote scan trigger -- [ ] **TELE-02**: /verify command — key verification -- [ ] **TELE-03**: /recon command — dork execution -- [ ] **TELE-04**: /status, /stats, /providers, /help commands +- [x] **TELE-01**: /scan command — remote scan trigger +- [x] **TELE-02**: /verify command — key verification +- [x] **TELE-03**: /recon command — dork execution +- [x] **TELE-04**: /status, /stats, /providers, /help commands - [ ] **TELE-05**: /subscribe and /unsubscribe for auto-notifications -- [ ] **TELE-06**: /key command — full key detail in private chat +- [x] **TELE-06**: /key command — full key detail in private chat - [ ] **TELE-07**: Auto-notification on new key findings ### Scheduled Scanning diff --git a/.planning/STATE.md b/.planning/STATE.md index 1da07ac..4d206f9 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,14 +3,14 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: milestone status: executing -stopped_at: Completed 16-01-PLAN.md -last_updated: "2026-04-06T13:48:35.313Z" +stopped_at: Completed 17-03-PLAN.md +last_updated: "2026-04-06T14:36:30.928Z" last_activity: 2026-04-06 progress: total_phases: 18 - completed_phases: 14 - total_plans: 85 - completed_plans: 83 + completed_phases: 15 + total_plans: 86 + completed_plans: 84 percent: 20 --- @@ -100,6 +100,7 @@ Progress: [██░░░░░░░░] 20% | Phase 15 P01 | 3min | 2 tasks | 13 files | | Phase 15 P03 | 4min | 2 tasks | 11 files | | Phase 16 P01 | 4min | 2 tasks | 6 files | +| Phase 17 P03 | 5min | 3 tasks | 6 files | ## Accumulated Context @@ -152,6 +153,8 @@ Recent decisions affecting current work: - [Phase 16]: VT uses x-apikey header per official API v3 spec - [Phase 16]: IX uses three-step flow: POST search, GET results, GET file content - [Phase 16]: URLhaus tag lookup with payload endpoint fallback +- [Phase 17]: Telego v1.8.0 handler context pattern: *th.Context implements context.Context for scan/recon timeout propagation +- [Phase 17]: /key enforced private-chat-only via chat.Type check; all other bot commands use masked keys ### Pending Todos @@ -166,6 +169,6 @@ None yet. ## Session Continuity -Last session: 2026-04-06T13:46:09.383Z -Stopped at: Completed 16-01-PLAN.md +Last session: 2026-04-06T14:36:30.924Z +Stopped at: Completed 17-03-PLAN.md Resume file: None diff --git a/.planning/phases/17-telegram-scheduler/17-03-PLAN.md b/.planning/phases/17-telegram-scheduler/17-03-PLAN.md new file mode 100644 index 0000000..f0ea258 --- /dev/null +++ b/.planning/phases/17-telegram-scheduler/17-03-PLAN.md @@ -0,0 +1,82 @@ +--- +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 ` — trigger scan on path, return findings (masked only, never unmasked in Telegram) +- `/verify ` — 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 ` — 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 diff --git a/.planning/phases/17-telegram-scheduler/17-03-SUMMARY.md b/.planning/phases/17-telegram-scheduler/17-03-SUMMARY.md new file mode 100644 index 0000000..01b9cac --- /dev/null +++ b/.planning/phases/17-telegram-scheduler/17-03-SUMMARY.md @@ -0,0 +1,68 @@ +--- +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 `: 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