fix(setup): record email unverified so onboarding works without SMTP (87279a13) · Commits · FelisMC / Felis · GitLab

docs/openapi.yaml

+40 −0

Changes for docs/openapi.yaml: 40 added lines, 0 removed lines.
Original line number	Diff line number	Diff line
		@@ -3317,6 +3317,46 @@ paths:
		application/json:
		schema: { $ref: '#/components/schemas/Error' }

		/api/v1/account/email:
		post:
		tags: [account]
		operationId: setEmail
		summary: Record the caller's email WITHOUT verifying it (setup bootstrap, spec §B2).
		description: >
		Writes the supplied address to the authenticated principal's user row and
		clears email_verified (already false for a fresh Owner). The setup bootstrap
		has no SMTP, so the Owner cannot receive an emailed code; a later Settings/SMTP
		flow proves control of the address via /account/email/verify.
		x-felis-face: [external]
		x-felis-tier: app
		security: [{ accessJWT: [] }]
		requestBody:
		required: true
		content:
		application/json:
		schema:
		type: object
		required: [email]
		properties:
		email: { type: string, format: email }
		responses:
		'200':
		description: Email recorded (unverified).
		content:
		application/json:
		schema:
		type: object
		required: [email]
		properties:
		email: { type: string, format: email }
		'400':
		description: A valid email is required.
		content:
		application/json:
		schema: { $ref: '#/components/schemas/Error' }
		'401':
		$ref: '#/components/responses/Unauthorized'

		/api/v1/account/passkey/register/begin:
		post:
		tags: [account]

internal/api/api.go

+25 −10

Changes for internal/api/api.go: 25 added lines, 10 removed lines.
Original line number	Diff line number	Diff line
		@@ -391,6 +391,10 @@ func (a *API) externalAPIRoutes() []apiRoute {
		// email is an ordinary authenticated operation, scoped to the principal.
		{Method: "POST", Pattern: "/api/v1/account/email/start", SetupAllowed: true, h: a.handleEmailOTPStart},
		{Method: "POST", Pattern: "/api/v1/account/email/verify", SetupAllowed: true, h: a.handleEmailOTPVerify},
		// Record-only email: the setup wizard's Step 1 stores the Owner's address
		// UNVERIFIED (no SMTP at bootstrap ⇒ no code to mail). email_verified stays
		// false until a later Settings/SMTP flow proves control via /email/verify above.
		{Method: "POST", Pattern: "/api/v1/account/email", SetupAllowed: true, h: a.handleSetEmail},
		// Passkey enrollment (spec §14 WebAuthn / Phase 6 bind), web side: /register/begin
		// mints a credential-creation challenge for the caller, /register/finish verifies
		// the authenticator's attestation and binds the passkey, and the credentials
		@@ -522,7 +526,7 @@ func (a *API) buildFace(routes []apiRoute, guard func(http.Handler) http.Handler
		// explicitly opts out. The wrapper is nil-principal safe, so it is inert on
		// the internal face (service-token callers carry no Principal).
		if !rt.SetupAllowed {
		h = a.requireEmailVerified(h)
		h = a.requireOnboarded(h)
		}
		auth.HandleFunc(pattern, h)
		}
		@@ -542,21 +546,32 @@ func (a *API) baseChain(h http.Handler) http.Handler {
		return withRequestID(withRecover(h))
		}

		// requireEmailVerified fences an authenticated route behind the setup-lockdown:
		// a session whose EmailVerified is false (a freshly-onboarded principal that has
		// not yet proved control of its email) is restricted to SetupAllowed routes only.
		// The wrapper is nil-principal safe, so it is inert on the internal face
		// (service-token callers carry no Principal) and on the external face's admin
		// Zero-Trust paths (those carry an IsAdmin/IsOwner principal that has already
		// passed email verification at account creation).
		func (a *API) requireEmailVerified(h http.HandlerFunc) http.HandlerFunc {
		// requireOnboarded fences an authenticated route behind the setup-lockdown: a
		// freshly-onboarded principal that has not finished setup is restricted to
		// SetupAllowed routes only. The lockdown lifts on a durable login credential, NOT
		// on email verification: the bootstrap Owner has no verified email (no SMTP exists
		// at bootstrap) and a passkey is the ONLY credential that logs the Owner in
		// pre-SMTP (email-OTP login refuses admin accounts; op-login needs SMTP + a second
		// admin). So passkey enrollment is what completes setup — and it must, or the
		// unverified Owner could never reach the Settings page to configure SMTP.
		//
		// Only a session principal whose email is still unverified reaches the passkey
		// lookup; after setup that is just the bootstrap Owner, so the extra query is not
		// on any hot path. The wrapper is nil-principal safe, so it is inert on the
		// internal face (service-token callers carry no Principal) and on the external
		// face's admin Zero-Trust paths (those carry an IsAdmin/IsOwner principal that has
		// already passed email verification at account creation).
		func (a *API) requireOnboarded(h http.HandlerFunc) http.HandlerFunc {
		return func(w http.ResponseWriter, r *http.Request) {
		p := principalFromContext(r.Context())
		if p != nil && p.ViaSession && !p.EmailVerified {
		creds, _ := a.Repo.PasskeyCredentialsForUser(r.Context(), p.UserID)
		if len(creds) == 0 {
		writeError(w, r, newError(http.StatusForbidden, "setup_required",
		"email verification is required before this action is available"))
		"passkey enrollment is required before this action is available"))
		return
		}
		}
		h(w, r)
		}
		}

