From a7daed3b85468c842fc792bb73c943f7be3c50cb Mon Sep 17 00:00:00 2001 From: salvacybersec Date: Mon, 6 Apr 2026 17:34:28 +0300 Subject: [PATCH] docs(17-04): complete subscribe/unsubscribe + notification dispatcher plan Co-Authored-By: Claude Opus 4.6 (1M context) --- .planning/REQUIREMENTS.md | 6 +- .planning/ROADMAP.md | 8 +- .planning/STATE.md | 14 ++- .../17-telegram-scheduler/17-04-SUMMARY.md | 103 ++++++++++++++++++ 4 files changed, 118 insertions(+), 13 deletions(-) create mode 100644 .planning/phases/17-telegram-scheduler/17-04-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index dd22aa3..af3bbee 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -236,15 +236,15 @@ Requirements for initial release. Each maps to roadmap phases. - [ ] **TELE-02**: /verify command — key verification - [ ] **TELE-03**: /recon command — dork execution - [ ] **TELE-04**: /status, /stats, /providers, /help commands -- [ ] **TELE-05**: /subscribe and /unsubscribe for auto-notifications +- [x] **TELE-05**: /subscribe and /unsubscribe for auto-notifications - [ ] **TELE-06**: /key command — full key detail in private chat -- [ ] **TELE-07**: Auto-notification on new key findings +- [x] **TELE-07**: Auto-notification on new key findings ### Scheduled Scanning - [x] **SCHED-01**: Cron-based recurring scan scheduling - [ ] **SCHED-02**: keyhunter schedule add/list/remove commands -- [ ] **SCHED-03**: Auto-notify on scheduled scan completion +- [x] **SCHED-03**: Auto-notify on scheduled scan completion ## v2 Requirements diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 75f1a84..4a3179d 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -342,10 +342,10 @@ Plans: **Plans**: 5 plans Plans: -- [ ] 17-01-PLAN.md — Bot package skeleton: telego dependency, Bot struct, long polling, auth middleware -- [ ] 17-02-PLAN.md — Scheduler package + storage tables: gocron wrapper, subscribers/scheduled_jobs CRUD +- [x] 17-01-PLAN.md — Bot package skeleton: telego dependency, Bot struct, long polling, auth middleware +- [x] 17-02-PLAN.md — Scheduler package + storage tables: gocron wrapper, subscribers/scheduled_jobs CRUD - [ ] 17-03-PLAN.md — Bot command handlers: /scan, /verify, /recon, /status, /stats, /providers, /help, /key -- [ ] 17-04-PLAN.md — Subscribe/unsubscribe handlers + notification dispatcher (scheduler→bot bridge) +- [x] 17-04-PLAN.md — Subscribe/unsubscribe handlers + notification dispatcher (scheduler→bot bridge) - [ ] 17-05-PLAN.md — CLI wiring: cmd/serve.go + cmd/schedule.go replacing stubs ### Phase 18: Web Dashboard @@ -391,5 +391,5 @@ Phases execute in numeric order: 1 → 2 → 3 → ... → 18 | 14. OSINT CI/CD Logs, Web Archives & Frontend Leaks | 1/1 | Complete | 2026-04-06 | | 15. OSINT Forums, Collaboration & Log Aggregators | 2/4 | Complete | 2026-04-06 | | 16. OSINT Threat Intel, Mobile, DNS & API Marketplaces | 0/? | Complete | 2026-04-06 | -| 17. Telegram Bot & Scheduled Scanning | 0/5 | Not started | - | +| 17. Telegram Bot & Scheduled Scanning | 3/5 | In Progress| | | 18. Web Dashboard | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 943812a..0ca1ce2 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 17-01-PLAN.md -last_updated: "2026-04-06T14:28:54.411Z" +stopped_at: Completed 17-04-PLAN.md +last_updated: "2026-04-06T14:34:18.714Z" last_activity: 2026-04-06 progress: total_phases: 18 completed_phases: 14 - total_plans: 85 - completed_plans: 84 + total_plans: 90 + completed_plans: 86 percent: 20 --- @@ -101,6 +101,7 @@ Progress: [██░░░░░░░░] 20% | Phase 15 P03 | 4min | 2 tasks | 11 files | | Phase 16 P01 | 4min | 2 tasks | 6 files | | Phase 17 P01 | 3min | 2 tasks | 4 files | +| Phase 17 P04 | 3min | 2 tasks | 4 files | ## Accumulated Context @@ -154,6 +155,7 @@ Recent decisions affecting current work: - [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 promoted from indirect to direct; context cancellation for graceful shutdown; rate limit 60s scan/verify/recon, 5s others +- [Phase 17]: Separated format from send for testable notifications without telego mock ### Pending Todos @@ -168,6 +170,6 @@ None yet. ## Session Continuity -Last session: 2026-04-06T14:28:54.406Z -Stopped at: Completed 17-01-PLAN.md +Last session: 2026-04-06T14:34:18.710Z +Stopped at: Completed 17-04-PLAN.md Resume file: None diff --git a/.planning/phases/17-telegram-scheduler/17-04-SUMMARY.md b/.planning/phases/17-telegram-scheduler/17-04-SUMMARY.md new file mode 100644 index 0000000..557dec5 --- /dev/null +++ b/.planning/phases/17-telegram-scheduler/17-04-SUMMARY.md @@ -0,0 +1,103 @@ +--- +phase: 17-telegram-scheduler +plan: 04 +subsystem: telegram +tags: [telego, telegram, notifications, subscribers, scheduler] + +requires: + - phase: 17-01 + provides: Bot struct, Config, command dispatch, Start/Stop lifecycle + - phase: 17-02 + provides: subscribers table CRUD (AddSubscriber, RemoveSubscriber, ListSubscribers, IsSubscribed), scheduler JobResult + +provides: + - /subscribe and /unsubscribe command handlers + - NotifyNewFindings dispatcher (scheduler to bot bridge) + - NotifyFinding real-time individual finding notification + - formatNotification/formatErrorNotification/formatFindingNotification helpers + +affects: [17-05, serve-command, scheduled-scanning] + +tech-stack: + added: [] + patterns: [separate-format-from-send for testable notification logic, per-subscriber error resilience] + +key-files: + created: + - pkg/bot/subscribe.go + - pkg/bot/notify.go + - pkg/bot/subscribe_test.go + modified: + - pkg/bot/bot.go + +key-decisions: + - "Separated formatting from sending for testability without mocking telego" + - "Nil bot field used as test-mode indicator to skip actual SendMessage calls" + - "Zero-finding results produce no notification (silent success)" + +patterns-established: + - "Format+Send separation: formatNotification returns string, NotifyNewFindings iterates subscribers" + - "Per-subscriber resilience: log error and continue to next subscriber on send failure" + +requirements-completed: [TELE-05, TELE-07, SCHED-03] + +duration: 3min +completed: 2026-04-06 +--- + +# Phase 17 Plan 04: Subscribe/Unsubscribe + Notification Dispatcher Summary + +**/subscribe and /unsubscribe handlers with NotifyNewFindings dispatcher bridging scheduler job completions to Telegram messages for all subscribers** + +## Performance + +- **Duration:** 3 min +- **Started:** 2026-04-06T14:30:33Z +- **Completed:** 2026-04-06T14:33:36Z +- **Tasks:** 2 +- **Files modified:** 4 + +## Accomplishments +- /subscribe checks IsSubscribed before adding, /unsubscribe reports rows affected +- NotifyNewFindings sends formatted message to all subscribers when scheduled scans find keys +- NotifyFinding provides real-time per-finding notification with always-masked keys +- 6 tests covering subscribe DB round-trip, no-subscriber no-op, zero-finding skip, message format validation + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Implement /subscribe, /unsubscribe handlers** - `d671695` (feat) +2. **Task 2: Notification dispatcher and tests (RED)** - `f7162aa` (test) +3. **Task 2: Notification dispatcher and tests (GREEN)** - `2643927` (feat) + +## Files Created/Modified +- `pkg/bot/subscribe.go` - /subscribe and /unsubscribe command handlers using storage layer +- `pkg/bot/notify.go` - NotifyNewFindings, NotifyFinding dispatchers with format helpers +- `pkg/bot/subscribe_test.go` - 6 tests for subscribe/unsubscribe and notification formatting +- `pkg/bot/bot.go` - Removed stub implementations replaced by subscribe.go + +## Decisions Made +- Separated formatting from sending: formatNotification/formatErrorNotification/formatFindingNotification return strings, tested independently without telego mock +- Nil telego.Bot field used as test-mode indicator to skip actual SendMessage calls while still exercising all logic paths +- Zero-finding scan completions produce no notification (avoids subscriber fatigue) +- Error results get a separate error notification format + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered +- go.sum had merge conflict markers from worktree merge; resolved by removing conflict markers and running go mod tidy + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness +- Notification pipeline complete: scheduler OnComplete -> NotifyNewFindings -> all subscribers +- Ready for Plan 17-05 (serve command integration wiring bot + scheduler together) + +--- +*Phase: 17-telegram-scheduler* +*Completed: 2026-04-06*