Password reset and email verification: single-use hashed links, reset by verified email or an administrator's link, verification on every address change, notification mail only to verified addresses, and a file:// mail transport for development 34beb1a7e376

-- Email verification and password reset links (hub spec §5.1.1). Only the

-- BLAKE3 hash of a link's secret is stored.

CREATE TABLE account_links (

    id         INTEGER PRIMARY KEY,

    account_id INTEGER NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,

    kind       TEXT NOT NULL CHECK (kind IN ('reset', 'verify')),

    hash       TEXT NOT NULL UNIQUE,

    -- The address a verification link verifies.

    email      TEXT NOT NULL DEFAULT '',

    -- The administrator who issued a reset link, when one did.

    created_by INTEGER REFERENCES accounts(id) ON DELETE SET NULL,

    created_ms INTEGER NOT NULL,

    expires_ms INTEGER NOT NULL,

    used_ms    INTEGER

);

CREATE INDEX account_links_by_account ON account_links (account_id, kind, created_ms DESC);

//! Outgoing mail (hub spec §5.1.1, §10): SMTP through lettre, or, for

//! development and tests, `file:///dir`, which writes each message to that

//! directory instead of sending it.

use crate::Shared;

/// Whether the hub can send mail at all.

pub fn enabled(app: &Shared) -> bool {

    let cfg = &app.config.email;

    !cfg.smtp.is_empty() && !cfg.from.is_empty()

}

/// Send a plain-text message. The subject gets the site's name in brackets.

pub async fn send(app: &Shared, to_name: &str, to_addr: &str, subject: &str, body: &str) -> Result<(), String> {

    if !enabled(app) {

        return Err("this hub does not send mail".into());

    }

    let cfg = &app.config.email;

    let subject = format!("[{}] {subject}", app.config.site.name);

    if let Some(dir) = cfg.smtp.strip_prefix("file://") {

        let name = format!("{}-{}.eml", crate::db::now_ms(), crate::auth::random_hex(4));

        let text = format!("From: {}\nTo: {to_name} <{to_addr}>\nSubject: {subject}\n\n{body}", cfg.from);

        return tokio::fs::write(std::path::Path::new(dir).join(name), text).await.map_err(|e| format!("write mail to {dir}: {e}"));

    }

    use lettre::message::header::ContentType;

    use lettre::{AsyncSmtpTransport, AsyncTransport, Message, Tokio1Executor};

    let from = cfg.from.parse().map_err(|e| format!("[email] from: {e}"))?;

    let to = format!("{to_name} <{to_addr}>").parse().or_else(|_| to_addr.parse()).map_err(|e| format!("address {to_addr}: {e}"))?;

    let message = Message::builder()

        .from(from)

        .to(to)

        .subject(subject)

        .header(ContentType::TEXT_PLAIN)

        .body(body.to_string())

        .map_err(|e| e.to_string())?;

    let transport = AsyncSmtpTransport::<Tokio1Executor>::from_url(&cfg.smtp).map_err(|e| format!("[email] smtp: {e}"))?.build();

    transport.send(message).await.map(|_| ()).map_err(|e| format!("sending to {to_addr}: {e}"))

}

//! Email verification and password reset (hub spec §5.1.1).

use super::{Error, Page, Shell};

use crate::auth::{self, Viewer};

use crate::db::{self, accounts};

use crate::Shared;

use askama::Template;

use axum::extract::{Form, Path, State};

use axum::response::{IntoResponse, Redirect, Response};

use serde::Deserialize;

const MINUTE: i64 = 60_000;

pub const VERIFY_TTL_MS: i64 = 48 * 60 * MINUTE;

pub const RESET_TTL_MS: i64 = 60 * MINUTE;

pub const ADMIN_RESET_TTL_MS: i64 = 24 * 60 * MINUTE;

/// At most one mailed link of a kind per account (and address) in this time.

pub const MAIL_EVERY_MS: i64 = 2 * MINUTE;

/// At most this many verification mails per account per hour, whatever the addresses.

pub const VERIFY_PER_HOUR: i64 = 10;

#[derive(Template)]

#[template(path = "reset.html")]

pub struct RecoveryPage {

    shell: Shell,

    /// `request`, `sent`, `new`, `invalid`, `verified`, `verify-invalid`.

    mode: &'static str,

    mail: bool,

    error: Option<String>,

    username: String,

    secret: String,

}

impl RecoveryPage {

    fn new(app: &Shared, shell: Shell, mode: &'static str) -> RecoveryPage {

        RecoveryPage { shell, mode, mail: crate::mail::enabled(app), error: None, username: String::new(), secret: String::new() }

    }

}

/// Send a verification link for the account's current email.

