tfa: add api::methods::unlock_tfa

This mostly serves as documentation for the API call to be
implemented across our products. It's otherwise already just
a oneliner on the TfaConfig.

Signed-off-by: Wolfgang Bumiller <w.bumiller@proxmox.com>

proxmox-tfa/src/api/methods.rs

@@ -179,6 +179,21 @@ pub fn delete_tfa(config: &mut TfaConfig, userid: &str, id: &str) -> Result<bool
     }
 }
 
+/// API call implementation for `PUT /users/{userid}/unlock-tfa`.
+///
+/// This should only be allowed for user administrators.
+///
+/// The TFA config must be WRITE locked.
+///
+/// The caller must *save* the config if `true` is returned!
+///
+/// Errors only if the user was not found.
+///
+/// Returns `true` if the user was previously locked out, `false` if nothing was changed.
+pub fn unlock_tfa(config: &mut TfaConfig, userid: &str) -> Result<bool, Error> {
+    config.unlock_tfa(userid)
+}
+
 #[cfg_attr(feature = "api-types", api(
     properties: {
         "entries": {

proxmox-tfa/src/api/mod.rs

@@ -144,14 +144,16 @@ fn check_webauthn<'a, 'config: 'a, 'origin: 'a>(
 
 impl TfaConfig {
     /// Unlock a user's 2nd factor authentication (including TOTP).
-    pub fn unlock_tfa(&mut self, userid: &str) -> Result<(), Error> {
+    /// Returns whether the user was locked before calling this method.
+    pub fn unlock_tfa(&mut self, userid: &str) -> Result<bool, Error> {
         match self.users.get_mut(userid) {
             Some(user) => {
+                let ret = user.totp_locked || user.tfa_is_locked();
                 user.totp_locked = false;
                 user.tfa_locked_until = None;
-                Ok(())
+                Ok(ret)
             }
-            None => bail!("no such challenge"),
+            None => bail!("no such user"),
         }
     }