familysync/.planning/milestones/v1.0-phases/01-foundation-broker-spike/01-02-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
01-foundation-broker-spike	02	execute	2	01-01	apps/api/src/auth/middleware.ts apps/api/src/auth/user.ts apps/api/src/routes/me.ts apps/api/src/index.ts apps/api/tests/auth/user.test.ts apps/pwa/src/App.tsx apps/pwa/src/api/client.ts .env.example	true	AUTH-01 AUTH-02 AUTH-03	truths artifacts key_links An unauthenticated request to /api/* is redirected to Authelia's authorize endpoint (302) After login, the OIDC callback upserts a users row keyed by oidc_iss + oidc_sub (never email) Each member is auto-assigned a stable, distinct color from a curated palette on first login; re-login returns the same color Session persists via @hono/oidc-auth refresh-token rotation — no iframe, refresh held backend-side GET /api/me returns the authenticated user's identity + color The PWA shell renders the logged-in member's name and color swatch path provides exports apps/api/src/auth/user.ts upsertUser(oidcIss, oidcSub, displayName) with round-robin color assignment upsertUser COLOR_PALETTE path provides apps/api/src/auth/middleware.ts oidcAuthMiddleware wiring + getAuth → upsertUser bridge path provides exports apps/api/src/routes/me.ts GET /api/me → { user: { id, displayName, color } } meRouter from to via pattern apps/api/src/routes/me.ts apps/api/src/auth/user.ts upsertUser call upsertUser( from to via pattern apps/api/src/index.ts @hono/oidc-auth oidcAuthMiddleware on /api/* oidcAuthMiddleware from to via pattern apps/pwa/src/App.tsx /api/me React Query fetch api/me

Deliver the OIDC authentication vertical slice: wire `@hono/oidc-auth` against the already-deployed Authelia, upsert a stable user identity keyed by `oidc_iss + oidc_sub` on first authenticated request, auto-assign a stable per-member color from a curated palette, expose `GET /api/me`, and render the logged-in member (name + color) in the PWA shell.

After this plan a real user can: hit the app, get redirected to Authelia, log in, and land on a shell that shows their name and their assigned color — with the session persisting across the access-token refresh window. This is AUTH-01/02/03 end to end.

Purpose: Authentication is the gate for every other feature; the identity + color row is consumed by the calendar broker (Plan 03) and all later phases. Output: Working Authelia OIDC login, stable identity + color, /api/me, authenticated PWA shell.

<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @./CLAUDE.md @.planning/phases/01-foundation-broker-spike/01-CONTEXT.md @.planning/phases/01-foundation-broker-spike/01-RESEARCH.md @.planning/phases/01-foundation-broker-spike/01-01-SUMMARY.md

<artifacts_produced>

Artifacts this phase produces (Plan 02)

New files: apps/api/src/auth/middleware.ts, apps/api/src/auth/user.ts, apps/api/src/routes/me.ts, apps/pwa/src/api/client.ts.

New exported symbols: upsertUser (auth/user.ts), COLOR_PALETTE (auth/user.ts), meRouter (routes/me.ts), setupAuth/oidc middleware mount (auth/middleware.ts).

New route paths: GET /api/me, GET /callback (OIDC callback handled by processOAuthCallback).

New env vars: OIDC_AUTH_SECRET, OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_REDIRECT_URI, OIDC_AUTH_EXTERNAL_URL. </artifacts_produced>

Task 1: User upsert + stable color assignment (AUTH-03) apps/api/src/auth/user.ts, apps/api/tests/auth/user.test.ts - .planning/phases/01-foundation-broker-spike/01-RESEARCH.md (§ "User upsert with color assignment" code example, § "Pattern 2" users schema) - .planning/phases/01-foundation-broker-spike/01-CONTEXT.md (D-06 color auto-assign round-robin by join order; D-10 identity = oidc_iss+oidc_sub never email) - apps/api/src/db/schema.ts (users table from Plan 01) - apps/api/tests/auth/user.test.ts (RED stub from Plan 01 — fill GREEN here) - upsertUser called with a new (oidcIss, oidcSub) inserts a row and assigns COLOR_PALETTE[userCount % palette.length] - upsertUser called twice with the same (oidcIss, oidcSub) returns the SAME row and SAME color (idempotent, no duplicate insert) - Two distinct oidcSub values receive DISTINCT colors (until palette wraps) - Identity lookup uses oidc_iss AND oidc_sub — never email/displayName Create `src/auth/user.ts` exporting `COLOR_PALETTE` (a curated array of >=4 visually-distinct, accessible hex hues per D-06 / Claude's Discretion — e.g. calm blue, warm coral, forest green, soft purple; exact values Claude's choice) and `upsertUser(oidcIss, oidcSub, displayName?)`. Logic per RESEARCH example: SELECT existing by `and(eq(users.oidcIss, oidcIss), eq(users.oidcSub, oidcSub))`; if present return it; else COUNT existing users, assign `COLOR_PALETTE[count % length]`, INSERT, return the new row. Use `$returningId()` then re-select (mysql2 has no RETURNING). Never key on email.

Fill `tests/auth/user.test.ts` GREEN using the test-DB fixture (tests/helpers/db.ts): assert (a) first insert assigns palette[0]; (b) second user assigns palette[1]; (c) re-upsert of user 1 returns the identical row + color and does not create a duplicate; (d) lookup is by iss+sub.

cd apps/api && pnpm vitest run tests/auth/user.test.ts --reporter=verbose - `src/auth/user.ts` exports `upsertUser` and `COLOR_PALETTE` (length >= 4) - tests/auth/user.test.ts passes all four cases (insert color, second distinct color, idempotent re-upsert, identity by iss+sub) - grep confirms `users.oidcIss` and `users.oidcSub` used in the WHERE; no `users.email` lookup exists user.test.ts green; color assignment deterministic and stable; identity keyed on iss+sub. Task 2: Authelia OIDC middleware + /api/me + authenticated PWA shell (AUTH-01/02) apps/api/src/auth/middleware.ts, apps/api/src/routes/me.ts, apps/api/src/index.ts, .env.example, apps/pwa/src/api/client.ts, apps/pwa/src/App.tsx - .planning/phases/01-foundation-broker-spike/01-RESEARCH.md (§ "Pattern 1: @hono/oidc-auth Middleware Wiring" incl. env vars + Authelia client YAML, § "Hono app bootstrap", § "Pitfall 1: OIDC_AUTH_EXTERNAL_URL", § "Pitfall 7: client secret plain vs hashed") - .planning/phases/01-foundation-broker-spike/01-CONTEXT.md (D-11 skip groups claim; D-12 backend holds refresh token, no iframe) - apps/api/src/auth/user.ts (upsertUser from Task 1) - apps/api/src/index.ts (Hono bootstrap from Plan 01) Create `src/auth/middleware.ts`: configure `oidcAuthMiddleware()` from @hono/oidc-auth. In `src/index.ts`: register `app.get('/callback', (c) => processOAuthCallback(c))` BEFORE the auth middleware, then `app.use('/api/*', oidcAuthMiddleware())`. Keep `/health` (Plan 01) unauthenticated — mount it before the /api guard. Required env vars (add real placeholders to .env.example): OIDC_AUTH_SECRET (32+ char), OIDC_ISSUER (Authelia base URL — middleware fetches /.well-known/openid-configuration), OIDC_CLIENT_ID, OIDC_CLIENT_SECRET (PLAIN secret per Pitfall 7, NOT the pbkdf2 hash), OIDC_REDIRECT_URI (https://familysync./callback), OIDC_AUTH_EXTERNAL_URL (https://familysync. — MANDATORY behind Pangolin per Pitfall 1, else redirect_uri mismatch). Do NOT request the `groups` scope (D-11). Scopes: openid, profile, email only.

Create `src/routes/me.ts` exporting `meRouter` (Hono): GET / calls `getAuth(c)` to read `iss`, `sub`, `email`, then `upsertUser(auth.iss, auth.sub, auth.email)` and returns `{ user: { id, displayName, color } }`. Mount `app.route('/api/me', meRouter)`.

Session persistence (AUTH-02) is handled by @hono/oidc-auth refresh-token rotation (backend-held refresh token, no iframe — D-12). Note in a code comment that OIDC_AUTH_REFRESH_INTERVAL / OIDC_AUTH_EXPIRES govern this; defaults are acceptable for v1.

PWA: create `apps/pwa/src/api/client.ts` with a typed `fetchMe()` (GET /api/me, credentials: 'include'). Update `App.tsx`: React Query `useQuery(['me'], fetchMe)`; on 401/redirect the browser follows Authelia (full-page). Render the member's displayName and a color swatch using `user.color`. Keep the /health indicator from Plan 01.

Also record the Authelia client registration YAML (from RESEARCH Pattern 1) in the SUMMARY so the operator can paste it into Authelia's configuration.yml — this is the only human-side config (no code change in this repo).

cd apps/api && pnpm exec tsc --noEmit && grep -q "oidcAuthMiddleware" src/index.ts && grep -q "OIDC_AUTH_EXTERNAL_URL" ../../.env.example && grep -q "upsertUser" src/routes/me.ts - `src/index.ts` registers `/callback` via processOAuthCallback BEFORE `oidcAuthMiddleware` and guards `/api/*` - `/health` remains reachable without authentication (mounted before the /api guard) - `.env.example` lists OIDC_AUTH_SECRET, OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_REDIRECT_URI, OIDC_AUTH_EXTERNAL_URL - `src/routes/me.ts` calls `getAuth` then `upsertUser` and returns user id/displayName/color - No `groups` scope requested anywhere (grep -v '^#' src | grep -c "groups" == 0 in auth code) - `apps/pwa/src/App.tsx` fetches `/api/me` and renders `user.color` - `pnpm exec tsc --noEmit` exits 0 tsc clean; /api/* guarded by OIDC, /callback wired, /health still public; /api/me returns identity+color; PWA renders the member; Authelia client YAML captured in SUMMARY.

<threat_model>

Trust Boundaries

Boundary	Description
Browser → Pangolin → Hono /api/*	Untrusted client; only authenticated requests cross (OIDC session cookie)
Authelia → /callback	OIDC authorization-code exchange; PKCE + state validate the callback
Hono → Authelia token endpoint	Backend confidential client; client_secret + refresh token never reach the browser

STRIDE Threat Register

Threat ID	Category	Component	Disposition	Mitigation Plan
T-02-01	Spoofing	OIDC redirect_uri	mitigate	Authelia validates exact match; OIDC_REDIRECT_URI env must equal the registered URI; OIDC_AUTH_EXTERNAL_URL set so Pangolin Host header cannot forge the redirect (Pitfall 1)
T-02-02	Spoofing	CSRF on /callback	mitigate	@hono/oidc-auth uses PKCE (state + code_verifier); require_pkce true, S256 in Authelia client
T-02-03	Tampering	OIDC session JWT cookie	mitigate	Cookie signed with OIDC_AUTH_SECRET (32+ char), httpOnly + Secure + SameSite; verified every request
T-02-04	Information Disclosure	Refresh token / client_secret	mitigate	Backend-only (D-12); never serialized to frontend; not logged; OIDC_CLIENT_SECRET is the plain secret in env, never committed
T-02-05	Elevation of Privilege	/api/* without auth	mitigate	oidcAuthMiddleware mounted on /api/*; no guest access (ASVS V4)
T-02-06	Spoofing	Identity confusion via mutable email	mitigate	Identity keyed on oidc_iss + oidc_sub, never email (D-10)

</threat_model>

- `pnpm exec tsc --noEmit` clean - user.test.ts green (from Task 1) - index.ts mounts oidcAuthMiddleware on /api/*, /callback before it, /health public - /api/me returns identity + color - .env.example complete (OIDC_* + OIDC_AUTH_EXTERNAL_URL) - Manual (Plan 04 deploy): unauthenticated /api/me → 302 to Authelia; after login lands on shell with name + color

<success_criteria>

• AUTH-01: unauthenticated /api/* redirects to Authelia; login lands authenticated (verified live in Plan 04)
• AUTH-02: session persists via backend refresh-token rotation (no iframe)
• AUTH-03: stable identity (iss+sub) + stable distinct per-member color, asserted by unit tests
• /api/me returns the member; PWA shell shows name + color </success_criteria>

Create `.planning/phases/01-foundation-broker-spike/01-02-SUMMARY.md` when done. Include the Authelia client registration YAML for the operator.