hanna/fabrica

feat: email verification via SMTP and `fabrica user verify`

5c1ec80 · hanna committed on 2026-07-25

Add email-address verification (migration 0009: user_emails.verified_at +
email_tokens). Adding an email or self-registering issues a 24h single-use
token and emails a /verify-email/{token} link; redeeming it marks the address
verified. Unverified addresses show a badge with a Resend button and cannot be
made primary. Existing addresses are back-filled as verified, and admin/CLI/
invite accounts are created verified. `fabrica user verify <name>` manually
verifies a user's primary email for instances without SMTP.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

assets/base.css +8 −0

crates/cli/src/user_cmd.rs +22 −0

crates/mail/src/templates.rs +8 −0

crates/model/src/entity.rs +10 −0

crates/store/src/users.rs +131 −11

crates/web/src/lib.rs +2 −0

crates/web/src/pages.rs +109 −4

crates/web/src/tests.rs +30 −1

migrations/postgres/0009_email_verification.sql +13 −0

migrations/sqlite/0009_email_verification.sql +13 −0

 .email-list {
   margin-bottom: 0;
+}
+.badge-verified {
+  color: var(--fb-success);
+  border-color: var(--fb-success);
+}
+.badge-unverified {
+  color: var(--fb-fg-muted);
+  border-color: var(--fb-border);
+}
 .email-visibility {
   margin: 0;
   padding: 0.85rem 0;

         /// The user to enable.
         name: String,
     },
+    /// Manually mark a user's primary email verified (for when SMTP is not set
+    /// up, or to vouch for an account).
+    Verify {
+        /// The user to verify.
+        name: String,
+    },
     /// Delete a user. Refuses if the user still owns repositories unless
     /// `--purge` is given.
     Del {
         UserCommand::List => block_on(list(config_path, json)),
         UserCommand::Disable { name } => block_on(set_disabled(config_path, name, true)),
         UserCommand::Enable { name } => block_on(set_disabled(config_path, name, false)),
+        UserCommand::Verify { name } => block_on(verify(config_path, name)),
         UserCommand::Del { name, purge, yes } => block_on(del(config_path, name, *purge, *yes)),
+    }
+}
     Ok(ExitCode::SUCCESS)
+}
+/// Manually mark a user's primary email verified.
+async fn verify(config_path: Option<&Path>, name: &str) -> anyhow::Result<ExitCode> {
+    let (_config, store) = open_store(config_path).await?;
+    let user = require_user(&store, name).await?;
+    if store.verify_primary_email(&user.id).await? {
+        println!(
+            "verified {}'s primary email ({})",
+            user.username, user.email
+        );
+    } else {
+        println!("{} has no primary email to verify", user.username);
+    }
+    Ok(ExitCode::SUCCESS)
+}
 async fn del(
     config_path: Option<&Path>,
     name: &str,

     Activate,
     /// A password-reset link.
     Reset,
+    /// An email-address verification link.
+    VerifyEmail,
+}
 impl Purpose {
         match self {
             Self::Activate => "activate",
             Self::Reset => "reset",
+            Self::VerifyEmail => "verify-email",
+        }
+    }
+}
             format!("A password reset was requested for your {instance_name} account."),
             "choose a new password",
         ),
+        Purpose::VerifyEmail => (
+            format!("Verify your email for {instance_name}"),
+            format!("Confirm this email address to use it on {instance_name}."),
+            "verify this email address",
+        ),
     };
     let plain = format!(

     pub email: String,
     /// Whether this is the user's primary address.
     pub is_primary: bool,
+    /// When the address was verified, or `None` if still unverified.
+    pub verified_at: Option<Timestamp>,
     /// Creation time.
     pub created_at: Timestamp,
+}
+impl UserEmail {
+    /// Whether the address has been verified.
+    #[must_use]
+    pub fn verified(&self) -> bool {
+        self.verified_at.is_some()
+    }
+}
 /// A registered account.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct User {

             .map_err(|e| {
                 map_conflict(e, "user", &[("email", "email"), ("username", "username")])
             })?;
-        // Seed the primary email row so `user_emails` holds every address.
+        // Seed the primary email row so `user_emails` holds every address. It is
+        // created verified — admin/CLI/invite accounts are trusted; the
+        // self-registration path explicitly re-opens verification afterwards.
         sqlx::query(
-            "INSERT INTO user_emails (id, user_id, email, email_lower, is_primary, created_at) \
+            "INSERT INTO user_emails \
-             VALUES ($1, $2, $3, $4, $5, $6)",
+             (id, user_id, email, email_lower, is_primary, verified_at, created_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7)",
+        )
         .bind(new_id())
         .bind(user.id.clone())
         .bind(user.email.to_lowercase())
         .bind(true)
         .bind(user.created_at)