pub async fn send_verification(app: &Shared, account: &accounts::Account) -> Result<(), String> {

    if account.email.is_empty() || account.email_verified {

        return Ok(());

    }

    if !crate::mail::enabled(app) {

        return Err("This hub cannot send mail, so addresses cannot be verified yet.".into());

    }

    let now = db::now_ms();

    let recent = accounts::last_link_ms(&app.db, account.id, "verify", Some(&account.email)).await.map_err(|e| e.to_string())?;

    if recent.is_some_and(|t| now - t < MAIL_EVERY_MS) {

        return Err("A verification link was sent less than two minutes ago.".into());

    }

    if accounts::links_since(&app.db, account.id, "verify", now - 60 * MINUTE).await.map_err(|e| e.to_string())? >= VERIFY_PER_HOUR {

        return Err("Too many verification links this hour; try again later.".into());

    }

    let secret =

        accounts::create_link(&app.db, account.id, "verify", &account.email, None, VERIFY_TTL_MS).await.map_err(|e| e.to_string())?;

    let url = format!("{}/verify/{secret}", app.config.base_url());

    let body = format!(

        "Confirm that {} is the email address of {} on {}:\n\n{url}\n\nThe link works for 48 hours. If you did not ask for this, ignore it.\n",

        account.email,

        account.username,

        app.config.site.name

    );

    crate::mail::send(app, account.name(), &account.email, "Confirm your email address", &body).await

}

/// `GET /verify/{secret}`.

pub async fn verify(State(app): State<Shared>, viewer: Viewer, Path(secret): Path<String>) -> Result<Page<RecoveryPage>, Error> {

    let shell = Shell::new(&app, "/verify", &viewer);

    let e = |e| Error::from_db(shell.clone(), e);

    let link = accounts::live_link(&app.db, "verify", &secret).await.map_err(e)?;

    let account = match &link {

        Some(l) => accounts::account_by_id(&app.db, l.account_id).await.map_err(e)?,

        None => None,

    };

    match (link, account) {

        // Only the address the link was sent to, and only while it is still the account's.

        (Some(l), Some(a)) if a.email == l.email && accounts::use_link(&app.db, l.id).await.map_err(e)? => {

            accounts::set_email_verified(&app.db, a.id, true).await.map_err(e)?;

            accounts::audit(&app.db, Some(&a), "email.verified", &a.username, &a.email).await.ok();

            let mut page = RecoveryPage::new(&app, shell, "verified");

            page.username = a.email;

            Ok(Page(page))

        }

        _ => Ok(Page(RecoveryPage::new(&app, shell, "verify-invalid"))),

    }

}

/// `GET /login/reset`.

pub async fn request_form(State(app): State<Shared>, viewer: Viewer) -> Page<RecoveryPage> {

    Page(RecoveryPage::new(&app, Shell::new(&app, "/login/reset", &viewer), "request"))

}

#[derive(Deserialize)]

pub struct RequestForm {

    who: String,

}

/// `POST /login/reset`: the same answer whether or not anything matched.

pub async fn request(State(app): State<Shared>, viewer: Viewer, Form(f): Form<RequestForm>) -> Result<Page<RecoveryPage>, Error> {

    let shell = Shell::new(&app, "/login/reset", &viewer);

    if !crate::mail::enabled(&app) {

        return Ok(Page(RecoveryPage::new(&app, shell, "request")));

    }

    let who = f.who.trim();

    let e = |e| Error::from_db(shell.clone(), e);

    let account = if who.contains('@') {

        accounts::account_by_verified_email(&app.db, who).await.map_err(e)?

    } else {

        accounts::account_by_name(&app.db, who).await.map_err(e)?

    };

    if let Some(a) = account.filter(|a| a.email_verified && !a.email.is_empty() && !a.banned) {

        let recent = accounts::last_link_ms(&app.db, a.id, "reset", None).await.map_err(e)?;

        if !recent.is_some_and(|t| db::now_ms() - t < MAIL_EVERY_MS) {

            let secret = accounts::create_link(&app.db, a.id, "reset", "", None, RESET_TTL_MS).await.map_err(e)?;

            let url = format!("{}/login/reset/{secret}", app.config.base_url());

            let body = format!(

                "Someone asked to reset the password of {} on {}. To choose a new password, open:\n\n{url}\n\nThe link works once, for one hour. If it was not you, ignore this; your password stays as it is.\n",

                a.username, app.config.site.name

            );

            // Sent in the background, so the answer takes as long either way.

            let (mailer, name, addr, user) = (app.clone(), a.name().to_string(), a.email.clone(), a.username.clone());

            tokio::spawn(async move {

                if let Err(err) = crate::mail::send(&mailer, &name, &addr, "Reset your password", &body).await {

                    tracing::warn!("reset mail for {user}: {err}");

                }

            });

            accounts::audit(&app.db, Some(&a), "password.reset_requested", &a.username, "").await.ok();

        }

    }

    Ok(Page(RecoveryPage::new(&app, shell, "sent")))

}

