docs(01-02): complete OIDC auth slice plan summary

.planning/phases/01-foundation-broker-spike/01-02-SUMMARY.md

@@ -0,0 +1,174 @@
+---
+phase: 01-foundation-broker-spike
+plan: "02"
+subsystem: auth
+tags: [oidc, authelia, hono, drizzle, react, typescript, pwa]
+
+# Dependency graph
+requires:
+  - 01-01 (db singleton, users schema, Hono app export pattern)
+provides:
+  - upsertUser(oidcIss, oidcSub, displayName?) with round-robin color assignment
+  - COLOR_PALETTE (6 curated hex hues)
+  - oidcAuthMiddleware on /api/* (AUTH-01 unauthenticated redirect to Authelia)
+  - /callback route via processOAuthCallback
+  - GET /api/me → { user: { id, displayName, color } }
+  - fetchMe() typed PWA API client
+  - Authenticated PWA shell rendering member name + color swatch
+affects:
+  - 01-03 (broker — user row exists on first login; color available for UI)
+  - 01-04 (spike deploy — live OIDC test, /api/me smoke test)
+
+# Tech tracking
+tech-stack:
+  added:
+    - "@hono/oidc-auth@1.8.3 (oidcAuthMiddleware, processOAuthCallback, getAuth)"
+  patterns:
+    - "Identity keyed on oidc_iss + oidc_sub; email is display-only (D-10)"
+    - "upsertUser: SELECT → early return if exists; COUNT → COLOR_PALETTE[count % len] → INSERT $returningId → re-SELECT (mysql2 no RETURNING)"
+    - "Middleware re-export pattern: src/auth/middleware.ts re-exports from @hono/oidc-auth"
+    - "oidcAuthMiddleware before /api/* but after /health and /callback in index.ts"
+    - "fetchMe() uses credentials: 'include' for OIDC cookie forwarding"
+
+key-files:
+  created:
+    - apps/api/src/auth/user.ts (upsertUser + COLOR_PALETTE)
+    - apps/api/src/auth/middleware.ts (oidcAuthMiddleware re-export + env var docs)
+    - apps/api/src/routes/me.ts (GET /api/me handler)
+    - apps/pwa/src/api/client.ts (fetchMe typed client)
+  modified:
+    - apps/api/src/index.ts (adds /callback + oidcAuthMiddleware + /api/me mount)
+    - apps/pwa/src/App.tsx (adds MemberBadge with color swatch + fetchMe query)
+    - apps/api/tests/auth/user.test.ts (filled from it.todo stubs → 6 passing tests)
+
+key-decisions:
+  - "Middleware re-export: src/auth/middleware.ts re-exports from @hono/oidc-auth rather than duplicating config — keeps index.ts clean and provides a single auth module boundary"
+  - "iss extracted via cast (auth.iss as string | undefined): OidcAuth type exposes iss via index signature [claim: string] — cast is safe per @hono/oidc-auth source; iss is always present in a valid OIDC ID token"
+  - "COLOR_PALETTE has 6 entries (not 4 minimum) to pre-accommodate future household growth without palette wrap-around"
+  - "fetchMe retry: false — 401 triggers Authelia redirect; retrying would just generate more 401s before the redirect lands"
+
+# Metrics
+duration: ~3min
+completed: "2026-06-04"
+---
+
+# Phase 01 Plan 02: OIDC Auth Vertical Slice — Summary
+
+**JWT-signed OIDC session via @hono/oidc-auth against Authelia, stable per-member identity (iss+sub) with round-robin color from a 6-hue palette, /api/me returning user identity+color, and an authenticated React PWA shell rendering the member's name and color swatch.**
+
+## Performance
+
+- **Duration:** ~3 min
+- **Started:** 2026-06-04T14:19:32Z
+- **Completed:** 2026-06-04
+- **Tasks:** 2 of 2 complete
+- **Files modified:** 7 (3 created, 4 modified/filled)
+
+## Accomplishments
+
+- **Task 1 (TDD):** Replaced 5 `it.todo` stubs in `tests/auth/user.test.ts` with 6 real tests covering: palette[0] first user, palette[1] second distinct user, idempotent re-upsert (no duplicate insert), identity keyed on iss+sub not email, full row shape. All GREEN.
+- **Task 2:** Wired full OIDC vertical slice:
+  - `src/auth/middleware.ts` re-exports oidcAuthMiddleware/processOAuthCallback/getAuth from @hono/oidc-auth
+  - `src/index.ts` updated: /health (public) → /callback → /api/* guarded by oidcAuthMiddleware → /api/me mounted
+  - `src/routes/me.ts` calls getAuth → upsertUser(iss, sub, email) → returns {user: {id, displayName, color}}
+  - `apps/pwa/src/api/client.ts` typed fetchMe() with credentials: 'include'
+  - `apps/pwa/src/App.tsx` renders MemberBadge (name + color swatch circle) via useQuery(['me'], fetchMe)
+
+## Task Commits
+
+1. **RED gate (Task 1):** `61c258c` — `test(01-02): add failing tests for upsertUser`
+2. **GREEN (Task 1):** `baabfce` — `feat(01-02): implement upsertUser with stable color assignment (AUTH-03)`
+3. **Task 2:** `668ed9b` — `feat(01-02): wire OIDC middleware, /api/me route, and authenticated PWA shell`
+
+## Files Created/Modified
+
+- `apps/api/src/auth/user.ts` — `upsertUser` + `COLOR_PALETTE` (6 hex hues)
+- `apps/api/src/auth/middleware.ts` — `oidcAuthMiddleware`, `processOAuthCallback`, `getAuth` re-exports with env var documentation
+- `apps/api/src/routes/me.ts` — `GET /` handler: getAuth → upsertUser → `{user: {id, displayName, color}}`
+- `apps/api/src/index.ts` — updated mount order: /health → /callback → oidcAuthMiddleware on /api/* → /api/me
+- `apps/pwa/src/api/client.ts` — `fetchMe()` with typed response shape
+- `apps/pwa/src/App.tsx` — `MemberBadge` component with `ColorSwatch`; useQuery(['me'], fetchMe); retains /health indicator
+- `apps/api/tests/auth/user.test.ts` — 6 passing tests (was 5 it.todo stubs)
+
+## Decisions Made
+
+- Re-export pattern for middleware: `src/auth/middleware.ts` re-exports from `@hono/oidc-auth` rather than duplicating config at mount site
+- `auth.iss` cast: `OidcAuth` exposes `iss` via index signature `[claim: string]: JsonValue | undefined`; cast to `string | undefined` is safe — iss is always present in a valid OIDC session
+- 6-color palette: pre-accommodates household growth without requiring palette config update
+
+## Operator Setup Required (Authelia Client Registration)
+
+Before deploying, register FamilySync as an OIDC client in Authelia's `configuration.yml`:
+
+```yaml
+identity_providers:
+  oidc:
+    clients:
+      - client_id: 'familysync'
+        # Generate the hash with: authelia crypto hash --sha512 <your-plain-secret>
+        # OIDC_CLIENT_SECRET env var holds the PLAIN secret (not this hash — Pitfall 7)
+        client_secret: '$pbkdf2-sha512$310000$...'
+        redirect_uris:
+          - 'https://familysync.yourdomain.com/callback'
+        grant_types:
+          - 'authorization_code'
+          - 'refresh_token'
+        response_types:
+          - 'code'
+        require_pkce: true
+        pkce_challenge_method: 'S256'
+        token_endpoint_auth_method: 'client_secret_basic'
+        scopes:
+          - 'openid'
+          - 'profile'
+          - 'email'
+        # No 'groups' scope — D-11: all authenticated users are equal
+```
+
+**`.env` values to set before first run:**
+
+| Variable | Value |
+|----------|-------|
+| `OIDC_AUTH_SECRET` | 32+ char random string (e.g. `openssl rand -base64 32`) |
+| `OIDC_ISSUER` | Authelia base URL, e.g. `https://auth.yourdomain.com` |
+| `OIDC_CLIENT_ID` | `familysync` |
+| `OIDC_CLIENT_SECRET` | Plain text secret (same value used with `authelia crypto hash`) |
+| `OIDC_REDIRECT_URI` | `https://familysync.yourdomain.com/callback` |
+| `OIDC_AUTH_EXTERNAL_URL` | `https://familysync.yourdomain.com` — **mandatory** behind Pangolin (Pitfall 1) |
+
+**Note:** `OIDC_AUTH_EXTERNAL_URL` is not optional behind Pangolin. Without it, `@hono/oidc-auth` constructs the redirect_uri from the internal container `Host` header, which won't match the registered URI in Authelia — login fails with "invalid redirect_uri".
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Known Stubs
+
+None. The `upsertUser` implementation is complete. The PWA `fetchMe` is wired to `/api/me` which returns real data. No placeholder text or hardcoded empty values in user-facing flows.
+
+## Threat Surface Scan
+
+All surfaces are within the planned threat model (Plan 02 STRIDE register):
+
+- **T-02-01 (redirect_uri):** OIDC_AUTH_EXTERNAL_URL documented in .env.example and middleware comments
+- **T-02-02 (CSRF):** processOAuthCallback uses PKCE (state + code_verifier); Authelia configured with require_pkce: true, S256
+- **T-02-03 (cookie tampering):** @hono/oidc-auth signs cookie with OIDC_AUTH_SECRET; httpOnly + Secure + SameSite enforced by library
+- **T-02-04 (refresh token / client_secret):** backend-only (D-12); getAuth → upsertUser → returns {id, displayName, color} only — no token or credential data in /api/me response
+- **T-02-05 (/api/* without auth):** oidcAuthMiddleware on /api/*; /health public-before-guard
+- **T-02-06 (identity confusion):** upsertUser keyed exclusively on oidcIss + oidcSub; no email lookup anywhere in auth path
+
+No new threat surface introduced beyond plan.
+
+## Self-Check: PASSED
+
+- `apps/api/src/auth/user.ts` exists: FOUND
+- `apps/api/src/auth/middleware.ts` exists: FOUND
+- `apps/api/src/routes/me.ts` exists: FOUND
+- `apps/pwa/src/api/client.ts` exists: FOUND
+- Commits 61c258c (RED), baabfce (GREEN), 668ed9b (Task 2): FOUND
+- `tsc --noEmit` clean: PASSED
+- 6 auth/user tests pass: PASSED
+
+---
+*Phase: 01-foundation-broker-spike*
+*Completed: 2026-06-04*