Heimdall/README.md

# Heimdall

Heimdall is the shared auth authority taking shape for GameCult-hosted
experiments.

The point is painfully simple:

- stop rebuilding Discord/Patreon login glue in every app
- keep provider OAuth, linked identities, grants, entitlements, and session
  issuance in one place
- let app runtimes verify signed claims locally so "shared auth" does not
  become "everything phones home for every request"
- keep app-domain data separate so "shared auth" does not become "shared swamp"

## Front Door

- **Value:** one shared auth authority: provider OAuth (Discord, Patreon, GitHub, Twitch, YouTube, Spotify), linked identities, grants, entitlements and session issuance, with Ed25519-signed claims that app backends verify locally.
- **Problem:** every GameCult app was rebuilding Discord/Patreon login glue. Heimdall centralizes identity authority and keeps app-domain data in the apps.
- **Entry points:**
  - `src/index.ts` and `src/app.ts`: the Fastify service. `src/signing.ts` and `src/claims.ts` issue JWTs and serve `/.well-known/jwks.json`; `src/oauth.ts` and `src/providers.ts` own provider flows.
  - `src/verifier.ts`: the local verifier helper an app backend imports to validate Heimdall JWTs without phoning home.
  - `src/odin-publication.ts` and `plugins/gamecult.heimdall.access`: the redacted Odin/Eve provider advertisement and the `gamecult.heimdall.access` plugin (`docs/eve-access-plugin.md`).
  - `docs/architecture.md`, `docs/service-contract.md`, `docs/verse-service-contract.md`, `docs/app-profiles/`: the contracts.
  - `pnpm install`, `pnpm dev`, `pnpm test` (see Dev Commands).
- **Live:** a stateful first slice: signing and JWKS, OAuth state for six providers, in-memory and Postgres stores, a real Discord callback path for the Repixelizer flow, sealed provider tokens, the loopback CultNet operation boundary, Idunn health publication, and the deployed Ghostlight Eve host consuming the discovered boundary.
- **Planned:** the two-account and eight-account Ghostlight human canaries, refresh and revocation flows, admin surfaces, and broader inspection projections beyond the redacted access boundary.

## Current Shape

This repo now has a stateful first slice instead of a decorative skeleton.

Landed right now:

- a TypeScript/Fastify service scaffold under `src/`
- Ed25519 JWT signing plus `/.well-known/jwks.json`
- file-backed signing-key loading/bootstrap so restart does not vaporize the
  service identity when you configure a real key path
- signed OAuth start-state scaffolding for Discord, Patreon, GitHub, Twitch,
  YouTube, and Spotify
- durable auth/control-plane storage with in-memory and Postgres backends
- account, linked-identity, session, persistent OAuth attempt, grant,
  entitlement snapshot, and audit
  persistence
- a real Discord OAuth callback path for the first Repixelizer access flow
- direct backend callback handoff for same-host or Yggdrasil-reachable app
  backends
- AES-256-GCM sealing for managed provider tokens at rest
- a one-time browser completion exchange kept as fallback for opener
  `postMessage` handoff
- app profile surfaces for Repixelizer, StreamPixels, and Spotiverse
- signed claim issuance for app-local verification experiments
- a local verifier helper in `src/verifier.ts` so app backends can validate
  Heimdall JWTs without phoning home on every guarded request
- a read-only Odin/Eve provider advertisement export that names redacted
  CultCache witness document shapes and paths without touching live secrets
- a daemon-owned CultCache boundary witness at `GC_ACCESS_CULTCACHE_PATH`
  containing the Heimdall provider advertisement, command boundary, transport
  profile, and Idunn daemon-health summary
- optional Idunn daemon-health publication over `cultnet.transport.rudp.v0`
  when `GC_ACCESS_IDUNN_RUDP_HEALTH` is configured
- the `gamecult.heimdall.access` Eve plugin with executable `describe`,
  `validate`, and `project` operations plus a browser reference adapter
- a loopback-only CultNet operation boundary on port `4101` for authenticated
  `heimdall.auth.begin` and `heimdall.auth.complete`; app payloads and completion
  claims are AES-256-GCM wrapped and HMAC-bound to expiry, nonce, operation,
  runtime, and idempotency identity
- redacted provider, command-boundary, plugin, and transport records published
  through Odin under unique typed catalog keys; secret-bearing auth state never
  enters the catalog
- the deployed Ghostlight Eve host consumes that discovered boundary and keeps
  routine app-session verification local

Remaining work:

- the two-account and eight-account Ghostlight human canaries
- refresh/revocation flows and admin surfaces
- broader admin and inspection projections beyond the redacted access boundary

Canonical docs:

- `docs/architecture.md`
- `docs/implementation-plan.md`
- `docs/service-contract.md`
- `docs/verse-service-contract.md`
- `docs/app-profiles/repixelizer.md`
- `docs/app-profiles/streampixels.md`
- `docs/app-profiles/spotiverse.md`
- `state/map.yaml`
- `notes/fresh-workspace-handoff.md`

## Dev Commands

```powershell
pnpm install
pnpm dev
pnpm test
pnpm build
pnpm export:provider-advertisement
```

## Working Loop

1. Rehydrate from canonical state.
2. Keep identity authority central and app-domain data local.
3. Prefer a Yggdrasil-hosted shared service over duplicated per-app provider
   stacks.
4. Let app backends verify signed claims locally instead of begging Heimdall on
   every guarded route.
5. Commit finished passes before the notes start breeding.