From eba0bb095d4c9268376e5a1e44fe2df9ea056c92 Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Wed, 17 Jun 2026 17:22:39 -0400 Subject: [PATCH] docs(19-05): complete dev-bypass rework + harness + CI plan (checkpoint) --- .../19-05-SUMMARY.md | 199 ++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 .planning/phases/19-local-auth-no-oidc-mode/19-05-SUMMARY.md diff --git a/.planning/phases/19-local-auth-no-oidc-mode/19-05-SUMMARY.md b/.planning/phases/19-local-auth-no-oidc-mode/19-05-SUMMARY.md new file mode 100644 index 0000000..c9a048c --- /dev/null +++ b/.planning/phases/19-local-auth-no-oidc-mode/19-05-SUMMARY.md @@ -0,0 +1,199 @@ +--- +phase: 19-local-auth-no-oidc-mode +plan: "05" +subsystem: auth +tags: [local-auth, dev-bypass, playwright, e2e, ci, break-glass, option-c, d-15] +status: checkpoint +dependency_graph: + requires: + - issueLocalSessionCookie / getCookie (from 19-01) + - local_credentials Drizzle table + 0003 migration (from 19-01) + - devAuthBypass() + DEV_USER (from apps/api/src/auth/devBypass.ts) + - hashPassword / verifyPassword (from 19-01) + - localAuthMiddleware (from 19-03) + provides: + - devSessionCookieMiddleware(): issues real local-session cookie under bypass (Option C) + - apps/api/scripts/reset-admin.ts: break-glass CLI (dev-only, D-13) + - apps/pwa/e2e/login.spec.ts: real-login-form e2e spec (AUTH-LOCAL-12/15) + - global-setup.ts: local_credentials dev seed (devuser/devpass) + TRUNCATE + - ci.yml: LOCAL_SESSION_SECRET + local_credentials seed in harness job + affects: + - apps/api/src/auth/devBypass.ts (devSessionCookieMiddleware added) + - apps/api/src/index.ts (devSessionCookieMiddleware mounted after devAuthBypass) + - apps/pwa/e2e/global-setup.ts (TRUNCATE + INSERT local_credentials) + - .gitea/workflows/ci.yml (LOCAL_SESSION_SECRET + local_credentials seed step) + - apps/api/tests/routes/* (mock devBypass now exports devSessionCookieMiddleware) +tech_stack: + added: [] + patterns: + - Option C: devSessionCookieMiddleware issues real JWT cookie under bypass (D-14/D-15) + - Production hard-guard FIRST check pattern (mirrors devAuthBypass, T-19-24) + - Inline scrypt PHC hashPassword (Pitfall 11 — plain Node.js scripts) + - CLI --dry-run flag: validates without writing (T-19-26) + - vitest mock update pattern: add new exports to all vi.mock(devBypass.js) blocks +key_files: + created: + - apps/api/scripts/reset-admin.ts + - apps/pwa/e2e/login.spec.ts + modified: + - apps/api/src/auth/devBypass.ts + - apps/api/src/index.ts + - apps/pwa/e2e/global-setup.ts + - .gitea/workflows/ci.yml + - apps/api/tests/lib/requireAdmin.test.ts + - apps/api/tests/routes/admin.test.ts + - apps/api/tests/routes/authMode.test.ts + - apps/api/tests/routes/lists.test.ts + - apps/api/tests/routes/localAuth.test.ts + - apps/api/tests/routes/push.test.ts + - apps/api/tests/routes/setup.test.ts +decisions: + - "Option C (devSessionCookieMiddleware): minimal-change path — bypass keeps setting c.get('user') AND issues local-session cookie, so existing specs pass unchanged" + - "devSessionCookieMiddleware degrades gracefully when LOCAL_SESSION_SECRET is absent (skip cookie issuance) rather than throwing" + - "reset-admin uses mysql2/promise createConnection (same as global-setup.ts) — no new deps" + - "CI local_credentials seed step uses inline CJS hashPassword (--input-type=commonjs) matching the existing CI seed pattern" + - "LOCAL_SESSION_SECRET CI value: 'dev-secret-change-me-0000000000000000' — 36 chars, documented as dev-only" + - "login.spec.ts scoped to desktop/Chromium only — other profiles reach the app via bypass cookie unchanged" +metrics: + duration: "~13 minutes" + completed: "2026-06-17" + tasks_completed: 3 + tasks_total: 4 + files_created: 2 + files_modified: 11 +--- + +# Phase 19 Plan 05: Dev-Bypass Rework + Harness + CI Summary + +**One-liner:** Option C devSessionCookieMiddleware issues real local-session cookie under DEV_AUTH_BYPASS, break-glass reset-admin CLI, login.spec.ts real-form e2e, global-setup seeds local_credentials, and CI harness job gets LOCAL_SESSION_SECRET. + +## Status: CHECKPOINT REACHED + +Task 4 is a `type="checkpoint:human-verify"` (gate="blocking"). Tasks 1-3 are complete and committed. The plan pauses for human confirmation that the full Playwright harness + CI run are green and that no dev artifact ships in the published image (D-15 boundary). + +## Tasks Completed + +| Task | Name | Commit | Key Files | +|------|------|--------|-----------| +| 1 | Option C — devSessionCookieMiddleware | 3094df8 | devBypass.ts, index.ts | +| 2 | Break-glass reset-admin CLI | 8239187 | apps/api/scripts/reset-admin.ts | +| 3 | global-setup seed + login.spec.ts + CI env | 1f94dc5 | global-setup.ts, login.spec.ts, ci.yml + 7 test mocks | + +## Task 4: Checkpoint (Pending Human Verification) + +**Checkpoint type:** `human-verify` (blocking) + +### What was verified locally + +**API tests:** 446/446 tests pass (all 34 test files, including devBypass.test.ts: 3/3). + +**Typecheck:** `pnpm --filter @familysync/api typecheck` and `pnpm --filter @familysync/pwa typecheck` both exit 0. + +**reset-admin --dry-run:** Exit 0; no password value ("ignored") in output. + +**D-15 boundary verified:** +- `.dockerignore` excludes `apps/api/scripts/` (reset-admin.ts never ships) — confirmed in file. +- `.dockerignore` excludes `apps/pwa/e2e/` (global-setup seed never ships) — confirmed in file. +- `devSessionCookieMiddleware()` production hard-guard is FIRST check (line 105 of devBypass.ts). +- `reset-admin.ts` NODE_ENV=production throw is FIRST executable statement (line 26). +- `LOCAL_SESSION_SECRET` in ci.yml is a documented dev-only value, never in the published image. + +**E2E login.spec.ts:** Cannot run locally yet — `LoginPage.tsx` is being produced by the concurrent plan 04 executor in the same wave. The spec is structurally correct (matches UI-SPEC selectors `id="login-username"`, `role="heading" name="Sign in"`, etc.) and will run as part of the full harness after wave 4 merges. + +### What the human needs to verify + +1. **Push and run CI:** Push the branch → confirm the Gitea CI `harness` job is green. The harness job now includes `LOCAL_SESSION_SECRET` and the `local_credentials` seed step. The full Playwright suite (iphone + pixel + desktop) should pass including `login.spec.ts` on the desktop profile. +2. **D-15 image boundary:** Confirm the `publish.yml` image-hygiene assertion still passes (no `apps/api/scripts/` or `apps/pwa/e2e/` artifacts in the published image). Spot-check `.dockerignore` covers both dirs. +3. **Confirm login.spec.ts passes:** After wave 4 merges (plan 04 completes LoginPage.tsx), confirm `pnpm --filter @familysync/pwa test:e2e --grep "login"` exits 0 on the desktop profile. + +**Resume signal:** Type "approved" if the full harness + CI are green and no dev artifact ships. + +## What Was Built + +### Task 1: devSessionCookieMiddleware (Option C) + +**`apps/api/src/auth/devBypass.ts`** — new export `devSessionCookieMiddleware(): MiddlewareHandler`: +- Production hard-guard FIRST check: `NODE_ENV === 'production'` → no-op (T-19-24, D-15) +- No-op when `DEV_AUTH_BYPASS !== 'true'` +- No-op when `LOCAL_SESSION_SECRET` not set (degrades gracefully) +- When active: if no `local-session` cookie present, calls `issueLocalSessionCookie(c, DEV_USER.id)` +- Imports: `getCookie` from hono/cookie, `issueLocalSessionCookie` from localSession.ts + +**`apps/api/src/index.ts`** — mounts `devSessionCookieMiddleware()` immediately after `devAuthBypass()` on `/api/*`. + +### Task 2: reset-admin.ts (Break-Glass CLI) + +**`apps/api/scripts/reset-admin.ts`** — standalone break-glass CLI (149 lines): +- NODE_ENV=production throw as FIRST executable statement (D-13/D-15) +- `.dockerignore apps/api/scripts/` excludes it from the prod image (IMG-02) +- Inline scrypt PHC `hashPassword()` (Pitfall 11 — cannot import compiled TS from plain script) +- Parses `--username` / `--password` / `--dry-run` from process.argv +- Upserts `users` row (is_admin=true, claimed=true) then upserts `local_credentials` row +- Never logs the password value (T-19-26) +- `--dry-run`: validates args + DB connection without writing; exit 0 + +### Task 3: global-setup seed + login.spec.ts + CI harness env + +**`apps/pwa/e2e/global-setup.ts`**: +- Added `hashPasswordInline()` inline scrypt PHC (Pitfall 11 — plain Node.js) +- Added `TRUNCATE TABLE local_credentials` to the TRUNCATE block +- Added `INSERT INTO local_credentials (user_id, username, password_hash) VALUES (1, 'devuser', ?) ON DUPLICATE KEY UPDATE ...` after member_credentials seed + +**`apps/pwa/e2e/login.spec.ts`** (new, 98 lines): +- Scoped to desktop/Chromium only (other profiles use bypass cookie) +- Uses `context.clearCookies()` before each test to strip the bypass-issued cookie +- Test 1: unauthenticated navigation → /login; brand + "Sign in" heading + form visible +- Test 2: wrong password → `role="status"` shows "Incorrect username or password." +- Test 3: devuser/devpass → navigates away from /login + +**`.gitea/workflows/ci.yml`** harness job: +- Added new "Seed local_credentials for dev user (id=1)" step (CJS inline script with hashPassword) +- Added `LOCAL_SESSION_SECRET: 'dev-secret-change-me-0000000000000000'` to harness env +- LOCAL_SESSION_SECRET is a dev-only value, never in the published image (IMG gates) + +**Test mock fixes (Rule 1 — Bug):** Added `devSessionCookieMiddleware: () => async (_c, next) => next()` to all 7 `vi.mock('../../src/auth/devBypass.js', ...)` blocks that used an explicit factory return object (admin, setup, push, lists, localAuth, authMode, requireAdmin tests). `events.test.ts` uses `importOriginal` + spread and already picks up the new export automatically. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] vitest mock missing devSessionCookieMiddleware export** +- **Found during:** Task 3 — running the full API test suite after Task 1's devBypass.ts change +- **Issue:** 7 test files mock `devBypass.js` with an explicit factory object. After adding `devSessionCookieMiddleware` to devBypass.ts, vitest reported "No `devSessionCookieMiddleware` export is defined on the mock" for every mock that did not include it. +- **Fix:** Added `devSessionCookieMiddleware: () => async (_c, next) => next()` to all 7 explicit mock factories: admin.test.ts, setup.test.ts, push.test.ts (both `vi.mock` and `vi.doMock`), lists.test.ts, localAuth.test.ts, authMode.test.ts, requireAdmin.test.ts. +- **Files modified:** 7 test files +- **Commit:** 1f94dc5 + +## D-15 Guarantee + +| Artifact | Dev boundary | Enforcement | +|----------|--------------|-------------| +| `devSessionCookieMiddleware` | NODE_ENV=production hard-guard (FIRST check) + IMG-01 boot guard | T-19-24 | +| `reset-admin.ts` | NODE_ENV=production throw (FIRST statement) + .dockerignore apps/api/scripts/ | T-19-25, IMG-02 | +| `local_credentials` dev seed | Lives in apps/pwa/e2e/global-setup.ts (.dockerignore apps/pwa/e2e/) + CI step only | T-19-23 | +| `LOCAL_SESSION_SECRET` in CI | Dev-only value in harness job env; never in Dockerfile or published image | IMG-01/02/03 | + +## Known Stubs + +None. All new code performs real operations. + +## Threat Surface Scan + +No new network endpoints introduced. New surface: +- `devSessionCookieMiddleware`: internal middleware, no external exposure; guarded by NODE_ENV=production FIRST check (T-19-24). +- `reset-admin.ts`: CLI only (docker exec), guarded by NODE_ENV=production throw + .dockerignore exclusion (T-19-25). + +All surfaces are within the plan's threat model (T-19-23 through T-19-26). + +## Self-Check: PASSED + +All created files confirmed present on disk: +- FOUND: apps/api/scripts/reset-admin.ts +- FOUND: apps/pwa/e2e/login.spec.ts + +All commits confirmed in git log: +- 3094df8: feat(19-05): Option C — devSessionCookieMiddleware issues real local-session cookie under bypass +- 8239187: feat(19-05): add break-glass reset-admin CLI (dev-only, .dockerignore'd) +- 1f94dc5: feat(19-05): global-setup local_credentials seed + login.spec.ts + CI harness env + +API tests: 446/446 pass (all 34 test files); typecheck: exit 0.