TOTP google authenticator implemented properly well

src/models/_entities/users.rs

@@ -26,6 +26,9 @@ pub struct Model {
     pub magic_link_expiration: Option<DateTimeWithTimeZone>,
     pub theme: String,
     pub account_type: String,
+    pub totp_secret: Option<String>,
+    pub totp_enabled_at: Option<DateTimeWithTimeZone>,
+    pub totp_backup_codes: Option<String>,
 }
 
 #[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]

src/models/users.rs

@@ -5,6 +5,7 @@ use loco_rs::{auth::jwt, hash, prelude::*};
 use passwords::PasswordGenerator;
 use serde::{Deserialize, Serialize};
 use serde_json::Map;
+use totp_rs::{Algorithm, Secret, TOTP};
 use uuid::Uuid;
 
 use crate::models::_entities::o_auth2_sessions;
@@ -16,6 +17,45 @@ pub const MAGIC_LINK_EXPIRATION_MIN: i8 = 5;
 /// Minimum gap between verification-email resends for one account, in seconds.
 pub const VERIFICATION_RESEND_COOLDOWN_SECS: i64 = 60;
 
+// TODO(security): `users.totp_secret` is stored as a PLAINTEXT base32 string.
+// Unlike `password` (a one-way hash) the TOTP secret must be kept in reversible
+// form — the server needs the original value to recompute codes — so it is
+// effectively password-equivalent: anyone who can read this column can mint
+// valid 2FA codes for that user. It is deliberately left in plaintext for now
+// and treated like the app's other server-side secrets (e.g. the SMTP password,
+// kept out of the DB entirely). When secrets get a proper at-rest story, encrypt
+// this column with a key held OUTSIDE the database (env / `pass`), decrypting
+// only in memory. The single read/write site is `build_totp` +
+// `begin_totp_enrollment` below; `totp_backup_codes` are already hashed and need
+// no change. Grep `TODO(security)` to find this.
+
+/// TOTP (Google Authenticator) parameters. These are the values Google
+/// Authenticator assumes; it ignores anything else encoded in the otpauth URL,
+/// so they must stay SHA1 / 6 digits / 30s or codes won't match.
+const TOTP_ISSUER: &str = "Kompress";
+const TOTP_DIGITS: usize = 6;
+/// Accept codes ±1 time-step (~30s) to tolerate client/server clock drift.
+const TOTP_SKEW: u8 = 1;
+const TOTP_STEP: u64 = 30;
+/// Number of one-time recovery codes generated when 2FA is enabled.
+pub const TOTP_BACKUP_CODE_COUNT: usize = 8;
+
+/// Build a [`TOTP`] from a stored base32 secret and the account label (email).
+/// Returns `None` if the secret can't be decoded.
+fn build_totp(secret_base32: &str, account: &str) -> Option<TOTP> {
+    let bytes = Secret::Encoded(secret_base32.to_string()).to_bytes().ok()?;
+    TOTP::new(
+        Algorithm::SHA1,
+        TOTP_DIGITS,
+        TOTP_SKEW,
+        TOTP_STEP,
+        bytes,
+        Some(TOTP_ISSUER.to_string()),
+        account.to_string(),
+    )
+    .ok()
+}
+
 #[derive(Debug, Deserialize, Serialize)]
 pub struct LoginParams {
     pub email: String,
@@ -241,6 +281,68 @@ impl Model {
         self.account_type == "company"
     }
 
+    /// Whether two-factor auth is active for this account. This is the single
+    /// source of truth used by the login flow: a secret may be present during a
+    /// half-finished enrollment, but 2FA only gates login once it is *confirmed*
+    /// (which is what sets `totp_enabled_at`).
+    #[must_use]
+    pub fn totp_enabled(&self) -> bool {
+        self.totp_enabled_at.is_some()
+    }
+
+    /// Build the [`TOTP`] for this user from its stored secret, if any.
+    fn totp(&self) -> Option<TOTP> {
+        let secret = self.totp_secret.as_deref()?;
+        build_totp(secret, &self.email)
+    }
+
+    /// A `data:image/png;base64,...` QR for the *pending* secret plus the secret
+    /// itself (shown as a manual-entry fallback). Used on the enrollment page.
+    /// Returns `None` if no secret is staged or QR rendering fails.
+    #[must_use]
+    pub fn totp_provisioning(&self) -> Option<(String, String)> {
+        let totp = self.totp()?;
+        let qr = totp.get_qr_base64().ok()?;
+        Some((
+            format!("data:image/png;base64,{qr}"),
+            self.totp_secret.clone()?,
+        ))
+    }
+
+    /// Verify a 6-digit authenticator code against the stored secret. Returns
+    /// false if no secret is staged or the code is wrong. Works both during
+    /// enrollment confirmation and at login.
+    #[must_use]
+    pub fn verify_totp_code(&self, code: &str) -> bool {
+        let code = code.trim().replace(' ', "");
+        self.totp()
+            .and_then(|t| t.check_current(&code).ok())
+            .unwrap_or(false)
+    }
+
+    /// Whether `code` matches one of the still-unused backup codes.
+    #[must_use]
+    pub fn matches_backup_code(&self, code: &str) -> bool {
+        let code = code.trim().replace([' ', '-'], "");
+        self.backup_code_hashes()
+            .iter()
+            .any(|h| hash::verify_password(&code, h))
+    }
+
+    /// The stored hashed backup codes (empty if none).
+    fn backup_code_hashes(&self) -> Vec<String> {
+        self.totp_backup_codes
+            .as_deref()
+            .and_then(|s| serde_json::from_str::<Vec<String>>(s).ok())
+            .unwrap_or_default()
+    }
+
+    /// How many unused backup codes remain.
+    #[must_use]
+    pub fn backup_codes_remaining(&self) -> usize {
+        self.backup_code_hashes().len()
+    }
+
     /// Seconds the user must still wait before another verification email may be
     /// sent — 0 means a resend is allowed now. Throttling resends off the last
     /// `email_verification_sent_at` keeps the endpoint from being an easy way to
@@ -446,6 +548,96 @@ impl ActiveModel {
         self.magic_link_expiration = ActiveValue::set(None);
         self.update(db).await.map_err(ModelError::from)
     }
+
+    /// Stage a fresh TOTP secret for enrollment. This does **not** turn 2FA on —
+    /// `totp_enabled_at` stays null until the user proves they scanned it by
+    /// confirming a code (see [`Self::enable_totp`]). Any previously staged
+    /// secret/backup codes are discarded so re-enrolling always starts clean.
+    pub async fn begin_totp_enrollment(mut self, db: &DatabaseConnection) -> ModelResult<Model> {
+        let secret = match Secret::generate_secret().to_encoded() {
+            Secret::Encoded(s) => s,
+            // generate_secret() always yields raw bytes that encode cleanly.
+            Secret::Raw(_) => unreachable!("to_encoded() returns Encoded"),
+        };
+        self.totp_secret = ActiveValue::set(Some(secret));
+        self.totp_enabled_at = ActiveValue::set(None);
+        self.totp_backup_codes = ActiveValue::set(None);
+        self.update(db).await.map_err(ModelError::from)
+    }
+
+    /// Confirm enrollment and switch 2FA on. The caller must have already
+    /// verified a code against the staged secret. Generates and stores hashed
+    /// one-time backup codes and returns the plaintext codes to display **once**.
+    pub async fn enable_totp(
+        mut self,
+        db: &DatabaseConnection,
+    ) -> ModelResult<(Model, Vec<String>)> {
+        let (plain, hashes) = generate_backup_codes()?;
+        let encoded = serde_json::to_string(&hashes).map_err(|e| ModelError::Any(e.into()))?;
+        self.totp_enabled_at = ActiveValue::set(Some(Local::now().into()));
+        self.totp_backup_codes = ActiveValue::set(Some(encoded));
+        let model = self.update(db).await.map_err(ModelError::from)?;
+        Ok((model, plain))
+    }
+
+    /// Turn 2FA off and wipe all TOTP state. Callers gate this behind a fresh
+    /// confirmation (password or a current code).
+    pub async fn disable_totp(mut self, db: &DatabaseConnection) -> ModelResult<Model> {
+        self.totp_secret = ActiveValue::set(None);
+        self.totp_enabled_at = ActiveValue::set(None);
+        self.totp_backup_codes = ActiveValue::set(None);
+        self.update(db).await.map_err(ModelError::from)
+    }
+
+    /// Remove a used backup code from the stored set so it can't be reused.
+    /// `code` is matched against the remaining hashes; a no-op if it doesn't
+    /// match (the caller decides whether a match was required).
+    pub async fn consume_backup_code(
+        mut self,
+        db: &DatabaseConnection,
+        code: &str,
+    ) -> ModelResult<Model> {
+        let code = code.trim().replace([' ', '-'], "");
+        let current: Vec<String> = match self.totp_backup_codes.as_ref() {
+            Some(s) => serde_json::from_str(s.as_str()).unwrap_or_default(),
+            None => Vec::new(),
+        };
+        let remaining: Vec<String> = current
+            .into_iter()
+            .filter(|h| !hash::verify_password(&code, h))
+            .collect();
+        let encoded = serde_json::to_string(&remaining).map_err(|e| ModelError::Any(e.into()))?;
+        self.totp_backup_codes = ActiveValue::set(Some(encoded));
+        self.update(db).await.map_err(ModelError::from)
+    }
+
+    /// Replace the backup codes with a fresh set (e.g. after the user used some).
+    /// Only meaningful while 2FA is enabled; returns the new plaintext codes.
+    pub async fn regenerate_backup_codes(
+        mut self,
+        db: &DatabaseConnection,
+    ) -> ModelResult<(Model, Vec<String>)> {
+        let (plain, hashes) = generate_backup_codes()?;
+        let encoded = serde_json::to_string(&hashes).map_err(|e| ModelError::Any(e.into()))?;
+        self.totp_backup_codes = ActiveValue::set(Some(encoded));
+        let model = self.update(db).await.map_err(ModelError::from)?;
+        Ok((model, plain))
+    }
+}
+
+/// Generate `TOTP_BACKUP_CODE_COUNT` recovery codes, returning
+/// `(plaintext, hashes)`. Only the hashes are persisted; the plaintext is shown
+/// to the user once and never stored.
+fn generate_backup_codes() -> ModelResult<(Vec<String>, Vec<String>)> {
+    let mut plain = Vec::with_capacity(TOTP_BACKUP_CODE_COUNT);
+    let mut hashes = Vec::with_capacity(TOTP_BACKUP_CODE_COUNT);
+    for _ in 0..TOTP_BACKUP_CODE_COUNT {
+        let code = hash::random_string(10).to_lowercase();
+        let hashed = hash::hash_password(&code).map_err(|e| ModelError::Any(e.into()))?;
+        plain.push(code);
+        hashes.push(hashed);
+    }
+    Ok((plain, hashes))
 }
 
 /// Google OpenID Connect user profile (the fields our scopes request).