Merge pull request #14 from Spacecraft-Software/apikey-auth

feat(vault): Bitwarden personal API-key auth (2FA accounts)

Author: UnbreakableMJ

CHANGELOG.md

@@ -10,6 +10,38 @@ range may break in any release.
 
 ### Added
 
+- **Bitwarden personal API-key authentication (2FA accounts).** A new auth path
+  that uses the OAuth2 `client_credentials` grant, which is *not* 2FA-challenged
+  — so an account with two-factor auth enabled can finally authenticate without
+  an interactive TOTP prompt (Vault has no TOTP entry). The API key authenticates
+  the *session* only; the `Key` it returns is still wrapped under the stretched
+  master key, so **the master password is still required at every unlock** to
+  decrypt the vault.
+  - `vault login --api-key`: reads `$BW_CLIENTID` / `$BW_CLIENTSECRET` (matching
+    the official `bw` CLI), else prompts, then reads the master password. On
+    success the agent authenticates via `client_credentials` and **persists the
+    key** (0600 `apikey.json` in the account data dir) so plain `vault unlock`
+    (and the TUI unlock) auto-reuse it — no 2FA, no re-supplying creds.
+  - `vault apikey status` / `vault apikey forget` manage the stored key (status
+    echoes only the non-secret `client_id`; forget falls back to the password
+    grant).
+  - `vault-api`: `BitwardenClient::login_api_key` (`grant_type=client_credentials`,
+    `scope=api`). `vault-store`: `ApiKeyCreds` + `save`/`load`/`delete_apikey_to_dir`
+    (atomic, 0600, custom `Debug` that redacts the secret). `vault-ipc`: optional
+    `api_key` on `Request::Unlock` (serde-defaulted, forward-compatible) plus
+    `ApiKeyStatus` / `ApiKeyForget` verbs and an `ApiKeyStatus` response (never
+    carries the secret). `vault-agent`: grant selection (request creds → persisted
+    key → password) with persistence on enrollment, and `ensure_online` now falls
+    back to API-key re-auth — so a PIN/offline session of an API-key account can
+    still go online for `sync`/edits even when the grant issued no refresh token.
+  - The key is protected at rest by filesystem permissions (0600) only: it must
+    be readable *before* unlock (it's used during auth), so it can't be wrapped
+    under the user key — the same trust level as the stored refresh token.
+  - Tests: `vault-api` wiremock for the `client_credentials` form + a bad-key
+    `ServerStatus`; `vault-store` round-trip / delete / `NotFound` / 0600-mode /
+    Debug-redaction units; `vault-ipc` transport round-trips (`api_key` present
+    + absent-decodes-to-`None`, `ApiKeyStatus`). No new external dependencies.
+
 - **TUI in-place unlock.** When the agent is locked, `vault-tui` no longer
   dead-ends at a "run `vault unlock`" banner — it shows an interactive unlock
   prompt for the registered account: type the master password, or `Tab` to a

README.md

@@ -82,6 +82,35 @@ stored token (no master password needed); only a genuinely offline box stays
 read-only. Five wrong PINs disable the PIN and require a master-password unlock
 — bounding brute-force of a short secret.
 
+### API-key login (2FA accounts)
+
+If your account has two-factor auth enabled, the password grant is rejected
+with a 2FA challenge that Vault can't answer interactively. Generate a
+**personal API key** in the web vault (Settings → Security → Keys → *View API
+Key*) and log in with it — the `client_credentials` grant skips the 2FA prompt:
+
+```sh
+BW_CLIENTID=user.xxxx BW_CLIENTSECRET=… vault login --api-key
+# or, interactively (prompts for client_id / client_secret), then:
+#   Master password: …
+```
+
+The API key authenticates the *session* only — **you still enter your master
+password** to decrypt the vault; the key just gets you past 2FA. On success the
+agent stores the key (`apikey.json`, `0600`, in the account data dir), so plain
+`vault unlock` and the TUI unlock reuse it automatically — no further 2FA, no
+re-entering the key. A stored key also lets a PIN/offline session go back online
+for `sync` and edits.
+
+```sh
+vault apikey status      # configured? (shows the non-secret client_id)
+vault apikey forget      # delete the stored key; logins revert to the password grant
+```
+
+The key is protected at rest by filesystem permissions (`0600`) only: it must
+be usable *before* the vault is unlocked, so it can't be encrypted under your
+key — the same trust level as the stored refresh token or an SSH private key.
+
 ## Configuration
 
 Persistent settings live at `$XDG_CONFIG_HOME/vault/config.toml`, managed with

crates/vault-agent/src/server.rs

@@ -81,11 +81,19 @@ async fn dispatch(req: Request, state: &Arc<Mutex<AgentState>>) -> Response {
             email,
             password,
             device_id,
+            api_key,
         } => {
             // Wrap the password so it is zeroised on drop no matter how
             // perform_unlock fares; deref coercion hands it to the API as &[u8].
             let password = zeroize::Zeroizing::new(password);
-            let unlock_res = perform_unlock(&server, &email, &password, device_id.as_deref()).await;
+            let unlock_res = perform_unlock(
+                &server,
+                &email,
+                &password,
+                device_id.as_deref(),
+                api_key.as_ref(),
+            )
+            .await;
             match unlock_res {
                 Ok(vault) => {
                     let mut s = state.lock().await;
@@ -130,6 +138,15 @@ async fn dispatch(req: Request, state: &Arc<Mutex<AgentState>>) -> Response {
         Request::PinStatus { server, email } => {
             Response::PinStatus(crate::unlock::pin_status(&server, &email))
         }
+        Request::ApiKeyStatus { server, email } => {
+            Response::ApiKeyStatus(crate::unlock::apikey_status(&server, &email))
+        }
+        Request::ApiKeyForget { server, email } => {
+            match crate::unlock::apikey_forget(&server, &email) {
+                Ok(()) => Response::Ok,
+                Err(e) => Response::Error(e),
+            }
+        }
         Request::Lock => {
             let mut s = state.lock().await;
             s.lock();

crates/vault-agent/src/state.rs

@@ -100,28 +100,53 @@ impl Vault {
         if self.client.is_some() {
             return Ok(());
         }
-        let Some(refresh) = self.refresh_token.as_ref() else {
-            return Err(IpcError::Offline);
-        };
         let urls = vault_api::BaseUrls::self_hosted(&self.server)
             .map_err(|e| IpcError::Internal(e.to_string()))?;
         let device =
             uuid::Uuid::parse_str(&self.device_id).unwrap_or_else(|_| uuid::Uuid::new_v4());
-        let mut client = vault_api::BitwardenClient::with_refresh_token(
-            urls,
-            device,
-            "vault-agent",
-            rt_string(refresh),
-        )
-        .map_err(|e| IpcError::Internal(e.to_string()))?;
-        // A failed refresh (network down, or token revoked) → stay offline.
-        client.refresh().await.map_err(|_| IpcError::Offline)?;
-        // Keep the (possibly rotated) refresh token in memory for re-persist.
-        if let Some(rt) = client.refresh_token() {
-            self.refresh_token = Some(Zeroizing::new(rt.to_owned()));
+
+        // 1. Prefer the stored refresh token — cheapest, no creds re-sent.
+        if let Some(refresh) = self.refresh_token.as_ref()
+            && let Ok(mut client) = vault_api::BitwardenClient::with_refresh_token(
+                urls.clone(),
+                device,
+                "vault-agent",
+                rt_string(refresh),
+            )
+            && client.refresh().await.is_ok()
+        {
+            // Keep the (possibly rotated) refresh token in memory for re-persist.
+            if let Some(rt) = client.refresh_token() {
+                self.refresh_token = Some(Zeroizing::new(rt.to_owned()));
+            }
+            self.client = Some(client);
+            return Ok(());
         }
-        self.client = Some(client);
-        Ok(())
+
+        // 2. Fall back to a stored API key: the client_credentials grant
+        //    re-authenticates without 2FA or a refresh token, and needs only a
+        //    live client (the user key is already in memory). This is what lets
+        //    a PIN/offline session of an API-key account go online for writes.
+        if let Some(dir) = vault_store::default_data_dir()
+            .map(|d| d.join(account_dir_name(&self.server, &self.email)))
+            && let Ok(creds) = vault_store::load_apikey_from_dir(&dir)
+        {
+            let mut client = vault_api::BitwardenClient::new(urls, device, "vault-agent")
+                .map_err(|e| IpcError::Internal(e.to_string()))?;
+            if client
+                .login_api_key(&creds.client_id, creds.client_secret.as_bytes())
+                .await
+                .is_ok()
+            {
+                if let Some(rt) = client.refresh_token() {
+                    self.refresh_token = Some(Zeroizing::new(rt.to_owned()));
+                }
+                self.client = Some(client);
+                return Ok(());
+            }
+        }
+
+        Err(IpcError::Offline)
     }
 }
 

crates/vault-agent/src/unlock.rs

@@ -7,10 +7,10 @@ use std::collections::HashMap;
 use uuid::Uuid;
 use zeroize::Zeroizing;
 
-use vault_api::{BaseUrls, BitwardenClient, SyncResponse};
+use vault_api::{BaseUrls, BitwardenClient, SyncResponse, TokenResponse};
 use vault_core::cipher::{Cipher, decrypt_user_key};
 use vault_core::kdf::{KdfParams, derive_master_key, stretch_master_key};
-use vault_ipc::proto::Error as IpcError;
+use vault_ipc::proto::{ApiKeyCreds, Error as IpcError};
 use vault_store::VaultCache;
 
 use crate::state::{Vault, account_dir_name};
@@ -26,8 +26,9 @@ pub async fn perform_unlock(
     email: &str,
     password: &[u8],
     device_id: Option<&str>,
+    api_key: Option<&ApiKeyCreds>,
 ) -> Result<Vault, IpcError> {
-    match online_unlock(server, email, password, device_id).await {
+    match online_unlock(server, email, password, device_id, api_key).await {
         Ok(vault) => Ok(vault),
         Err(IpcError::Network(net)) => {
             // Network down — recover from cache if we have one for this account.
@@ -47,6 +48,7 @@ async fn online_unlock(
     email: &str,
     password: &[u8],
     device_id: Option<&str>,
+    api_key: Option<&ApiKeyCreds>,
 ) -> Result<Vault, IpcError> {
     let email_lower = email.trim().to_lowercase();
     let urls = BaseUrls::self_hosted(server).map_err(|e| IpcError::Internal(e.to_string()))?;
@@ -70,10 +72,19 @@ async fn online_unlock(
     let stretch_enc = Zeroizing::new(stretch_enc);
     let stretch_mac = Zeroizing::new(stretch_mac);
 
-    let token = client
-        .login_password(&email_lower, password, params)
-        .await
-        .map_err(translate_login_err)?;
+    // Authenticate. An API key (request-supplied or previously persisted) uses
+    // the client_credentials grant, which skips 2FA; otherwise the password
+    // grant. Either way the master key derived above is what decrypts the vault.
+    let token = obtain_token(
+        &mut client,
+        &email_lower,
+        password,
+        params,
+        api_key,
+        server,
+        email,
+    )
+    .await?;
 
     let encrypted_user_key = token
         .key
@@ -114,6 +125,81 @@ async fn online_unlock(
     Ok(vault)
 }
 
+/// Authenticate `client` and return the token. Grant selection: request-supplied
+/// API-key creds (persisted on success, so future unlocks reuse them) → a
+/// previously stored API key → the password grant. The API-key grants use
+/// `client_credentials`, which skips 2FA; the password grant can surface
+/// [`IpcError::TwoFactorRequired`].
+async fn obtain_token(
+    client: &mut BitwardenClient,
+    email_lower: &str,
+    password: &[u8],
+    params: KdfParams,
+    api_key: Option<&ApiKeyCreds>,
+    server: &str,
+    email: &str,
+) -> Result<TokenResponse, IpcError> {
+    if let Some(creds) = api_key {
+        let token = client
+            .login_api_key(&creds.client_id, &creds.client_secret)
+            .await
+            .map_err(api_err)?;
+        // Enrollment succeeded — persist the key so plain `unlock` reuses it.
+        persist_apikey(server, email, creds)?;
+        return Ok(token);
+    }
+    if let Some(stored) =
+        cache_dir(server, email).and_then(|d| vault_store::load_apikey_from_dir(&d).ok())
+    {
+        return client
+            .login_api_key(&stored.client_id, stored.client_secret.as_bytes())
+            .await
+            .map_err(api_err);
+    }
+    client
+        .login_password(email_lower, password, params)
+        .await
+        .map_err(translate_login_err)
+}
+
+/// Persist a request-supplied API key (0600) for the account. The
+/// `client_secret` is valid UTF-8 here — `login_api_key` already verified it
+/// against the server.
+fn persist_apikey(server: &str, email: &str, creds: &ApiKeyCreds) -> Result<(), IpcError> {
+    let dir = cache_dir(server, email)
+        .ok_or_else(|| IpcError::Internal("no data directory".to_owned()))?;
+    let client_secret = String::from_utf8(creds.client_secret.clone())
+        .map_err(|_| IpcError::Internal("api-key client_secret is not valid UTF-8".to_owned()))?;
+    let store_creds = vault_store::ApiKeyCreds {
+        client_id: creds.client_id.clone(),
+        client_secret,
+    };
+    vault_store::save_apikey_to_dir(&dir, &store_creds)
+        .map_err(|e| IpcError::Internal(format!("write api key: {e}")))?;
+    Ok(())
+}
+
+/// Report whether an API key is stored for the account (never the secret).
+#[must_use]
+pub fn apikey_status(server: &str, email: &str) -> vault_ipc::proto::ApiKeyStatus {
+    let creds = cache_dir(server, email).and_then(|d| vault_store::load_apikey_from_dir(&d).ok());
+    vault_ipc::proto::ApiKeyStatus {
+        configured: creds.is_some(),
+        client_id: creds.map(|c| c.client_id),
+    }
+}
+
+/// Forget the stored API key for the account (idempotent — no key is success).
+///
+/// # Errors
+///
+/// [`IpcError::Internal`] if the data dir can't be located or the removal fails.
+pub fn apikey_forget(server: &str, email: &str) -> Result<(), IpcError> {
+    let dir = cache_dir(server, email)
+        .ok_or_else(|| IpcError::Internal("no data directory".to_owned()))?;
+    vault_store::delete_apikey_from_dir(&dir).map_err(|e| IpcError::Internal(e.to_string()))
+}
+
 /// Offline unlock from the encrypted local cache — no network. Recovers the
 /// user key from the master password via the cached protected key, then builds
 /// a read-only (`client = None`) vault. A wrong password is `BadPassword`.

crates/vault-api/src/client.rs

@@ -264,6 +264,65 @@ impl BitwardenClient {
         }
     }
 
+    /// `POST /connect/token` with `grant_type=client_credentials` — authenticate
+    /// with a Bitwarden **personal API key** (`client_id = "user.<uuid>"` +
+    /// `client_secret`, from the web vault). This grant is **not** 2FA-challenged,
+    /// so it's the way to obtain a token for an account with two-factor auth
+    /// enabled without an interactive TOTP prompt.
+    ///
+    /// The API key authenticates the *session* only: the returned
+    /// [`TokenResponse`] still carries the user key wrapped under the stretched
+    /// master key (`key`), so the caller must still derive the master key from
+    /// the master password to decrypt the vault — the API key never replaces it.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`Error::Credential`] if `client_secret` is not valid UTF-8,
+    /// [`Error::ServerStatus`] on a rejected API key (a plain `400` — there is
+    /// no 2FA branch on this grant), or [`Error::Transport`] on transport failure.
+    pub async fn login_api_key(
+        &mut self,
+        client_id: &str,
+        client_secret: &[u8],
+    ) -> Result<TokenResponse> {
+        // Held in Zeroizing so the secret scrubs on drop even on early return.
+        let secret = Zeroizing::new(
+            std::str::from_utf8(client_secret)
+                .map_err(|_| Error::Credential("api-key client_secret is not valid UTF-8"))?
+                .to_owned(),
+        );
+        let url = self
+            .urls
+            .identity
+            .join("connect/token")
+            .map_err(|_| Error::BaseUrl("could not build token URL"))?;
+
+        let device = self.device_id.to_string();
+        let form: [(&str, &str); 7] = [
+            ("grant_type", "client_credentials"),
+            ("scope", "api"),
+            ("client_id", client_id),
+            ("client_secret", secret.as_str()),
+            ("deviceType", "14"),
+            ("deviceIdentifier", &device),
+            ("deviceName", &self.device_name),
+        ];
+
+        let resp = self.http.post(url).form(&form).send().await?;
+        let status = resp.status();
+        if status.is_success() {
+            let token: TokenResponse = resp.json().await?;
+            self.access_token = Some(Zeroizing::new(token.access_token.clone()));
+            self.refresh_token = token.refresh_token.clone().map(Zeroizing::new);
+            Ok(token)
+        } else {
+            Err(Error::ServerStatus {
+                status: status.as_u16(),
+                message: resp.text().await.unwrap_or_default(),
+            })
+        }
+    }
+
     /// `GET /sync` — fetch the full encrypted vault. Requires a prior `login_password`.
     ///
     /// # Errors

crates/vault-api/src/error.rs

@@ -28,6 +28,10 @@ pub enum Error {
     #[error("invalid base URL: {0}")]
     BaseUrl(&'static str),
 
+    /// A caller-supplied credential was malformed (e.g. a non-UTF-8 API-key secret).
+    #[error("invalid credential: {0}")]
+    Credential(&'static str),
+
     /// Operation requires a two-factor token Vault doesn't yet support (M2).
     #[error("two-factor authentication required (provider {0:?}) — not yet implemented")]
     TwoFactorRequired(Vec<u32>),