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 now a first landed Heimdall skeleton.

What exists right now is:

- the shared architecture note
- the concrete service contract in `docs/service-contract.md`
- app-binding notes for Repixelizer and StreamPixels
- a standalone TypeScript/Fastify service skeleton under `src/`
- Ed25519 JWT signing plus JWKS/discovery exposure
- OAuth start/callback contract surfaces with signed `state`
- app-profile-driven claim issuance for Repixelizer and StreamPixels
- in-memory/Postgres auth-control-plane storage
- persisted accounts, linked identities, sessions, grants, entitlement
  snapshots, and audit records
- a real Discord provider callback slice for Repixelizer access
- a direct backend callback handoff for same-host app integrations
- a one-time browser completion handoff so auth callback pages can post back to
  the opener instead of leaking final app auth in URL fragments, now retained
  as fallback rather than the preferred same-host path
- file-backed signing-key loading/bootstrap for stable service identity
- AES-256-GCM token sealing for managed provider credentials at rest
- a local verifier helper that app backends can use against Heimdall JWKS
- Repixelizer has consumed the direct backend callback flow in its hosted web
  layer and verifies Heimdall Ed25519 access tokens locally
- signed refresh tokens and `/v1/apps/{appSlug}/sessions/refresh` let app
  backends reissue short-lived app claims without restarting provider OAuth
- Discord and Patreon access-token refresh landed for Repixelizer entitlement
  re-evaluation
- generic Twitch and YouTube OAuth callback runtimes for StreamPixels identity
  and managed creator connections
- an app-authenticated managed-credential resolve endpoint so StreamPixels can
  call provider APIs without storing refresh tokens locally
- managed Twitch/YouTube/Joystick credentials refresh inside Heimdall before resolution
  when they are expired or near expiry
- StreamPixels now starts viewer and creator Twitch/YouTube OAuth through
  Heimdall, redeems one-time completion codes server-side, and keeps local
  profile/creator connector binding state in StreamPixels
- Heimdall is deployed on Yggdrasil at `https://heimdall.gamecult.org` with
  nginx/TLS, Postgres storage, stable file-backed signing, configured token
  custody, and public health/discovery/JWKS checks passing
- Repixelizer is deployed on Yggdrasil at
  `https://repixelizer.gamecult.org` with Heimdall mode enabled, Discord as the
  only public provider, required access, and queue protection
- explicit state/doctrine scaffolding so the plan does not immediately turn into
  soup
- a daemon-owned boundary witness store plus optional Idunn RUDP health pulse
  so Heimdall can advertise provider/boundary truth to Odin and Idunn without
  pretending HTTP/status checks own the daemon
- the `gamecult.heimdall.access` Eve plugin, persistent auth attempts, and a
  loopback-only authenticated CultNet command boundary for Ghostlight

## 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

### 0. Complete the Ghostlight Eve access cut

Landed in Heimdall:

- public plugin manifest, advertisement, state schemas, fixtures, pure ABI, and
  browser reference adapter
- persistent attempt lifecycle in memory and Postgres
- encrypted/HMAC-bound `heimdall.auth.begin` and `heimdall.auth.complete`
- exact source-runtime admission, nonce/expiry checks, idempotent retries, and
  single-use completion redemption
- Odin-safe plugin and private-route metadata without secret-bearing state

Remaining outside this repo:

- complete the two-account and eight-account Ghostlight human canaries
- pressure refresh, logout, stale completion, and Odin-outage behavior through
  the deployed browser host

Live proof:

- Heimdall `1086aee01169bf60e8a492b2740db1c6f3e8cabf` with CultLib
  `5cefa0db0079a8e3ee22f29d7b9e6e5aa60912a9` is active on Yggdrasil
- Odin's typed snapshot returns the provider, command boundary, plugin, and
  transport profile under their unique record keys
- Ghostlight accepted a canonical anonymous `heimdall.auth.begin` by resolving
  that boundary through Odin; the navigation receipt exposed only advertised
  Discord and Heimdall origins

