Heimdall/notes/fresh-workspace-handoff.md

# Fresh Workspace Handoff

This is the re-entry packet for this repo (path: whatever the checkout is; it has moved drives before).

It is intentionally short. Historical proof belongs in git history and the
distilled `state/evidence.jsonl` ledger; the shared architecture belongs in
`docs/architecture.md`; the forward build order belongs in
`docs/implementation-plan.md`.

## Rehydrate

From the repo root:

```powershell
python .\tools\heimdall_state.py status
Get-Content '.\state\map.yaml'
Get-Content '.\notes\fresh-workspace-handoff.md'
Get-Content '.\docs\architecture.md'
Get-Content '.\docs\implementation-plan.md'
git status --short --branch
git log --oneline -5
Get-Content '.\state\evidence.jsonl' -Tail 8
```

Do not trust this file for the exact live HEAD. Always check git.

## Active Work

Joystick H1 is merged and live (PR GameCult/Heimdall#1; campaign
`joystick:campaign:self`). Next: `joystick:follow_up:h1-joystick-consent-round-trip`, then
StreamPixels S0/S1 (other sessions). Open Heimdall follow-ups, by id:
`joystick:follow_up:cross-process-failed-refresh-marker`,
`joystick:follow_up:connect-start-needs-app-auth`,
`joystick:follow_up:heimdall-idunn-onboarding`,
`joystick:follow_up:joystick-viewer-signin-public-bot`. The Ghostlight KLTST
canaries below stay open, behind them.

## Current Orientation

Yggdrasil runs Heimdall `d51fa6b`, hand-deployed 2026-10-19 15:51Z;
gamecult-ops `210a1af` records backup, rollback and provenance. Facts below
about Odin, Ghostlight and CultLib pins were verified at `1086aee` (2026-08-22)
and are not re-verified at `d51fa6b`.

- At `1086aee01169bf60e8a492b2740db1c6f3e8cabf` Heimdall ran with CultLib
  `5cefa0db0079a8e3ee22f29d7b9e6e5aa60912a9`
- Heimdall publishes four redacted access records to Odin under unique keys:
  `eve:provider:heimdall`, `heimdall:command-boundary`,
  `eve:plugin:gamecult.heimdall.access`, and `heimdall:transport-profile`
- Odin `b4f9a2e95f0b41cebdeddc49223781d1d3c7b42a` persists and returns all four;
  it does not proxy private commands or receive claims
- Ghostlight `b515ca90c25573005a616244143803b37f2d06ec` resolves the boundary through
  Odin and accepted a live canonical anonymous `heimdall.auth.begin`; its unit
  has no direct Heimdall endpoint

- `gamecult.heimdall.access` now has a manifest, advertisement, schemas,
  fixtures, executable `describe`/`validate`/`project` ABI, and browser
  reference adapter
- Heimdall persists OAuth attempts and serves authenticated
  `heimdall.auth.begin` / `heimdall.auth.complete` / `heimdall.auth.refresh` /
  `heimdall.auth.logout` through loopback
  CultNet/RUDP on port `4101`
- private commands are source-runtime, app-secret, expiry, nonce, and
  idempotency bound; their MessagePack payloads and completion claims are
  AES-256-GCM wrapped
- the Ghostlight app profile now requires its caller-owned Discord role policy;
  Heimdall evaluates it and Ghostlight remains owner of local sessions,
  memberships, and campaigns
- refresh verifies the exact persisted session revision before reissuing a
  claim; logout expires that session and advances its revision, so a stale or
  racing refresh cannot resurrect revoked custody

- this repo now has a first stateful Heimdall service slice
- the canonical shared architecture lives in `docs/architecture.md`
- the concrete HTTP/JWKS contract lives in `docs/service-contract.md`
- app profiles live under `docs/app-profiles/`
- the key boundary is explicit:
  - Heimdall owns OAuth, linking, managed provider credential custody, grants,
    entitlement refresh, and signed claim issuance
  - app-domain data stays app-owned by default
  - host apps verify signed claims locally for routine auth instead of calling
    Heimdall on every request
- the landed service now exposes:
  - `/.well-known/jwks.json`
  - `/.well-known/heimdall-configuration`
  - `/v1/oauth/{provider}/start`
  - `/v1/oauth/{provider}/callback`
  - `/v1/apps/{appSlug}/auth-completions/redeem`
  - `/v1/apps/{appSlug}/sessions/refresh`
  - `/v1/apps/{appSlug}/managed-credentials/resolve`
- the Discord callback path now performs real code exchange, identity
  resolution, auth persistence, entitlement evaluation, audit logging, and
  claim issuance for the Repixelizer slice
- browser-style auth handoff now uses a one-time completion code posted back to
  the opener, with backend redemption instead of fragment-token handoff
- same-host or Yggdrasil-reachable app integrations can now ask Heimdall to
  deliver the auth result directly to an app backend callback endpoint, leaving
  the browser with only status/attempt signaling