async fn reset_target(app: &Shared, secret: &str) -> sqlx::Result<Option<(accounts::AccountLink, accounts::Account)>> {

    let Some(link) = accounts::live_link(&app.db, "reset", secret).await? else { return Ok(None) };

    let account = accounts::account_by_id(&app.db, link.account_id).await?;

    Ok(account.filter(|a| !a.banned).map(|a| (link, a)))

}

/// `GET /login/reset/{secret}`.

pub async fn new_password_form(State(app): State<Shared>, viewer: Viewer, Path(secret): Path<String>) -> Result<Page<RecoveryPage>, Error> {

    let shell = Shell::new(&app, "/login/reset", &viewer);

    match reset_target(&app, &secret).await.map_err(|e| Error::from_db(shell.clone(), e))? {

        Some((_, a)) => {

            let mut page = RecoveryPage::new(&app, shell, "new");

            page.username = a.username;

            page.secret = secret;

            Ok(Page(page))

        }

        None => Ok(Page(RecoveryPage::new(&app, shell, "invalid"))),

    }

}

#[derive(Deserialize)]

pub struct NewPasswordForm {

    password: String,

    confirm: String,

}

/// `POST /login/reset/{secret}`.

pub async fn set_new_password(

    State(app): State<Shared>,

    viewer: Viewer,

    Path(secret): Path<String>,

    Form(f): Form<NewPasswordForm>,

) -> Result<Response, Error> {

    let shell = Shell::new(&app, "/login/reset", &viewer);

    let e = |e| Error::from_db(shell.clone(), e);

    let Some((link, account)) = reset_target(&app, &secret).await.map_err(e)? else {

        return Ok(Page(RecoveryPage::new(&app, shell, "invalid")).into_response());

    };

    let problem = if f.password != f.confirm {

        Some("The two passwords differ.".to_string())

    } else {

        auth::password_ok(&f.password).err().map(String::from)

    };

    if let Some(msg) = problem {

        let mut page = RecoveryPage::new(&app, shell, "new");

        page.username = account.username;

        page.secret = secret;

        page.error = Some(msg);

        return Ok(Page(page).into_response());

    }

    if !accounts::use_link(&app.db, link.id).await.map_err(e)? {

        return Ok(Page(RecoveryPage::new(&app, shell, "invalid")).into_response());

    }

    let hash = auth::hash_password(&f.password).map_err(|err| Error::bad(shell.clone(), err.to_string()))?;

    // A new session salt ends every session; other reset links die with it.

    accounts::set_password(&app.db, account.id, &hash, &auth::random_hex(16)).await.map_err(e)?;

    accounts::void_links(&app.db, account.id, "reset").await.map_err(e)?;

    let by = if link.created_by.is_some() { "administrator's link" } else { "emailed link" };

    accounts::audit(&app.db, Some(&account), "password.reset", &account.username, by).await.ok();

    Ok(Redirect::to("/login?reset=1").into_response())

}

/// An administrator's reset link for an account (the admin page shows it once).

pub async fn admin_reset_link(app: &Shared, admin: &accounts::Account, target: &accounts::Account) -> sqlx::Result<String> {

    let secret = accounts::create_link(&app.db, target.id, "reset", "", Some(admin.id), ADMIN_RESET_TTL_MS).await?;

    accounts::audit(&app.db, Some(admin), "admin.account.reset_link", &target.username, "valid 24 hours").await.ok();

    Ok(format!("{}/login/reset/{secret}", app.config.base_url()))

}

//! Email verification and password reset (hub spec §5.1.1), with mail

//! written to a directory (`file://`) so the test reads what was sent.

use axum::body::Body;

use axum::http::{header, Request, StatusCode};

use http_body_util::BodyExt;

use oxygenhub::config::Config;

use oxygenhub::{db, Shared};

use std::path::{Path, PathBuf};

use tower::ServiceExt;

fn hermetic() {

    static ONCE: std::sync::Once = std::sync::Once::new();

    static DIR: std::sync::OnceLock<tempfile::TempDir> = std::sync::OnceLock::new();

    ONCE.call_once(|| {

        let d = tempfile::tempdir().unwrap();

        std::env::set_var("OXY_HOME", d.path());

        DIR.set(d).ok();

    });

}

struct Hub {

    app: Shared,

    mailbox: PathBuf,

    _dir: tempfile::TempDir,

}

async fn hub(mail: bool) -> Hub {

    hermetic();

    let dir = tempfile::tempdir().unwrap();

    let mailbox = dir.path().join("mailbox");

    std::fs::create_dir_all(&mailbox).unwrap();

    let mut config = Config::load(dir.path()).unwrap();

    config.server.base_url = "http://hub.test".into();

    config.registration.mode = "open".into();

    if mail {

        config.email.smtp = format!("file://{}", mailbox.display());

        config.email.from = "OxygenHub <[email protected]>".into();

    }

    let app = oxygenhub::build(config).await.unwrap();

    Hub { app, mailbox, _dir: dir }

}

struct Res {

    status: StatusCode,

    body: String,

