docs(auth): verify open/SMART auth end to end + local Keycloak (#198)

[angela-helios]

Deliverable for #198. Everything in the verification section was executed against a running stack (HFS + Keycloak 26.1 from docker/keycloak/), not read off the code.

docs/auth-verification.md covers

1. Auth verified end to end — a results table (14 checks): SMART discovery served + auth-exempt, 401 with no token, SMART v2 scope enforcement (full-access writes; read-only client gets 403 on create and on an out-of-scope type), signature/tampering, algorithm allow-list, issuer, JWKS fetch, JTI (all three backends), and audience (positive + negative).
2. Local Keycloak runbook — bring-up, token retrieval, running HFS against the realm, accept/deny.
3. UI login flow — the intended browser Authorization Code + PKCE flow (sequence diagram) and exactly what HFS must add (authorize/callback routes, server-side state + PKCE verifier, session cookie, discovery wiring, a public realm client). Design for a follow-up, not built here.
4. Login-screen theming matrix — Keycloak / Okta / Auth0 / Entra: what each can customize and how portable it is, with a recommendation (do IdP-native theming; ship a Helios Keycloak theme; document branding knobs for the others; keep HFS out of the login-screen business).

Defects found while verifying (filed separately)

• auth: JTI replay cache rejects legitimate reuse of bearer access tokens (default config unusable with Keycloak) #205 — the JTI replay cache rejects legitimate reuse of a bearer access token: the 2nd request with the same still-valid token is 401ed. Single-use jti belongs to private_key_jwt client assertions (IdP-side), not resource-server access tokens. With the default memory backend HFS is effectively unusable against Keycloak until HFS_AUTH_JTI_BACKEND=disabled. redis behaves the same (persistence across restarts verified).
• auth: HFS_AUTH_AUDIENCE is not enforced when the token lacks an aud claim #206 — HFS_AUTH_AUDIENCE is bypassed by a token with no aud claim (jsonwebtoken only validates aud when present).

Neither is fixed here — this pass verifies and reports.

Low-risk fixes included (so the runbook works as written)

• docker/keycloak/realm.json: hardcoded-audience mapper (aud: hfs-api) on both service clients, so audience validation is exercisable locally — verified matching aud → 200, wrong expected aud → 401. (Makes auth: HFS_AUTH_AUDIENCE is not enforced when the token lacks an aud claim #206 observable; doesn't fix the missing-claim bypass.)
• docker/keycloak/get-token.sh: parse the token JSON with whichever of jq/node/python3 actually works (a Windows python3 stub alias resolves but fails), instead of python3 only.

Not covered (called out in the doc)

• private_key_jwt with a real asymmetric client assertion — the committed realm's clients use client-secret; HFS's validation role is identical either way, but the advertised capability isn't exercised until the realm gains such a client.
• Discovery advertises private_key_jwt + RS384/ES384 while the realm uses client-secret + RS256 — a config-fidelity gap (documented, not filed).

Closes #198.

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[angela-helios]

Helios login theme (part 4 of #198 — login-screen customization)

Answering the customization question concretely: yes, and here it is. Since HFS is not the auth server, the login screen is IdP-owned — so this brands Keycloak (the IdP we bundle) with a CSS-only theme: Helios logo, Figtree, accent #33b8ff, light surface, all from the Dashboard V1.1 tokens. It extends the stock keycloak theme with no template forks, so it survives Keycloak upgrades.

Wired up: docker/keycloak/themes/helios/ mounted into the container, selected via the realm loginTheme, and rendered end to end through a new public Authorization Code + PKCE client (hfs-web) + demo/demo test user — the scaffolding the §3 browser-login build will plug into.

Rendered and verified via headless Chrome against the running Keycloak. The password show/hide input-group needed extra styling for Keycloak 26 — a defect caught only because the page was actually rendered, not curl'd.