- signing keys can now load from a persisted file path and bootstrap that file
  on first boot when explicitly enabled
- managed provider tokens are now sealed at rest with AES-256-GCM instead of
  being dumped into "encrypted" columns raw like an insult
- `src/verifier.ts` now provides a small local JWT verifier seam for app
  backends
- Repixelizer has consumed the backend-callback flow in its hosted web layer:
  it creates local auth attempts, asks Heimdall to start OAuth, receives the
  direct backend callback, verifies Heimdall Ed25519 access tokens locally, and
  adopts httpOnly local sessions
- Heimdall is now deployed on Yggdrasil at `https://heimdall.gamecult.org`
  behind nginx/TLS with Postgres storage, file-backed signing-key bootstrap,
  configured token custody, and public health/discovery/JWKS checks passing
- Repixelizer is now deployed on Yggdrasil at
  `https://repixelizer.gamecult.org` with Heimdall mode enabled, Discord and
  Patreon as public providers, required access enabled, and queue protection
  enabled
- Repixelizer public auth-start returns Discord and Patreon authorization URLs
  using the Heimdall callback and Repixelizer backend handoff
- Repixelizer auth now has a refresh path: Heimdall issues signed refresh
  tokens with access claims, `/v1/apps/{appSlug}/sessions/refresh` reissues
  short-lived access claims, and Discord/Patreon provider tokens refresh inside
  Heimdall before entitlement re-evaluation
- Twitch and YouTube now have generic OAuth exchange and identity runtimes
- GitHub is still catalogued, but its callback runtime is not implemented
- StreamPixels now delegates viewer and creator Twitch/YouTube OAuth to
  Heimdall, redeems Heimdall completion codes server-side, writes its own
  viewer sessions and connector bindings, and resolves current provider access
  tokens from Heimdall without storing refresh tokens locally
- Spotiverse now delegates Spotify OAuth to Heimdall. Heimdall has a
  `spotiverse` app profile and `spotify` provider runtime; Spotiverse stores a
  local Heimdall account binding and resolves current Spotify access through
  `/v1/apps/spotiverse/managed-credentials/resolve` without storing provider
  refresh tokens.
- Bifrost now has a `bifrost` app profile for Discord/Patreon member access.
  Bifrost sends caller-owned KTLST Discord role and Patreon tier policies
  through trusted backend-callback OAuth starts; Heimdall owns provider
  OAuth/token custody and configured backend callback allowlisting.
- Bifrost patron support sync now reuses Heimdall's existing linked Patreon
  identity and membership reader. `POST /v1/apps/bifrost/patron-support/sync`
  is app-authenticated, refreshes the stored Patreon credential if needed,
  reads active paid Patreon tier evidence, and emits a signed
  `RecurringSupportSnapshot` to Bifrost's
  `/heimdall/patron-support/events` intake.
- Public Yggdrasil Heimdall has been deployed with the Spotiverse/Spotify code
  path, Spotify provider credentials, a Spotiverse shared secret, and an
  allowlisted loopback portal callback at
  `http://127.0.0.1:18796/auth/heimdall/callback`.
- Heimdall and StreamPixels are deployed on Yggdrasil for the StreamPixels
  migration slice; Twitch callback handling has been patched so provider token
  `scope` can be either a space-delimited string or an array
- live StreamPixels Twitch sign-in through Heimdall has succeeded on Yggdrasil
  and Heimdall audit showed callback success, completion creation, and
  completion redemption
- the ignored local `secrets/heimdall-service.env` artifact now has
  `GC_ACCESS_PROVIDER_TWITCH_*` and `GC_ACCESS_PROVIDER_YOUTUBE_*` populated
  for the StreamPixels migration slice
- the intended first deployment shape is a Heimdall service on Yggdrasil behind
  nginx, not an embedded cross-runtime shared library fantasy
- Heimdall now writes a daemon-owned boundary witness store at
  `GC_ACCESS_CULTCACHE_PATH` containing provider advertisement, command
  boundary, transport profile, and daemon-health summary state
- Heimdall can now publish `heimdall.cultnet-rudp-provider-health` to Idunn
  over `cultnet.transport.rudp.v0` when `GC_ACCESS_IDUNN_RUDP_HEALTH` is
  configured; HTTP `/healthz`, JWKS, discovery, systemd, and nginx routing
  remain compatibility witnesses
- Since `1086aee` Heimdall persists its private
  provider-health identity at `/srv/heimdall/keys/provider-health-identity.cc`
  and publishes canonical signed health independently of the slower Verse
  snapshot cadence. Idunn owns the exact root trust binding, authenticated
  admission, lifecycle decision, and redacted public `.cc` projection.
- Odin commit `b4f9a2e95f0b41cebdeddc49223781d1d3c7b42a` retains the RUDP health
  reliability cut and registers Heimdall's command-boundary, plugin, and
  transport schemas so the typed catalog can persist rather than silently drop
  them. Live proof returned all four exact Heimdall records.