    cookie: Option<String>,

    location: String,

}

async fn send(app: &Shared, method: &str, path: &str, cookie: Option<&str>, form: Option<&str>) -> Res {

    let mut req = Request::builder().method(method).uri(path);

    if let Some(c) = cookie {

        req = req.header(header::COOKIE, format!("oxyhub={c}"));

    }

    let body = match form {

        Some(f) => {

            req = req.header(header::CONTENT_TYPE, "application/x-www-form-urlencoded");

            Body::from(f.to_string())

        }

        None => Body::empty(),

    };

    let res = oxygenhub::router(app.clone()).oneshot(req.body(body).unwrap()).await.unwrap();

    let status = res.status();

    let h = |k| res.headers().get(k).and_then(|v: &axum::http::HeaderValue| v.to_str().ok()).map(String::from);

    let cookie = h(header::SET_COOKIE).and_then(|v| v.split(';').next().and_then(|kv| kv.split_once('=')).map(|(_, v)| v.to_string()));

    let location = h(header::LOCATION).unwrap_or_default();

    let bytes = res.into_body().collect().await.unwrap().to_bytes();

    Res { status, body: String::from_utf8_lossy(&bytes).into_owned(), cookie, location }

}

async fn get(app: &Shared, path: &str, cookie: Option<&str>) -> Res {

    send(app, "GET", path, cookie, None).await

}

async fn post(app: &Shared, path: &str, cookie: Option<&str>, form: &str) -> Res {

    send(app, "POST", path, cookie, Some(form)).await

}

fn csrf_of(page: &str) -> String {

    let i = page.find("name=\"_csrf\" value=\"").expect("csrf field") + "name=\"_csrf\" value=\"".len();

    page[i..].split('"').next().unwrap().to_string()

}

/// Every message so far, oldest first, as text.

fn mail(dir: &Path) -> Vec<String> {

    let mut names: Vec<_> = std::fs::read_dir(dir).unwrap().flatten().map(|e| e.path()).collect();

    names.sort();

    names.iter().map(|p| std::fs::read_to_string(p).unwrap()).collect()

}

/// Mail is sent in the background for resets; wait for `n` messages.

async fn mail_count(dir: &Path, n: usize) -> Vec<String> {

    for _ in 0..100 {

        let m = mail(dir);

        if m.len() >= n {

            return m;

        }

        tokio::time::sleep(std::time::Duration::from_millis(20)).await;

    }

    mail(dir)

}

/// The path of the first `http://hub.test/…` link in a message.

fn link(message: &str, prefix: &str) -> String {

    let i = message.find(&format!("http://hub.test{prefix}")).expect("a link") + "http://hub.test".len();

    message[i..].split_whitespace().next().unwrap().to_string()

}

async fn account(app: &Shared, name: &str) -> db::accounts::Account {

    db::accounts::account_by_name(&app.db, name).await.unwrap().unwrap()

}

#[tokio::test(flavor = "multi_thread")]

