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

**Gathered:** 2026-06-16
**Status:** Ready for planning

<domain>
## Phase Boundary

Let an operator run FamilySync entirely on **local DB username/password accounts with no OIDC/Authelia required**, while keeping OIDC available as an opt-in, generic (RFC-compliant, not Authelia-specific) provider that can be wired in later from the admin UI. Builds directly on the Phase-12 pre-OIDC local-user foundation (nullable `users.oidc_iss`/`oidc_sub`, the `claimed` marker, and the first-login-claims merge in `upsertUser`).

**In scope:** local credential storage (scrypt) + local login flow; a new local login UI in the PWA; a stateless local-session cookie + middleware; coexistence with the existing OIDC middleware; admin-managed local account creation + password set/change/reset; per-user OIDC-link (replacing local for that user); de-Authelia-izing OIDC config/copy to a generic OIDC provider; a lockout/break-glass recovery mechanism; reworking dev-bypass + the Phase 7/8 Playwright harness to cover the new login UI.

**Out of scope:** a full pluggable multi-auth-provider framework (LDAP, magic-link, multiple OIDC) — that is the auth-layer counterpart of backlog 999.1, a future phase. Email-based password reset (email is out of project scope). BYO-CalDAV provider abstraction (999.1, separate).

</domain>

<decisions>
## Implementation Decisions

### Mode & Coexistence
- **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.