+        .bind(user.created_at)
         .execute(&mut *tx)
         .await
         .map_err(|e| map_conflict(e, "user", &[("email_lower", "email")]))?;
     /// Returns [`StoreError::Query`] on a database failure.
     pub async fn emails_by_user(&self, user_id: &str) -> Result<Vec<model::UserEmail>, StoreError> {
         let rows = sqlx::query(
-            "SELECT id, user_id, email, is_primary, created_at FROM user_emails \
+            "SELECT id, user_id, email, is_primary, verified_at, created_at FROM user_emails \
              WHERE user_id = $1 ORDER BY is_primary DESC, created_at ASC",
+        )
         .bind(user_id)
                     user_id: r.try_get("user_id")?,
                     email: r.try_get("email")?,
                     is_primary: self.get_bool(r, "is_primary")?,
+                    verified_at: r.try_get("verified_at")?,
                     created_at: r.try_get("created_at")?,
                 })
             })
             user_id: user_id.to_string(),
             email: email.to_string(),
             is_primary: false,
+            verified_at: None,
             created_at: now_ms(),
         };
         sqlx::query(
         Ok(deleted > 0)
+    }
-    /// Make one of a user's addresses primary, mirroring it into `users.email`.
+    /// Make one of a user's **verified** addresses primary, mirroring it into
+    /// `users.email`. Returns `false` if the address is missing or unverified.
     ///
     /// # Errors
     ///
         user_id: &str,
         email_id: &str,
     ) -> Result<bool, StoreError> {
-        // Confirm the address belongs to the user and capture its value.
+        // Confirm the address belongs to the user, is verified, and capture it.
-        let row = sqlx::query("SELECT email FROM user_emails WHERE id = $1 AND user_id = $2")
+        let row = sqlx::query(
-            .bind(email_id)
+            "SELECT email FROM user_emails \
-            .bind(user_id)
+             WHERE id = $1 AND user_id = $2 AND verified_at IS NOT NULL",
-            .fetch_optional(&self.pool)
+        )
-            .await?;
+        .bind(email_id)
+        .bind(user_id)
+        .fetch_optional(&self.pool)
+        .await?;
         let Some(row) = row else {
             return Ok(false);
         };
         Ok(())
+    }
+    /// Begin (or restart) verification of an email address: mark it unverified,
+    /// drop any outstanding tokens, and store a fresh `token` valid for 24 hours.
+    /// The caller generates the random token and emails the link.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`StoreError::Query`] on a database failure.
+    pub async fn begin_email_verification(
+        &self,
+        email_id: &str,
+        token: &str,
+    ) -> Result<(), StoreError> {
+        let now = now_ms();
+        let mut tx = self.pool.begin().await?;
+        sqlx::query("UPDATE user_emails SET verified_at = NULL WHERE id = $1")
+            .bind(email_id)
+            .execute(&mut *tx)
+            .await?;
+        sqlx::query("DELETE FROM email_tokens WHERE email_id = $1")
+            .bind(email_id)
+            .execute(&mut *tx)
+            .await?;
+        sqlx::query(
+            "INSERT INTO email_tokens (token, email_id, expires_at, created_at) \
+             VALUES ($1, $2, $3, $4)",
+        )
+        .bind(token)
+        .bind(email_id)
+        .bind(now + 24 * 60 * 60 * 1000)
+        .bind(now)
+        .execute(&mut *tx)
+        .await?;
+        tx.commit().await?;
+        Ok(())
+    }
+    /// Redeem a verification token: mark its address verified and consume the
+    /// token. Returns the owning user id, or `None` if the token is unknown or
+    /// expired.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`StoreError::Query`] on a database failure.
+    pub async fn verify_email_token(&self, token: &str) -> Result<Option<String>, StoreError> {
+        let now = now_ms();
+        let row = sqlx::query(
+            "SELECT t.email_id, e.user_id FROM email_tokens t \
+             JOIN user_emails e ON e.id = t.email_id \
+             WHERE t.token = $1 AND t.expires_at > $2",
+        )
+        .bind(token)
+        .bind(now)
+        .fetch_optional(&self.pool)
+        .await?;
+        let Some(row) = row else {
+            return Ok(None);
+        };
+        let email_id: String = row.try_get("email_id")?;
+        let user_id: String = row.try_get("user_id")?;
+        let mut tx = self.pool.begin().await?;
+        sqlx::query("UPDATE user_emails SET verified_at = $1 WHERE id = $2")
+            .bind(now)
+            .bind(&email_id)
+            .execute(&mut *tx)
+            .await?;
+        sqlx::query("DELETE FROM email_tokens WHERE token = $1")
+            .bind(token)
+            .execute(&mut *tx)
+            .await?;
+        tx.commit().await?;
+        Ok(Some(user_id))
+    }
+    /// Look up an email row id owned by `user_id`, for resending verification.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`StoreError::Query`] on a database failure.
+    pub async fn email_owned_by(
+        &self,
+        user_id: &str,
+        email_id: &str,
+    ) -> Result<Option<model::UserEmail>, StoreError> {
+        Ok(self
+            .emails_by_user(user_id)
+            .await?
+            .into_iter()
+            .find(|e| e.id == email_id))
+    }
+    /// Mark the user's primary email verified (the manual `user verify` path,
+    /// used when SMTP is unavailable).
+    ///
+    /// # Errors
+    ///
+    /// Returns [`StoreError::Query`] on a database failure.
+    pub async fn verify_primary_email(&self, user_id: &str) -> Result<bool, StoreError> {
+        let updated = sqlx::query(
+            "UPDATE user_emails SET verified_at = $1 WHERE user_id = $2 AND is_primary = $3",
+        )
+        .bind(now_ms())
+        .bind(user_id)
+        .bind(true)
+        .execute(&self.pool)
+        .await?
+        .rows_affected();
+        Ok(updated > 0)
+    }
     /// Set (or clear) a user's password hash.
     ///
     /// Passing `Some(hash)` sets the credential and clears the

             "/invite/{token}",
             get(pages::invite_form).post(pages::invite_submit),
