Heimdall/docs/implementation-plan.md

Heimdall Implementation Plan

What this file is

This file is the forward plan and active hypothesis ledger for Heimdall.

It is not the canonical shared architecture note. That lives in docs/architecture.md.

If the code or the architecture note disagrees with this plan, trust the code and the architecture note first, then fix this file.

Current machine

There is no landed auth machine here yet.

What exists right now is:

• the shared architecture note
• app-binding notes for Repixelizer and StreamPixels
• explicit state/doctrine scaffolding so the plan does not immediately turn into soup

Primary objective

Build Heimdall as a shared auth authority service that can:

• own provider OAuth and identity linking
• issue signed sessions and app-facing claims
• refresh Discord and Patreon entitlements
• evaluate per-app capability rules
• expose a clean contract to app backends without owning their domain data

Current priorities

1. Lock the service boundary

Goals:

• keep Heimdall scoped to auth/control-plane machinery
• keep app-domain data in app-owned stores
• keep app profiles thin and explicit

2. Define the contract before the service grows teeth

Goals:

• define signed claim/session shapes
• define OAuth start/callback/link surfaces
• define grant and entitlement persistence boundaries
• define how app backends verify claims locally

3. Make Repixelizer the first auth-blank consumer

Goals:

• gate hosted access and queue submission through Heimdall-issued claims
• attach queue ownership to account_id and session_id
• preserve the existing hosted GUI and queue runtime

4. Migrate StreamPixels without flattening its good local seams

Goals:

• move provider/linking authority toward Heimdall
• keep viewer profiles, creator memberships, connector creds, and audience data in StreamPixels
• keep creator/operator route authorization local to StreamPixels after claim verification

5. Capture the Yggdrasil deployment shape early

Goals:

• treat Heimdall as a localhost service behind nginx on Yggdrasil
• support same-host callers first
• avoid per-request network chatter for routine app authorization

Proposed phases

Phase 1: Contract and schema scaffold

• define:
  • signed claim/session payloads
  • JWKS or equivalent verification surface
  • OAuth state and callback contracts
  • grant / entitlement / audit record shapes
  • app profile / capability rule inputs and outputs

Phase 2: Heimdall service skeleton

• create the first real service layout for:
  • provider OAuth start/callback routes
  • account / linked-identity persistence
  • session issuance and refresh
  • capability evaluation
  • audit logging

Phase 3: Repixelizer binding

• integrate Heimdall into the hosted demo
• gate POST /api/jobs
• gate per-job read/cancel/event routes by local session ownership

Phase 4: StreamPixels authority migration

• replace provider/linking authority paths with Heimdall calls where they truly belong
• keep viewer/session expansion, creator memberships, and operator route enforcement local where they are app-domain concerns

Phase 5: Ops and deploy

• define nginx/systemd/env/runbook surfaces for Heimdall on Yggdrasil
• keep callers and state stores localhost-first where practical

Guardrails

• do not let auth reuse become data mixing
• do not turn Heimdall into a mandatory round-trip for every guarded app route
• do not fantasize about one shared cross-runtime embedded library; the apps can share contracts without sharing a runtime
• do not duplicate the shared architecture note into app profiles
• do not rip out app-local ownership and authorization logic that still belongs in the app
• keep one clear hypothesis per pass
• commit completed work before the planning notes start breeding