uebliche

Appearance

Feature Plan: Twitch Connect & Live Indicator ​

Summary ​

  • Owner: Freddi
  • Status: Delivery
  • Target Release: 2025.11.x
  • Backlog Entry: docs/agendas/uebliche.md → 📥 Inbox (Twitch Login + ingame „LIVE“-Identifikator)

Goals ​

  • Let players link their Twitch account to Übliche via a secure OAuth flow and surface that connection in their profile.
  • Display a real-time “LIVE” identifier in-game (scoreboard/tab list/title overlay) when a connected player is currently streaming Übliche.
  • Provide staff tooling to verify Twitch link status and manually trigger rescans when stream metadata changes.

Scope ​

  • Build Twitch OAuth integration (authorization code + PKCE) within the dashboard/app, persisting tokens and profile metadata server-side.
  • Add backend services to poll the Twitch Helix API for live status and propagate updates to the Minecraft server in near real-time.
  • Extend player profile data structures to reference Twitch user IDs, display names, thumbnails, and last-live timestamps.
  • Deliver a minimally viable UI: linking screen, status badge in dashboard profile, and an in-game indicator (tab list suffix + optional action bar flash).
  • Out of scope: landing page embeds, cosmetics, or streamer scheduling features (tracked in separate backlog items).

Implementation Outline ​

  1. OAuth Setup
    • Register Twitch application (client ID/secret, redirect URIs for dev/prod).
    • Implement authorization code + PKCE flow in dashboard (reuse existing auth module patterns); handle login and linking separate from account sign-in.
    • Store access + refresh tokens encrypted alongside Twitch user metadata (id, login, display_name, profile_image_url).
  2. Backend Services
    • Create TwitchAuthService for token refresh + credential storage, with scheduled sweeps to keep tokens fresh.
    • Add TwitchLiveStatusService that queries Helix /streams for linked users (batching by 100 max) on a short cadence (e.g. 60s) and publishes status changes.
    • Expose REST endpoints and events to the Minestom layer so the game server can mark players as live when events fire.
  3. Game Server Integration
    • Extend player session metadata to carry Twitch connect info; on live updates, toggle scoreboard/tab decorations and broadcast optional chat/system message.
    • Add throttling so repeated toggles don’t spam players; ensure indicator clears when stream ends.
  4. Dashboard/UI Updates
    • Profile page: show Twitch linking panel with current status, refresh time, and unlink action.
    • Admin oversight: add Twitch column/filter to user directory or moderation tools to inspect link/live state.
  5. Security & Compliance
    • Enforce scopes (user:read:email, maybe channel:read:stream_key not needed) with least privilege.
    • Log all link/unlink actions to audit trail; provide GDPR-compliant delete flow that revokes tokens via Twitch API.
  6. Observability
    • Metrics for OAuth success/failure, token refresh errors, Helix polling latency, live toggle counts.
    • Alerting when polling errors exceed threshold or live status falls behind expected cadence.

Dependencies ​

  • Twitch developer credentials and organization approval for redirect URIs.
  • Existing auth/session infrastructure in app and server modules for storing external identity links.
  • Minestom event bus or messaging channel to broadcast status changes to in-game clients.
  • Secrets management solution for Twitch client secret storage.

Risks & Mitigations ​

  • API rate limits: Batch Helix calls by user ID and cache responses; degrade gracefully to longer poll intervals on limit exhaustion.
  • Token expiry: Implement proactive refresh with jitter and fail-safe unlink fallback if refresh repeatedly fails.
  • Account hijack potential: Require re-auth when linking, confirm Minecraft identity via authenticated session, and add optional staff verification for suspicious links.
  • Live indicator accuracy: Double-check stream game/category equals Übliche (or configured set) before toggling; add manual override for false positives.

Validation Plan ​

  • Unit/integration tests for OAuth callback handler, token refresh, and live polling scheduler.
  • Stage environment manual test: link Twitch test user, start/stop stream, confirm live flag toggles in dashboard and in-game.
  • Pen-test review for callback endpoints and token storage.
  • Post-launch monitoring: dashboards for poll latency, mismatch counts, and volume of link/unlink actions.

Notes & Decisions ​

  • 2025-11-05 – Prefer PKCE flow to avoid storing client secret in front-end; server handles token exchange.
  • 2025-11-05 – Live indicator MVP uses scoreboard suffix + action bar pulse; evaluate hologram or particle effects later when cosmetics feature lands.
  • 2025-11-05 – OAuth linking (web popup + backend storage) landed; next: wire Helix polling + in-game LIVE indicator delivery.

References ​