BanGUI/Docs/Tasks.md

29) Blocklist URL validation has DNS-rebinding window

• Where found:
  • backend/app/utils/ip_utils.py
  • backend/app/services/blocklist_service.py
• Why this is needed:
  • Validation at create/update does not guarantee safe runtime destination.
• Goal:
  • Enforce SSRF safety at connect/request time as well.
• What to do:
  • Add runtime destination/IP allow-deny validation in HTTP layer.
• Possible traps and issues:
  • Resolver/cache behavior may vary across environments.
• Docs changes needed:
  • Add blocklist network security notes and runtime checks.
• Doc references:
  • Docs/Architekture.md
  • https://cheatsheetseries.owasp.org/cheatsheets/Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html

---

30) Setup persistence is non-atomic across DB contexts

• Where found:
  • backend/app/services/setup_service.py
  • backend/app/repositories/settings_repo.py
• Why this is needed:
  • Partial commits during setup can leave inconsistent state.
• Goal:
  • Make setup operations transactional and crash-safe.
• What to do:
  • Introduce staged setup state and transaction boundaries.
• Possible traps and issues:
  • SQLite transaction handling across multiple DB files is limited.
• Docs changes needed:
  • Add setup state machine and rollback behavior.
• Doc references:
  • Docs/Architekture.md

---

31) Fire-and-forget reschedule may fail silently

• Where found:
  • backend/app/tasks/blocklist_import.py
• Why this is needed:
  • Schedule update requests can succeed while background reschedule fails.
• Goal:
  • Make schedule updates deterministic and observable.
• What to do:
  • Await reschedule path or persist task outcome status and surface errors.
• Possible traps and issues:
  • Blocking request path might add latency if scheduler is busy.
• Docs changes needed:
  • Document scheduling reliability guarantees.
• Doc references:
  • Docs/Features.md

---

32) RateLimiter cleanup function is not scheduled/used

• Where found:
  • backend/app/utils/rate_limiter.py
  • backend/app/startup.py
• Why this is needed:
  • Rate limiter state can grow over long runtimes.
• Goal:
  • Ensure periodic cleanup or bounded memory strategy.
• What to do:
  • Add scheduled cleanup or auto-eviction structure.
• Possible traps and issues:
  • Cleanup cadence too frequent can add overhead.
• Docs changes needed:
  • Add operational notes for auth throttling lifecycle.
• Doc references:
  • backend/app/utils/rate_limiter.py

---

33) Trusted proxy configuration is hardcoded in auth router

• Where found:
  • backend/app/routers/auth.py
  • backend/app/utils/client_ip.py
• Why this is needed:
  • Incorrect client IP extraction can break per-IP rate limiting behind proxies.
• Goal:
  • Move trusted proxies to validated runtime config.
• What to do:
  • Add settings for trusted proxy IPs/CIDRs.
  • Validate and use these in client IP extraction.
• Possible traps and issues:
  • Over-trusting headers can enable spoofing.
• Docs changes needed:
  • Add reverse-proxy deployment configuration section.
• Doc references:
  • Docs/Instructions.md

---

34) Setup redirect allowlist uses broad prefix matching

• Where found:
  • backend/app/main.py
• Why this is needed:
  • Prefix-based allow rules are fragile for future route additions.
• Goal:
  • Use exact path or route-level allow policy.
• What to do:
  • Replace startswith matching with explicit allowlist checks.
• Possible traps and issues:
  • API docs and setup flow paths must remain reachable.
• Docs changes needed:
  • Add setup guard route policy documentation.
• Doc references:
  • backend/app/main.py

---

35) API client sends JSON and CSRF header for every request method

• Where found:
  • frontend/src/api/client.ts
• Why this is needed:
  • Extra headers on GET increase unnecessary CORS preflights and noise.
• Goal:
  • Apply headers by method/body requirements.
• What to do:
  • Only set Content-Type for requests with JSON body.
  • Send CSRF header for mutating cookie-authenticated requests only.
• Possible traps and issues:
  • CSRF protection assumptions must still hold for all mutating paths.
• Docs changes needed:
  • Update frontend API client contract and CSRF notes.
• Doc references:
  • backend/app/middleware/csrf.py

---

36) Polling continues when tab is not visible

• Where found:
  • frontend/src/hooks/usePolledData.ts
  • frontend/src/hooks/useBlocklistStatus.ts
• Why this is needed:
  • Unnecessary backend load and client resource usage in background tabs.
• Goal:
  • Pause/reduce polling when page is hidden.
• What to do:
  • Add visibility-aware polling strategy and optional backoff.
• Possible traps and issues:
  • Data may appear stale immediately after tab restore if refresh is delayed.
• Docs changes needed:
  • Add frontend polling lifecycle policy.
• Doc references:
  • Docs/Web-Development.md

---

37) Multi-worker safety check depends on one environment variable

• Where found:
  • backend/app/startup.py
• Why this is needed:
  • Other process managers can still launch multiple workers without this variable.
• Goal:
  • Enforce scheduler single-executor safety regardless of launcher.
• What to do:
  • Add robust single-run lock/leader mechanism for scheduler ownership.
• Possible traps and issues:
  • Locking strategy must be reliable in container orchestration.
• Docs changes needed:
  • Expand deployment constraints and supported run modes.
• Doc references:
  • Docs/Architekture.md

---

38) History archive query paths may need explicit indexing plan

• Where found:
  • backend/app/db.py
  • backend/app/repositories/history_archive_repo.py
• Why this is needed:
  • Large archive datasets can degrade filter/sort performance.
• Goal:
  • Add indexes aligned with real query patterns.
• What to do:
  • Benchmark common history queries.
  • Add migration with targeted indexes.
• Possible traps and issues:
  • Extra indexes increase write cost and DB size.
• Docs changes needed:
  • Add DB performance/indexing section for history.
• Doc references:
  • Docs/Backend-Development.md
  • https://www.sqlite.org/queryplanner.html

---

39) No explicit DI container strategy for backend service graph

• Where found:
  • backend/app/dependencies.py
  • backend/app/services
• Why this is needed:
  • Dependency construction and lifecycle are partly implicit.
• Goal:
  • Define a clear dependency wiring pattern for services and repositories.
• What to do:
  • Create service composition root pattern and document usage.
• Possible traps and issues:
  • Over-engineering if container abstraction is too heavy for current size.
• Docs changes needed:
  • Add dependency wiring chapter.
• Doc references:
  • Docs/Architekture.md

---

40) Frontend and backend observability are not aligned

• Where found:
  • backend/app/main.py
  • frontend/src
• Why this is needed:
  • Backend uses structured logging while frontend error telemetry is mostly local and ad-hoc.
• Goal:
  • Define unified error telemetry and correlation approach.
• What to do:
  • Introduce frontend error reporting pipeline and request correlation IDs.
• Possible traps and issues:
  • PII/sensitive payload leakage risk in client-side telemetry.
• Docs changes needed:
  • Add observability and privacy-safe logging guidelines.
• Doc references:
  • Docs/Architekture.md
  • Docs/Web-Development.md