### Session Issuance
- **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** (consistent with the app's existing storage-less-JWT approach; right for household scale). 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 and treat issuer/client as generic OIDC config. Mirrors the planned BYO-CalDAV provider abstraction (999.1).
- **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.

### Password Hashing & Storage
- **D-08:** Hash local passwords with **`node:crypto` scrypt** — zero new dependency, no native node-gyp build in the Docker image (honors the stack's deliberate no-native-dep stance, the same reason Drizzle was chosen over Prisma). Encode **algorithm + params + salt alongside the hash** so parameters can evolve. (argon2id/bcrypt native addons explicitly rejected.)
- **D-09:** Store local credentials in a **new `local_credentials` table** — `user_id` (FK to `users`, UNIQUE), `username` (UNIQUE), `password_hash` (encoded), `createdAt`/`updatedAt` — mirroring the `member_credentials` pattern. Keeps the `users` row identity-method-agnostic. **Auth methods are a per-user property**: a user has local login iff a `local_credentials` row exists, and OIDC login iff an `oidc_iss+oidc_sub` binding exists. Drizzle **generate+migrate, never push** (additive migration on populated MariaDB — same rule as Phases 10/12).

### Accounts & OIDC-Link
- **D-10:** **Admin creates members** + sets an initial password; the member changes it later. **No open self-signup** (wrong trust model for a private household app exposed via Pangolin).
- **D-11:** Password lifecycle = **self-change (current + new) + admin-reset** from the admin UI. **No email reset** (email out of project scope). Reuses the admin surface that already rotates Fastmail app passwords.
- **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, per Phase-12 D-10), **delete that user's `local_credentials` row** → they become OIDC-only. OIDC-only users never receive a local credential. The returned `iss+sub` must not already belong to another user.
- **D-13 (break-glass):** Lockout recovery does **not** need to be a permanent local user account (avoids a member-vs-operator capability split — explicitly rejected). Instead, 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`. Exact form → researcher (see Open Questions).

### Testing & Dev-Bypass
- **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**. It is bound by the existing Phase-16 image-hygiene gates: the IMG-01 boot guard (`assertNotDevBypassInProduction`), `.dockerignore` (IMG-02), and the publish-time hygiene assertion (IMG-03). New dev-seed-login artifacts must be covered by those same gates.

### 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).
These were "you decide" responses; rationale captured above. Researcher/planner may refine implementation detail but should not reverse the locked choice without cause.

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Auth foundation this phase extends
- `apps/api/src/auth/user.ts` — `upsertUser` (identity = `oidc_iss+oidc_sub`, never email; first-login-claims of the single unclaimed row; first-login-wins `is_admin` bootstrap; `claimed` semantics). The local-account + OIDC-link model generalizes this.
- `apps/api/src/auth/middleware.ts` — OIDC middleware wiring + `oidcConfigFallbackMiddleware` (env-OR-`app_config` fallback for `OIDC_ISSUER`/`OIDC_CLIENT_ID`/`app_external_url`). The generic-OIDC config path lives here.
- `apps/api/src/auth/devBypass.ts` — `devAuthBypass()` + `DEV_USER`; the `c.set('user', …)` pattern the new local-auth middleware mirrors. Subject of the dev-bypass rework (D-14/D-15).
- `apps/api/src/auth/persistSessionCookie.ts` — session-cookie persistence helper (referenced by the session model).
- `apps/api/src/index.ts` — middleware mount order (`/api/setup` pre-auth → `devAuthBypass` → `oidcConfigFallback` → `oidcAuthMiddleware` → `persistSessionCookie`); `devBypassActive` computed once at boot; `assertNotDevBypassInProduction()` boot guard. Local-login routes + middleware slot in here.
- `apps/api/src/routes/me.ts` — `resolveUserId` (dev-bypass `c.get('user')` first, else `getAuth`) + `needsProviderSetup`/`isAdmin` exposure. The user-resolution seam for all routes.
- `apps/api/src/db/schema.ts` — `users` (nullable `oidc_iss`/`oidc_sub`, `claimed`, `is_admin`, `uniq_oidc_identity`), `member_credentials` (pattern to mirror for `local_credentials`), `app_config` (k/v config; PROHIBITION list for secrets-in-DB).
- `apps/api/src/routes/admin.ts` + `apps/api/src/lib/requireAdmin.ts` — admin route surface + role guard the account-management UI and OIDC config UI extend.
- `apps/api/src/routes/setup.ts` + `apps/api/src/lib/setupGuard.ts` — Phase-12 pre-auth wizard + 423 lock; the first-local-admin bootstrap replaces the current unclaimed-user provisioning.

### Image hygiene / dev-prod boundary (constrains D-15)
- `apps/api/src/lib/bootGuards.ts` — `assertNotDevBypassInProduction` (IMG-01).
- `.dockerignore` (repo root) — IMG-02 dev-artifact exclusion.
- `.gitea/workflows/publish.yml` — IMG-03 publish-time image-hygiene + boot-smoke assertions.

### Test harness this phase must update
- `apps/pwa/playwright.config.ts` + `apps/pwa/e2e/` (global-setup deterministic mysql2 seed, `layout.spec.ts`, `calendar.spec.ts`, `lists.spec.ts`) — Phase 7 harness; auth reached via `DEV_AUTH_BYPASS`.
- `.gitea/workflows/ci.yml` — CI `harness` job (brings up dev stack with `DEV_AUTH_BYPASS=true`).

### Provenance / prior decisions
- `.planning/phases/12-initial-setup-wizard/12-CONTEXT.md` §Deferred Ideas — origin of this phase (full local-auth/no-OIDC mode deferred from Phase 12; D-07 local-user groundwork is the deliberate foundation).
- `.planning/ROADMAP.md` §"Phase 19" — goal, dependency on Phase 12, and the four seed open questions.
- `.planning/PROJECT.md` §Constraints / §Auth — Authelia-OIDC constraint context; MariaDB-only; no-native-dep stance.

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `member_credentials` table shape + `validateEncryptAndStoreCredential` flow (`broker/credentialSync.ts`) — direct template for the `local_credentials` table and an admin-managed create/reset write path.
- `devAuthBypass()`'s `c.set('user', …)` pattern — the new local-auth middleware reuses it so downstream routes (`resolveUserId` in every router) need no change.
- `oidcConfigFallbackMiddleware` (env-OR-`app_config`) — the established pattern for admin-UI-written OIDC config taking effect.
- Phase-12 `upsertUser` claim/link machinery — the OIDC-link flow (D-12) is a generalization (bind `iss+sub` to an already-authenticated local user, then drop their local credential).
- `assertNotDevBypassInProduction` + `.dockerignore` + `publish.yml` hygiene assertions — the enforcement surface for D-15.

### Established Patterns
- **Identity = `oidc_iss+oidc_sub`, never email** (Phase-12 D-10) — local accounts are a separate per-user credential, and OIDC-link must be explicit (no email matching).
- **Drizzle generate+migrate, never push** — additive migration on populated MariaDB (Phases 10/12 precedent); applies to the new `local_credentials` table.
- **`is_admin` is the server boundary; client `isAdmin` is UX-only** — local-auth admin gating reuses `requireAdmin`.
- **Secrets stay in env, never in `app_config`/DB** (Phase-12 PROHIBITION) — the local-session signing secret and scrypt config live in env, not the DB.
- **Storage-less JWT session cookie** (CLAUDE.md, `@hono/oidc-auth`) — the local-session cookie follows the same stateless philosophy (D-05).

### Integration Points
- New local-login routes + local-auth middleware mount in `index.ts` alongside (and ordered against) `devAuthBypass`/`oidcAuthMiddleware`; the OIDC guard must not 302-redirect local-mode requests.
- The PWA gate (App.tsx setup/login routing) gains a login screen and a login-vs-OIDC chooser; `/api/me` / a new auth-mode endpoint tells the PWA which methods to offer.
- Setup wizard bootstrap shifts from "provision one unclaimed user" to "create the first local admin (username+password)".

</code_context>

<specifics>
## Specific Ideas

- "Bring Your Own Auth" framing (user's words) — explicitly do not pigeon-hole into Authelia; OIDC is one generic provider, parallel to the intended "Bring Your Own CalDAV provider" direction (999.1).
- User leans toward **"replace dev-bypass with seeded auto-login"** for the harness, but defers the final call to the researcher.
- User prefers the **break-glass to be a CLI/env override rather than a user account**, to avoid added user/capability complexity.

</specifics>

<deferred>
## Deferred Ideas

- **Full pluggable auth-provider framework** (registry/plugin for LDAP, magic-link, multiple simultaneous OIDC providers) — auth-layer counterpart of backlog 999.1; its own future phase/milestone. Phase 19 builds only a clean internal seam.
- **Member-vs-operator capability/role split** — considered for the break-glass account, explicitly rejected in favor of a CLI/env recovery mechanism + the existing single `is_admin` flag.
- **Email-based password reset** — out of project scope (no email features).

## Open Questions for Research

- **Dev-bypass rework (decide among 3):** (a) keep bypass + seed a real test login for login-specific specs; (b) replace bypass with seeded auto-login through the real local flow (user's lean); (c) bypass auto-issues a real local-session cookie. Must satisfy D-14 + the D-15 dev-only/no-prod-image constraint.
- **Break-glass recovery form:** CLI/console command vs env override (or both) for create/reset-local-admin and/or disable-OIDC; how it interacts with the boot-time mode/middleware selection.
- **OIDC-only user provisioning:** how an OIDC-only user is first created given D-10 forbids email-matching unclaimed rows — just-in-time on first OIDC login vs admin pre-creation + claim (the Phase-12 single-unclaimed-row claim can't disambiguate multiple pre-created placeholders).
- **Login-vs-OIDC mode signalling to the PWA:** reuse/extend `/api/me` or `/api/setup/status`, or a new pre-auth `/api/auth/mode` endpoint, so the login page knows which methods to render.
- **Local-login hardening:** rate-limiting / lockout / timing-safe compare on the local login endpoint (household scale, but Pangolin-exposed).

</deferred>

---

*Phase: 19-local-auth-no-oidc-mode*
*Context gathered: 2026-06-16*