async fn verification_and_reset() {

    let h = hub(true).await;

    let app = &h.app;

    let r = post(app, "/register", None, "username=andy&email=andy%40example.com&password=correct-horse-battery").await;

    assert_eq!(r.status, StatusCode::SEE_OTHER, "{}", r.body);

    let old_session = r.cookie.unwrap();

    // Registration sends a verification link; until it is used, no reset mail.

    let m = mail(&h.mailbox);

    assert_eq!(m.len(), 1);

    assert!(m[0].contains("To: andy <[email protected]>") && m[0].contains("Subject: [OxygenHub] Confirm your email address"), "{}", m[0]);

    let verify = link(&m[0], "/verify/");

    assert!(!account(app, "andy").await.email_verified);

    let settings = get(app, "/settings", Some(&old_session)).await;

    assert!(settings.body.contains("Not verified yet") && settings.body.contains("send a new one"));

    let sent = post(app, "/login/reset", None, "who=andy").await;

    assert!(sent.body.contains("Check your email"));

    tokio::time::sleep(std::time::Duration::from_millis(200)).await;

    assert_eq!(mail(&h.mailbox).len(), 1, "no reset to an unverified address");

    // The link verifies once.

    assert!(get(app, &verify, None).await.body.contains("Email verified"));

    assert!(account(app, "andy").await.email_verified);

    assert!(get(app, &verify, None).await.body.contains("already used"), "single use");

    assert!(get(app, "/verify/00ff", None).await.body.contains("already used"));

    // Reset by verified email (any case); a second request within two minutes sends nothing.

    let unknown = post(app, "/login/reset", None, "who=nobody").await;

    let known = post(app, "/login/reset", None, "who=ANDY%40example.com").await;

    assert_eq!(unknown.body, known.body, "the answer does not reveal accounts");

    let m = mail_count(&h.mailbox, 2).await;

    assert_eq!(m.len(), 2);

    assert!(m[1].contains("Subject: [OxygenHub] Reset your password"));

    let reset = link(&m[1], "/login/reset/");

    post(app, "/login/reset", None, "who=andy").await;

    tokio::time::sleep(std::time::Duration::from_millis(200)).await;

    assert_eq!(mail(&h.mailbox).len(), 2, "rate limited");

    // Choosing the new password: checks, then every session ends.

    let form = get(app, &reset, None).await;

    assert!(form.body.contains("Choose a new password") && form.body.contains("andy"));

    let differ = post(app, &reset, None, "password=new-password-long-enough&confirm=other-password-long").await;

    assert!(differ.body.contains("The two passwords differ"));

    let weak = post(app, &reset, None, "password=short&confirm=short").await;

    assert!(weak.body.contains("class=\"error\""), "password rules apply");

    let done = post(app, &reset, None, "password=new-password-long-enough&confirm=new-password-long-enough").await;

    assert_eq!((done.status, done.location.as_str()), (StatusCode::SEE_OTHER, "/login?reset=1"));

    assert!(get(app, "/login?reset=1", None).await.body.contains("Your password is set"));

    assert!(get(app, &reset, None).await.body.contains("expired or was already used"), "single use");

    let stale = get(app, "/settings", Some(&old_session)).await;

    assert!(stale.status.is_redirection() || !stale.body.contains("name=\"_csrf\""), "the old session ended");

    let wrong = post(app, "/login", None, "username=andy&password=correct-horse-battery").await;

    assert!(wrong.body.contains("Wrong username or password"));

    let signed = post(app, "/login", None, "username=andy&password=new-password-long-enough").await;

    assert_eq!(signed.status, StatusCode::SEE_OTHER);

    let session = signed.cookie.unwrap();

    let audit = db::accounts::audit_rows(&app.db, 50).await.unwrap();

    assert!(audit.iter().any(|a| a.action == "password.reset" && a.detail == "emailed link"));

    // Changing the email unverifies it; only the link for the current address counts.

    let page = get(app, "/settings", Some(&session)).await;

    let csrf = csrf_of(&page.body);

    let save = |email: &'static str| {

        let csrf = csrf.clone();

        let session = session.clone();

        async move {

            post(app, "/settings", Some(&session), &format!("_csrf={csrf}&display_name=Andy&email={email}&bio=&website=&location=")).await

        }

    };

    let saved = save("b%40example.com").await;

    assert!(saved.body.contains("A verification link is on its way to [email protected]"), "{}", saved.body);

    assert!(!account(app, "andy").await.email_verified);

    let to_b = link(mail(&h.mailbox).last().unwrap(), "/verify/");

    save("c%40example.com").await;

    let to_c = link(mail(&h.mailbox).last().unwrap(), "/verify/");

    assert!(get(app, &to_b, None).await.body.contains("no longer has"), "an old address's link does nothing");

    assert!(!account(app, "andy").await.email_verified);

    assert!(get(app, &to_c, None).await.body.contains("Email verified"));

    assert_eq!(account(app, "andy").await.email, "[email protected]");

    // A second link to the same address within two minutes is refused.

    save("d%40example.com").await;

    let again = post(app, "/settings/email/verify", Some(&session), &format!("_csrf={csrf}")).await;

    assert!(again.body.contains("less than two minutes ago"), "{}", again.body);

    // An administrator's link, for an account without a verified email.

    post(app, "/register", None, "username=bob&email=&password=bob-password-long-enough").await;

    let admin = get(app, "/admin", Some(&session)).await;

    assert!(admin.body.contains("value=\"reset_link\""));

    let r = post(app, "/admin/account", Some(&session), &format!("_csrf={}&username=bob&action=reset_link", csrf_of(&admin.body))).await;

    assert!(r.body.contains("Reset link for bob"), "{}", r.body);

    let i = r.body.find("http://hub.test/login/reset/").unwrap() + "http://hub.test".len();

    let bob_link: String = r.body[i..].chars().take_while(|c| c.is_ascii_alphanumeric() || *c == '/').collect();

    assert_eq!(post(app, &bob_link, None, "password=bob-new-password-ok&confirm=bob-new-password-ok").await.location, "/login?reset=1");

    let audit = db::accounts::audit_rows(&app.db, 50).await.unwrap();

    assert!(audit.iter().any(|a| a.action == "admin.account.reset_link" && a.target == "bob"));

    assert!(audit.iter().any(|a| a.action == "password.reset" && a.target == "bob" && a.detail == "administrator's link"));

}

#[tokio::test(flavor = "multi_thread")]

async fn without_mail_an_administrator_resets() {

    let h = hub(false).await;

    let page = get(&h.app, "/login/reset", None).await;

    assert!(page.body.contains("does not send email") && !page.body.contains("SEND A RESET LINK"));

    let sent = post(&h.app, "/login/reset", None, "who=andy").await;

    assert!(!sent.body.contains("Check your email"));

    assert!(get(&h.app, "/login", None).await.body.contains("href=\"/login/reset\""));

}