### 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. Keep the contract tight while it goes live

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
  This now exists in reference form and Repixelizer has a Python consumer in
  its hosted web layer.

### 3. Launch Repixelizer with Discord first

Goals:

- deploy Heimdall on Yggdrasil with stable signing, encrypted token custody,
  and persistent Postgres storage
- configure the Discord OAuth app redirect URI to
  `https://heimdall.gamecult.org/v1/oauth/discord/callback`
- configure Heimdall's Discord client credentials for the Repixelizer-owned
  Discord OAuth app
- configure Repixelizer for `GC_ACCESS_MODE=heimdall` and
  `GC_ACCESS_ALLOWED_PROVIDERS=discord,patreon`
- configure Repixelizer's Discord access policy with its GameCult guild id and
  allowed role ids; Repixelizer sends that policy to Heimdall during the
  backend-callback OAuth start
- run the live browser OAuth flow and confirm Repixelizer receives the backend
  callback, verifies the claim locally, adopts a local session, gates hosted
  access, and stamps queued jobs with `account_id` / `session_id`

Deployment/configuration status:

- the deployment and service wiring are done
- public health/discovery/JWKS/config checks pass
- public Repixelizer auth-start returns Discord and Patreon authorization URLs
  using the Heimdall callback and Repixelizer backend handoff
- the Discord authorization URL requests only `identify guilds.members.read`
- the Patreon authorization URL requests only `identity identity[email]`
- the remaining launch check is the real interactive provider browser flow

Current Discord policy:

- Heimdall grants Repixelizer `entitlement.app_access` only when the Discord
  member has one of the role ids Repixelizer sent in its caller-owned
  entitlement policy
- launch policy is intentionally role-gated: the GameCult Discord can remain
  public, but Repixelizer access is limited to members with either `KLTST`
  or the Patreon-synced `Inner Sanctum` role

Current Patreon policy:

- Heimdall grants Repixelizer `entitlement.app_access` only when Patreon returns
  a currently entitled tier titled `Inner Sanctum`
- the policy is title-based, not amount-based

### 4. Migrate StreamPixels without flattening its good local seams

Goals:

- move provider/linking authority to Heimdall
- keep viewer profiles, creator memberships, connector bindings, diagnostics,
  runtime behavior, and audience data
  in StreamPixels
- keep creator/operator route authorization local to StreamPixels after claim
  verification

Landed:

- Heimdall handles Twitch/YouTube OAuth exchange and identity resolution
- Heimdall stores managed provider tokens and exposes current access-token
  resolution to app backends through an app shared secret
- StreamPixels delegates viewer claim/link and creator connector OAuth starts
  to Heimdall
- StreamPixels redeems completion codes through its service, then owns local
  viewer profile linking or creator connector binding

Still to verify:

- real browser StreamPixels viewer claim/link
- real creator connector attach for Twitch and YouTube
- runtime polling/subscription behavior using Heimdall-resolved credentials

### 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

Landed in the first pass:

- signed claim/session payload shape
- Ed25519 JWKS verification surface
- OAuth `state` and callback contract surfaces
- app profile / capability rule inputs and outputs

Still to do in this phase:

- key rotation policy instead of just stable key loading
- token custody retrieval and refresh have landed (see `docs/architecture.md`, Managed credential custody); the open pieces are the follow-ups listed there

### Phase 2: Heimdall service skeleton

Landed in the first pass:

- provider OAuth start route scaffolding
- callback route scaffolding with signed-state validation
- session/claim issuance contract
- capability evaluation for shared app capabilities

Next in this phase:

- connection lifecycle and token-rotation work

Landed for the Ghostlight private-command consumer:

- exact persisted-session validation for refresh
- revision-bound logout revocation with stale-refresh rejection

### Phase 3: Repixelizer binding

Landed in Repixelizer:

- Heimdall hosted auth mode
- direct backend callback receipt
- local Ed25519 JWT verification against Heimdall JWKS
- httpOnly local session adoption
- hosted landing-page provider buttons
- hosted route and queue/job ownership checks

Still to do for this phase:

- deploy and configure both services
- verify the real Discord OAuth path end to end

### 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