---
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.