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.
- 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.
-`.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.
-`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).
| Both always live | Local form + OIDC button always shown | |
**User's choice:** Free-text — "Default to local and add the ability to wire OIDC in later if wanted."
**Notes:** Local is the always-available default; OIDC is additive/opt-in.
### Q2 — How does the app know OIDC is wired in, and what happens to local login?
| Option | Description | Selected |
|--------|-------------|----------|
| Auto-detect, local stays live | OIDC on when config present; local always available | (partial) |
| Auto-detect, OIDC takes over | Local disabled once OIDC present | |
| Explicit app_config toggle | Separate `auth_mode` controlled from admin UI | (partial) |
**User's choice:** Free-text — OIDC config is set/stored in a later step, so wire it into the **admin UI**; give users the choice of which to use at login; **no local login UI exists today** so it must be built.
**Notes:** Blend — admin-UI-configured OIDC, both methods offered at login, user chooses.
---
## Session Issuance
### Q1 — What backs a local login session?
| Option | Description | Selected |
|--------|-------------|----------|
| Stateless signed JWT cookie | userId in signed httpOnly cookie; no DB table | ✓ (Claude) |
| Columns on users | Add username + password_hash to users | |
| You decide | — | ✓ |
**User's choice:** "You decide."
**Notes:** Claude chose a separate `local_credentials` table — best fits the BYO-Auth per-user-method seam (one row can hold both a local credential and an OIDC binding).
---
## Accounts & OIDC-Link
### Q1 — How are local accounts created?
| Option | Description | Selected |
|--------|-------------|----------|
| Admin creates members | Wizard creates first admin; admin creates rest | ✓ |
| Admin creates + invite link | One-time set-password link | |
### Q3 — After OIDC-link, what methods stay valid? (reformulated after clarification)
| Option | Description | Selected |
|--------|-------------|----------|
| Both stay valid | Row holds local + OIDC; either logs in | |
| OIDC primary, local fallback | Same data model, UI emphasis on OIDC | |
| OIDC replaces local | Linking removes local credential | ✓ (per user) |
**User's choice:** Initially requested clarification; then chose **OIDC replaces local per user** — there can/should be OIDC-only users with no local creds. Raised the need for a break-glass path.
**Notes:** Auth methods are per-user (presence of local_credentials row and/or OIDC binding). Break-glass need surfaced here.
### Q4 — Break-glass capability model?
| Option | Description | Selected |
|--------|-------------|----------|
| Protected local admin (no new role model) | Initial admin, un-removable local cred | |
| Operator-only account (member/operator split) | Strip member capability from break-glass | |
| Let researcher scope it | Lock the requirement, defer the how | ✓ (twist) |
**User's choice:** Let researcher scope it — **with a twist: break-glass can be a CLI/console command or env override instead of a user**, removing the added-user/capability complexity.
**Notes:** No new role/capability model; reuse `is_admin`. Recovery mechanism (not account) to be scoped by researcher.
---
## Testing & Dev-Bypass (added mid-discussion at user's request)
### Q1 — How should DEV_AUTH_BYPASS evolve?
| Option | Description | Selected |
|--------|-------------|----------|
| Bypass stays + seed a real test login | Fast bypass for most specs; real form for login specs | |
| Replace bypass with seeded auto-login | Harness logs in via real local flow | (user's lean) |
| Bypass auto-issues a real local session | Bypass logs in seeded user, skips form | |
**User's choice:** Defer final determination to the **research agent**; user **leans toward "replace bypass with seeded auto-login."**
**Notes:** Hard constraint — the seeded test login / dev-bypass **stays dev-only and never ships in the Docker/prod image** (Phase 16 IMG-01/02/03 gates apply).
---
## Claude's Discretion
- Local session backing → stateless signed JWT cookie (D-05).
- Credential storage location → separate `local_credentials` table (D-09).
## Deferred Ideas
- Full pluggable auth-provider framework (registry/plugin; LDAP, magic-link, multi-OIDC) — future phase, counterpart of 999.1.
- Member-vs-operator capability/role split — rejected in favor of CLI/env break-glass recovery.
- Email-based password reset — out of project scope.
| Logo mark | SVG or PNG, favicon-derived | Must fit in 48×48px box at 1x; provide 2x/3x for retina. `alt=""` (decorative — app name already in text) |
| App name text | Same string "FamilySync" or updated display name | Rendered as text, not image — screen readers read it |
| Tagline | Optional; may be removed | If removed, set `--brand-tagline-display: none` — no layout reflow |
| Background hero | Optional — if added, must go behind the entire page, not just the brand slot | `var(--brand-bg): none` default; Phase 17 sets to a CSS gradient or subtle image |
| Aspect-ratio box | Phase 17 MUST keep the 48px height reserve | Prevents layout shift; use `aspect-ratio: 1/1; width: var(--brand-logo-size)` |
Phase 17 asset swap is: update `<BrandSlot>` internals (image src) + set CSS custom property
values. No changes to `<LoginPage>` layout, spacing, or card structure are permitted by this
contract.
---
## Surface Architecture
### Surface 1 — Login Page Shell (`/login`)
A standalone full-page route. No AppNav, no BottomTabBar, no SetupBanner, no
| Link OIDC sheet heading | "Link OIDC identity" |
| Link OIDC sheet body | "After linking, you'll sign in with your OIDC provider instead of a username and password. Your local password will be removed." |
| Link OIDC secondary note | "This can't be undone from the app. Contact your admin if you need to revert." |
| Link OIDC cancel button | "Cancel" |
| Link OIDC confirm button | "Continue with OIDC" |
| Link OIDC post-redirect error (409) | "This OIDC identity is already linked to another account. Please contact your admin." |
- Never use the word "Authelia" in any user-facing copy. Use "your OIDC provider" or
"Login with OIDC" everywhere.
- Never say "delete" or "remove" when describing the OIDC-link consequence — use
"your local password will be removed" (passive, factual, non-alarming).
- Admin copy ("Reset password") is direct — admins are comfortable with technical vocabulary.
- End-user copy ("Sign in", "Forgot your password? Ask your admin.") is warm and low-friction —
optimized for the non-technical Apple household member.
---
## Destructive Actions
| Action | Trigger | Confirmation approach |
|--------|---------|----------------------|
| Link OIDC identity (removes local credential for that user) | "Link OIDC identity" in SettingsSheet → "Continue with OIDC" tap | Two-step: open confirmation sheet (step 1, explains consequence) + explicit "Continue with OIDC" tap (step 2). The confirmation sheet clearly states "your local password will be removed." No additional modal/dialog beyond this sheet. |
| Admin password reset | "Reset password" in admin member row → sheet submit | Two-step: open reset sheet (step 1) + explicit "Reset password" tap with filled-in new password (step 2). No separate confirmation dialog — the act of filling and submitting a new value is the acknowledgement. |
No hard-delete of local accounts in this phase. Account removal is out of scope.
---
## Accessibility Contract
### Login page (Surfaces 1–10)
- `role="main"` on the content column
- `<h1>` is the app name "FamilySync" in the brand slot (page-level heading);
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
