luckberg/familysync
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(quick-260610-k1z): plan/summary/verification + STATE row (persist OIDC cookie, Verified)

Browse Source
This commit is contained in:
Lucas Berger
2026-06-10 14:35:41 -04:00
parent 8343faddce
commit bf5f87eda8
4 changed files with 320 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/quick/260610-k1z-persist-oidc-session-cookie-with-maxage-/260610-k1z-PLAN.md
+155
View File
@@ -0,0 +1,155 @@
---
phase: 260610-k1z
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- apps/api/src/auth/persistSessionCookie.ts
- apps/api/src/index.ts
- apps/api/tests/auth/persistSessionCookie.test.ts
autonomous: true
requirements: [AUTH-02]
must_haves:
truths:
- "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"
artifacts:
- path: "apps/api/src/auth/persistSessionCookie.ts"
provides: "persistSessionCookie() Hono MiddlewareHandler that upgrades the session-scoped oidc-auth cookie to a persistent one"
exports: ["persistSessionCookie"]
min_lines: 25
- path: "apps/api/tests/auth/persistSessionCookie.test.ts"
provides: "Vitest unit tests for the persist + guard behaviors"
contains: "persistSessionCookie"
- path: "apps/api/src/index.ts"
provides: "Mounting of persistSessionCookie immediately after oidcAuthMiddleware inside the !devBypassActive block"
contains: "persistSessionCookie"
key_links:
- from: "apps/api/src/index.ts"
to: "apps/api/src/auth/persistSessionCookie.ts"
via: "import + app.use('/api/*', persistSessionCookie()) inside if (!devBypassActive)"
pattern: "persistSessionCookie\\(\\)"
- from: "apps/api/src/auth/persistSessionCookie.ts"
to: "oidcAuthJwt context var (set by @hono/oidc-auth)"
via: "c.get('oidcAuthJwt') read; cookie re-issued only when truthy"
pattern: "oidcAuthJwt"
---
<objective>
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.
</objective>
<execution_context>
@$HOME/.claude/gsd-core/workflows/execute-plan.md
@$HOME/.claude/gsd-core/templates/summary.md
</execution_context>
<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.
</context>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: Create persistSessionCookie() middleware</name>
<files>apps/api/src/auth/persistSessionCookie.ts</files>
<behavior>
- 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.
</behavior>
<action>
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.
</action>
<verify>
<automated>pnpm --filter @familysync/api typecheck</automated>
</verify>
<done>persistSessionCookie.ts exists, exports persistSessionCookie(): MiddlewareHandler, guards on c.get('oidcAuthJwt'), and `pnpm --filter @familysync/api typecheck` exits 0.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: Wire middleware into index.ts + add unit tests</name>
<files>apps/api/src/index.ts, apps/api/tests/auth/persistSessionCookie.test.ts</files>
<behavior>
- Test A (persist): with a Hono app that sets c.set('oidcAuthJwt', '<jwt>') 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).
</behavior>
<action>
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).
</action>
<verify>
<automated>pnpm --filter @familysync/api typecheck && pnpm --filter @familysync/api exec vitest run tests/auth/</automated>
</verify>
<done>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).</done>
</task>
</tasks>
<verification>
- `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.
</verification>
<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>
<notes>
- 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.
</notes>
<output>
Create `.planning/quick/260610-k1z-persist-oidc-session-cookie-with-maxage-/260610-k1z-SUMMARY.md` when done
</output>
.planning/quick/260610-k1z-persist-oidc-session-cookie-with-maxage-/260610-k1z-SUMMARY.md
+89
View File
@@ -0,0 +1,89 @@
---
phase: 260610-k1z
plan: 01
subsystem: auth
tags: [oidc, session, cookie, pwa, persistence]
dependency_graph:
requires: [@hono/oidc-auth oidcAuthJwt context var]
provides: [persistSessionCookie middleware, AUTH-02]
affects: [apps/api/src/index.ts]
tech_stack:
added: []
patterns: [hono-middleware, cookie-upgrade]
key_files:
created:
- apps/api/src/auth/persistSessionCookie.ts
- apps/api/tests/auth/persistSessionCookie.test.ts
modified:
- apps/api/src/index.ts
decisions:
- "Set-before-next ordering: cookie re-issued before await next() so any future downstream logout/delete wins as the last Set-Cookie"
- "Guard on c.get('oidcAuthJwt'): falsy path does nothing — no resurrection of deleted/absent cookies"
- "Conditional domain: domain key absent (not undefined) when OIDC_COOKIE_DOMAIN unset — mirrors library logic"
metrics:
duration: ~5m
completed: "2026-06-10T18:32:47Z"
tasks_completed: 2
files_changed: 3
---
# Phase 260610-k1z Plan 01: Persist OIDC Session Cookie with Max-Age Summary
**One-liner:** Hono middleware that upgrades the session-scoped oidc-auth cookie (no maxAge) set by @hono/oidc-auth to a persistent cookie with Max-Age, SameSite=Lax, guarded to never resurrect absent/deleted cookies.
## What Was Built
`persistSessionCookie()` is a thin Hono `MiddlewareHandler` mounted immediately after `oidcAuthMiddleware()` in `index.ts` (inside the `!devBypassActive` block). It reads `c.get('oidcAuthJwt')` — a context key set by @hono/oidc-auth only on requests where a valid session was created or refreshed — and re-issues the same signed JWT as a persistent Set-Cookie (adding `Max-Age` + `SameSite=Lax`). When `oidcAuthJwt` is falsy (logged-out, no session, unauthenticated), it is a pure passthrough: no cookie is emitted.
## Tasks Completed
| Task | Name | Commit | Files |
|------|------|--------|-------|
| 1 | Create persistSessionCookie() middleware | aabcb5d | apps/api/src/auth/persistSessionCookie.ts |
| 2 | Wire into index.ts + unit tests | 8343fad | apps/api/src/index.ts, apps/api/tests/auth/persistSessionCookie.test.ts |
## Verification Results
### typecheck
```
$ pnpm --filter @familysync/api typecheck
$ tsc --noEmit
(exit 0 — no output)
```
### vitest run tests/auth/
```
RUN v4.1.8 /home/luc/Projects/familysync/apps/api
Test Files 3 passed (3)
Tests 14 passed (14)
Start at 14:32:33
Duration 2.45s (transform 162ms, setup 1.74s, import 142ms, tests 152ms, environment 0ms)
```
All 3 auth test files pass (devBypass, user, persistSessionCookie). 14/14 tests green including:
- Test A (persist path): truthy oidcAuthJwt → Set-Cookie with Max-Age, SameSite=Lax, HttpOnly, Secure
- Test B (guard path): absent oidcAuthJwt → no oidc-auth Set-Cookie emitted
- Guard variant: empty string oidcAuthJwt → no resurrection
## Deviations from Plan
None — plan executed exactly as written.
## Known Stubs
None.
## Threat Flags
None. The new middleware only re-issues a cookie that @hono/oidc-auth already set; it does not open new network endpoints or auth paths.
## Self-Check: PASSED
- [x] apps/api/src/auth/persistSessionCookie.ts exists
- [x] apps/api/tests/auth/persistSessionCookie.test.ts exists
- [x] apps/api/src/index.ts contains `persistSessionCookie()`
- [x] Commit aabcb5d exists
- [x] Commit 8343fad exists
- [x] typecheck exits 0
- [x] vitest tests/auth/ all pass
.planning/quick/260610-k1z-persist-oidc-session-cookie-with-maxage-/260610-k1z-VERIFICATION.md
+75
View File
@@ -0,0 +1,75 @@
---
phase: 260610-k1z
verified: 2026-06-10T18:35:00Z
status: passed
score: 4/4 must-haves verified
overrides_applied: 0
---
# Phase 260610-k1z: Persist OIDC Session Cookie with Max-Age — Verification Report
**Phase Goal:** Persist the OIDC session cookie with maxAge so PWA/browser sessions survive close — WITHOUT ever resurrecting a deleted/logged-out session.
**Verified:** 2026-06-10T18:35:00Z
**Status:** passed
**Re-verification:** No — initial verification
## Goal Achievement
### Observable Truths
| # | Truth | Status | Evidence |
|---|-------|--------|----------|
| 1 | Truthy oidcAuthJwt → response re-sets oidc-auth cookie with Max-Age, SameSite=Lax, HttpOnly, Secure | VERIFIED | `persistSessionCookie.ts` lines 47–76: guard passes, `setCookie(c, name, jwt, { httpOnly:true, secure:true, sameSite:'Lax', maxAge, ... })` called before `await next()` |
| 2 | Falsy/absent oidcAuthJwt → NO oidc-auth Set-Cookie emitted (no resurrection guard) | VERIFIED | Lines 47–50: `if (!jwt) { await next(); return }` — hard early exit before any `setCookie` call; covered by Test B (absent) and guard variant (empty string), both passing |
| 3 | Cookie carries httpOnly:true, secure:true, sameSite:'Lax'; domain included only when OIDC_COOKIE_DOMAIN set | VERIFIED | Options object built lines 63–69 (always includes httpOnly/secure/sameSite); `if (process.env.OIDC_COOKIE_DOMAIN)` guard at line 71 adds domain key only when env var is set — key absent (not undefined) when unset |
| 4 | `pnpm --filter @familysync/api typecheck` exits 0 | VERIFIED | Run output: `$ tsc --noEmit` — exit 0, no diagnostic output |
**Score:** 4/4 truths verified
### Required Artifacts
| Artifact | Expected | Status | Details |
|----------|----------|--------|---------|
| `apps/api/src/auth/persistSessionCookie.ts` | persistSessionCookie() MiddlewareHandler; min 25 lines | VERIFIED | 81 lines; exports `persistSessionCookie(): MiddlewareHandler`; imports only `hono` and `hono/cookie` — no new dependencies |
| `apps/api/tests/auth/persistSessionCookie.test.ts` | Vitest unit tests; contains "persistSessionCookie" | VERIFIED | 123 lines; 4 tests across 2 describe groups; pure unit test (no MariaDB, no @hono/oidc-auth import) |
| `apps/api/src/index.ts` | Mounts persistSessionCookie immediately after oidcAuthMiddleware inside !devBypassActive | VERIFIED | Line 14: import present; lines 52–54: `app.use('/api/*', oidcAuthMiddleware())` followed immediately by `app.use('/api/*', persistSessionCookie())` — both inside `if (!devBypassActive)` block |
### Key Link Verification
| From | To | Via | Status | Details |
|------|----|-----|--------|---------|
| `apps/api/src/index.ts` | `apps/api/src/auth/persistSessionCookie.ts` | `import { persistSessionCookie } from './auth/persistSessionCookie.js'` + `app.use('/api/*', persistSessionCookie())` inside `if (!devBypassActive)` | VERIFIED | Import at line 14; usage at line 54; ordering correct — line 53 oidcAuthMiddleware, line 54 persistSessionCookie |
| `apps/api/src/auth/persistSessionCookie.ts` | oidcAuthJwt context var (@hono/oidc-auth) | `c.get('oidcAuthJwt' as never)` read; cookie re-issued only when truthy | VERIFIED | Line 40: `const jwt = c.get('oidcAuthJwt' as never) as string | undefined`; line 47: falsy guard; no import of @hono/oidc-auth |
### Behavioral Spot-Checks (Vitest)
| Behavior | Command | Result | Status |
|----------|---------|--------|--------|
| Full tests/auth/ suite | `pnpm --filter @familysync/api exec vitest run tests/auth/` | 3 test files, 14 tests, all passed | PASS |
| Test A — persist path (Max-Age + SameSite=Lax + HttpOnly + Secure present) | included in suite above | passes | PASS |
| Test A variant — same JWT value re-issued unchanged | included in suite above | passes | PASS |
| Test B — guard path (absent oidcAuthJwt → no Set-Cookie) | included in suite above | passes | PASS |
| Test B variant — empty string oidcAuthJwt → no resurrection | included in suite above | passes | PASS |
### Anti-Patterns Found
None. No TBD/FIXME/XXX markers, no placeholder returns, no empty handlers, no hardcoded empty data in modified files. `persistSessionCookie.ts` is fully implemented; all three modified files are substantive.
### Scope Constraint Verification
| Constraint | Status | Evidence |
|------------|--------|----------|
| No changes to @hono/oidc-auth | VERIFIED | Only files modified: persistSessionCookie.ts (new), index.ts (import + 2 lines), persistSessionCookie.test.ts (new) |
| No changes to package.json | VERIFIED | No package.json in modified files list; only `hono/cookie` used, which ships with the existing `hono` dependency |
| No changes to .env | VERIFIED | Not in modified files list |
| Cookie set BEFORE await next() | VERIFIED | `setCookie(c, name, jwt, options)` at line 76; `await next()` at line 78 |
| Middleware NOT mounted under dev bypass | VERIFIED | Both `oidcAuthMiddleware()` and `persistSessionCookie()` registrations are inside `if (!devBypassActive)` block (index.ts lines 51–55) |
### Human Verification Required
None — all behavioral properties verified programmatically via unit tests and static code analysis.
---
_Verified: 2026-06-10T18:35:00Z_
_Verifier: Claude (gsd-verifier)_