Heimdall/docs/implementation-plan.md

127 lines
3.8 KiB
Markdown
Raw Normal View History

2026-04-26 11:41:27 +01:00
# Heimdall Implementation Plan
2026-04-26 05:18:35 +01:00
## What this file is
2026-04-26 11:41:27 +01:00
This file is the forward plan and active hypothesis ledger for Heimdall.
2026-04-26 05:18:35 +01:00
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:
2026-04-26 11:41:27 +01:00
- the shared architecture note
2026-04-26 05:18:35 +01:00
- app-binding notes for Repixelizer and StreamPixels
2026-04-26 11:41:27 +01:00
- explicit state/doctrine scaffolding so the plan does not immediately turn
into soup
2026-04-26 05:18:35 +01:00
## Primary objective
2026-04-26 11:41:27 +01:00
Build Heimdall as a shared auth authority service that can:
2026-04-26 05:18:35 +01:00
- own provider OAuth and identity linking
2026-04-26 11:41:27 +01:00
- issue signed sessions and app-facing claims
2026-04-26 05:18:35 +01:00
- refresh Discord and Patreon entitlements
- evaluate per-app capability rules
2026-04-26 11:41:27 +01:00
- expose a clean contract to app backends without owning their domain data
2026-04-26 05:18:35 +01:00
## Current priorities
2026-04-26 11:41:27 +01:00
### 1. Lock the service boundary
2026-04-26 05:18:35 +01:00
Goals:
2026-04-26 11:41:27 +01:00
- keep Heimdall scoped to auth/control-plane machinery
2026-04-26 05:18:35 +01:00
- keep app-domain data in app-owned stores
- keep app profiles thin and explicit
2026-04-26 11:41:27 +01:00
### 2. Define the contract before the service grows teeth
2026-04-26 05:18:35 +01:00
Goals:
2026-04-26 11:41:27 +01:00
- define signed claim/session shapes
- define OAuth start/callback/link surfaces
- define grant and entitlement persistence boundaries
- define how app backends verify claims locally
2026-04-26 05:18:35 +01:00
2026-04-26 11:41:27 +01:00
### 3. Make Repixelizer the first auth-blank consumer
2026-04-26 05:18:35 +01:00
Goals:
2026-04-26 11:41:27 +01:00
- gate hosted access and queue submission through Heimdall-issued claims
2026-04-26 05:18:35 +01:00
- attach queue ownership to `account_id` and `session_id`
- preserve the existing hosted GUI and queue runtime
2026-04-26 11:41:27 +01:00
### 4. Migrate StreamPixels without flattening its good local seams
2026-04-26 05:18:35 +01:00
Goals:
2026-04-26 11:41:27 +01:00
- move provider/linking authority toward Heimdall
2026-04-26 05:18:35 +01:00
- keep viewer profiles, creator memberships, connector creds, and audience data
in StreamPixels
2026-04-26 11:41:27 +01:00
- 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
2026-04-26 05:18:35 +01:00
## Proposed phases
2026-04-26 11:41:27 +01:00
### 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
2026-04-26 05:18:35 +01:00
2026-04-26 11:41:27 +01:00
- create the first real service layout for:
- provider OAuth start/callback routes
- account / linked-identity persistence
- session issuance and refresh
- capability evaluation
- audit logging
2026-04-26 05:18:35 +01:00
2026-04-26 11:41:27 +01:00
### Phase 3: Repixelizer binding
2026-04-26 05:18:35 +01:00
2026-04-26 11:41:27 +01:00
- integrate Heimdall into the hosted demo
2026-04-26 05:18:35 +01:00
- gate `POST /api/jobs`
- gate per-job read/cancel/event routes by local session ownership
2026-04-26 11:41:27 +01:00
### Phase 4: StreamPixels authority migration
2026-04-26 05:18:35 +01:00
2026-04-26 11:41:27 +01:00
- 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
2026-04-26 05:18:35 +01:00
2026-04-26 11:41:27 +01:00
### Phase 5: Ops and deploy
2026-04-26 05:18:35 +01:00
2026-04-26 11:41:27 +01:00
- define nginx/systemd/env/runbook surfaces for Heimdall on Yggdrasil
- keep callers and state stores localhost-first where practical
2026-04-26 05:18:35 +01:00
## Guardrails
- do not let auth reuse become data mixing
2026-04-26 11:41:27 +01:00
- 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
2026-04-26 05:18:35 +01:00
- do not duplicate the shared architecture note into app profiles
2026-04-26 11:41:27 +01:00
- do not rip out app-local ownership and authorization logic that still belongs
in the app
2026-04-26 05:18:35 +01:00
- keep one clear hypothesis per pass
- commit completed work before the planning notes start breeding