internal/api/api_test.go

+10 −0

Changes for internal/api/api_test.go: 10 added lines, 0 removed lines.
Original line number	Diff line number	Diff line
		@@ -359,6 +359,16 @@ func (f *fakeRepo) VerifyEmailOTP(_ context.Context, userID, purpose, codeHash s
		}
		return live.email, nil
		}
		func (f *fakeRepo) SetUserEmail(_ context.Context, userID, email string) error {
		for _, u := range f.staff { // record + clear verified (proves nothing) — mirrors PGRepo
		if u.ID == userID {
		u.Email = email
		u.EmailVerified = false
		return nil
		}
		}
		return ErrNotFound
		}

		// CreatePasskeyChallenge / ConsumePasskeyChallengeByUser mirror PGRepo's contract so
		// the hermetic tests exercise the same semantics: a fresh begin supersedes ALL prior

internal/api/handlers_email_otp.go

+36 −0

Changes for internal/api/handlers_email_otp.go: 36 added lines, 0 removed lines.
Original line number	Diff line number	Diff line
		@@ -230,6 +230,42 @@ func (a *API) deliverOTP(ctx context.Context, email, code string) error {
		return a.Mailer.SendOTP(ctx, email, code)
		}

		// setEmailRequest is the record-email body: the address to bind to the caller's
		// account WITHOUT an OTP round-trip.
		type setEmailRequest struct {
		Email string `json:"email"`
		}

		// handleSetEmail records the caller's email without verifying it (SetupAllowed). The
		// setup bootstrap has no SMTP, so the Owner cannot receive an emailed code; the
		// address is stored unverified and a later Settings/SMTP flow proves control of it.
		// This is the setup wizard's Step-1 write. The OTP start/verify pair above is left
		// intact for the Account page and for post-SMTP verification — this door deliberately
		// does NOT touch email_verified.
		func (a API) handleSetEmail(w http.ResponseWriter, r http.Request) {
		p := principalFromContext(r.Context())
		if err := requireJSONContentType(r); err != nil {
		writeError(w, r, err)
		return
		}
		var req setEmailRequest
		if err := decodeJSON(w, r, &req); err != nil {
		writeError(w, r, err)
		return
		}
		email := strings.TrimSpace(req.Email)
		if !looksLikeEmail(email) {
		writeError(w, r, newError(http.StatusBadRequest, "bad_request", "a valid email is required"))
		return
		}
		if err := a.Repo.SetUserEmail(r.Context(), p.UserID, email); err != nil {
		writeError(w, r, err)
		return
		}
		a.audit(r, auditActor(p), "account.email.set", "")
		writeJSON(w, http.StatusOK, map[string]any{"email": email})
		}

		// auditActor picks the most identifying actor string for a principal: the audited
		// Access email when present, else the stable user id. A player mid-onboarding may
		// not have a verified email yet, so the id keeps the audit row attributable.

internal/api/handlers_setup.go

+10 −2

Changes for internal/api/handlers_setup.go: 10 added lines, 2 removed lines.
Original line number	Diff line number	Diff line
		@@ -104,7 +104,11 @@ func (a API) handleSetupRedeem(w http.ResponseWriter, r http.Request) {
		"email": u.Email,
		"email_verified": u.EmailVerified,
		"has_passkey": hasPasskey,
		"setup_required": !u.EmailVerified \|\| !hasPasskey,
		// Setup completes on email recorded + passkey enrolled. NOT email_verified:
		// the bootstrap has no SMTP, so the Owner's address is stored unverified and a
		// later Settings/SMTP flow verifies it. Passkey is the Owner's only pre-SMTP
		// login credential, so it — not email verification — is the durable gate.
		"setup_required": u.Email == "" \|\| !hasPasskey,
		})
		}

		@@ -131,6 +135,10 @@ func (a API) handleSetupStatus(w http.ResponseWriter, r http.Request) {
		"email": u.Email,
		"email_verified": u.EmailVerified,
		"has_passkey": hasPasskey,
		"setup_required": !u.EmailVerified \|\| !hasPasskey,
		// Setup completes on email recorded + passkey enrolled. NOT email_verified:
		// the bootstrap has no SMTP, so the Owner's address is stored unverified and a
		// later Settings/SMTP flow verifies it. Passkey is the Owner's only pre-SMTP
		// login credential, so it — not email verification — is the durable gate.
		"setup_required": u.Email == "" \|\| !hasPasskey,
		})
		}