# Phase 19: Local Auth (No-OIDC Mode) - Research

**Researched:** 2026-06-17
**Domain:** Authentication — local username/password credentials, stateless JWT session cookies, Hono middleware ordering, Drizzle schema migration
**Confidence:** HIGH

---

<user_constraints>
## User Constraints (from CONTEXT.md)

### Locked Decisions

- **D-01:** Local auth is the **default and always available**. OIDC is **opt-in/additive**, never a replacement for the local path at the system level.
- **D-02:** OIDC is configured from the **admin UI** (extends the Phase-12 config that already lands in `app_config`: `oidc_issuer`, `oidc_client_id`, `app_external_url`). When OIDC is configured, **both methods are offered and the user chooses at login** (local username/password OR "Login with OIDC").
- **D-03:** This must **not break the existing live OIDC deployment**. The two current household members already authenticate via Authelia (`oidc_iss`/`oidc_sub` set, `claimed=true`); they continue as OIDC users. Local auth is layered on additively.
- **D-04:** A **new local login UI (username + password) must be built in the PWA** — none exists today. The PWA currently boots straight into the authed app (OIDC redirect) or via dev-bypass; there is no login form.
- **D-05:** Local logins are backed by a **stateless signed httpOnly JWT cookie** carrying `userId`, validated by a **new local-auth middleware that sets `c.get('user')`** the same way `auth/devBypass.ts` does — so every downstream route resolves the user unchanged. **No DB sessions table**. Tradeoff accepted: a password change cannot retroactively invalidate other live sessions; logout = clear cookie.
- **D-06 (BYO-Auth principle):** Local auth is first-class; OIDC is treated as a **generic RFC-compliant provider, not Authelia-hardcoded**. `@hono/oidc-auth` is already provider-agnostic — work is to de-Authelia-ize config keys and user-facing copy.
- **D-07 (BYO-Auth scope):** Ship **local + one generic OIDC** with a **clean internal seam** for future methods. **No plugin/registry framework** in this phase.
- **D-08:** Hash local passwords with **`node:crypto` scrypt** — zero new dependency, no native node-gyp build. Encode **algorithm + params + salt alongside the hash** so parameters can evolve.
- **D-09:** Store local credentials in a **new `local_credentials` table** — `user_id` (FK to `users`, UNIQUE), `username` (UNIQUE), `password_hash` (encoded), `createdAt`/`updatedAt`. Drizzle **generate+migrate, never push**.
- **D-10:** **Admin creates members** + sets an initial password; the member changes it later. **No open self-signup**.
- **D-11:** Password lifecycle = **self-change (current + new) + admin-reset** from the admin UI. **No email reset**.
- **D-12:** **OIDC link replaces local at the per-user level**: when a local user links an OIDC identity (explicit action while authenticated as that user — never an email match), **delete that user's `local_credentials` row** → they become OIDC-only.
- **D-13 (break-glass):** Lockout recovery is a **CLI/console command and/or env override** (e.g. create/reset a local admin, or disable/force-off OIDC), run on the host/container. **No new role/capability model**; reuse today's single `users.is_admin`.
- **D-14:** The new login UI requires touching existing API/unit tests and the **Phase 7/8 Playwright harness** (which today reaches the authed PWA purely via `DEV_AUTH_BYPASS`, skipping any login). Both the already-authed fast path and the **real login form** must remain testable.
- **D-15 (hard constraint):** Any seeded test login / reworked dev-bypass mechanism **stays dev-only and never ships in the Docker/prod image**. Bound by the existing Phase-16 image-hygiene gates: IMG-01 boot guard (`assertNotDevBypassInProduction`), `.dockerignore` (IMG-02), and the publish-time hygiene assertion (IMG-03).

### Claude's Discretion (decided in-discussion)
- Session backing mechanism (chose stateless signed JWT cookie — D-05).
- Credential storage location (chose separate `local_credentials` table — D-09).

### Deferred Ideas (OUT OF SCOPE)
- **Full pluggable auth-provider framework** (registry/plugin for LDAP, magic-link, multiple simultaneous OIDC providers) — auth-layer counterpart of backlog 999.1.
- **Member-vs-operator capability/role split** — explicitly rejected in favor of a CLI/env recovery mechanism.
- **Email-based password reset** — out of project scope.
</user_constraints>

---

<phase_requirements>
## Phase Requirements

The following REQ-IDs are newly defined by this phase. The planner should include them verbatim in PLAN.md task descriptions and VALIDATION.md.

| ID | Description | Research Support |
|----|-------------|------------------|
| AUTH-LOCAL-01 | `local_credentials` Drizzle schema + migration (0003): `user_id` FK UNIQUE, `username` UNIQUE, `password_hash` varchar | §Schema Change, §Standard Stack §Migration |
| AUTH-LOCAL-02 | `hashPassword(password)` and `verifyPassword(hash, candidate)` helpers using `node:crypto` scrypt in PHC-style encoded format | §Password Hashing |
| AUTH-LOCAL-03 | `POST /api/auth/local/login` route — timing-safe verify, issue `local-session` JWT cookie, return 401/429/423/200 | §Local Login Endpoint |
| AUTH-LOCAL-04 | `localAuthMiddleware` — reads `local-session` cookie, validates JWT, sets `c.get('user')` identical to devBypass; mounts in `index.ts` before OIDC guard | §Middleware Slot |
| AUTH-LOCAL-05 | `GET /api/auth/mode` pre-auth endpoint — returns `{ localEnabled: true, oidcEnabled: boolean }` based on `app_config` OIDC keys | §Auth Mode Endpoint |
| AUTH-LOCAL-06 | `POST /api/auth/local/logout` — clears `local-session` cookie; `GET /api/auth/local/logout` alias | §Logout |
| AUTH-LOCAL-07 | `POST /api/admin/members` — admin creates local member: insert `users` row + `local_credentials` row with hashed initial password | §Admin Account Management |
| AUTH-LOCAL-08 | `POST /api/admin/members/:id/password` — admin resets a local member's password (no current-password required); admin-gated | §Admin Account Management |
| AUTH-LOCAL-09 | `POST /api/me/password` — self-change password: verify current password, hash new, update `local_credentials` | §Self-Service Password |
| AUTH-LOCAL-10 | OIDC-link flow: `POST /api/me/link-oidc` (or reuse OIDC callback, see §OIDC-Link Flow) — bind `oidc_iss+oidc_sub` to the authenticated user, delete their `local_credentials` row | §OIDC-Link Flow |
| AUTH-LOCAL-11 | Break-glass CLI — Node.js script `scripts/reset-admin.ts` runnable as `tsx scripts/reset-admin.ts` inside the container, creates/resets a local admin by username without requiring an existing session | §Break-Glass |
| AUTH-LOCAL-12 | PWA `LoginPage` component (`/login` route) per UI-SPEC Surface 1–10: username+password form, `BrandSlot`, OIDC button when `oidcEnabled`, error state machine | §UI — LoginPage |
| AUTH-LOCAL-13 | PWA admin additions: "Add member" form (UI-SPEC Surface 11A) + "Reset password" modal (Surface 11B) in `AdminPage.tsx` | §UI — Admin |
| AUTH-LOCAL-14 | PWA self-service: "Change password" sheet (UI-SPEC Surface 12) in `SettingsSheet.tsx`; "Link OIDC identity" confirmation sheet (Surface 13) | §UI — Settings |
| AUTH-LOCAL-15 | `App.tsx` login gate: fetch `/api/auth/mode` pre-auth, add `/login` route (standalone), redirect unauthenticated users there when `localEnabled`, skip if valid local or OIDC session | §PWA Routing Gate |
| AUTH-LOCAL-16 | Playwright harness dev-bypass rework: "option C" (bypass issues a real local-session cookie), update `global-setup.ts` to seed `local_credentials` for dev user (id=1), update CI workflow | §Dev-Bypass Rework |
| AUTH-LOCAL-17 | `/api/me` response extended with `hasLocalCredential: boolean` so `SettingsSheet` and `AdminPage` know which users have local creds | §API Extensions |
| AUTH-LOCAL-18 | `app_config` OIDC key de-Authelia-ization: rename any Authelia-specific copy in config keys and comments to generic OIDC labels (no key name change — keys are already generic `oidc_issuer` etc.) | §BYO-Auth De-Authelia-ization |
| AUTH-LOCAL-19 | Rate-limiting on `POST /api/auth/local/login`: in-memory per-IP counter (Map), 5 failures → 60s cooldown → 429; account lockout at 10 failures → 423; cleared on success | §Rate Limiting |
| AUTH-LOCAL-20 | Vitest unit tests: password hashing round-trip, timing-safe compare, login success/failure/lockout, middleware session validation, OIDC-link 409 conflict | §Validation Architecture |
</phase_requirements>