{% extends "base.html" %}

{% block title %}{% if mode == "verified" || mode == "verify-invalid" %}Email address{% else %}Reset your password{% endif %}{% endblock %}

{% block content %}

{% if mode == "verified" %}

<div class="head"><h1>Email verified</h1></div>

<p class="note"><strong>{{ username }}</strong> is confirmed. Notification email can go there now.</p>

<p><a href="/settings">Settings</a></p>

{% else if mode == "verify-invalid" %}

<div class="head"><h1>Email address</h1></div>

<p class="error">This verification link has expired, was already used, or is for an address the account no longer has.</p>

<p>Send a new one from <a href="/settings">Settings</a>.</p>

{% else if mode == "request" %}

<div class="head"><h1>Reset your password</h1></div>

{% if mail %}

<form class="card" method="post" action="/login/reset">

  <label for="who">Username or verified email</label><input type="text" id="who" name="who" autocomplete="username" autofocus required>

  <button type="submit">SEND A RESET LINK</button>

</form>

<p class="small mute">The link goes to the account's verified email and works once, for one hour.</p>

{% else %}

<p>This hub does not send email. Ask an administrator for a reset link: they can issue one from the admin page, valid for 24 hours.</p>

{% endif %}

<p class="small mute"><a href="/login">Back to sign in</a></p>

{% else if mode == "sent" %}

<div class="head"><h1>Check your email</h1></div>

<p>If that matches an account with a verified email, a reset link is on its way. It works once, for one hour.</p>

<p class="small mute">Nothing arriving? The account may have no verified email; an administrator can issue a reset link instead.</p>

{% else if mode == "new" %}

<div class="head"><h1>Choose a new password <small>{{ username }}</small></h1></div>

{% if let Some(e) = error %}<p class="error">{{ e }}</p>{% endif %}

<form class="card" method="post" action="/login/reset/{{ secret }}">

  <input type="text" name="username" value="{{ username }}" autocomplete="username" hidden>

  <label for="password">New password</label><input type="password" id="password" name="password" autocomplete="new-password" required autofocus>

  <label for="confirm">The same again</label><input type="password" id="confirm" name="confirm" autocomplete="new-password" required>

  <button type="submit">SET PASSWORD</button>

</form>

<p class="small mute">Every session of this account is signed out. Two-factor sign-in stays on if you use it.</p>

{% else %}

<div class="head"><h1>Reset your password</h1></div>

<p class="error">This reset link has expired or was already used.</p>

<p><a href="/login/reset">Ask for a new one</a></p>

{% endif %}

{% endblock %}

    // A changed address is unverified until its own link is used.

    sqlx::query(

        "UPDATE accounts SET display_name = ?, email_verified = CASE WHEN email = ? THEN email_verified ELSE 0 END, email = ? WHERE id = ?",

    )

    .bind(display_name)

    .bind(email)

    .bind(email)

    .bind(id)

    .execute(pool)

    .await?;

}

// ------------------------------------------------------ account links

/// A verification or reset link (hub spec §5.1.1).

#[derive(Clone, Debug, FromRow)]

pub struct AccountLink {

    pub id: i64,

    pub account_id: i64,

    pub kind: String,

    pub hash: String,

    pub email: String,

    pub created_by: Option<i64>,

    pub created_ms: i64,

    pub expires_ms: i64,

    pub used_ms: Option<i64>,

}

/// Make a link; returns its secret (shown or sent once, stored as a hash).

pub async fn create_link(

    pool: &Pool,

    account_id: i64,

    kind: &str,

    email: &str,

    created_by: Option<i64>,

    ttl_ms: i64,

) -> sqlx::Result<String> {

    let secret = crate::auth::random_hex(32);

    let now = now_ms();

    sqlx::query(

        "INSERT INTO account_links (account_id, kind, hash, email, created_by, created_ms, expires_ms) VALUES (?, ?, ?, ?, ?, ?, ?)",

    )

    .bind(account_id)

    .bind(kind)

    .bind(crate::auth::token_hash(&secret))

    .bind(email)

    .bind(created_by)

    .bind(now)

    .bind(now + ttl_ms)

    .execute(pool)

    .await?;

    Ok(secret)

}

/// An unused, unexpired link of this kind with this secret.

pub async fn live_link(pool: &Pool, kind: &str, secret: &str) -> sqlx::Result<Option<AccountLink>> {

    sqlx::query_as("SELECT * FROM account_links WHERE kind = ? AND hash = ? AND used_ms IS NULL AND expires_ms > ?")

        .bind(kind)

        .bind(crate::auth::token_hash(secret))

        .bind(now_ms())

        .fetch_optional(pool)

        .await

}

/// Consume a link; false when it was already used (a race lost).

