Phase 12: Initial Setup Wizard Goal: On first run (no admin/credentials configured), the operator is guided through a validated, step-by-step wizard to bootstrap the app — env presence, generated secrets to copy, DB/OIDC/VAPID/app-password validation — instead of hand-editing .env / docker-compose.yml; once complete, the setup endpoints lock. Status: Verified ✓
Adds a standalone 4-step first-run wizard (Welcome → Instance config → Calendar credential → Complete) reachable pre-auth, gated by a setup_complete flag in app_config. The backend exposes seven pre-auth /api/setup/* handlers that each re-check isSetupLocked() and 423 once setup is done. The wizard creates an unclaimed local admin user + encrypted CalDAV credential; the first real OIDC login claims that user (binding identity, preserving is_admin). Live validation covers DB (SELECT 1), OIDC discovery, the VAPID public-key↔env pair, and the Fastmail app password via a real CalDAV PROPFIND.
Changes
Plan 12-01: schema — unclaimed users
users.claimed column added; oidc_iss/oidc_sub made nullable so the wizard can create local rows before an OIDC identity exists. (apps/api/src/db/schema.ts, migration)
Plan 12-02: setup guard + routes
isSetupLocked() per-call DB evaluation (explicit setup_complete + effective-config branch); setupRouter with all 7 pre-auth handlers. (apps/api/src/lib/setupGuard.ts, apps/api/src/routes/setup.ts)
Plan 12-03: first-login-claims
upsertUser claims the unclaimed wizard user on first OIDC login, preserving is_admin; D-08 test suite. (apps/api/src/auth/user.ts, user.test.ts)
Plan 12-04: wizard UI
7 setup API client functions + SetupAlreadyLockedError; standalone 4-step wizard with Terminal/Locked surfaces. (apps/pwa/src/api/client.ts, apps/pwa/src/routes/SetupPage.tsx)
Plan 12-05: Instance-step gap closure (gaps 1, 3, 4)
Trimmed intro copy (no DB-vs-env aside); read-only disabled DB-name field under App URL; Instance field values preserved across Back navigation.
Plan 12-06: backend gap closure (gaps 2, 3)
validate/vapid rejects a submitted public key that doesn't match env VAPID_PUBLIC_KEY; GET /api/setup/status returns { setupComplete, dbName } (non-secret DB name only).
Plan 12-07: route gate + freshness (gaps 5, 6)
/setup reverse-gated on setupComplete ("Setup already complete" surface, never re-mounts wizard); ['me']staleTime: 0 so the post-wizard "Set up your calendar" banner clears once the claimed credential is in effect.
Requirements Addressed
SETUP-01, SETUP-02, SETUP-03, SETUP-04
Verification
Automated verification: passed (9/9 must-haves)
Human end-to-end (real Fastmail CalDAV): completed by operator — 12-UAT.md Test 5 (credential validated, "Setup complete" shown, /setup locks)
UAT re-verification after gap closure: 6 passed, 1 environment-blocked (gap 6 banner-clear not exercisable under DEV_AUTH_BYPASS; covered by green SetupBanner/App/user.test.ts). All 6 diagnosed gaps confirmed closed.
Test suites green: API 407/407, PWA 263/263
Key Decisions
Wizard stores credential against an unclaimed local admin user; the first OIDC login claims it (preserves is_admin, binds identity). Not exercisable under dev-bypass (hardcoded DEV_USER); verified by unit tests.
validate/vapid asserts the submitted public key equals env VAPID_PUBLIC_KEY; the private key is never compared or echoed.
Only the non-secret DB_NAME is surfaced to the wizard — never DB_HOST/DB_USER/DB_PASSWORD.
OIDC validation checks issuer discovery only (a Client ID can only be verified at first real sign-in) — the row is honestly labeled "OIDC discovery resolved."
## Summary
**Phase 12: Initial Setup Wizard**
**Goal:** On first run (no admin/credentials configured), the operator is guided through a validated, step-by-step wizard to bootstrap the app — env presence, generated secrets to copy, DB/OIDC/VAPID/app-password validation — instead of hand-editing `.env` / `docker-compose.yml`; once complete, the setup endpoints lock.
**Status:** Verified ✓
Adds a standalone 4-step first-run wizard (Welcome → Instance config → Calendar credential → Complete) reachable pre-auth, gated by a `setup_complete` flag in `app_config`. The backend exposes seven pre-auth `/api/setup/*` handlers that each re-check `isSetupLocked()` and 423 once setup is done. The wizard creates an unclaimed local admin user + encrypted CalDAV credential; the first real OIDC login claims that user (binding identity, preserving `is_admin`). Live validation covers DB (`SELECT 1`), OIDC discovery, the VAPID public-key↔env pair, and the Fastmail app password via a real CalDAV PROPFIND.
## Changes
### Plan 12-01: schema — unclaimed users
`users.claimed` column added; `oidc_iss`/`oidc_sub` made nullable so the wizard can create local rows before an OIDC identity exists. (`apps/api/src/db/schema.ts`, migration)
### Plan 12-02: setup guard + routes
`isSetupLocked()` per-call DB evaluation (explicit `setup_complete` + effective-config branch); `setupRouter` with all 7 pre-auth handlers. (`apps/api/src/lib/setupGuard.ts`, `apps/api/src/routes/setup.ts`)
### Plan 12-03: first-login-claims
`upsertUser` claims the unclaimed wizard user on first OIDC login, preserving `is_admin`; D-08 test suite. (`apps/api/src/auth/user.ts`, `user.test.ts`)
### Plan 12-04: wizard UI
7 setup API client functions + `SetupAlreadyLockedError`; standalone 4-step wizard with Terminal/Locked surfaces. (`apps/pwa/src/api/client.ts`, `apps/pwa/src/routes/SetupPage.tsx`)
### Plan 12-05: Instance-step gap closure (gaps 1, 3, 4)
Trimmed intro copy (no DB-vs-env aside); read-only disabled DB-name field under App URL; Instance field values preserved across Back navigation.
### Plan 12-06: backend gap closure (gaps 2, 3)
`validate/vapid` rejects a submitted public key that doesn't match env `VAPID_PUBLIC_KEY`; `GET /api/setup/status` returns `{ setupComplete, dbName }` (non-secret DB name only).
### Plan 12-07: route gate + freshness (gaps 5, 6)
`/setup` reverse-gated on `setupComplete` ("Setup already complete" surface, never re-mounts wizard); `['me']` `staleTime: 0` so the post-wizard "Set up your calendar" banner clears once the claimed credential is in effect.
## Requirements Addressed
- SETUP-01, SETUP-02, SETUP-03, SETUP-04
## Verification
- [x] Automated verification: **passed** (9/9 must-haves)
- [x] Human end-to-end (real Fastmail CalDAV): completed by operator — `12-UAT.md` Test 5 (credential validated, "Setup complete" shown, `/setup` locks)
- [x] UAT re-verification after gap closure: **6 passed, 1 environment-blocked** (gap 6 banner-clear not exercisable under `DEV_AUTH_BYPASS`; covered by green `SetupBanner`/`App`/`user.test.ts`). All 6 diagnosed gaps confirmed closed.
- [x] Test suites green: API 407/407, PWA 263/263
## Key Decisions
- Wizard stores credential against an **unclaimed** local admin user; the first OIDC login claims it (preserves `is_admin`, binds identity). Not exercisable under dev-bypass (hardcoded `DEV_USER`); verified by unit tests.
- `validate/vapid` asserts the submitted public key equals env `VAPID_PUBLIC_KEY`; the private key is never compared or echoed.
- Only the non-secret `DB_NAME` is surfaced to the wizard — never `DB_HOST`/`DB_USER`/`DB_PASSWORD`.
- OIDC validation checks issuer discovery only (a Client ID can only be verified at first real sign-in) — the row is honestly labeled "OIDC discovery resolved."
Restored onto phase-12 branch — discuss-phase originally committed the
context (dc41073) on the phase-18 branch by mistake.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Covers pre-auth /api/setup/* route surface, minimal-env-kernel + DB-backed
config model, pre-OIDC local user + first-login-claims schema migration,
defense-in-depth 423 guard, generate-secrets helper script, and explicit
reconciliation of the SETUP-03 and D-09 deviations from the roadmap.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Resolve plan-checker warning (mark RESEARCH Open Questions RESOLVED),
fill VALIDATION.md Nyquist map (nyquist_compliant), record planning
complete in STATE, annotate ROADMAP wave dependencies.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drop Step 2 "Generate Secrets" (secrets move to pre-boot helper script per D-05),
rework Step 2 to collect non-secret config via form fields (app URL, OIDC issuer,
client_id, VAPID public key) written to app_config per D-02, and reduce wizard
from 5 steps to 4. All design tokens, surfaces, and a11y contracts unchanged.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Remove .notNull() from users.oidc_iss and users.oidc_sub (wizard creates
local rows before OIDC identity is known; first-login-claims binds later)
- Add users.claimed boolean (default false NOT NULL) to distinguish pending
wizard rows from OIDC-bound rows (D-07)
- Add Phase 12 app_config key documentation + prohibition comment (D-01/SC-3)
- Generate migration 0002_lethal_millenium_guard.sql via drizzle-kit generate
(MODIFY COLUMN for nullable, ADD COLUMN claimed — no DROP/recreate)
- Append backfill: UPDATE users SET claimed=true WHERE oidc_iss IS NOT NULL
so existing OIDC users cannot be matched by first-login-claims (D-08)
- Apply migration via drizzle-kit migrate — users.claimed column verified in dev DB
- Add scripts/generate-secrets.mjs: plain ESM script that prints
SESSION_SECRET + APP_PASSWORD_ENCRYPTION_KEY (32 random bytes each,
hex-encoded) and VAPID_PUBLIC_KEY + VAPID_PRIVATE_KEY from web-push
generateVAPIDKeys() — all to stdout only (SC-3: nothing written to disk)
- Resolve web-push as CommonJS default import from apps/api/node_modules
(avoids a root-level dependency; named-export ESM form not supported)
- Wire root package.json "generate-secrets" script: node scripts/generate-secrets.mjs
- Add apps/api/src/lib/setupGuard.ts exporting isSetupLocked(): Promise<boolean>
(Wave-0 stub returns false; real DB impl ships in Plan 02)
Doc comment enforces D-10: re-evaluate fresh on every call, never module-cache
- Add apps/api/src/routes/setup.ts exporting setupRouter = new Hono()
(empty router; handlers + index.ts mount added in Plan 02)
Doc comment notes pre-auth surface position — before /api/* OIDC chain
- Fill setupRouter: GET /status, POST /config, POST /validate/{db,oidc,vapid},
POST /credential, POST /complete (SETUP-01/02)
- isSetupLocked() is FIRST statement in every handler; returns 423 if locked (SETUP-04/D-10)
- /status uses isSetupLocked() directly: covers both explicit + effective-config branches
- /config: zod-validates {oidcIssuer:https, oidcClientId, vapidPublicKey, appExternalUrl};
upserts oidc_issuer|oidc_client_id|vapid_public_key|app_external_url into app_config
- /validate/db: db.execute(sql`SELECT 1`); 200 ok, 503 on failure
- /validate/oidc: fetches discovery doc with AbortSignal.timeout(5000); reads oidc_issuer
from app_config; 200 ok, 400 on unreachable/non-2xx
- /validate/vapid: webpush.setVapidDetails() structural check; reads ONLY from process.env
(VAPID_PRIVATE_KEY never from app_config, never returned; T-12-06/SC-3)
- /credential: inserts local user (oidcIss=null, claimed=false, isAdmin=true) FIRST
(Pitfall 5 FK), then calls validateEncryptAndStoreCredential(); noEchoHook + error map
- /complete: upserts setup_complete='true'; 200 first call, 423 second (Pitfall 8/D-10)
- Mount setupRouter pre-auth in index.ts BEFORE devAuthBypass() (T-12-09/Pitfall 1)
- All 394 tests pass (5 todo = D-08 RED scaffolds); typecheck clean
- A2 CONFIRMED: @hono/oidc-auth reads OIDC_ISSUER/OIDC_CLIENT_ID/OIDC_AUTH_EXTERNAL_URL
at per-request call time (env(c) → process.env), NOT at import time — fresh instance
boots cleanly without OIDC env vars
- Implement oidcConfigFallbackMiddleware in auth/middleware.ts: reads OIDC_ISSUER,
OIDC_CLIENT_ID, OIDC_AUTH_EXTERNAL_URL from app_config when process.env is absent,
injects into process.env before oidcAuthMiddleware() reads it (D-02/D-03/Recommendation a)
- Mount oidcConfigFallbackMiddleware before oidcAuthMiddleware() in index.ts so
wizard-configured instances work before a container restart
- Verify /api/setup mount order: line 49 < devAuthBypass line 54 (T-12-09/Pitfall 1)
- Fix push.test.ts vi.doMock for middleware.js: add oidcConfigFallbackMiddleware stub
- 394 tests pass | 5 todo (D-08 RED scaffolds); typecheck clean
- Add isNull import from drizzle-orm; add appConfig to schema imports
- After identity lookup, read app_config.setup_complete per call (D-10 freshness)
- When setup_complete='true' and unclaimed user exists (isNull(oidcIss) AND claimed=false):
claim it via db.update() — binds oidcIss/oidcSub, sets claimed=true, preserves is_admin
- shouldBeAdmin gated: flagRow?.value !== 'true' AND admin COUNT === 0 (T-12-11)
- No email keying in claim branch — isNull(oidcIss) AND claimed=false only (D-10/T-12-12)
- 399 tests pass; typecheck clean
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Tests for all 7 setup client function exports (fetchSetupStatus, postSetupConfig,
validateSetupDb, validateSetupOidc, validateSetupVapid, postSetupCredential, postSetupComplete)
- Tests for SetupPage rendering: page title, Welcome step heading, 4-step indicator,
Continue button, role=main, aria-live region
- Tests for no AppNav/BottomTabBar in wizard output
- Tests for Already Locked screen (alreadyLocked prop) and Sign-in link
BUG 1: Rename SetupConfigPayload fields from snake_case to camelCase to match
the API configSchema (appExternalUrl, oidcIssuer, oidcClientId, vapidPublicKey).
Update SetupPage.tsx handleSaveAndValidate to send the correct camelCase keys.
BUG 2: Extract human-readable message from ZodError object in postSetupConfig
error handler. When body.error is an object with issues[], use issues[0].message
instead of stringifying the object (which produces "[object Object]").
All 245 PWA tests pass; TypeScript clean.
- Add 4 VAPID validation tests to SetupPage.test.tsx (CR-01 gap closure)
- Tests assert: validateSetupVapid is called, VAPID row renders, Continue
is blocked when VAPID fails, Continue appears only after all 3 pass
- 3 tests currently FAIL (RED) — current code lacks validateSetupVapid import
and has no vapid ValidationRow or vapid gate on bothPassed
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Import validateSetupVapid from api/client.ts in SetupPage.tsx
- Add vapid: ValidationRowState to validationRows state (alongside db/oidc)
- Extend configMutation.onSuccess chain: DB → OIDC → VAPID (sequential)
- Add ValidationRow for VAPID with pending/success/failure text
- Gate setBothPassed(true) on all three rows passing (db AND oidc AND vapid)
- Update anyPending and handleSaveAndValidate reset to include vapid state
- All 249 PWA tests pass; TypeScript clean
Closes CR-01; satisfies SETUP-02 "VAPID private key decodes to 32 bytes"
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The server's credentialSchema does not declare providerType; it was being
silently stripped by Zod. Remove it from the request body and add a
contract test suite asserting the exact wire keys sent, mirroring the
existing BUG-1 tests for postSetupConfig.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
After $returningId() insert, if the re-select returns null the handler
returned 503 without deleting the just-inserted user row, leaving an
unclaimed admin row with no credential. Delete before returning 503 to
mirror the cleanup already present in the catch block.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Two concurrent POST /api/setup/credential requests could both pass
isSetupLocked(), observe no unclaimed row, and both insert — leaving two
unclaimed admin rows with no recovery path. Wrap the count-check + user
insert in a transaction with SELECT COUNT(*) ... FOR UPDATE to acquire a
row/gap lock, ensuring at most one unclaimed admin row is created.
Returns 409 when a concurrent request already holds an unclaimed row.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The oidcConfigFallbackMiddleware permanently mutates process.env on first
request then never re-reads from DB. Log an explicit info message when each
value is written so operators can see when a restart is required to pick up
config changes, and add inline documentation of the single-write semantics
to prevent silent misconfiguration after a re-run of the wizard.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The catch block previously echoed err.message (which may contain internal
network addresses like ECONNREFUSED 192.168.1.50:9091) to the pre-auth
caller. Log the raw message server-side only and return a generic user-
facing string with no internal network detail.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Without a prerequisite check, an operator could call POST /api/setup/complete
directly, setting setup_complete=true with no admin user or credential row,
leaving no recovery path without manual DB surgery.
Add an inner join check for an unclaimed user with an associated credential;
return 422 if absent. Update /complete tests to seed the prerequisite for
the success path and add an explicit 422 regression test.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
generate-secrets.mjs was importing from ../apps/api/node_modules/web-push/src/index.js
(a private source path) which breaks if web-push restructures internally or
workspace hoisting moves the package. Replace with Node.js built-in createECDH
('prime256v1') which produces identical base64url-encoded keys, including the
same defensive padding logic as web-push for short key buffers.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
email.trim() was already used in the saveDisabled guard but not applied to
the mutate call payload. A non-empty value with leading/trailing spaces would
pass the guard and reach the server untrimmed, causing Zod's z.string().email()
to reject it with a generic 400 and no diagnostic path for the user.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Drizzle mysql2 execute() returns [rows, fields] for SELECT queries; the
generic type parameter alone does not correctly type the result. Use
unknown cast pattern consistent with admin.ts to access the count row.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
isSetupLocked() now checks for an unclaimed local wizard user
(oidcIss IS NULL, claimed=false) before firing the effective-config
branch. During the credential→complete window, this sentinel prevents
a production container with VAPID env set from blocking POST /complete
with 423. The explicit setup_complete flag (Check 1) still locks
unconditionally once written. Adds regression test that sets VAPID env
explicitly (no beforeEach clearing) to reproduce the production scenario.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
appExternalUrl is injected as OIDC_AUTH_EXTERNAL_URL (the redirect URI
base); Authelia rejects non-https redirect URIs in production. Added
.refine() guard matching the existing oidcIssuer pattern. Added test
that verifies http:// appExternalUrl is rejected with 400.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- apps/api/src/auth/user.ts: upsertUser step-5 insert now sets claimed=true
for all OIDC-created users. An identity-bound OIDC user is never a pending
wizard bootstrap user; explicit claimed=true prevents ambiguity with the
(oidcIss IS NULL AND claimed=false) sentinel used by the TOCTOU guard and
isSetupLocked. First-login-claims path is unaffected (it updates a
pre-existing oidcIss=null row; this change only touches the fresh insert).
- apps/api/src/routes/setup.ts: TOCTOU guard in POST /credential now queries
WHERE oidc_iss IS NULL AND claimed = false FOR UPDATE, matching the exact
definition of a pending wizard bootstrap user. This provides defense-in-depth
against any future path that could produce claimed=false OIDC rows.
- apps/api/tests/auth/user.test.ts: new WR-01 test asserts that the fresh
OIDC insert sets claimed=true in the values passed to db.insert().
- apps/api/tests/routes/setup.test.ts: new WR-01 integration test seeds an
OIDC user with claimed=false (oidcIss NOT NULL) and verifies POST /credential
still succeeds (guard ignores the OIDC row, only counts local wizard rows).
All 402 API tests, 253 PWA tests, and typecheck pass.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- read app_config.vapid_public_key and compare to process.env.VAPID_PUBLIC_KEY
- mismatched/absent submitted key → 400 before the structural check
- VAPID_PRIVATE_KEY still env-only, never compared or returned (T-12-06)
- status returns { setupComplete, dbName } from process.env.DB_NAME (null fallback)
- only the DB name; never DB_HOST/DB_USER/DB_PASSWORD
- SetupStatusResponse carries dbName?: string | null for the PWA read-only field
- Root cause confirmed = mechanism (ii): ['me'] staleness, NOT a backend linking gap
(upsertUser claim preserves users.id → credential stays linked → DB needsProviderSetup=false)
- SetupBanner ['me'] query staleTime 5min → 0 so a pre-claim stale cache entry is
refetched on mount; banner hides once needsProviderSetup resolves false
- App.tsx boot ['me'] staleTime also set to 0 (committed with Task 1) for the same reason
- Add SetupBanner.test.tsx regression: absent when false, present (no dismiss) when true,
stale-cache refetch hides banner; success-only dismissal contract preserved (no X button)
- Log pre-existing PWA lint errors (SetupPage.test.tsx, setupClient.contract.test.ts) to deferred-items.md
- Remove the 'written to the database — not your environment file' aside from the Instance step intro
- Render a read-only, disabled DB-name field under App URL, populated from GET /api/setup/status dbName
- Helper text explains DB is configured via Docker env; only dbName is surfaced (T-12-3DB)
- Tests: assert aside absent, DB field readOnly/disabled with mocked dbName, existing DB validation row intact
- Lift appUrl/oidcIssuer/oidcClientId/vapidPublicKey into SetupPage so Step2 unmount preserves them
- Step2Config now reads/writes these via fields/setFields props
- Fastmail app password stays in Step3 local state, never lifted/persisted, cleared on unmount (T-12-15)
- Tests: Back from Calendar restores all four Instance values; password not persisted across nav
oidcConfigFallbackMiddleware (Phase 12) reads OIDC config from app_config on
every /api/* request when OIDC_ISSUER/CLIENT_ID/AUTH_EXTERNAL_URL are absent.
CI's api job sets no OIDC env, so events/login tests (which mock db with a
partial query chain) 500'd on every request. Local runs passed only because
ambient .env supplied the vars. Set dummy OIDC config in vitest test.env so the
middleware always takes the env path — hermetic across CI and local.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
security/gitleaks: allowlist apps/api/tests/routes/setup.test.ts — synthetic
VAPID test pair (verified absent from .env), same class as existing fixture
allowlist entries.
security/audit: waive GHSA-88fw-hqm2-52qc (hono CORS) — not exploitable, the
app uses no hono cors() middleware; newly-published vs pinned hono 4.12.23.
harness/e2e: seed app_config.setup_complete='true' + a dev-admin credential in
global-setup so the Phase-12 setup gate no longer redirects every spec to
/setup (was causing all 95 e2e failures) and no onboarding banner renders.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Summary
Phase 12: Initial Setup Wizard
Goal: On first run (no admin/credentials configured), the operator is guided through a validated, step-by-step wizard to bootstrap the app — env presence, generated secrets to copy, DB/OIDC/VAPID/app-password validation — instead of hand-editing
.env/docker-compose.yml; once complete, the setup endpoints lock.Status: Verified ✓
Adds a standalone 4-step first-run wizard (Welcome → Instance config → Calendar credential → Complete) reachable pre-auth, gated by a
setup_completeflag inapp_config. The backend exposes seven pre-auth/api/setup/*handlers that each re-checkisSetupLocked()and 423 once setup is done. The wizard creates an unclaimed local admin user + encrypted CalDAV credential; the first real OIDC login claims that user (binding identity, preservingis_admin). Live validation covers DB (SELECT 1), OIDC discovery, the VAPID public-key↔env pair, and the Fastmail app password via a real CalDAV PROPFIND.Changes
Plan 12-01: schema — unclaimed users
users.claimedcolumn added;oidc_iss/oidc_submade nullable so the wizard can create local rows before an OIDC identity exists. (apps/api/src/db/schema.ts, migration)Plan 12-02: setup guard + routes
isSetupLocked()per-call DB evaluation (explicitsetup_complete+ effective-config branch);setupRouterwith all 7 pre-auth handlers. (apps/api/src/lib/setupGuard.ts,apps/api/src/routes/setup.ts)Plan 12-03: first-login-claims
upsertUserclaims the unclaimed wizard user on first OIDC login, preservingis_admin; D-08 test suite. (apps/api/src/auth/user.ts,user.test.ts)Plan 12-04: wizard UI
7 setup API client functions +
SetupAlreadyLockedError; standalone 4-step wizard with Terminal/Locked surfaces. (apps/pwa/src/api/client.ts,apps/pwa/src/routes/SetupPage.tsx)Plan 12-05: Instance-step gap closure (gaps 1, 3, 4)
Trimmed intro copy (no DB-vs-env aside); read-only disabled DB-name field under App URL; Instance field values preserved across Back navigation.
Plan 12-06: backend gap closure (gaps 2, 3)
validate/vapidrejects a submitted public key that doesn't match envVAPID_PUBLIC_KEY;GET /api/setup/statusreturns{ setupComplete, dbName }(non-secret DB name only).Plan 12-07: route gate + freshness (gaps 5, 6)
/setupreverse-gated onsetupComplete("Setup already complete" surface, never re-mounts wizard);['me']staleTime: 0so the post-wizard "Set up your calendar" banner clears once the claimed credential is in effect.Requirements Addressed
Verification
12-UAT.mdTest 5 (credential validated, "Setup complete" shown,/setuplocks)DEV_AUTH_BYPASS; covered by greenSetupBanner/App/user.test.ts). All 6 diagnosed gaps confirmed closed.Key Decisions
is_admin, binds identity). Not exercisable under dev-bypass (hardcodedDEV_USER); verified by unit tests.validate/vapidasserts the submitted public key equals envVAPID_PUBLIC_KEY; the private key is never compared or echoed.DB_NAMEis surfaced to the wizard — neverDB_HOST/DB_USER/DB_PASSWORD.- Fill setupRouter: GET /status, POST /config, POST /validate/{db,oidc,vapid}, POST /credential, POST /complete (SETUP-01/02) - isSetupLocked() is FIRST statement in every handler; returns 423 if locked (SETUP-04/D-10) - /status uses isSetupLocked() directly: covers both explicit + effective-config branches - /config: zod-validates {oidcIssuer:https, oidcClientId, vapidPublicKey, appExternalUrl}; upserts oidc_issuer|oidc_client_id|vapid_public_key|app_external_url into app_config - /validate/db: db.execute(sql`SELECT 1`); 200 ok, 503 on failure - /validate/oidc: fetches discovery doc with AbortSignal.timeout(5000); reads oidc_issuer from app_config; 200 ok, 400 on unreachable/non-2xx - /validate/vapid: webpush.setVapidDetails() structural check; reads ONLY from process.env (VAPID_PRIVATE_KEY never from app_config, never returned; T-12-06/SC-3) - /credential: inserts local user (oidcIss=null, claimed=false, isAdmin=true) FIRST (Pitfall 5 FK), then calls validateEncryptAndStoreCredential(); noEchoHook + error map - /complete: upserts setup_complete='true'; 200 first call, 423 second (Pitfall 8/D-10) - Mount setupRouter pre-auth in index.ts BEFORE devAuthBypass() (T-12-09/Pitfall 1) - All 394 tests pass (5 todo = D-08 RED scaffolds); typecheck clean- Add setupQuery (queryKey: setupStatus, staleTime: 0) alongside meQuery; queries GET /api/setup/status via fetchSetupStatus on every app load - Add <Route path="/setup" element={<SetupPage />}> as standalone pre-auth route - Add redirect gate: while loading → aria-hidden div (no flash); setupComplete===false → <Navigate to="/setup"> (no AppNav/BottomTabBar rendered); true → normal shell - Add App.test.tsx covering both branches (setupComplete false/true) + loading state; 236 tests pass, typecheck clean- Add setupClient.contract.test.ts with 9 tests targeting two bugs: BUG 1: SetupConfigPayload interface must use camelCase keys matching the API configSchema (appExternalUrl, oidcIssuer, oidcClientId, vapidPublicKey) — TypeScript compile error confirms mismatch BUG 2: postSetupConfig must throw readable string when API returns ZodError object in error field (not [object Object]) - Tests 7-8 fail (BUG 2 confirmed); TypeScript errors confirm BUG 1generate-secrets.mjs was importing from ../apps/api/node_modules/web-push/src/index.js (a private source path) which breaks if web-push restructures internally or workspace hoisting moves the package. Replace with Node.js built-in createECDH ('prime256v1') which produces identical base64url-encoded keys, including the same defensive padding logic as web-push for short key buffers. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>- status returns { setupComplete, dbName } from process.env.DB_NAME (null fallback) - only the DB name; never DB_HOST/DB_USER/DB_PASSWORD - SetupStatusResponse carries dbName?: string | null for the PWA read-only field