familysync/.planning/milestones/v1.1-phases/12-initial-setup-wizard/12-CONTEXT.md

Phase 12: Initial Setup Wizard - Context

Gathered: 2026-06-15 Status: Ready for planning

## Phase Boundary

Phase 12 delivers the first-run, pre-auth setup wizard that bootstraps a fresh FamilySync instance through a validated, step-by-step flow instead of hand-editing config — and reworks the admin bootstrap so the operator who completes setup becomes the admin.

Delivers:

• A standalone /setup page (the only screen outside the OIDC guard), reached when the instance is not yet configured, that collects non-secret config, validates live connectivity (DB / OIDC / VAPID / Fastmail CalDAV), provisions the first local user + credential, and locks (setup_complete + 423 guard) on completion.
• A minimal-env-kernel + DB-backed-config model: the running app reads non-secret config from app_config (written by the wizard) instead of requiring it all in env.
• A repo helper script to generate the bootstrap secrets before first boot.
• The WR-01 bootstrap rework: a pre-OIDC local user, claimed by the first OIDC login.

NOT in this phase:

• The visual redesign of the wizard from scratch — 12-UI-SPEC.md already contracts the look/feel (but see the ⚠ note: its validate-only assumption is partially superseded — Steps 2–4 need rework; this phase revises the UI-SPEC, it does not re-derive the design system).
• Full local-auth / no-OIDC operating mode (deferred — see Deferred Ideas).
• Multi-provider credentials beyond Fastmail/CalDAV (Phase 10 D-04 generic shape only).
• Any new crypto or a duplicate credential-storage path (reuse Phase 10's helper).

## Implementation Decisions

Wizard nature — minimal env kernel + DB-backed config

• D-01: Minimal env kernel. Only the irreducible bootstrap floor stays in env (it cannot live in the DB it protects/reaches): DB connection (chicken-and-egg), SESSION_SECRET, APP_PASSWORD_ENCRYPTION_KEY (storing it beside the ciphertext it decrypts defeats the encryption — SC-3 / Pitfall 10), VAPID_PRIVATE_KEY (SC-3 bars it from the DB), and OIDC client_secret.
• D-02: Non-secret config moves to app_config. The wizard collects via form fields and writes the non-secret, runtime-read config to app_config: app/external URL, **OIDC issuer
  • client_id**, VAPID public key. Runtime consumers (auth middleware boot config, push, broker) read these from app_config rather than env. This is the operator's "config lives in the DB" goal, bounded by the D-01 floor.
• D-03: Env resolution precedence. Kernel env values come from Docker-provided process.env first, falling back to a .env file (standard dotenv precedence). .env is not eliminated — it shrinks to the kernel.
• ⚠ Supersedes the validate-only 12-UI-SPEC.md. Steps 3/4 now need input fields (they collect config, not just validate env). The UI-SPEC must be revised before/within planning — see Canonical References.

Restart & resume — no mid-wizard restart

• D-04: Full kernel defined before first boot. The operator sets the entire env kernel (DB connection + all secrets) before the container's first boot, via an Unraid template / clear bootstrap instructions. The container comes up already holding its secrets, so the wizard never forces a paste-and-restart mid-flow. The mid-wizard restart problem is designed out.
• D-05: Secret generation → repo helper script. Generation moves OUT of the wizard to a repo helper script (e.g. npm run generate-secrets) that prints all four values (SESSION_SECRET, APP_PASSWORD_ENCRYPTION_KEY, VAPID public + private) formatted for pasting, generating the VAPID pair with the app's own web-push lib for an exact match.
• D-06: Stateless resume. No persisted step cursor. Because the kernel is present at boot, the validation steps simply re-pass on any refresh/re-entry; the env + DB are the progress state.
• ⚠ SETUP-03 deviation. SETUP-03 says "the wizard generates secrets." Under this model the wizard does not generate; the helper script does, at provisioning time. UI-SPEC Step 2 ("Generate Secrets" + copy + acknowledge) is dropped/reworked. Capture as a requirements deviation for the planner/researcher.

Credential + admin — pre-OIDC local user, claimed at first login

• D-07: Pre-OIDC local user. The wizard provisions a local user row (no OIDC identity yet) that holds the first validated Fastmail credential and the pending-admin status. Schema: users.oidc_iss / oidc_sub become nullable, plus a claimed/pending marker, so a user can exist before OIDC and be adopted later.
• D-08: First-login-claims. The first OIDC login after setup_complete claims/merges the single unclaimed local user — populating its oidc_iss/oidc_sub, keeping the credential + is_admin. This repurposes Phase 10's first-login-wins (D-01 there) from "creates a new admin" to "claims the pending admin," and is the WR-01 bootstrap rework Phase 10 flagged for Phase 12. No email coupling (respects D-10 identity model). Threat model: only household members can reach Authelia OIDC at all, so the claim window is acceptable for a 2-person self-hosted app.
• D-09: Credential stored via setup endpoint reusing the shared helper. A pre-auth /api/setup/* endpoint stores the local user's credential by calling the shared validateEncryptAndStoreCredential helper internally (no new crypto, no duplicated logic). CalDAV PROPFIND validation (SC-2) runs here against the entered app password. ⚠ Deviation from the literal roadmap constraint "do NOT create /api/setup/credentials — reuse the Phase 10 admin routes": a pre-auth wizard physically cannot call the admin-gated /api/admin/credentials. The deviation honors the constraint's spirit (reuse the helper / no new crypto) while satisfying the pre-auth requirement. Flag for the researcher to confirm the exact endpoint shape.

Completion signal & 423 guard

• D-10: Defense-in-depth guard. Each setup-route invocation locks (423) if app_config.setup_complete is true OR the system is already effectively configured (a member_credentials row exists AND VAPID env present) — re-evaluated fresh every call, never cached at startup. Satisfies SC-4 (the flag) and SC-5 (the live check), and protects manually/upgrade-configured instances that never set the flag. The wizard only flips setup_complete once preconditions are met, so it cannot self-lock mid-flow.

Claude's Discretion

• Exact reworked step list (e.g. Welcome / Config-collect / Validate / Credential / Complete) and per-step field grouping — planner's call, consistent with the revised UI-SPEC.
• Exact /api/setup/* route paths and the app_config key naming for the new non-secret config — planner's call, following the existing routes/*.ts Hono + app_config key/value pattern (already used for household_timezone).
• The migration packaging for the nullable-OIDC-identity + claimed-marker schema change (Drizzle generate+migrate, never push).
• Whether runtime config reads from app_config are cached per-process or read per-request — planner's call, balancing the SC-5 "every invocation" intent for the guard specifically.

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Requirements & roadmap

• .planning/REQUIREMENTS.md — SETUP-01..04 (full wording). Note the captured deviations: SETUP-03 ("wizard generates secrets") is reworked → repo helper script (D-05); SETUP-01's "wizard defines config" is realized as collect-to-app_config for non-secret values only (D-02), with the secret/DB floor staying in env (D-01).
• .planning/ROADMAP.md §Phase 12 — goal, 5 success criteria, pitfalls, and the hard constraints. Two literal constraints are deliberately deviated (with rationale above): "wizard generates secrets" (D-05) and "no /api/setup/credentials, reuse admin routes" (D-09). The researcher must reconcile these explicitly.
• .planning/ROADMAP.md lines ~160-170 — v1.1 DB-foundation note (app_config.setup_complete created in Phase 10, consumed here) and the shared /api/admin surface constraint.

UI design contract (PARTIALLY SUPERSEDED — must be revised)

• .planning/phases/12-initial-setup-wizard/12-UI-SPEC.md — the design system, tokens, surfaces, copywriting, and a11y contract still hold. BUT its core validate-only assumption is superseded by D-02 (Steps 3/4 collect config → need input fields) and D-04/D-05 (Step 2 "Generate Secrets" is dropped — generation is pre-boot). Revise the UI-SPEC's Wizard-Steps and Interaction-Contract sections before/within planning; do not implement Steps 2–4 as currently written.

Prior-phase context this phase builds on

• .planning/phases/10-admin-role-settings/10-CONTEXT.md — D-01 first-login-wins (tightened here to first-login-claims), D-03 isAdmin on /api/me, D-04 generic provider credential shape, D-07 self-service SetupBanner/CredentialSheet, the shared validateEncryptAndStoreCredential helper, and the app_config table/setup_complete column.
• .planning/codebase/ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md — API/PWA layout, route + schema + frontend conventions to match.

Key source files

• apps/api/src/auth/user.ts — the documented first-login-wins hook (l.108-122) that this phase tightens to gate on setup_complete and repurposes to claim the pending local user (D-08).
• apps/api/src/db/schema.ts — users (make oidc_iss/oidc_sub nullable + add claimed marker, D-07), app_config (new non-secret config keys, D-02), member_credentials (per-user, reused).
• apps/api/src/routes/admin.ts — existing app_config upsert pattern (household_timezone, l.196-263) and the validateEncryptAndStoreCredential reuse target (D-09).
• apps/api/src/broker/crypto.ts — encryptPassword/decryptPassword (reuse, no changes).
• apps/api/src/broker/client.ts — createDAVClient/fetchCalendars for CalDAV PROPFIND validation (SC-2).
• apps/api/src/index.ts — route mounting + middleware order; /api/setup/* mounts before the OIDC guard (like /health).
• apps/api/src/lib/householdTimezone.ts — existing example of an app_config-backed runtime read (pattern to follow for D-02 config reads).
• apps/pwa/src/App.tsx — the app-level gate that redirects to /setup when unconfigured (per UI-SPEC §Routing); apps/pwa/src/components/SetupBanner.tsx + CredentialSheet.tsx — the self-service credential flow reused post-login. </canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• validateEncryptAndStoreCredential (Phase 10) — the single validate→encrypt→store path; D-09 calls it from the pre-auth setup endpoint against the local user id.
• broker/crypto.ts + broker/client.ts — credential encryption + CalDAV PROPFIND validation; reused unchanged for SC-2/SC-3.
• app_config key/value table + the household_timezone upsert/read pattern (routes/admin.ts, lib/householdTimezone.ts) — the template for D-02's non-secret config storage and runtime reads.
• SetupBanner + CredentialSheet (self-service mode, D-07 of Phase 10) — the post-login credential UX; complements the wizard rather than duplicating it.
• First-login-wins block in auth/user.ts — written specifically to be tightened here (its inline comment names this phase).

Established Patterns

• Routes are per-feature Hono routers under apps/api/src/routes/; /api/setup/* mounts before the OIDC guard (only /health-style pre-auth surface today).
• Identity is oidc_iss + oidc_sub, never email (D-10) — D-08 claim must NOT introduce email-keyed matching.
• Schema migrations via drizzle-kit generate + migrate, never push (drizzle-mariadb-push-unsafe).
• PWA routing is declarative react-router in App.tsx; server state via TanStack Query.

Integration Points

• app_config.setup_complete (created Phase 10) → flipped here on completion; read by the gate + the 423 guard (D-10) + the tightened first-login claim (D-08).
• New app_config non-secret keys (D-02) → read by auth-config boot, push, and the PWA (e.g. VAPID public key fetched rather than baked into the build).
• Nullable-OIDC-identity + claimed marker (D-07) → consumed by upsertUser/login (D-08) and is the seed the deferred local-auth phase extends.
• GET /api/setup/status (pre-OIDC) → drives the App.tsx redirect-to-/setup gate. </code_context>

## Specific Ideas

• The operator explicitly wants config to live in the DB, with .env reduced to a Docker-fed (or .env-fallback) kernel — the wizard is the source of truth for non-secret config (D-01/D-02/D-03).
• The operator runs an Unraid deployment and envisions an Unraid template (or equivalent clear instructions) that fully provisions the env kernel before first boot (D-04) — this is why the in-wizard generate-and-restart dance is intentionally removed.
• The credential/local-user model is framed as provider-agnostic: "when we switch from Fastmail to a generic provider, the first user who gets provisioned will need to enter this" — keep the Phase 10 generic provider shape (D-04 there); Fastmail/CalDAV remains the only implementation.
• The local user is explicitly conceived as a "local user who gets merged into an OIDC user once that's set up" (D-07/D-08).

## Deferred Ideas

• Local-auth / no-OIDC operating mode — the operator wants the option to run FamilySync entirely on local DB users with no OIDC, and wire OIDC in later (they use it this way themselves). Its own future phase. Phase 12's pre-OIDC local-user provisioning (D-07) is the deliberate foundation that phase extends — capture now, build later. (Roadmap/backlog: add a phase.)

None of the above is in scope for Phase 12 beyond laying the local-user groundwork.

---

Phase: 12-initial-setup-wizard Context gathered: 2026-06-15