pub async fn use_link(pool: &Pool, id: i64) -> sqlx::Result<bool> {

    let r =

        sqlx::query("UPDATE account_links SET used_ms = ? WHERE id = ? AND used_ms IS NULL").bind(now_ms()).bind(id).execute(pool).await?;

    Ok(r.rows_affected() == 1)

}

/// Void every unused link of a kind for an account.

pub async fn void_links(pool: &Pool, account_id: i64, kind: &str) -> sqlx::Result<()> {

    sqlx::query("UPDATE account_links SET used_ms = ? WHERE account_id = ? AND kind = ? AND used_ms IS NULL")

        .bind(now_ms())

        .bind(account_id)

        .bind(kind)

        .execute(pool)

        .await?;

    Ok(())

}

/// When the account's newest link of a kind (for this address, when given) was made, for rate limits.

pub async fn last_link_ms(pool: &Pool, account_id: i64, kind: &str, email: Option<&str>) -> sqlx::Result<Option<i64>> {

    match email {

        Some(e) => {

            sqlx::query_scalar("SELECT MAX(created_ms) FROM account_links WHERE account_id = ? AND kind = ? AND email = ?")

                .bind(account_id)

                .bind(kind)

                .bind(e)

                .fetch_one(pool)

                .await

        }

        None => {

            sqlx::query_scalar("SELECT MAX(created_ms) FROM account_links WHERE account_id = ? AND kind = ?")

                .bind(account_id)

                .bind(kind)

                .fetch_one(pool)

                .await

        }

    }

}

/// How many links of a kind the account got since `since_ms`.

pub async fn links_since(pool: &Pool, account_id: i64, kind: &str, since_ms: i64) -> sqlx::Result<i64> {

    sqlx::query_scalar("SELECT COUNT(*) FROM account_links WHERE account_id = ? AND kind = ? AND created_ms >= ?")

        .bind(account_id)

        .bind(kind)

        .bind(since_ms)

        .fetch_one(pool)

        .await

}

pub async fn set_email_verified(pool: &Pool, id: i64, verified: bool) -> sqlx::Result<()> {

    sqlx::query("UPDATE accounts SET email_verified = ? WHERE id = ?").bind(verified).bind(id).execute(pool).await?;

    Ok(())

}

/// The account with this verified email (case-insensitive), if exactly one.