---

## Summary

Phase 19 builds a complete local username/password authentication system on top of the Phase 12 pre-OIDC user foundation. The core architectural move is to add a parallel authentication path alongside the existing `@hono/oidc-auth` middleware: a new `localAuthMiddleware` that reads a signed `local-session` cookie (JWT, HS256 via Hono's built-in `Jwt.sign`/`Jwt.verify`) and populates `c.get('user')` with the same shape that `devAuthBypass()` uses, so all downstream routes work unchanged.

No new npm dependencies are required. Password hashing uses `node:crypto` scrypt (Node.js stdlib), JWT signing uses Hono's built-in `Jwt` from `hono/utils/jwt`, and session cookies use the existing `hono/cookie` helpers (`getCookie`/`setCookie`). The `local_credentials` table mirrors the `member_credentials` shape already in the schema. The migration is a straightforward additive `drizzle-kit generate` + `migrate`.

The PWA adds a `/login` route (standalone, no AppNav/BottomTabBar — same pattern as `/setup`). The login gate is driven by a new pre-auth `GET /api/auth/mode` endpoint. Existing OIDC users are completely unaffected by all of this: their `oidcAuthMiddleware` path is unchanged; the local auth path only fires for requests that arrive with a `local-session` cookie.

**Primary recommendation:** Implement in three waves: (1) schema + credential helpers + API routes, (2) middleware wiring + mode endpoint + PWA login page, (3) admin UI extensions + OIDC-link + break-glass + harness update.

---

## Architectural Responsibility Map

| Capability | Primary Tier | Secondary Tier | Rationale |
|------------|-------------|----------------|-----------|
| Password hashing/verification | API / Backend | — | Secrets never leave server; `node:crypto` scrypt runs server-side only |
| Session JWT sign/verify | API / Backend | — | `LOCAL_SESSION_SECRET` is an env-floor secret; client only holds opaque cookie |
| Auth middleware selection | API / Backend | — | `index.ts` is the single mount-order source of truth |
| Auth mode signalling | API / Backend (pre-auth endpoint) | Frontend fetch | `/api/auth/mode` is the authoritative source; PWA reads it |
| Login form UI | Browser / Client | — | React component, form state, client-side validation |
| Admin member management | API / Backend | Admin UI (client) | Server enforces `requireAdmin`; client is UX-only |
| OIDC-link binding | API / Backend | Browser / Client (confirmation UI) | Actual `iss+sub` binding + `local_credentials` delete is a backend transaction |
| Break-glass recovery | API / Backend (CLI script) | — | Host/container-side only; no UI surface |
| Cookie issuance | API / Backend | — | `httpOnly + Secure + SameSite=Lax`; client cannot write it |
| Rate-limiting / lockout | API / Backend | Browser / Client (error display) | In-memory Map on the server; UI mirrors the 429/423 response |

---

## Standard Stack

### Core (no new packages — everything already installed)

| Library | Version | Purpose | Status |
|---------|---------|---------|--------|
| `node:crypto` | stdlib (Node 22) | `scrypt`, `scryptSync`, `randomBytes`, `timingSafeEqual` | [VERIFIED: codebase — confirmed available in Node 22.22.3 on this machine] |
| `hono` | 4.12.23 (installed) | `Jwt.sign`, `Jwt.verify` from `hono/utils/jwt`; `getCookie`, `setCookie` from `hono/cookie` | [VERIFIED: codebase — `Jwt.sign` and `Jwt.verify` confirmed callable at runtime from `hono/utils/jwt`; `getCookie`/`setCookie` confirmed from `hono/cookie`] |
| `drizzle-orm` | 0.45.2 (installed) | New `local_credentials` table; `drizzle-kit generate` + `migrate` | [VERIFIED: codebase — already in use; `mysqlTable`, `unique`, `index` patterns from `schema.ts`] |
| `zod` | 3.25.x (installed) | Validate login request body (`username`, `password`) | [VERIFIED: codebase — already used in every route] |

### Zero new npm dependencies

This phase installs **no new packages**. All required capabilities are in the existing stack:

- Password hashing: `node:crypto` scrypt (stdlib, confirmed available)
- JWT signing: `hono/utils/jwt` `Jwt.sign`/`Jwt.verify` (confirmed callable from `hono@4.12.23`)
- Cookie read/write: `hono/cookie` `getCookie`/`setCookie` (already used in `persistSessionCookie.ts`)
- Schema: `drizzle-orm` `mysqlTable` (same pattern as `member_credentials`)
- Input validation: `zod` + `@hono/zod-validator` (already used in every route)

**Installation:** None required.

---

## Package Legitimacy Audit

No new packages are introduced in this phase. All libraries listed above are already installed and legitimacy-verified from prior phases.

**Packages removed due to SLOP verdict:** None
**Packages flagged as suspicious:** None (hono is flagged SUS by the seam's "too-new" heuristic because its last publish date happens to be recent, but it is the same `hono@4.12.23` already installed and running in production — not a new install)

---

## Architecture Patterns

### System Architecture Diagram

```
PWA /login page
   ↓  GET /api/auth/mode (pre-auth, no middleware)
   ←  { localEnabled: true, oidcEnabled: boolean }

   ↓  POST /api/auth/local/login { username, password }
   API auth/localLogin.ts
     → local_credentials lookup by username
     → verifyPassword(stored_hash, candidate)  [node:crypto timingSafeEqual]
     → Jwt.sign({ userId, iat, exp }, LOCAL_SESSION_SECRET)
     ← Set-Cookie: local-session=<JWT>; httpOnly; Secure; SameSite=Lax
     ← 200 { ok: true }

   ↓  Any subsequent /api/* request (carries local-session cookie)
   index.ts middleware chain:
     devAuthBypass()       — no-op passthrough (bypass not set in prod)
     localAuthMiddleware() — getCookie('local-session'), Jwt.verify(), c.set('user', {id, ...})
                             → next() if valid cookie; else fall through
     oidcConfigFallback    — injects OIDC config from app_config if absent
     oidcAuthMiddleware()  — skipped if c.get('user') already set? [see §Middleware Slot]
     persistSessionCookie()— OIDC sessions only
     ↓ downstream routes read c.get('user') — unchanged

PWA /admin → AdminPage
   ↓  GET /api/admin/members (returns hasLocalCredential per member)
   ↓  POST /api/admin/members { displayName, username, initialPassword }
      → users INSERT + local_credentials INSERT (hashed)
   ↓  POST /api/admin/members/:id/password { newPassword, confirmPassword }
      → local_credentials UPDATE (hashed)

PWA SettingsSheet
   ↓  POST /api/me/password { currentPassword, newPassword }
      → verifyPassword(stored, current) → UPDATE hash
   ↓  POST /api/me/link-oidc  (authenticated as local user)
      → initiates OIDC authorization-code redirect
      → on /callback with valid OIDC session:
          bind iss+sub to users row (must not conflict with existing user)
          DELETE local_credentials WHERE user_id = current
          → user is now OIDC-only

Break-glass:
   docker exec familysync-api node scripts/reset-admin.ts --username admin --password <new>
   → direct DB write: upsert local_credentials for username, ensure is_admin=true
```

### Recommended Project Structure

New files (additions only):

```
apps/api/src/
├── auth/
│   ├── localCredentials.ts    # hashPassword(), verifyPassword() using node:crypto scrypt
│   ├── localSession.ts        # issueLocalSessionCookie(), verifyLocalSessionCookie(), clearLocalSessionCookie()
│   └── localAuthMiddleware.ts # Hono middleware: getCookie → Jwt.verify → c.set('user')
├── routes/
│   ├── authMode.ts            # GET /api/auth/mode (pre-auth)
│   └── localAuth.ts           # POST /api/auth/local/login, /logout
└── db/
    └── migrations/
        └── 0003_local_credentials.sql   # generated by drizzle-kit

apps/api/scripts/
└── reset-admin.ts             # break-glass CLI (dev-only gate: .dockerignore excludes scripts/)

apps/pwa/src/
├── routes/
│   └── LoginPage.tsx          # /login standalone page (UI-SPEC Surfaces 1–10)
└── components/
    └── BrandSlot.tsx          # phase-17 seam component (UI-SPEC §Brand Slot)
```

Modified files:

```
apps/api/src/
├── db/schema.ts               # + local_credentials table definition
├── routes/admin.ts            # + POST /members, POST /members/:id/password
├── routes/me.ts               # + POST /password, + hasLocalCredential in GET response
├── routes/setup.ts            # + link-oidc callback handler (or reuse /callback)
└── index.ts                   # + mount localAuthMiddleware, authModeRouter before OIDC guard

apps/pwa/src/
├── App.tsx                    # + /login route, auth-mode fetch gate
├── api/client.ts              # + fetchAuthMode(), fetchLocalLogin(), fetchLocalLogout(), etc.
├── routes/AdminPage.tsx       # + LOCAL ACCOUNTS section (Surfaces 11A, 11B)
└── components/SettingsSheet.tsx # + Change password row (Surface 12), Link OIDC row (Surface 13)
```

---

## Password Hashing Pattern

### PHC-Style Encoding with `node:crypto` scrypt

D-08 mandates `node:crypto` scrypt with the algorithm + params + salt encoded alongside the hash so parameters can evolve. The established pattern for self-describing encoded hashes is a `$`-delimited PHC-style string. [VERIFIED: codebase — scryptSync, randomBytes, timingSafeEqual all available in Node 22.22.3; runtime confirmed]

```typescript
// Source: node:crypto docs + runtime-verified on Node 22.22.3
import { scryptSync, randomBytes, timingSafeEqual } from 'node:crypto';

// Parameters (OWASP-compatible for scrypt at this resource level)
const SCRYPT_N = 16384;  // CPU/memory cost — 2^14; increase to 2^15 if hardware permits
const SCRYPT_R = 8;
const SCRYPT_P = 1;
const KEY_LEN  = 32;     // 256-bit output

/**
 * Hash a password. Returns a self-describing encoded string:
 *   scrypt$N$r$p$<salt_base64url>$<hash_base64url>
 *
 * The $-delimited format is inspired by PHC and allows future parameter upgrades
 * without a separate migration — verifyPassword parses all fields from the string.
 */
export function hashPassword(password: string): string {
  const salt = randomBytes(16);
  const hash = scryptSync(password, salt, KEY_LEN, { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P });
  return [
    'scrypt',
    SCRYPT_N,
    SCRYPT_R,
    SCRYPT_P,
    salt.toString('base64url'),
    hash.toString('base64url'),
  ].join('$');
}

/**
 * Verify a password against a stored encoded hash.
 * Uses timingSafeEqual to prevent timing-oracle attacks.
 * Returns false (never throws) on any parse/format mismatch.
 */
export function verifyPassword(storedEncoded: string, candidate: string): boolean {
  try {
    const [, n, r, p, saltB64, hashB64] = storedEncoded.split('$');
    const salt = Buffer.from(saltB64, 'base64url');
    const storedHash = Buffer.from(hashB64, 'base64url');
    const candidateHash = scryptSync(candidate, salt, storedHash.length, {
      N: Number(n), r: Number(r), p: Number(p),
    });
    return timingSafeEqual(storedHash, candidateHash);
  } catch {
    return false;
  }
}
```

**Key points:**
- `scryptSync` blocks the event loop. For login (infrequent in a 2-person household) this is acceptable. If async is preferred, use `promisify(scrypt)` from `node:util`.
- `timingSafeEqual` requires equal-length buffers — `storedHash.length` as keylen ensures this.
- The encoded string is ~83 characters at N=16384 — fits comfortably in `varchar(256)`.

**Note on pepper:** D-08 specifies no pepper (env-only secret kernel). The scrypt salt + encoding is sufficient for this use case. Adding a pepper would require another env var and would not materially improve security for this threat model (household scale, Pangolin-exposed but not public).

---

## Drizzle Schema Change

### `local_credentials` Table

Mirrors the `member_credentials` shape but stores username + password hash. [VERIFIED: codebase — `member_credentials` pattern in `schema.ts` lines 74–94; `mysqlTable`, `int`, `varchar`, `timestamp`, `unique`, `index` all imported]

```typescript
// In apps/api/src/db/schema.ts — additive only
export const localCredentials = mysqlTable(
  'local_credentials',
  {
    id: int().primaryKey().autoincrement(),
    userId: int('user_id')
      .notNull()
      .references(() => users.id, { onDelete: 'cascade' }),
    username: varchar('username', { length: 128 }).notNull(),
    // PHC-encoded: scrypt$N$r$p$<salt_b64url>$<hash_b64url> — self-describing
    passwordHash: varchar('password_hash', { length: 256 }).notNull(),
    createdAt: timestamp('created_at').defaultNow().notNull(),
    updatedAt: timestamp('updated_at').defaultNow().onUpdateNow(),
  },
  (t) => [
    // One local credential per user (UNIQUE on user_id)
    unique('uniq_local_cred_user').on(t.userId),
    // Username is globally unique (login identifier)
    unique('uniq_local_cred_username').on(t.username),
    index('idx_local_credentials_user_id').on(t.userId),
  ],
);
```

### Migration Workflow

Drizzle generate+migrate only — never push (established rule; `push` emits false destructive diffs on MariaDB). [VERIFIED: codebase — 0002 migration and `scripts` in `package.json`]

```bash
# 1. Add localCredentials to schema.ts
# 2. Generate migration
pnpm --filter @familysync/api db:generate
# → apps/api/src/db/migrations/0003_local_credentials.sql

# 3. Review generated SQL (must be purely additive — CREATE TABLE only)
# 4. Apply
pnpm --filter @familysync/api db:migrate
```

The generated SQL will be something like:
```sql
CREATE TABLE `local_credentials` (
  `id` int AUTO_INCREMENT PRIMARY KEY,
  `user_id` int NOT NULL REFERENCES `users`(`id`) ON DELETE CASCADE,
  `username` varchar(128) NOT NULL,
  `password_hash` varchar(256) NOT NULL,
  `created_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at` timestamp DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  CONSTRAINT `uniq_local_cred_user` UNIQUE(`user_id`),
  CONSTRAINT `uniq_local_cred_username` UNIQUE(`username`),
  INDEX `idx_local_credentials_user_id`(`user_id`)
);
```

**Remember:** Export `localCredentials` from `schema.ts` so `test/setup.ts` can truncate it in `afterEach`.

---

## Middleware Slot and Ordering

### Current `index.ts` middleware chain

[VERIFIED: codebase — read `apps/api/src/index.ts`]

```
app.route('/api/setup', setupRouter)       // pre-auth
app.use('/api/*', devAuthBypass())         // DEV only — no-op in prod
if (!devBypassActive) {
  app.use('/api/*', oidcConfigFallbackMiddleware)
  app.use('/api/*', oidcAuthMiddleware())
  app.use('/api/*', persistSessionCookie())
}
```

### New middleware slot for Phase 19

The `localAuthMiddleware` must sit **between `devAuthBypass` and `oidcAuthMiddleware`**. It reads the `local-session` cookie. If the cookie is present and valid, it sets `c.get('user')` and calls `next()`. If no cookie, it falls through to `oidcAuthMiddleware`.

The key architectural requirement: `oidcAuthMiddleware` must **not** redirect to Authelia when the request already has a valid local session. The solution is to check whether `c.get('user')` is set before mounting `oidcAuthMiddleware`, or to make `localAuthMiddleware` short-circuit the OIDC path.

**Recommended approach:** Wrap `oidcAuthMiddleware` in a guard that skips it when `c.get('user')` is already populated:

```typescript
// index.ts updated middleware chain
app.route('/api/setup', setupRouter)           // pre-auth (no change)
app.route('/api/auth', authModeRouter)         // GET /api/auth/mode — pre-auth, no middleware
app.route('/api/auth', localAuthRouter)        // POST /api/auth/local/login + /logout — pre-auth

app.use('/api/*', devAuthBypass())             // DEV only (existing)

// NEW: local session check — populates c.get('user') if local-session cookie valid
app.use('/api/*', localAuthMiddleware())

if (!devBypassActive) {
  app.use('/api/*', oidcConfigFallbackMiddleware)
  // OIDC guard: skip if user already set by localAuthMiddleware or devAuthBypass
  app.use('/api/*', async (c, next) => {
    if (c.get('user')) { await next(); return; }
    await oidcAuthMiddleware()(c, next);
  });
  app.use('/api/*', persistSessionCookie())
}
```

**Why pre-auth for login/logout routes:** `POST /api/auth/local/login` must be reachable without a session (it's how a session is created). Mount it before the OIDC guard, just like `/api/setup/*`. The `GET /api/auth/mode` endpoint similarly needs no auth.

**Security note:** `localAuthMiddleware` must be a no-op when no `local-session` cookie is present — it should not attempt to verify a missing cookie and must not set `c.get('user')` to `undefined`. The downstream `oidcAuthMiddleware` redirects only when `c.get('user')` is falsy.

---

## JWT Session Cookie Pattern

### `issueLocalSessionCookie` / `verifyLocalSessionCookie`

Uses Hono's built-in `Jwt` from `hono/utils/jwt`. The algorithm is HS256 (symmetric, fast, appropriate for a single-server household app). [VERIFIED: codebase — `Jwt.sign` and `Jwt.verify` confirmed callable at runtime]

```typescript
// Source: hono/utils/jwt (runtime-verified in this project)
import { Jwt } from 'hono/utils/jwt';
import { setCookie, getCookie, deleteCookie } from 'hono/cookie';
import type { Context } from 'hono';

const COOKIE_NAME = 'local-session';
const SESSION_MAX_AGE_SECONDS = Number(process.env.LOCAL_SESSION_EXPIRES ?? 86400); // 1 day default

export async function issueLocalSessionCookie(c: Context, userId: number): Promise<void> {
  const secret = process.env.LOCAL_SESSION_SECRET;
  if (!secret) throw new Error('LOCAL_SESSION_SECRET env var not set');

  const now = Math.floor(Date.now() / 1000);
  const payload = { userId, iat: now, exp: now + SESSION_MAX_AGE_SECONDS };

  const token = await Jwt.sign(payload, secret, 'HS256');

  setCookie(c, COOKIE_NAME, token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'Lax',
    path: '/',
    maxAge: SESSION_MAX_AGE_SECONDS,
  });
}

export async function verifyLocalSessionCookie(c: Context): Promise<number | null> {
  const secret = process.env.LOCAL_SESSION_SECRET;
  if (!secret) return null;

  const token = getCookie(c, COOKIE_NAME);
  if (!token) return null;

  try {
    const payload = await Jwt.verify(token, secret, 'HS256');
    return typeof payload.userId === 'number' ? payload.userId : null;
  } catch {
    return null;
  }
}

export function clearLocalSessionCookie(c: Context): void {
  deleteCookie(c, COOKIE_NAME, { path: '/', httpOnly: true, secure: true, sameSite: 'Lax' });
}
```

**Cookie name:** `local-session` (distinct from the OIDC cookie `oidc-auth` — avoids collision).

**`LOCAL_SESSION_SECRET` env var:** This is a new env-floor secret that must be added to the D-01 minimal env kernel documentation (it encrypts the local session JWT). It never goes to `app_config`. Operators generate it with `openssl rand -base64 32`. The `generate-secrets` script from Phase 12 should be extended to emit it.

---

## Local Login Endpoint

### `POST /api/auth/local/login`

[ASSUMED — specific implementation, but directly derived from the patterns in `setup.ts` and `admin.ts`]

```typescript
// apps/api/src/routes/localAuth.ts
const loginSchema = z.object({
  username: z.string().min(1).max(128).trim(),
  password: z.string().min(1).max(1000),
});

// Rate-limiting: simple in-memory Map (household scale; no Redis needed)
// { ip → { failCount, lockedUntil } }
const loginAttempts = new Map<string, { count: number; lockedUntil: number; lockedOut: boolean }>();
const RATE_WINDOW_FAILURES = 5;  // 5 failures → 60s cooldown
const RATE_WINDOW_SECS = 60;
const LOCKOUT_FAILURES = 10;     // 10 failures → account locked (admin must reset)

localAuthRouter.post('/login', zValidator('json', loginSchema, noEchoHook), async (c) => {
  const ip = c.req.header('x-forwarded-for') ?? c.req.raw.headers.get('host') ?? 'unknown';

  // Check rate limit / lockout
  const attempt = loginAttempts.get(ip);
  if (attempt?.lockedOut) {
    return c.json({ error: 'Account locked' }, 423);
  }
  if (attempt && attempt.count >= RATE_WINDOW_FAILURES && Date.now() < attempt.lockedUntil) {
    return c.json({ error: 'Too many attempts' }, 429);
  }

  const { username, password } = c.req.valid('json');

  // Lookup by username — constant-time operation for timing safety
  const [cred] = await db
    .select({ userId: localCredentials.userId, passwordHash: localCredentials.passwordHash })
    .from(localCredentials)
    .where(eq(localCredentials.username, username))
    .limit(1);

  // Always run verifyPassword even on unknown username (dummy hash) to prevent timing oracle
  const dummy = hashPassword('dummy-constant-time-filler');
  const valid = cred ? verifyPassword(cred.passwordHash, password) : verifyPassword(dummy, password);

  if (!valid || !cred) {
    // Increment failure counter
    const cur = loginAttempts.get(ip) ?? { count: 0, lockedUntil: 0, lockedOut: false };
    cur.count += 1;
    cur.lockedUntil = Date.now() + RATE_WINDOW_SECS * 1000;
    cur.lockedOut = cur.count >= LOCKOUT_FAILURES;
    loginAttempts.set(ip, cur);
    return c.json({ error: 'Invalid credentials' }, 401);
  }

  // Success: clear failure counter, issue session cookie
  loginAttempts.delete(ip);
  await issueLocalSessionCookie(c, cred.userId);
  return c.json({ ok: true }, 200);
});
```

**Security notes:**
- The `noEchoHook` must be used on `zValidator` for the login route — same as credential routes — to prevent Zod errors from echoing the submitted password.
- "Username not found" and "wrong password" return the same 401 + same copy — no field discrimination.
- The dummy hash prevents timing oracle on username enumeration.
- Rate-limiting is per-IP (from `X-Forwarded-For` header, which Pangolin sets). For a 2-person household this is more than sufficient.
- Lockout (423) is resolved only by admin password reset — mirrors the UI copy "Contact your admin to reset access".

---

## Auth Mode Endpoint

### `GET /api/auth/mode` (pre-auth)

Must be mounted **before** all auth middleware in `index.ts` (same pre-auth pattern as `/api/setup/*` and `/health`). [VERIFIED: codebase — `app.route('/api/setup', setupRouter)` mounts pre-auth; same pattern applies]

```typescript
// apps/api/src/routes/authMode.ts
authModeRouter.get('/', async (c) => {
  // localEnabled: always true — local auth is the default and always available (D-01)
  // oidcEnabled: true when oidc_issuer is configured in app_config OR process.env
  const issuerFromEnv = process.env.OIDC_ISSUER;
  let oidcEnabled = Boolean(issuerFromEnv);

  if (!oidcEnabled) {
    const [row] = await db
      .select({ value: appConfig.value })
      .from(appConfig)
      .where(eq(appConfig.key, 'oidc_issuer'))
      .limit(1);
    oidcEnabled = Boolean(row?.value);
  }

  return c.json({ localEnabled: true, oidcEnabled });
});
```

This endpoint is not protected by OIDC middleware. The PWA fetches it on app load before knowing if the user is authenticated.

---

## OIDC-Link Flow

D-12: when a local user explicitly links an OIDC identity, their `local_credentials` row is deleted and `users.oidc_iss`/`oidc_sub` are populated. The returned `iss+sub` must not already belong to another user.

### Recommended Implementation

The simplest approach reuses the existing `/callback` handler: add a `link_mode` query param that signals the OIDC callback to run in "link" mode rather than "new session" mode.

**Flow:**
1. User (authenticated as local user with valid `local-session` cookie) clicks "Continue with OIDC"
2. PWA calls `POST /api/me/link-oidc` → server initiates OIDC authorization-code redirect with `state` parameter encoding `{ linkUserId: currentUserId, nonce }`
3. OIDC callback fires → `processOAuthCallback` handles the code exchange, gets `iss+sub`
4. Backend detects `linkUserId` in state → look up if `iss+sub` already belongs to a different user → if yes, 409 error page; if no, UPDATE `users SET oidc_iss, oidc_sub WHERE id = linkUserId`, DELETE from `local_credentials WHERE user_id = linkUserId`
5. Issue OIDC session (the user is now OIDC-only) → redirect to `/calendar`

**Alternative (simpler, recommended):** A dedicated `POST /api/me/link-oidc` endpoint that initiates the OIDC redirect. The current user's `userId` is encoded in the OIDC `state` parameter (signed to prevent CSRF). On callback, the backend reads `state.userId`, verifies the OIDC identity is unique, binds it.

**D-10 constraint:** Identity binding must use `iss+sub` from the OIDC token, never email. The `upsertUser` function already enforces this — the link flow must replicate this strictness.

**409 conflict:** If the `iss+sub` returned by OIDC already exists in `users`, return a redirect to an error page. The PWA displays: "This OIDC identity is already linked to another account. Please contact your admin."

---

## Admin Account Management API

### New Routes on `adminRouter`

Extends `apps/api/src/routes/admin.ts`. The `requireAdmin` guard at the router level already covers these. [VERIFIED: codebase — `adminRouter.use('*', requireAdmin)` is the first statement]

**Create member:**
```typescript
adminRouter.post('/members', zValidator('json', createMemberSchema, noEchoHook), async (c) => {
  // 1. Insert into users (displayName, color from palette)
  // 2. Hash initialPassword via hashPassword()
  // 3. Insert into local_credentials (userId, username, passwordHash)
  // If username conflict: 409
});
```

**Reset password:**
```typescript
adminRouter.post('/members/:id/password', zValidator('json', resetPasswordSchema, noEchoHook), async (c) => {
  // Admin does not need to know the current password (D-11)
  // 1. Verify target user exists + has local_credentials row
  // 2. Hash newPassword
  // 3. UPDATE local_credentials SET password_hash WHERE user_id
  // Also clear any in-memory lockout entry for this user
});
```

**Extend `GET /api/admin/members`** to include `hasLocalCredential: boolean` (LEFT JOIN on `local_credentials`).

---

## Self-Service Password Change

### `POST /api/me/password`

Added to `apps/api/src/routes/me.ts`. [ASSUMED — derived from existing `POST /api/me/credential` pattern]

```typescript
meRouter.post('/password', zValidator('json', changePasswordSchema, meNoEchoHook), async (c) => {
  const currentUserId = await resolveUserId(c);
  if (!currentUserId) return c.json({ error: 'Unauthorized' }, 401);

  const [cred] = await db.select().from(localCredentials).where(eq(localCredentials.userId, currentUserId)).limit(1);
  if (!cred) return c.json({ error: 'No local credential' }, 404);

  const { currentPassword, newPassword } = c.req.valid('json');
  if (!verifyPassword(cred.passwordHash, currentPassword)) {
    return c.json({ error: 'Current password incorrect' }, 401);
  }

  const newHash = hashPassword(newPassword);
  await db.update(localCredentials).set({ passwordHash: newHash }).where(eq(localCredentials.userId, currentUserId));

  return c.json({ ok: true }, 200);
});
```

**Note:** After a password change, existing sessions remain valid (D-05 tradeoff — stateless JWT, no revocation). This is documented and accepted.

---

## `/api/me` Extensions

`GET /api/me` must return `hasLocalCredential: boolean` so the PWA knows whether to show "Change password" and "Link OIDC identity" in `SettingsSheet`. [ASSUMED — straightforward LEFT JOIN on `local_credentials`]

Add `hasLocalCredential` alongside `isAdmin` and `needsProviderSetup` in the `resolveAdminAndSetupStatus` function.

---

## Break-Glass CLI

D-13: break-glass is a CLI/console command or env override. Recommended form: a standalone Node.js/tsx script `apps/api/scripts/reset-admin.ts` that:
1. Accepts `--username` and `--password` CLI args
2. Connects to the DB using the same env vars as the app (`DB_HOST`, `DB_USER`, etc.)
3. Upserts a `users` row with `is_admin=true, claimed=true` for the given username (or finds existing by username)
4. Upserts `local_credentials` for that user with the hashed password
5. Prints the resulting user ID

This script is:
- Not imported by any production code
- Listed in `.dockerignore` `scripts/` exclusion (verify `.dockerignore` covers this; if `scripts/` is not yet excluded, add it)
- Gated with a `NODE_ENV !== 'production'` guard as defense-in-depth

Usage: `docker exec -it familysync-api node --import=tsx/esm scripts/reset-admin.ts --username admin --password 'newpass'`

Alternatively: an `APP_RECOVERY_USER` + `APP_RECOVERY_PASSWORD` env pair that, if set at boot, creates/updates that local user before the server starts (similar to some Docker apps' `INITIAL_ADMIN_PASSWORD`). This is simpler to deploy but exposes the password in env. The CLI script is cleaner.

---

## Dev-Bypass Rework

### Recommendation: Option C — bypass issues a real local-session cookie

The three options from the CONTEXT.md open questions:

| Option | Description | Assessment |
|--------|-------------|------------|
| A | Keep bypass + seed a real test login for login-specific specs | Most complex — two auth paths in harness |
| B | Replace bypass with seeded auto-login through the real local flow | Requires changing ALL 40+ harness startup assertions; riskiest |
| C | Bypass auto-issues a real local-session cookie | Minimal change to existing harness; satisfies D-15 |

**Recommendation: Option C.** When `DEV_AUTH_BYPASS=true`:
- `devAuthBypass()` still sets `c.get('user')` (existing behavior — unchanged)
- A new companion `devSessionCookieMiddleware()` mounted just after `devAuthBypass()` issues a signed `local-session` cookie for `DEV_USER.id` (using `LOCAL_SESSION_SECRET`) on every request that doesn't already have one
- The PWA login page sees `local-session` cookie already set → skips to `/calendar`
- Login-specific Playwright specs can explicitly clear the cookie and test the real login form

This means:
1. The harness `global-setup.ts` seeds `local_credentials` for `DEV_USER` (id=1) with a known dev-only username/password
2. The `devAuthBypass()` function already handles the API-side auth
3. The PWA routing gate (which checks for a valid session cookie) works because a `local-session` cookie is present

**D-15 compliance:** `devSessionCookieMiddleware()` is inside `auth/devBypass.ts` (the same file the IMG-01 boot guard protects) and is only mounted when `DEV_AUTH_BYPASS=true`. The `assertNotDevBypassInProduction()` guard already blocks this in production.

**Minimal `global-setup.ts` change:**
```typescript
// Seed local_credentials for dev user (id=1) — Option C
await conn.execute(
  `INSERT INTO local_credentials (user_id, username, password_hash) VALUES (1, 'devuser', ?)
   ON DUPLICATE KEY UPDATE password_hash = VALUES(password_hash)`,
  [hashPassword('devpass')]
);
// (hashPassword is called inline or imported from a compiled path)
```

**CI `ci.yml` change:** Add `LOCAL_SESSION_SECRET=dev-secret-change-me` to the harness job env (used by `devSessionCookieMiddleware` and `global-setup.ts` hash). Add `local_credentials` table seed to the CI seeding step.

---

## PWA Routing Gate

### App.tsx changes

The current `App.tsx` setup gate checks `setupQuery.data?.setupComplete`. Phase 19 adds a parallel auth-mode gate. [VERIFIED: codebase — `App.tsx` lines 140–230 read]

**New fetch on app load:**
```typescript
const authModeQuery = useQuery({
  queryKey: ['authMode'],
  queryFn: () => fetch('/api/auth/mode').then(r => r.json()),
  staleTime: 60_000,  // auth mode changes rarely; 1 min stale is fine
});
```

**Gate logic (simplified):**
1. If setup not complete → `/setup`
2. If `meQuery` succeeds (user authenticated) → normal app
3. If `meQuery` fails 401 and `authMode.localEnabled` → `/login`
4. If `meQuery` fails 401 and `!authMode.localEnabled && authMode.oidcEnabled` → trigger OIDC redirect (top-level nav to `/api/login`)

The `/login` route renders `<LoginPage />` standalone (no AppNav, no BottomTabBar) — same pattern as `/setup`.

---

## BYO-Auth De-Authelia-ization

D-06 requires removing Authelia-specific copy from user-facing strings and config. [VERIFIED: codebase — checked `middleware.ts`, `index.ts`, `setup.ts` for "Authelia" references]

**What to change:**
- `apps/api/src/auth/middleware.ts` header comment: "Authelia as the identity provider" → "generic OIDC identity provider"
- Remove references to `OIDC_ISSUER` being "Authelia base URL" in inline comments → "OIDC issuer URL"
- The `app_config` keys are already generic (`oidc_issuer`, `oidc_client_id`) — no key changes needed
- The setup wizard Step 3 label (if any) mentioning Authelia → generic "OIDC provider"
- User-facing copy: already handled by UI-SPEC (never say "Authelia")

**What NOT to change:** The actual `@hono/oidc-auth` library, PKCE flow, or any runtime behavior — these are already provider-agnostic.

---

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Password hashing | Custom hash function | `node:crypto` scrypt | Side-channel timing, parameter management, salt uniqueness |
| JWT signing | HMAC-SHA256 manually | `Jwt.sign`/`Jwt.verify` from `hono/utils/jwt` | Already installed; handles base64url encoding, exp checking |
| Cookie serialization | Manual `Set-Cookie` string | `hono/cookie` `setCookie`/`getCookie` | Already used in `persistSessionCookie.ts`; handles attributes correctly |
| Constant-time comparison | `===` on hash strings | `timingSafeEqual` from `node:crypto` | Prevents timing oracle attacks on credential comparison |
| OIDC code exchange | Custom OAuth flow | `@hono/oidc-auth` `processOAuthCallback` + `oidcAuthMiddleware` | Already installed and working |
| Rate-limiting storage | Redis or DB sessions | In-memory Map | Household scale; single process; Redis is overkill |

**Key insight:** This phase's auth primitives are entirely in stdlib (`node:crypto`) and packages already installed (`hono/utils/jwt`, `hono/cookie`). The zero-new-dependency constraint is achievable without compromise.

---

## Common Pitfalls

### Pitfall 1: OIDC guard 302-redirecting local-session requests

**What goes wrong:** `oidcAuthMiddleware()` intercepts requests that already have a valid `local-session` cookie and redirects to Authelia.

**Why it happens:** `oidcAuthMiddleware` redirects any request where `getAuth(c)` returns null, regardless of whether another auth mechanism already authenticated the user.

**How to avoid:** Wrap `oidcAuthMiddleware` in a guard that skips it when `c.get('user')` is already set (by `localAuthMiddleware` or `devAuthBypass`). See §Middleware Slot.

**Warning signs:** Local login succeeds (200 + cookie set) but next `/api/me` request returns 302.

---

### Pitfall 2: Timing oracle on username enumeration

**What goes wrong:** Login returns faster for non-existent usernames (no hash computation) than for wrong passwords (hash computed).

**Why it happens:** `if (!cred) return 401` skips `verifyPassword`.

**How to avoid:** Always call `verifyPassword` — use a pre-computed dummy hash when the username is not found (see §Local Login Endpoint).

**Warning signs:** Measurable latency difference in login responses for known vs unknown usernames.

---

### Pitfall 3: Zod error echoing the password

**What goes wrong:** `zValidator` default error handler returns `result.error` which includes `issues[].received` — the submitted password.

**Why it happens:** No `noEchoHook` provided.

**How to avoid:** All `zValidator` calls on the login, password-change, and create-member routes MUST use `noEchoHook`. [VERIFIED: codebase — pattern established in `setup.ts`, `admin.ts`, `me.ts`]

---

### Pitfall 4: `local-session` cookie colliding with `oidc-auth` cookie

**What goes wrong:** If the cookie name `local-session` matches the OIDC cookie name, `persistSessionCookie.ts` reads the wrong cookie.

**Why it happens:** `persistSessionCookie.ts` reads `process.env.OIDC_COOKIE_NAME ?? 'oidc-auth'` — these are different names by default.

**How to avoid:** Keep the local-session cookie name `local-session` (distinct from `oidc-auth`). Never set `OIDC_COOKIE_NAME=local-session` in env.

---

### Pitfall 5: `local_credentials` FK constraint before `users` row

**What goes wrong:** Inserting `local_credentials` before the `users` row exists fails with FK error.

**Why it happens:** `local_credentials.user_id` references `users.id`.

**How to avoid:** Always insert `users` row first, then `local_credentials`. Wrap in a transaction for admin create-member. [VERIFIED: codebase — same pattern documented in `setup.ts` at `POST /api/setup/credential`]

---

### Pitfall 6: OIDC-link without checking `iss+sub` uniqueness

**What goes wrong:** Two local users attempt to link the same OIDC account → one succeeds, one silently overwrites.

**Why it happens:** No uniqueness check before binding `iss+sub`.

**How to avoid:** Before UPDATE-ing `users.oidc_iss`/`oidc_sub`, SELECT to verify no existing row has that `iss+sub` pair. Return 409 if conflict. The `uniq_oidc_identity` index on `users` is also a safety net (will throw a DB unique violation). [VERIFIED: codebase — `schema.ts` line 63, `unique('uniq_oidc_identity').on(t.oidcIss, t.oidcSub)`]

---

### Pitfall 7: Dev bypass seeds in prod image

**What goes wrong:** `local_credentials` seed for dev user (id=1) ships in the production Docker image, granting access with a known password.

**Why it happens:** `scripts/` or seed data not excluded from Docker image.

**How to avoid:** Verify `.dockerignore` excludes `scripts/`. The `local_credentials` dev seed goes in `global-setup.ts` (Playwright) and the CI step — NOT in any migration or startup code. The `assertNotDevBypassInProduction()` guard blocks the dev-session-cookie middleware in production. [VERIFIED: codebase — IMG-01/02/03 gates from Phase 16]

---

### Pitfall 8: `Jwt.verify` import path

**What goes wrong:** `import { sign, verify } from 'hono/utils/jwt'` fails — `hono/utils/jwt` exports only `{ Jwt }` (default object), not named exports.

**Why it happens:** The Hono `utils/jwt/index.js` wraps the functions in a `Jwt` namespace object.

**How to avoid:** Use `import { Jwt } from 'hono/utils/jwt'` then call `Jwt.sign()` / `Jwt.verify()`. [VERIFIED: codebase — confirmed at runtime: `Jwt.sign type: function`]

---

### Pitfall 9: `Jwt.verify` throws on expired token (must catch)

**What goes wrong:** If the `local-session` JWT is expired, `Jwt.verify` throws `JwtTokenExpired` rather than returning null.

**Why it happens:** This is expected Hono behavior — errors are thrown, not returned.

**How to avoid:** Wrap `Jwt.verify` in try/catch in `verifyLocalSessionCookie`. Return `null` on any error (including expiry). [ASSUMED — derived from Hono JWT error types visible in `jwt.js` source]

---

### Pitfall 10: `LOCAL_SESSION_SECRET` missing at boot

**What goes wrong:** `issueLocalSessionCookie` throws because `LOCAL_SESSION_SECRET` is not set.

**Why it happens:** New env var; operator didn't add it to Docker compose.

**How to avoid:** Add a boot-time assertion alongside `assertNotDevBypassInProduction()`: check `LOCAL_SESSION_SECRET` is set and >= 32 chars when not in dev-bypass mode. Log a clear error and refuse to start.

---

### Pitfall 11: Harness `global-setup.ts` seeding `local_credentials` hash without importing app code

**What goes wrong:** `global-setup.ts` is plain Node.js (no tsx/TypeScript — per its own comment "Plain Node.js only"). If it tries to import `hashPassword` from the API source, it needs to compile first.

**Why it happens:** `global-setup.ts` uses `mysql2/promise` directly, no app imports.

**How to avoid:** Inline the `hashPassword` implementation in `global-setup.ts` (copy the 5-line scrypt hash function), or pre-hash the dev password at a known constant and hard-code the encoded string in the seed. Since `global-setup.ts` already knows the dev-bypass semantics, a hard-coded dev hash (never used in production) is acceptable.

---

## Code Examples

### scrypt hash + verify (production pattern)

```typescript
// Source: runtime-verified on Node 22.22.3 in this project
import { scryptSync, randomBytes, timingSafeEqual } from 'node:crypto';

export function hashPassword(password: string): string {
  const salt = randomBytes(16);
  const hash = scryptSync(password, salt, 32, { N: 16384, r: 8, p: 1 });
  return ['scrypt', 16384, 8, 1, salt.toString('base64url'), hash.toString('base64url')].join('$');
}

export function verifyPassword(stored: string, candidate: string): boolean {
  try {
    const [, n, r, p, saltB64, hashB64] = stored.split('$');
    const salt = Buffer.from(saltB64, 'base64url');
    const storedHash = Buffer.from(hashB64, 'base64url');
    const check = scryptSync(candidate, salt, storedHash.length, {
      N: Number(n), r: Number(r), p: Number(p),
    });
    return timingSafeEqual(storedHash, check);
  } catch {
    return false;
  }
}
```

### Hono JWT session cookie issuance

```typescript
// Source: runtime-verified — Jwt.sign/verify confirmed from hono/utils/jwt
import { Jwt } from 'hono/utils/jwt';
import { setCookie, getCookie, deleteCookie } from 'hono/cookie';

export async function issueLocalSessionCookie(c: Context, userId: number): Promise<void> {
  const secret = process.env.LOCAL_SESSION_SECRET!;
  const maxAge = Number(process.env.LOCAL_SESSION_EXPIRES ?? 86400);
  const now = Math.floor(Date.now() / 1000);
  const token = await Jwt.sign({ userId, iat: now, exp: now + maxAge }, secret, 'HS256');
  setCookie(c, 'local-session', token, {
    httpOnly: true,
    secure: process.env.NODE_ENV === 'production',
    sameSite: 'Lax',
    path: '/',
    maxAge,
  });
}
```

### localAuthMiddleware pattern (mirrors devAuthBypass)

```typescript
// Source: apps/api/src/auth/devBypass.ts (verified — the pattern to mirror)
import type { MiddlewareHandler } from 'hono';
import { verifyLocalSessionCookie } from './localSession.js';
import { db } from '../db/client.js';
import { users } from '../db/schema.js';
import { eq } from 'drizzle-orm';

export function localAuthMiddleware(): MiddlewareHandler {
  return async (c, next) => {
    // Skip if already authenticated (devAuthBypass ran first)
    if (c.get('user')) { await next(); return; }

    const userId = await verifyLocalSessionCookie(c);
    if (!userId) { await next(); return; }

    const [user] = await db.select().from(users).where(eq(users.id, userId)).limit(1);
    if (user) {
      c.set('user', {
        id: user.id,
        oidcIss: user.oidcIss ?? 'local',
        oidcSub: user.oidcSub ?? String(user.id),
        displayName: user.displayName ?? null,
        color: user.color,
      });
    }
    await next();
  };
}
```

---

## Environment Availability

| Dependency | Required By | Available | Version | Fallback |
|------------|------------|-----------|---------|----------|
| Node.js 22 | `node:crypto` scrypt | ✓ | 22.22.3 | — (required) |
| MariaDB | `local_credentials` table | ✓ (Docker) | 11.x | — |
| `hono/utils/jwt` | JWT session signing | ✓ | hono@4.12.23 | — (already installed) |
| `hono/cookie` | Cookie read/write | ✓ | hono@4.12.23 | — (already installed) |
| `drizzle-kit` | Schema migration | ✓ | 0.31.10 | — |
| `LOCAL_SESSION_SECRET` env | JWT signing | ✗ (not yet set) | — | Add to docker-compose env + generate-secrets script |

**Missing dependencies with no fallback:**
- `LOCAL_SESSION_SECRET` env var — must be added to the operator's Docker Compose file and to the `generate-secrets` script. Absence must be caught at boot.

---

## Validation Architecture

`workflow.nyquist_validation` is enabled (absent = enabled per config). Security-critical auth flows — all test seams enumerated.

### Test Framework

| Property | Value |
|----------|-------|
| Framework | Vitest 4.1.8 |
| Config file | `apps/api/vitest.config.ts` |
| Quick run command | `pnpm --filter @familysync/api test` |
| Full suite command | `pnpm --filter @familysync/api test && pnpm --filter @familysync/pwa test:e2e` |

### Phase Requirements → Test Map

| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| AUTH-LOCAL-01 | `local_credentials` table schema | integration | `pnpm --filter @familysync/api test tests/db/schema.test.ts` | ❌ Wave 0 |
| AUTH-LOCAL-02 | `hashPassword` round-trip + `verifyPassword` timing-safe | unit | `pnpm --filter @familysync/api test tests/auth/localCredentials.test.ts` | ❌ Wave 0 |
| AUTH-LOCAL-03 | `POST /api/auth/local/login` — 200 success, 401 wrong, 429 rate, 423 lockout | unit+integration | `pnpm --filter @familysync/api test tests/routes/localAuth.test.ts` | ❌ Wave 0 |
| AUTH-LOCAL-04 | `localAuthMiddleware` — sets c.get('user') with valid cookie; no-op without cookie | unit | `pnpm --filter @familysync/api test tests/auth/localAuthMiddleware.test.ts` | ❌ Wave 0 |
| AUTH-LOCAL-05 | `GET /api/auth/mode` — returns `{localEnabled:true, oidcEnabled}` | unit | `pnpm --filter @familysync/api test tests/routes/authMode.test.ts` | ❌ Wave 0 |
| AUTH-LOCAL-06 | `POST /api/auth/local/logout` — clears cookie | unit | included in `localAuth.test.ts` | ❌ Wave 0 |
| AUTH-LOCAL-07 | Admin create member — 201 on success, 409 on duplicate username | unit | `pnpm --filter @familysync/api test tests/routes/admin.test.ts` | ✅ (extend) |
| AUTH-LOCAL-08 | Admin reset password — updates hash | unit | included in `admin.test.ts` | ✅ (extend) |
| AUTH-LOCAL-09 | Self-change password — verify current, update hash | unit | `pnpm --filter @familysync/api test tests/routes/me.test.ts` | ✅ (extend) |
| AUTH-LOCAL-10 | OIDC-link — binds iss+sub, deletes local_credentials, 409 on conflict | unit | included in `me.test.ts` | ✅ (extend) |
| AUTH-LOCAL-11 | Break-glass CLI — creates admin user | manual/smoke | `tsx scripts/reset-admin.ts --dry-run` | ❌ Wave 0 |
| AUTH-LOCAL-12 | LoginPage renders brand slot + form; submits and receives cookie | e2e (Playwright) | `pnpm --filter @familysync/pwa test:e2e --grep "login"` | ❌ Wave 0 |
| AUTH-LOCAL-15 | App.tsx redirects unauthed user to /login | e2e | included in login spec | ❌ Wave 0 |
| AUTH-LOCAL-16 | Harness continues to work with Option C dev-bypass | e2e | existing harness | ✅ (verify after change) |
| AUTH-LOCAL-19 | Rate-limit 429 after 5 failures; lockout 423 after 10 | unit | included in `localAuth.test.ts` | ❌ Wave 0 |

### Sampling Rate

- **Per task commit:** `pnpm --filter @familysync/api test` (unit suite, ~10s)
- **Per wave merge:** `pnpm --filter @familysync/api test && pnpm --filter @familysync/pwa test` (unit + PWA unit)
- **Phase gate:** Full suite including Playwright harness before `/gsd-verify-work`

### Wave 0 Gaps

- [ ] `tests/auth/localCredentials.test.ts` — covers AUTH-LOCAL-02 (hash round-trip, timing-safe)
- [ ] `tests/auth/localAuthMiddleware.test.ts` — covers AUTH-LOCAL-04
- [ ] `tests/routes/authMode.test.ts` — covers AUTH-LOCAL-05
- [ ] `tests/routes/localAuth.test.ts` — covers AUTH-LOCAL-03/06/19
- [ ] `apps/pwa/e2e/login.spec.ts` — covers AUTH-LOCAL-12/15

---

## Security Domain

`security_enforcement: true` (enabled in config.json).

### Applicable ASVS Categories (Level 1)

| ASVS Category | Applies | Standard Control |
|---------------|---------|-----------------|
| V2 Authentication | YES | `node:crypto` scrypt + PHC encoding; `timingSafeEqual`; no username-enumeration timing oracle |
| V3 Session Management | YES | Stateless signed JWT; `httpOnly + Secure + SameSite=Lax`; maxAge 1 day; logout = cookie clear |
| V4 Access Control | YES | `requireAdmin` on all admin routes; `resolveUserId` always from session, never body; self-service can only modify own credential |
| V5 Input Validation | YES | `zod` + `@hono/zod-validator` on all auth routes; `noEchoHook` prevents Zod errors from echoing passwords |
| V6 Cryptography | YES (partially) | `node:crypto` scrypt (strong KDF); HS256 JWT (symmetric — acceptable for single-server; if multi-server ever applies, upgrade to RS256) |

### Known Threat Patterns

| Pattern | STRIDE | Standard Mitigation |
|---------|--------|---------------------|
| Username enumeration via timing | Information Disclosure | Dummy hash verify when username not found; `timingSafeEqual` |
| Credential brute force | Elevation of Privilege | Per-IP rate-limit (5 failures → 60s cooldown → 429); account lockout at 10 (423) |
| Session fixation | Elevation of Privilege | Issue new JWT on every login; old JWTs expire via `exp` claim |
| Password echoed in error response | Information Disclosure | `noEchoHook` on all `zValidator` calls on auth routes |
| Local-session cookie in prod image | Elevation of Privilege | D-15: `assertNotDevBypassInProduction()`; `.dockerignore` for scripts; seed only in `global-setup.ts` |
| OIDC-link CSRF | Tampering | `state` parameter in OIDC redirect must be signed/nonce'd; `iss+sub` uniqueness checked server-side |
| OIDC-link identity collision | Elevation of Privilege | `uniq_oidc_identity` DB constraint + pre-flight SELECT → 409 on conflict |
| Missing `LOCAL_SESSION_SECRET` | Elevation of Privilege | Boot-time assertion; loud error + non-zero exit |
| `local-session` cookie in XSS | Information Disclosure | `httpOnly: true` prevents JS access; OIDC cookie has same protection |

---

## State of the Art

| Old Approach | Current Approach | Notes |
|--------------|------------------|-------|
| argon2id (native addon) | `node:crypto` scrypt | D-08 mandates no native deps; scrypt is OWASP-approved for this use |
| DB session table | Stateless JWT cookie | D-05; consistent with `@hono/oidc-auth` pattern |
| Hardcoded Authelia references | Generic OIDC copy | D-06 BYO-Auth principle |

---

## Open Questions

### Resolved by Research

1. **Dev-bypass rework** → Recommend Option C (bypass issues real `local-session` cookie). Minimal harness change; satisfies D-14 and D-15.
2. **Break-glass form** → Recommend CLI script `scripts/reset-admin.ts` (tsx, runnable via `docker exec`). No new role model needed.
3. **OIDC-link mechanism** → Reuse OIDC callback (`/callback`) with a signed `state` parameter encoding `{ linkUserId }`. Simpler than a new endpoint because `processOAuthCallback` already handles the code exchange.
4. **`Jwt.sign`/`Jwt.verify` import** → `import { Jwt } from 'hono/utils/jwt'` (namespace import) — not named exports.

### Still Open (require planner decision)

1. **OIDC-only user provisioning:** How does an OIDC-only user get their `users` row now that the setup wizard's single-unclaimed-row claim (Phase 12 D-08) only works for one pre-created user? The current `upsertUser` in `auth/user.ts` already handles this: when `setup_complete === true` and no unclaimed row exists, it inserts a new fully-claimed OIDC user row (step 3/5 in `upsertUser`). The existing behavior already handles OIDC-only users without Phase 19 changes — no open issue here in practice. **Confirm:** planner should verify this path still works after Phase 19 DB changes.

2. **Admin UI for managing OIDC-only users:** Can an admin remove a user's OIDC binding (reverting them to local-only)? D-12 says OIDC-link is one-directional (removes local cred) and "can't be undone from the app." This is correct per the UI-SPEC. No admin UI for OIDC-unlinking is in scope for Phase 19.

3. **`LOCAL_SESSION_SECRET` and `generate-secrets` script update:** The Phase 12 `generate-secrets` script generates `SESSION_SECRET`, `APP_PASSWORD_ENCRYPTION_KEY`, and VAPID keys. It should be extended to also generate `LOCAL_SESSION_SECRET`. Planner should include a task to update `scripts/generate-secrets.ts`.

4. **`scripts/` in `.dockerignore`:** Verify `.dockerignore` already excludes `scripts/`. If not, a task to add `scripts/` to `.dockerignore` is required for D-15 compliance.

---

## Assumptions Log

| # | Claim | Section | Risk if Wrong |
|---|-------|---------|---------------|
| A1 | `Jwt.verify` throws on expired token (caught in try/catch in `verifyLocalSessionCookie`) | §Common Pitfalls 9, §JWT Session Cookie | Session cookie not cleared on expiry; user remains "logged in" until cookie maxAge expires naturally |
| A2 | `deleteCookie` from `hono/cookie` is available in hono@4.12.23 | §JWT Session Cookie | Logout implementation needs alternative cookie-clear method (can use `setCookie` with `maxAge: 0`) |
| A3 | OIDC-link via signed `state` param in `/callback` is the cleanest mechanism | §OIDC-Link Flow | May need a dedicated endpoint; planner may choose differently |
| A4 | The `scripts/reset-admin.ts` approach satisfies break-glass requirement | §Break-Glass | Operator may prefer env-var recovery; both are viable |
| A5 | `hono/utils/jwt` `Jwt.sign` uses Web Crypto API internally (async, returns Promise) | §JWT Session Cookie | If sync behavior is needed, alternative needed — but async is the Hono convention |

---

## Sources

### Primary (VERIFIED from codebase)
- `apps/api/src/auth/devBypass.ts` — `c.set('user')` pattern, `DEV_USER` shape, IMG-01 guard
- `apps/api/src/auth/middleware.ts` — OIDC middleware wiring, `oidcConfigFallbackMiddleware`
- `apps/api/src/auth/persistSessionCookie.ts` — `setCookie` pattern, maxAge, httpOnly/Secure
- `apps/api/src/auth/user.ts` — `upsertUser`, first-login-claims, D-10 identity model
- `apps/api/src/db/schema.ts` — `users`, `memberCredentials`, `appConfig` definitions
- `apps/api/src/index.ts` — full middleware ordering, pre-auth routes, `devBypassActive` pattern
- `apps/api/src/routes/admin.ts` — `requireAdmin`, `noEchoHook`, admin route patterns
- `apps/api/src/routes/me.ts` — `resolveUserId`, `resolveAdminAndSetupStatus`, `POST /credential`
- `apps/api/src/routes/setup.ts` — pre-auth route pattern, `isSetupLocked`, `noEchoHook`
- `apps/api/src/lib/bootGuards.ts` — `assertNotDevBypassInProduction`
- `apps/api/tests/routes/login.test.ts` — vitest mock patterns for auth tests
- `apps/pwa/e2e/global-setup.ts` — harness seed pattern, DEV_AUTH_BYPASS guard
- `apps/pwa/src/App.tsx` — PWA routing gate, setup gate, `meQuery`, route structure
- `apps/api/src/db/migrations/0002_lethal_millenium_guard.sql` — additive migration example
- `.gitea/workflows/ci.yml` — CI harness step, DEV_AUTH_BYPASS env, seed step pattern
- Node.js 22.22.3 runtime — confirmed: `scryptSync`, `randomBytes`, `timingSafeEqual` available
- `hono@4.12.23` runtime — confirmed: `Jwt.sign`, `Jwt.verify` from `hono/utils/jwt`; `getCookie`, `setCookie` from `hono/cookie`
- `hono/dist/utils/jwt/jwt.js` — source-read to understand error types and import shape

### Secondary (ASSUMED from training + project patterns)
- OWASP scrypt parameters (N=16384, r=8, p=1 as minimum; N=65536 preferred if hardware allows)
- PHC-style `$`-delimited encoded hash format for self-describing password hashes
- Rate-limit implementation as in-memory Map (appropriate for single-process household scale)

---

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH — everything is the existing installed stack; no new packages; runtime-verified
- Architecture: HIGH — derived directly from reading the actual middleware chain and existing patterns
- Pitfalls: HIGH — derived from actual code reading; most pitfalls are known from existing code comments
- Password hashing: HIGH — runtime-verified on Node 22.22.3
- JWT signing: HIGH — runtime-verified `Jwt.sign`/`Jwt.verify` from `hono/utils/jwt`
- OIDC-link mechanism: MEDIUM — derived from CONTEXT.md D-12 + existing `upsertUser` patterns; specific implementation is ASSUMED

**Research date:** 2026-06-17
**Valid until:** 2026-07-17 (stable stack; scrypt parameters are stable)