NextMyDay/docs/specs/spec-005-setup-wizard.md

SPEC-005 — /setup wizard & bootstrap

Field	Value
Status	Implemented (2026-10-13) — see §7; build/vet/test/-race green · static binary · live-smoked · rev 2026-10-14 (D-041): TOTP-only setup · rev 2026-10-15 (D-025/D-043): per-request tunnel gate — superseded · rev 2026-10-15b (D-044): the setup code + the first-run boilerplate · rev 2026-10-15c (D-045): the gate is the setup toggle; the code is optional; the tunnel gate retired · rev 2026-10-15d: the TOTP step renders the secret + verify form (was the enroll flow's JSON) — see §9/§10/§11
Created	2026-10-13
Author	OpenArchitect
Target milestone	M0
Governing decisions	D-021 · D-026 · D-035 · D-044 · D-045 · PROJECT_PLAN.md §5
Related	SPEC-003 (door) · SPEC-004 (identity)

---

1. Goal

Bring a fresh instance to life with a /setup wizard — enabled by the setup config toggle (D-045) and optionally locked by a setup code (D-044) — that creates the first user = the top admin (user_id = 1, role admin), then switches the instance to productive mode.

2. Non-goals

Module setup screens (each module owns its config). Multi-admin (there is one, D-034/§7.1).

3. Setup mode & the gate (D-045)

The gate is the config toggle setup. The instance is in one of three states:

setup: false · no admin   →  LOCKED   (a "set setup: true and restart" boilerplate; not claimable)
setup: true               →  the WIZARD (or the code form when `setup_code` is set)
setup: false · admin      →  PRODUCTIVE

• The app may bind any address — 0.0.0.0:8080 behind the proxy (D-043); no bind refusal.
• The gate is the config toggle setup (D-045).
  • setup: false, no admin → the app is locked: GET / and GET /setup show a boilerplate — "MyDay is not set up. Set setup: true in config.yaml and restart." Every other route → 404. This state is not publicly claimable.
  • setup: true → /setup serves the wizard (the operator's deliberate switch). GET / → a friendly page pointing at /setup. Every other route → 404.
  • Completion → the app writes setup: false and creates the admin → productive.
• setup_code is OPTIONAL (D-044 · D-045). If set in config.yaml, the wizard requires it (a second factor) and the code form comes first; if empty, the toggle alone admits. Single-use; rate-limited; redacted (A8).
• The peer/tunnel gate (D-025) is retired — setup: true is the gate; the SetupRequestAllowed peer+X-Forwarded-For rule no longer decides setup access. The XFF/XFP handling is kept for the client IP and the Secure/__Host- cookies + HSTS (A6/A11/D-043).
• The setup module is pinned at the door: the wizard's actions are reachable only through the reserved setup workflow (M1c/L3s · SPEC-003 §4).
• Residual (D-045): while setup: true, whoever reaches /setup first can claim the admin — set setup_code, or complete setup immediately.

4. The wizard

# setup: false · no admin  →  the boilerplate ("enable setup")   ← locked, not claimable
# setup: true              →  the wizard
GET  /setup                         → (if `setup_code` is set) the code form, else the wizard
POST /setup?do=setup&action=unlock  → the code → unlocks          (only when `setup_code` is set)
  Step 1  domain / base_url
  Step 2  the top admin — display_name · email · **TOTP enrollment**   (Passkey deferred — D-041)
  Step 3  mail (SMTP) · locale · timezone
POST /setup?do=setup&action=…       → each step (CSRF-protected)
  Finish  → persist settings → **setup: false**
          → user_id = 1 (role admin) · identity minted + activated · session minted

• Settings persist to config.yaml (D-035). Caveat: if the file is not writable, the wizard prints the values and instructs the operator to write them, then marks setup complete.
• One admin only: the wizard creates user_id = 1; later attempts to create another admin are rejected (SPEC-004 AC-6).
• TOTP only (D-041): the wizard does not enroll a Passkey — over plain-HTTP loopback a passkey would bind to 127.0.0.1 and be unusable at the public domain. The admin adds one at first login on the real origin, via the passkey nudge (SPEC-006 §8).

5. After setup

• /setup → 404 (delete, don't redirect). Re-entering requires config.setup: true + restart.
• config.yaml now reads setup: false; with an admin present the instance is productive. (Without an admin it would be the locked state — the toggle is off and there is nothing to serve; set setup: true and restart to resume.)
• The instance is served on its configured bind (typically 0.0.0.0:8080 behind the reverse proxy, D-043); the request scheme is taken from X-Forwarded-Proto (trusted proxy) or TLS.
• Audit: the bootstrap, the admin creation, and the enroll are all recorded (A11).

6. Acceptance criteria

#	Criterion
AC-1	setup: true → GET /setup serves the wizard directly when setup_code is empty; GET / points at it; every other route → 404
AC-2	With setup_code set, GET /setup shows the code form first (from any peer); only a request unlocked with the code reaches the wizard; a wrong/absent code gets a generic 403. The peer/tunnel rule (D-025) is retired (D-045)
AC-3	Completing the wizard creates user_id = 1 (role admin) with TOTP enrolled and no passkey (D-041)
AC-4	After completion config.setup = false (or printed) and /setup → 404
AC-5	A second admin cannot be created
AC-6	The full bootstrap is audited
AC-7	The setup code (when set) is single-use and rate-limited; a wrong or absent code gets a generic answer that reveals nothing, and the code is redacted from the logs (A8)
AC-8	setup: false with no admin → LOCKED: GET / and GET /setup render the "enable setup" boilerplate (200 — never a bare 404), every other route → 404, and the wizard is not claimable (D-045)

---

7. Implementation notes (accepted rulings)

Built 2026-10-13. build · vet · test (incl. -race) green; static CGO-free binary; live-smoked (/setup→200 + CSRF cookie · /home→404 · /→404 · action without CSRF→403 · step 1→2→2b advances · real WebAuthn begin and real sealed TOTP issue). AC-1…AC-6 all pass.

What landed

• internal/core/setup — the wizard (Actions): page + steps (domain.save · admin.create · admin.enroll.* · admin.totp.* · finish), the step state machine, and the persister.
• internal/core/server — RegisterSetupFlow (the setup core page + the setup action module); the setup-mode gate in dispatch (§3: only /setup + static served) and serveSetupAction (pre-session CSRF, A15).
• cmd/myday — wiring + configTarget (persists to config.yaml, never the committed example).
• internal/core/config — Marshal (the persisted document re-loads through the strict loader).
• internal/core/auth — Identities.ByUserID (additive; the wizard's "which step?" lookup).
• internal/core/auth/flow — Deps.SuccessPath (additive seam; the wizard injects /setup so a successful ceremony stays on the wizard).

Step 2 reuses SPEC-006 — the wizard calls flow.Actions.EnrollBegin/Finish/TOTPBegin/Verify with the admin's GUID; the ceremony is not duplicated.

The setup-mode gate (SPEC-005 §3, AC-1) — while in setup mode every route except /setup (+ static) is 404, including /home, /access, the canonical / → /home redirect, and every GUID branch. (Delete, don't redirect — a fresh instance has no app yet.)

#	Builder choice	Ruling
D-1	One admin only enforced by users.Create; the wizard returns 409 on a second attempt.	Accepted (AC-5).
D-2	The wizard's step is derived from the DB (admin exists? identity pending/active?) plus an in-memory draft for step 1's domain.	Accepted as the smallest state model.
D-3	A not-writable config.yaml → the YAML is printed to stdout with an instruction; setup still completes in memory.	Accepted (AC-4; §4 caveat).
D-4	Setup mode is LATCHED at startup (config.Setup, D-045) and cleared by an atomic Actions.Done(); config.Setup is never mutated (the live Config is an immutable startup snapshot, D-035).	Accepted — avoids a data race on the shared config and a per-request DB query, and holds setup mode through the whole wizard: once the admin row exists a live "no user" check would end setup mode before enrollment/finish. (D-045): the "no user" clause moved to the LOCKED state; setup mode is now purely the toggle.

Architect rulings on the flagged items:

#	Item	Ruling
R-6	Secrets are preserved verbatim, never generated — a config.example.yaml copy persists CHANGE_ME placeholders, so the next boot fails closed.	Generate. The wizard generates strong secrets (session · cookie · csrf · totp) when a secret is empty/placeholder, so a first boot from the example is viable. Folded into the next slice.
O-13	The WebAuthn RP is built at startup from server.base_url; step 1's domain doesn't rebuild it.	Surface to the owner — see O-13 in PROJECT_PLAN.md §9. A passkey enrolled over plain-HTTP loopback binds RP ID 127.0.0.1 and is unusable at the public domain. Does not block SPEC-007/008.
F-2	The ruling "serve the otpauth URL Cache-Control: no-store" (SPEC-006 §7) is not implemented.	Fix — add no-store to the enroll/TOTP (and setup) responses. Folded into the next slice.
D-5	Step-1's domain draft is in-memory only (a restart re-asks step 1).	Accepted — minor; DB state for steps 2–3 survives.

---

8. Implementation notes — TOTP-only setup (D-041, 2026-10-14)

Built 2026-10-14. build · vet · test (incl. -race) green; static CGO-free binary.

What changed

• Step 2 enrolls TOTP only — the wizard renders the authenticator form and the verify form; the passkey section and the admin.enroll.begin / admin.enroll.finish actions are gone. setup.Enroller now declares only TOTPBegin / TOTPVerify.
• flow.Deps.TOTPOnlyEnroll (new, default false) lets a PENDING identity activate on a verified TOTP code alone — the wizard's dedicated flow sets it. Normal GUID enrollment (/{GUID}, SPEC-006 §4) still requires both factors (AC-2).
• cmd/myday builds two flows over the same deps: the door's (two-factor, nudge-suppressed in setup mode) and the wizard's (TOTPOnlyEnroll, SuccessPath → /setup).
• AC-3 now asserts TOTP enrolled · no passkey; the audit set is user.create · identity.mint · enroll.totp.begin · enroll.complete · setup.admin · setup.complete (no enroll.passkey).

The admin adds a passkey at first login on the real origin, via the passkey nudge (SPEC-006 §8).

---

9. Implementation notes — the setup code & boilerplate (D-044, 2026-10-15b)

Superseded in part by D-045 (§10). The D-044 mechanics (the signed unlock cookie, the single-use/rate-limited/redacted code, the generic 403) are unchanged; what changed is the gate: setup: true is now the gate, setup_code is optional, and the peer/tunnel gate is retired. The code-form page now lives only at GET /setup (not /), and the code is no longer generated when blank.

Built 2026-10-15. build · vet · test -race green; static CGO-free binary; live-smoked against the real binary (banner + code, boilerplate at / and /setup behind a proxy, wrong code → 403, correct code → 303 + unlock cookie, the wizard follows, a spent code is refused, and neither the code nor a query-borne copy appears in the access log).

What landed

• internal/core/setup — Gate (gate.go): the setup code + the signed unlock cookie, and the first-run boilerplate renderer. Actions gains Unlock (the unlock action), Code and Gate.
• internal/core/server — Deps.SetupGate (a narrow SetupGate interface); dispatch now honours gate (b) (an unlocked request) alongside gate (a) (the tunnel), and hands GET /
  • an un-unlocked GET /setup to the boilerplate (never a bare 404).
• internal/core/httpx — Signer.Fingerprint: a keyed, one-way digest so the unlock cookie can bind to the code without carrying it.
• internal/core/config — setup_code (see D-1 below); cmd/myday builds the gate, wires it into the door, and prints the startup banner.

The gate, precisely

The code	128-bit, pinned by setup_code (D-045: no code is generated when it is blank — the toggle alone admits). Entry ignores case/separators.
Single-use	Accept retires the code on the first success; a failed attempt does not consume it.
The unlock	A signed cookie (myday_setup) carrying a fingerprint of the code — not the code — so it survives the code's retirement but dies on a restart (new code) or on completion (Clear). It is not the session cookie (no user exists).
Generic	A wrong and an absent code return the same 403 page/message.
Rate-limited	The /setup class of the A3 limiter covers the unlock form.
Redacted	The code rides a POST body (never a URL); a hand-typed ?code=… is redacted by RedactQuery (A8).
Audited	setup.unlock (unlocked / refused) — no code value.

#	Builder choice	Ruling
D-1	The config key is setup_code (top level), not the literal setup.code: setup: is already the boolean mode flag (D-026), and YAML cannot be both a scalar and a mapping.	Accepted — the smallest faithful encoding of "setup.code in config".
D-2	"Single-use" = the code retires on the first successful unlock; the browser keeps its signed unlock cookie (multi-tab works), a second visitor cannot re-use the printed value. A restart re-arms a pinned setup_code.	Accepted — honours single-use without a lock-out when a tab is closed.
D-3	GET / shows the first-run page always while the wizard is enabled — / is not the wizard. (D-045): / is now a landing that points at /setup; the code form is at /setup.	Accepted.
D-4	With no gate wired (a door built by hand) the first-run pages fall back to the strict 404 — the entrypoint always wires it.	Accepted — keeps the door honest without a setup package.

---

10. Implementation notes — the toggle gate & the optional code (D-045, 2026-10-15c)

Built 2026-10-15. build · vet · test -race green; static CGO-free binary; live-smoked against the real binary across all three states (locked boilerplate at / and /setup, the code-less wizard, the code form → unlock → wizard, and a full bootstrap: domain.save → admin.create → admin.totp.begin/verify → finish → config.yaml reads setup: false and /setup → 404).

What changed

• The gate is config.setup — setup: true enables the wizard; setup: false with no admin is the LOCKED state. The !bootstrapped() fail-safe clause was removed from setup mode and became the locked predicate (latched at startup).
• setup_code is optional — setup.New no longer generates a code; a blank code makes Gate.Required() false and the toggle alone admits. When set, the D-044 code mechanics apply unchanged.
• The peer/tunnel gate is retired — httpx.SetupRequestAllowed (and httpx.IsLoopbackIP) are deleted; the XFF/XFP handling is kept for the client IP and the Secure/__Host- cookies
  • HSTS (A6/A11/D-043).
• Three first-run pages — Gate.CodeForm (setup + required code, un-entered), Gate.Landing (GET / while setup is enabled), Gate.Locked (setup off, no admin). Deps.LockedMode carries the locked predicate; Deps.SetupMode now means "the wizard is enabled".
• The startup banner states the mode; it prints the code only when setup_code is set; in the locked state it tells the operator to set setup: true and restart.

#	Builder choice	Ruling
D-1	Static assets stay served in every first-run state (locked + enabled) so the boilerplate/code form render inside the shell — the "every other route → 404" rule covers app routes.	(builder; the smallest faithful reading — a stylesheet for the page that replaces the 404)
D-2	"No admin" (for the locked predicate) = no user row at all, latched at startup — not "no ACTIVE admin". A pending admin is therefore productive (enrolls via /{GUID}), never locked.	(builder)
D-3	The unlock action when no code is required is a no-op 303 → /setup rather than a 404.	(builder — a stale bookmark works)

---

11. Fix — the TOTP step renders the wizard page (2026-10-15d)

Bug: POST /setup?do=setup&action=admin.totp.begin answered with the enroll flow's JSON ({"otpauth_url":…}, Content-Type: application/json) — setup.Actions.TOTPBegin delegated to flow.Actions.TOTPBegin, which is webauthn.js's JSON API. The wizard is a server-rendered, no-JS flow, so the browser showed raw JSON and stalled at step 2 (§4's "TOTP enrollment" step rendered no secret at all).

Fix (the enroll flow's JSON contract is kept intact — webauthn.js depends on it):

• internal/core/auth/flow — the issue step is extracted into a write-free seam, Actions.IssueTOTP(ctx, guid) (string, error) (issues + persists the secret, returns the otpauth URL, writes nothing). TOTPBegin now calls it and keeps its JSON contract (writeJSON(w, 200, {"otpauth_url": url})).
• internal/core/setup — Enroller gains the write-free IssueTOTP and drops TOTPBegin (so the wizard's seam no longer exposes a JSON-writing method at all); Actions.TOTPBegin now renders an HTML page (text/html, inside the shell, no inline scripts) showing the otpauth URL, its human-readable secret for manual entry, and the verify form (posting to admin.totp.verify, carrying the pre-session CSRF token, A15).
• internal/core/setup/render.go — totpPage + secretFromOtpauth.
• Tests — internal/core/server/setup_wizard_test.go now asserts the begin response is text/html and carries the issued secret and the verify form (not merely 200); the end-to-end path (begin → real code → 303) is kept. enroll_login_test.go pins the enroll flow's JSON contract (application/json + "otpauth_url").

#	Builder choice	Ruling
D-1	The secret is shown as text (the otpauth URL plus the base32 secret extracted from it) rather than a QR image: the wizard is no-JS and a QR would pull in an image/barcode renderer for no gain.	(builder — "human-readable secret and/or QR")
D-2	pendingGUID now means pending AND in-window (its doc already read "still awaits enrollment"), so an expired window refuses the step (409) instead of letting IssueTOTP surface as a 500. TOTPVerify on an expired window answers 409 rather than the flow's 404 — a refusal either way.	(builder)
D-3	Enroller.TOTPBegin is removed — the fix left it unused by the wizard, and keeping a JSON-writing method on a no-JS seam is the coupling that caused the bug. flow.Actions.TOTPBegin (and its JSON contract for webauthn.js) is unchanged.	(builder — dead code after the fix; trivially reversible)