pub async fn account_by_verified_email(pool: &Pool, email: &str) -> sqlx::Result<Option<Account>> {

    let found: Vec<Account> = sqlx::query_as("SELECT * FROM accounts WHERE email_verified = 1 AND lower(email) = lower(?) LIMIT 2")

        .bind(email)

        .fetch_all(pool)

        .await?;

    Ok(if found.len() == 1 { found.into_iter().next() } else { None })

pub mod mail;

            // Only to addresses the account has proven it reads (hub spec §5.1.1).

            if a.email_notifications && a.email_verified && !a.email.is_empty() && crate::mail::enabled(app) {

    if let Err(e) = crate::mail::send(app, to.name(), &to.email, title, &body).await {

    if f.action == "reset_link" {

        if target.banned {

            return admin_page(&app, shell, Some("A banned account cannot be reset.".into())).await;

        }

        let url = super::recovery::admin_reset_link(&app, &me, &target).await.map_err(e)?;

        return admin_page(

            &app,

            shell,

            Some(format!("Reset link for {} (works once, for 24 hours; shown only now): {url}", target.username)),

        )

        .await;

    }

mod recovery;

        .route("/login/reset", get(recovery::request_form).post(recovery::request))

        .route("/login/reset/{secret}", get(recovery::new_password_form).post(recovery::set_new_password))

        .route("/verify/{secret}", get(recovery::verify))

        .route("/settings/email/verify", post(settings::resend_verification))

    /// Arrived from a password reset.

    reset: bool,

    reset: Option<String>,

    let reset = q.reset.is_some();

    Page(LoginPage { shell: Shell::new(&app, "/login", &viewer), error: None, next: safe_next(q.next), totp_for: None, reset })

        .into_response()

        Page(LoginPage { shell: shell.clone(), error: Some(msg.into()), next: next.clone(), totp_for, reset: false }).into_response()

    if let Err(e) = super::recovery::send_verification(&app, &account).await {

        tracing::info!("verification for {username}: {e}");

    }

    /// Whether the hub sends mail, for the "send a new link" button.

    mail: bool,

        SettingsPage { shell, me, notice: None, error: None, theme: theme_of(headers), themes: THEMES, mail: false }

    fn with_mail(mut self, app: &Shared) -> Self {

        self.mail = crate::mail::enabled(app);

        self

    }

    Ok(Page(SettingsPage::new(shell, me.account, &headers).with_mail(&app)))

}

/// `POST /settings/email/verify`: send a new verification link.

pub async fn resend_verification(

    State(app): State<Shared>,

    viewer: Viewer,

    headers: HeaderMap,

    Form(f): Form<super::session::CsrfForm>,

) -> Result<Page<SettingsPage>, Error> {

    let shell = Shell::new(&app, "/settings", &viewer);

    let me = require(&viewer, &shell)?;

    csrf(&viewer, &f.csrf, &shell)?;

    let page = SettingsPage::new(shell, me.account.clone(), &headers).with_mail(&app);

    Ok(Page(match super::recovery::send_verification(&app, &me.account).await {

        Ok(()) if me.account.email_verified => page.notice("Your email is already verified."),

        Ok(()) => page.notice(format!("A verification link is on its way to {}.", me.account.email)),

        Err(e) => page.error(e),

    }))

        return Ok(Page(

            SettingsPage::new(shell, me.account, &headers).with_mail(&app).error("The website must be an http:// or https:// address."),

        ));

    let changed = me.account.email != f.email.trim();

    let mut notice = "Profile saved.".to_string();

    if changed && !updated.email.is_empty() {

        accounts::audit(&app.db, Some(&updated), "email.changed", &updated.username, "").await.ok();

        match super::recovery::send_verification(&app, &updated).await {

            Ok(()) => notice = format!("Profile saved. A verification link is on its way to {}.", updated.email),

            Err(e) => notice = format!("Profile saved. {e}"),

        }

    }

    Ok(Page(SettingsPage::new(shell, updated, &headers).with_mail(&app).notice(notice)))

        return Ok(

            Page(SettingsPage::new(shell, me.account, &headers).with_mail(&app).error("Your current password is wrong.")).into_response()

        );

        return Ok(Page(SettingsPage::new(shell, me.account, &headers).with_mail(&app).error(e)).into_response());

#### 5.1.1 Email verification and password reset

Both use **account links**: 32 random bytes as hex in a URL, stored only as their BLAKE3 hash, bound to one account and one purpose, expiring, and consumed on first use.

- **Verification.** Setting or changing an email marks it unverified. When the hub can send mail it sends a link to the new address (valid 48 hours). The link verifies that exact address: one sent to an address the account has since replaced does nothing. The settings page shows whether the email is verified and can send a new link: at most one every two minutes for the same address, and ten an hour per account whatever the addresses, so the form cannot be used to mail other people. Notification email goes only to verified addresses.

- **Reset by email.** `/login/reset` takes a username or a verified email. When it matches an active account with a verified email and the hub can send mail, a link valid for one hour goes to that address, at most one every two minutes per account. The page answers the same way whether or not anything matched, so it cannot be used to find accounts.

- **Reset by an administrator.** When the hub cannot send mail, or the account has no verified email, an administrator issues a reset link from the admin page (valid 24 hours), shown once to hand over by other means. The audit log records who issued it.

- **Using a reset link** sets a new password (the same rules as registration), rotates the session salt so every existing session ends, voids the account's other reset links, and records `password.reset` in the audit log. It does not turn off TOTP: a reset account with two-factor sign-in still needs its code. A banned account cannot be reset.

- **Mail.** `[email] smtp` is an `smtp://` or `smtps://` URL, or `file:///path` for development, which writes each message to that directory as a file instead of sending it.

  <tr><td><a href="/{{ a.username }}">{{ a.username }}</a></td><td>{{ a.email }}{% if !a.email.is_empty() %} <span class="small mute" title="{% if a.email_verified %}verified{% else %}not verified{% endif %}">{% if a.email_verified %}✔{% else %}○{% endif %}</span>{% endif %}</td><td>{% if a.is_admin %}<span class="tag">admin</span>{% endif %}{% if a.banned %} <span class="tag bad">banned</span>{% endif %}{% if a.totp_enabled() %} <span class="tag">2fa</span>{% endif %}</td>

    {% if a.is_admin %}<button name="action" value="demote">demote</button>{% else %}<button name="action" value="promote">make admin</button>{% endif %}

    {% if !a.banned %}<button name="action" value="reset_link" title="A one-time password reset link to hand over">reset link</button>{% endif %}</form></td></tr>

{% if reset %}<p class="note">Your password is set. Sign in with it; every other session was signed out.</p>{% endif %}

<p class="small mute"><a href="/login/reset">Forgot your password?</a> · No account? <a href="/register">Register</a>.</p>

<form id="verify-email" method="post" action="/settings/email/verify" hidden><input type="hidden" name="_csrf" value="{{ shell.csrf }}"></form>

  <p class="small mute">Your email is never shown on your profile. {% if me.email.is_empty() %}Add one to receive notification email and reset your password by email.{% else if me.email_verified %}<span class="sig sig-valid">✔</span> Verified.{% else %}<span class="sig sig-unsigned">○</span> Not verified yet{% if mail %}: use the link we sent, or <button type="submit" form="verify-email" class="linkish">send a new one</button>{% endif %}.{% endif %}</p>

button.linkish { background: none; border: 0; padding: 0; margin: 0; color: var(--acc); font: inherit; cursor: pointer; text-transform: none; letter-spacing: normal; }

button.linkish:hover { text-decoration: underline; }