familysync/.planning/quick/260610-k1z-persist-oidc-session-cookie-with-maxage-/260610-k1z-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
260610-k1z	01	execute	1		apps/api/src/auth/persistSessionCookie.ts apps/api/src/index.ts apps/api/tests/auth/persistSessionCookie.test.ts	true	AUTH-02	truths artifacts key_links When @hono/oidc-auth produces a valid session this request (c.get('oidcAuthJwt') is truthy), the response re-sets the oidc-auth cookie with a persistent Max-Age so the browser keeps it across PWA/tab close When no valid session JWT is on context (logged-out / deleted / never-set request, c.get('oidcAuthJwt') is falsy), NO oidc-auth Set-Cookie is emitted — the middleware never resurrects a deleted or absent cookie (the critical correctness/security guard) The re-issued cookie carries httpOnly:true, secure:true, sameSite:'Lax', and the domain attribute only when OIDC_COOKIE_DOMAIN is set, mirroring the library's conditional-domain logic pnpm --filter @familysync/api typecheck exits 0 path provides exports min_lines apps/api/src/auth/persistSessionCookie.ts persistSessionCookie() Hono MiddlewareHandler that upgrades the session-scoped oidc-auth cookie to a persistent one persistSessionCookie 25 path provides contains apps/api/tests/auth/persistSessionCookie.test.ts Vitest unit tests for the persist + guard behaviors persistSessionCookie path provides contains apps/api/src/index.ts Mounting of persistSessionCookie immediately after oidcAuthMiddleware inside the !devBypassActive block persistSessionCookie from to via pattern apps/api/src/index.ts apps/api/src/auth/persistSessionCookie.ts import + app.use('/api/*', persistSessionCookie()) inside if (!devBypassActive) persistSessionCookie() from to via pattern apps/api/src/auth/persistSessionCookie.ts oidcAuthJwt context var (set by @hono/oidc-auth) c.get('oidcAuthJwt') read; cookie re-issued only when truthy oidcAuthJwt

Persist the OIDC session cookie so browser-stored sessions survive PWA/browser close.

@hono/oidc-auth 1.8.3 sets its oidc-auth session cookie with { path, httpOnly, secure } and NO maxAge/expires — a SESSION-SCOPED cookie the browser discards on PWA/tab close. On reopen there is no cookie, so the OIDC guard 302s to Authelia and forces re-login. The server-side session JWT is valid for OIDC_AUTH_EXPIRES (default 86400s), but the browser throws the cookie away regardless. The library exposes no option to set cookie maxAge.

Fix: a small Hono middleware mounted immediately after oidcAuthMiddleware() that re-issues the same oidc-auth cookie with a persistent maxAge (+ sameSite:'Lax'). It re-issues ONLY when the library set c.get('oidcAuthJwt') this request (i.e. a freshly created/refreshed valid session), and does NOTHING otherwise — so it never resurrects a deleted or absent cookie.

Purpose: Stop both household members from re-logging-in almost every time they open the PWA. Output: New middleware file + its tests, wired into index.ts.

<execution_context> @$HOME/.claude/gsd-core/workflows/execute-plan.md @$HOME/.claude/gsd-core/templates/summary.md </execution_context>

@CLAUDE.md @apps/api/src/index.ts @apps/api/src/auth/middleware.ts @apps/api/src/auth/devBypass.ts @apps/api/tests/auth/devBypass.test.ts

Ground truth on the library's cookie + context behavior (do NOT edit the library):

- @hono/oidc-auth/dist/index.js sets a session-scoped cookie via

setCookie(c, OIDC_COOKIE_NAME, session_jwt, { path, httpOnly:true, secure:true [, domain if OIDC_COOKIE_DOMAIN] })

with NO maxAge/expires, then immediately calls c.set('oidcAuthJwt', session_jwt).

- oidcAuthJwt is set ONLY on requests where a valid session is created/refreshed.

Logged-out / no-session requests do NOT set it. This is the guard signal.

Task 1: Create persistSessionCookie() middleware apps/api/src/auth/persistSessionCookie.ts - Truthy oidcAuthJwt: middleware re-issues the oidc-auth cookie with Max-Age set (persistent), SameSite=Lax, HttpOnly, Secure. - Falsy oidcAuthJwt (logged-out / never-set): middleware emits NO oidc-auth Set-Cookie (no resurrection) — the security guard. - Cookie name/path read from env with library-matching fallbacks; domain attribute included only when OIDC_COOKIE_DOMAIN is set. Create `apps/api/src/auth/persistSessionCookie.ts` exporting `persistSessionCookie(): MiddlewareHandler` (import the `MiddlewareHandler` type from 'hono'; import `setCookie` from 'hono/cookie').

Implements AUTH-02 session persistence. WHY-comment the file thoroughly: @hono/oidc-auth sets a SESSION-SCOPED oidc-auth cookie (no maxAge), so the browser drops it on PWA/tab close and the user is forced to re-login; this middleware upgrades that cookie to a persistent one. Cite that the library sets `c.set('oidcAuthJwt', session_jwt)` only on requests that create/refresh a valid session.

Behavior, inside the returned handler:
1. Read the freshly-signed session JWT from context: `const jwt = c.get('oidcAuthJwt' as never) as string | undefined`. Use the minimal cast because `oidcAuthJwt` is not in the typed Hono ContextVariableMap — mirror the existing "resolveUserId uses any" / loose-context convention rather than augmenting Hono generics for a library-internal key.
2. THE GUARD (must_have): if `jwt` is falsy, do NOT touch cookies — fall straight through to `await next()` and return. This is the property that prevents resurrecting a deleted/logged-out/never-set cookie. Comment it explicitly as the critical correctness property.
3. If `jwt` is truthy, re-issue the cookie BEFORE `await next()` (set-before-next: if any future downstream handler deletes the cookie, that delete becomes the LAST Set-Cookie and wins — safe ordering even though there is currently no logout/revoke route). Build options to mirror the library + harden:
   - name: `process.env.OIDC_COOKIE_NAME ?? 'oidc-auth'`
   - path: `process.env.OIDC_COOKIE_PATH ?? '/'`
   - httpOnly: true, secure: true
   - sameSite: 'Lax'
   - maxAge: `Number(process.env.OIDC_AUTH_EXPIRES ?? 86400)` (seconds — Hono's setCookie maxAge is in seconds)
   - domain: include the `domain` key ONLY when `process.env.OIDC_COOKIE_DOMAIN` is set (conditional-domain, mirroring the library). Build the options object so the domain key is absent (not `undefined`) when unset.
   Call `setCookie(c, name, jwt, options)` with the SAME jwt value the library signed (do not re-sign).
4. Then `await next()`.

Keep it tiny. Do NOT import or call into @hono/oidc-auth. Do NOT add new dependencies (hono/cookie ships with hono, already a dependency). Do NOT place fenced code blocks in production comments.

pnpm --filter @familysync/api typecheck persistSessionCookie.ts exists, exports persistSessionCookie(): MiddlewareHandler, guards on c.get('oidcAuthJwt'), and `pnpm --filter @familysync/api typecheck` exits 0. Task 2: Wire middleware into index.ts + add unit tests apps/api/src/index.ts, apps/api/tests/auth/persistSessionCookie.test.ts - Test A (persist): with a Hono app that sets c.set('oidcAuthJwt', '') then runs persistSessionCookie(), the response Set-Cookie for oidc-auth includes Max-Age, SameSite=Lax, HttpOnly, and Secure. - Test B (guard): with a Hono app that does NOT set oidcAuthJwt, the response has NO oidc-auth Set-Cookie (no resurrection). Edit `apps/api/src/index.ts`: - Add `import { persistSessionCookie } from './auth/persistSessionCookie.js'` alongside the other auth imports (use the `.js` extension — this is ESM/NodeNext, matching existing imports). - Inside the existing `if (!devBypassActive) { ... }` block, register `app.use('/api/*', persistSessionCookie())` on the line IMMEDIATELY AFTER `app.use('/api/*', oidcAuthMiddleware())` (still inside the same block — it only applies when OIDC is active; under dev bypass there is no oidc cookie). Add a one-line comment: re-issues the session-scoped oidc-auth cookie as persistent so PWA sessions survive close (AUTH-02). Make NO other changes to index.ts.

Create `apps/api/tests/auth/persistSessionCookie.test.ts` (vitest), following the harness style in apps/api/tests/auth/devBypass.test.ts (small Hono app, `app.request()`, inspect the Response). Tests live in tests/, never src/.
- Test A (persist path): build a Hono app; add a middleware that does `c.set('oidcAuthJwt' as never, 'header.payload.sig')` (a dummy non-empty JWT string) then calls the imported `persistSessionCookie()` next; add a GET /api/test handler returning 200. Request it, read `res.headers.get('set-cookie')`, and assert it contains the oidc-auth cookie name AND `Max-Age` AND `SameSite=Lax` AND `HttpOnly` AND `Secure`. (Match attribute names case-insensitively if needed; Hono emits `Max-Age`, `SameSite=Lax`, `HttpOnly`, `Secure`.)
- Test B (guard path — the security property): build a Hono app that does NOT set oidcAuthJwt, run `persistSessionCookie()`, hit a GET /api/test. Assert `res.headers.get('set-cookie')` is null OR does not contain the oidc-auth cookie name — i.e. no resurrection when there is no session JWT.
- Read the cookie NAME the same way the implementation does (`process.env.OIDC_COOKIE_NAME ?? 'oidc-auth'`) so the test stays correct if the env override is set; default 'oidc-auth' otherwise.
Do NOT call the real @hono/oidc-auth in the test — set the context var directly. Do NOT add DB/integration setup (keep it a pure unit test so it runs under the tests/auth/ filter without MariaDB).

pnpm --filter @familysync/api typecheck && pnpm --filter @familysync/api exec vitest run tests/auth/ index.ts mounts persistSessionCookie() immediately after oidcAuthMiddleware() inside the !devBypassActive block; both new tests pass; `pnpm --filter @familysync/api typecheck` exits 0 and `pnpm --filter @familysync/api exec vitest run tests/auth/` passes (including the existing devBypass/user auth tests). - `pnpm --filter @familysync/api typecheck` exits 0. - `pnpm --filter @familysync/api exec vitest run tests/auth/` passes — the new persist test, the new guard test, and the existing devBypass/user tests all green. - Do NOT run the full suite: ~68 pre-existing failures come from real-DB integration tests (MariaDB host port not exposed) and are unrelated to this change. - Manual confirmation of the wiring: persistSessionCookie() is registered on '/api/*' on the line immediately after oidcAuthMiddleware(), inside the `if (!devBypassActive)` block.

<success_criteria>

• A logged-in member who closes the PWA and reopens it later (within OIDC_AUTH_EXPIRES) is NOT bounced to Authelia — the oidc-auth cookie now has a Max-Age and persists.
• A logged-out / no-session request never receives an oidc-auth Set-Cookie from this middleware (no resurrection).
• No changes to @hono/oidc-auth, package.json, or .env. </success_criteria>

- Tuning the session lifetime is config-only, no code change: raising `OIDC_AUTH_EXPIRES` in .env (e.g. `2592000` for 30 days) extends both the server-side JWT lifetime AND the persisted cookie's Max-Age — the new middleware reads `OIDC_AUTH_EXPIRES` for maxAge automatically. The effective ceiling is still bounded by Authelia's refresh_token_lifespan. - Hono's `setCookie` maxAge is expressed in SECONDS (not ms), matching the OIDC_AUTH_EXPIRES unit — no conversion needed. Create `.planning/quick/260610-k1z-persist-oidc-session-cookie-with-maxage-/260610-k1z-SUMMARY.md` when done