## Critical Doctrine

- Persistent state is the agent's mind.
- Cut stale architecture notes as ruthlessly as stale code.
- Do not mistake "shared auth" for "shared database."
- Do not mistake "shared auth service" for "every guarded route must call the
  mothership."
- If compaction hits before boundary findings are persisted, that work is gone.
  Re-gather it instead of pretending continuity happened.

## Next Real Move

The Active Work follow-ups first. Everything below is the standing queue.

Do not continue implementation automatically from a rehydrate-only request.

The Idunn/swarm health transport cut is live. Do not regress Heimdall to
unsigned `idunn.daemon_health`, merge its private key into Idunn, or make HTTP
health an authority. The next product work is the Bifrost and remaining browser
verification listed below.

The active Ghostlight deployment cut is complete. The next Ghostlight work is a
real separate-account KLTST completion/refresh/logout canary, followed by the
eight-account Session Zero privacy and actor-binding smoke. Keep port `4101`
loopback-only and treat any claim, token, completion, app secret, or account
state in Odin/CultMesh/browser output as a release-blocking fault.

If the user asks to continue on Spotiverse, the current next move is the real
browser `/auth/login` flow through public Heimdall. The Yggdrasil SSH tunnel
must include reverse forward
`spotiverse-callback:18796:127.0.0.1:8796`, and local Spotiverse must point at
`https://heimdall.gamecult.org` with the matching `HEIMDALL_APP_SECRET`. Verify
managed credential resolution after login. Spotiverse should not regain local
Spotify OAuth token storage.

If the user asks to continue on StreamPixels, the current next move is real
browser verification:

- verify viewer claim/link through `https://streampixels.gamecult.org/auth/connect`
- Twitch viewer sign-in has already passed once; continue with YouTube and
  connector attachment verification
- verify creator connector attach from an admin creator session
- confirm StreamPixels persists local profile/connector binding state while
  Heimdall retains provider token custody
- if a provider callback fails, inspect Heimdall audit events and StreamPixels
  service logs before touching app/domain boundaries

Repixelizer still needs its real browser OAuth verification:

- open `https://repixelizer.gamecult.org/app/`
- start Discord sign-in with an account that has the `KLTST` or
  Patreon-synced `Inner Sanctum` role, or Patreon sign-in with a currently
  entitled tier titled `Inner Sanctum`
- confirm Repixelizer sends its app-owned provider policy in the
  backend-callback OAuth start
- confirm Heimdall receives the provider callback and evaluates entitlement
- confirm Repixelizer receives the backend callback, verifies the Heimdall
  token, adopts a local httpOnly session, and gates hosted/queue routes
- confirm the Discord authorization URL requests only `identify
  guilds.members.read`

Launch policy is role-gated on purpose: the GameCult Discord can remain public,
but Repixelizer access is limited to members with either `KLTST` or the
Patreon-synced `Inner Sanctum` role. Repixelizer owns that role policy through
its own runtime env and sends it to Heimdall during backend-callback OAuth
start; Heimdall owns provider OAuth mechanics and claim issuance, not the
per-app role list.

Patreon access is title-gated on the currently entitled tier title
`Inner Sanctum`; do not use currency amount as the durable policy because
currencies are weird little traps.

Bifrost needs browser verification after deployment:

- configure Heimdall with
  `GC_ACCESS_APP_BIFROST_BACKEND_CALLBACK_URLS=https://bifrost.gamecult.org/auth/heimdall/callback`
- configure Heimdall with `GC_ACCESS_APP_BIFROST_SHARED_SECRET_FILE`,
  `GC_ACCESS_BIFROST_PATRON_SUPPORT_ENDPOINT=https://bifrost.gamecult.org/heimdall/patron-support/events`,
  and `GC_ACCESS_BIFROST_PATRON_SUPPORT_SECRET_FILE`, each naming a credential
  file
- configure Bifrost with `Heimdall__DiscordGuildId`,
  `Heimdall__DiscordAllowedRoleIds__0=<KTLST-role-id>`, and
  `Heimdall__PatreonTierTitle=Inner Sanctum`
- configure Bifrost with the matching `Heimdall__PatronSupportIntakeSecret`
- start Discord sign-in from `https://bifrost.gamecult.org/` with a user that
  has the KTLST cult-member role
- start Patreon sign-in with a user that has the configured active tier
- confirm Bifrost creates/updates a local account and active standard
  membership while Heimdall keeps provider token custody
- trigger `/v1/apps/bifrost/patron-support/sync` for that linked Heimdall
  account and confirm Bifrost records a Patreon recurring-support snapshot
  without owning Patreon webhook or token custody

## Immediate Re-entry Instruction

After compaction, first rehydrate and reorient from the listed files and git
state. Wait for the user's next instruction unless they explicitly say to
continue.