+        )
+        .route("/verify-email/{token}", get(pages::verify_email))
         .route("/search", get(search::global))
         .route(
             "/settings",
         .route("/settings/emails", post(pages::email_add))
         .route("/settings/emails/primary", post(pages::email_primary))
         .route("/settings/emails/delete", post(pages::email_delete))
+        .route("/settings/emails/resend", post(pages::email_resend))
         .route("/settings/emails/visibility", post(pages::email_visibility))
         .route("/settings/password", post(pages::account_password))
         .route(

         Err(err) => return AppError::from(err).into_response(),
     };
+    // Send a verification email for the new primary address (best-effort).
+    if let Ok(emails) = state.store.emails_by_user(&user.id).await
+        && let Some(primary) = emails.into_iter().find(|e| e.is_primary)
+    {
+        send_email_verification(&state, &primary).await;
+    }
     match open_session(&state, &jar, &user, &headers).await {
         Ok(jar) => (jar, Redirect::to("/")).into_response(),
         Err(err) => err.into_response(),
         return AppError::BadRequest("Enter a valid email address.".to_string()).into_response();
+    }
     match state.store.add_email(&user.id, email).await {
-        Ok(_) => Redirect::to("/settings/account").into_response(),
+        Ok(added) => {
+            // Send a verification link (best-effort; logged on failure).
+            send_email_verification(&state, &added).await;
+            Redirect::to("/settings/account").into_response()
+        }
         Err(store::StoreError::Conflict { .. }) => {
             AppError::BadRequest("That email is already in use.".to_string()).into_response()
+        }
+    }
+}
+/// Issue a fresh verification token for `email` and email the link. Best-effort:
+/// store or mail failures are logged, not surfaced (the user can resend).
+async fn send_email_verification(state: &AppState, email: &model::UserEmail) {
+    let token = auth::new_secret();
+    if let Err(err) = state
+        .store
+        .begin_email_verification(&email.id, &token)
+        .await
+    {
+        tracing::warn!(error = %err, "could not store email verification token");
+        return;
+    }
+    let base = state.config.instance.url.trim_end_matches('/');
+    let link = format!("{base}/verify-email/{token}");
+    if let Err(err) = state
+        .mailer
+        .send_invite(
+            &state.config.instance.name,
+            &email.email,
+            None,
+            &link,
+            mail::Purpose::VerifyEmail,
+        )
+        .await
+    {
+        tracing::warn!(error = %err, email = %email.email, "could not send verification email");
+    }
+}
+/// `GET /verify-email/{token}` — redeem an email verification link.
+pub async fn verify_email(
+    State(state): State<AppState>,
+    jar: CookieJar,
+    Path(token): Path<String>,
+) -> Response {
+    match state.store.verify_email_token(&token).await {
+        Ok(Some(_)) => {
+            let (jar, chrome) = build_chrome(&state, jar, None, "/verify-email".to_string());
+            let body = html! {
+                div class="auth-wrap" {
+                    div class="auth-card" {
+                        h1 { "Email verified" }
+                        p class="muted" { "Your email address has been verified." }
+                        p { a class="btn btn-primary" href="/settings/account" { "Back to settings" } }
+                    }
+                }
+            };
+            (jar, page(&chrome, "Email verified", body)).into_response()
+        }
+        Ok(None) => {
+            AppError::BadRequest("That verification link is invalid or has expired.".to_string())
+                .into_response()
+        }
+        Err(err) => AppError::from(err).into_response(),
+    }
+}
+/// `POST /settings/emails/resend` — resend a verification email.
+pub async fn email_resend(
+    State(state): State<AppState>,
+    RequireUser(user): RequireUser,
+    jar: CookieJar,
+    headers: HeaderMap,
+    Form(form): Form<EmailIdForm>,
+) -> Response {
+    if verify_csrf(&jar, &headers, Some(&form.csrf)).is_err() {
+        return AppError::Forbidden.into_response();
+    }
+    if let Ok(Some(email)) = state.store.email_owned_by(&user.id, &form.id).await {
+        send_email_verification(&state, &email).await;
+    }
+    Redirect::to("/settings/account").into_response()
+}
 /// An email-id form (set-primary or delete).
 #[derive(Debug, Deserialize)]
 pub struct EmailIdForm {
     if verify_csrf(&jar, &headers, Some(&form.csrf)).is_err() {
         return AppError::Forbidden.into_response();
+    }
-    let _ = state.store.set_primary_email(&user.id, &form.id).await;
+    match state.store.set_primary_email(&user.id, &form.id).await {
-    Redirect::to("/settings/account").into_response()
+        Ok(true) => Redirect::to("/settings/account").into_response(),
+        Ok(false) => {
+            AppError::BadRequest("Verify the email address before making it primary.".to_string())
+                .into_response()
+        }
+        Err(err) => AppError::from(err).into_response(),
+    }
+}
 /// `POST /settings/emails/delete` — remove one of the viewer's secondary emails.
                                 span class="entry-row-title" {
                                     (e.email)
                                     @if e.is_primary { " " span class="badge" { "primary" } }
+                                    @if e.verified() {
+                                        " " span class="badge badge-verified" { "verified" }
+                                    } @else {
+                                        " " span class="badge badge-unverified" { "unverified" }
+                                    }
+                                }
+                            }
                             div class="entry-row-actions" {
-                                @if !e.is_primary {
+                                @if !e.verified() {
+                                    form method="post" action="/settings/emails/resend" {
+                                        input type="hidden" name="_csrf" value=(csrf);
+                                        input type="hidden" name="id" value=(e.id);
+                                        button class="btn" type="submit" { "Resend" }
+                                    }
+                                }
+                                @if !e.is_primary && e.verified() {
                                     form method="post" action="/settings/emails/primary" {
                                         input type="hidden" name="_csrf" value=(csrf);
                                         input type="hidden" name="id" value=(e.id);
                                         button class="btn" type="submit" { "Make primary" }
+                                    }
+                                }
+                                @if !e.is_primary {
                                     form method="post" action="/settings/emails/delete" {
                                         input type="hidden" name="_csrf" value=(csrf);
                                         input type="hidden" name="id" value=(e.id);

         .find(|e| e.email == "second@example.com")
         .unwrap();
     assert!(!second.is_primary);
+    assert!(!second.verified(), "added emails start unverified");
     let second_id = second.id.clone();
-    // Make it primary; users.email mirrors it.
+    // A new address must be verified before it can become primary.
+    let res = post(
+        "/settings/emails/primary",
+        format!("id={second_id}&_csrf={token}"),
+        cookie.clone(),
+    )
+    .await;
+    assert_eq!(
+        res.status(),
+        StatusCode::BAD_REQUEST,
+        "unverified cannot be primary"
+    );
+    // Exercise the verification flow: token issued, then redeemed.
+    state
+        .store
+        .begin_email_verification(&second_id, "verify-token")
+        .await
+        .unwrap();
+    assert!(
+        state
+            .store
+            .verify_email_token("verify-token")
+            .await
+            .unwrap()
+            .is_some()
+    );
+    // Now it can be made primary; users.email mirrors it.
     let res = post(
         "/settings/emails/primary",
         format!("id={second_id}&_csrf={token}"),

+-- Email-address verification: a nullable verified timestamp plus single-use,
+-- expiring verification tokens. Addresses that predate this migration are
+-- trusted (back-filled as verified).
+ALTER TABLE user_emails ADD COLUMN verified_at BIGINT;
+UPDATE user_emails SET verified_at = created_at;
+CREATE TABLE email_tokens (
+    token      TEXT PRIMARY KEY,
+    email_id   TEXT NOT NULL REFERENCES user_emails(id) ON DELETE CASCADE,
+    expires_at BIGINT NOT NULL,
+    created_at BIGINT NOT NULL
+);
+CREATE INDEX idx_email_tokens_email ON email_tokens (email_id);