Merge pull request #12 from Spacecraft-Software/token-refresh

feat(vault): token persistence + refresh

Author: UnbreakableMJ

CHANGELOG.md

@@ -10,6 +10,27 @@ range may break in any release.
 
 ### Added
 
+- **Token persistence + refresh.** The OAuth2 refresh token is now kept and
+  reused, so a cache/PIN/offline session can become fully capable and a
+  long-lived session survives access-token expiry.
+  - `vault-api`: `BitwardenClient` keeps the `refresh_token` from
+    `login_password`, exposes it (`refresh_token()`), and can be seeded with one
+    (`with_refresh_token`). New `refresh()` runs `grant_type=refresh_token`. The
+    four server ops (`sync`/`create`/`update`/`delete`) route through one
+    `send_with_auth` helper that, on a `401` with a refresh token held,
+    refreshes once and retries.
+  - The refresh token is persisted **encrypted under the user key** in the cache
+    (`refresh_token` envelope field) on online unlock + every `sync`, and
+    recovered into the in-memory session on a cache/PIN unlock.
+  - New `Vault::ensure_online`: a token-less session (offline / PIN) **lazily
+    upgrades** to online on its first `sync`/`add`/`edit`/`remove` by building a
+    client from the stored refresh token and refreshing — so PIN unlock stays
+    fast/offline but server ops "just work" when the network is up. A genuinely
+    offline box (or no stored refresh token) still returns `Error::Offline`.
+  - Tests: store refresh-token round-trip; `ensure_online` returns `Offline`
+    without a client/token and `Ok` with a live client; refresh-token recovery
+    from the cache on offline unlock. No new dependencies.
+
 - **PIN unlock.** Unlock the vault with a short PIN instead of the master
   password (like the Bitwarden extension/desktop), built on the encrypted cache.
   - `vault pin set` (requires an unlocked agent) encrypts the user key under a

README.md

@@ -72,9 +72,11 @@ vault pin status         # enrolled? attempts remaining?
 vault pin disable        # forget the PIN
 ```
 
-A PIN session is **read-only** (browse / `get` / copy from the encrypted cache);
-`sync` and edits need a master-password unlock. Five wrong PINs disable the PIN
-and require a master-password unlock — bounding brute-force of a short secret.
+A PIN session reads from the encrypted cache, and — once the network is
+reachable — transparently goes online for `sync` and edits by refreshing a
+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.
 
 ## Configuration
 

crates/vault-agent/src/state.rs

@@ -43,6 +43,11 @@ pub struct Vault {
     pub protected_user_key: String,
     /// Account KDF parameters (for offline master-key derivation / re-persist).
     pub kdf: vault_core::kdf::KdfParams,
+    /// `OAuth2` refresh token (decrypted, in memory) when one is available — from
+    /// the login token on an online unlock, or decrypted from the cache on an
+    /// offline/PIN unlock. Lets a token-less session go online via
+    /// [`Vault::ensure_online`] and is persisted (encrypted) by `persist_cache`.
+    pub refresh_token: Option<Zeroizing<String>>,
     /// Stable device id this session unlocked with (persisted to the cache).
     pub device_id: String,
     /// Most recent sync time (ISO 8601 UTC), or `None` if never synced.
@@ -71,10 +76,59 @@ impl Vault {
             .map_err(|e| IpcError::Internal(format!("encrypt cache: {e}")))?;
         cache.protected_user_key = Some(self.protected_user_key.clone());
         cache.kdf = Some(self.kdf);
+        // Persist the refresh token encrypted under the user key, so a later
+        // cache/PIN unlock can recover it and go online without the password.
+        if let Some(rt) = self.refresh_token.as_ref() {
+            cache.refresh_token =
+                Some(EncString::encrypt(&self.user_enc, &self.user_mac, rt.as_bytes()).serialize());
+        }
         vault_store::save_to_dir(&dir, &cache)
             .map_err(|e| IpcError::Internal(format!("write cache: {e}")))?;
         Ok(())
     }
+
+    /// Ensure the vault has a live, authenticated client — establishing one
+    /// from the held refresh token if the session was unlocked from cache
+    /// (offline / PIN). Returns `Error::Offline` when there's no token and no
+    /// way to get one (truly offline, or no refresh token persisted).
+    ///
+    /// # Errors
+    ///
+    /// [`IpcError::Offline`] if no client can be established;
+    /// [`IpcError::Internal`] on a malformed server URL.
+    pub async fn ensure_online(&mut self) -> Result<(), IpcError> {
+        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()));
+        }
+        self.client = Some(client);
+        Ok(())
+    }
+}
+
+/// Clone a `Zeroizing<String>` refresh token into a plain `String` for the API
+/// call (the client re-wraps it in `Zeroizing`).
+fn rt_string(rt: &Zeroizing<String>) -> String {
+    rt.as_str().to_owned()
 }
 
 /// Wrong-PIN attempts allowed before the PIN is wiped and a master-password
@@ -335,6 +389,7 @@ impl AgentState {
             .decrypt_name(&v.user_enc, &v.user_mac)
             .map_err(|e| IpcError::Decrypt(e.to_string()))?
             .unwrap_or_else(|| "<unnamed>".to_owned());
+        v.ensure_online().await?;
         v.client
             .as_mut()
             .ok_or(IpcError::Offline)?
@@ -389,6 +444,7 @@ impl AgentState {
             primary_uri: w.uri,
         };
         let mut cipher = Cipher::from_plain(&plain, &v.user_enc, &v.user_mac);
+        v.ensure_online().await?;
         let id = v
             .client
             .as_mut()
@@ -431,6 +487,7 @@ impl AgentState {
         apply_cipher_edits(&mut cipher, &overlay, &v.user_enc, &v.user_mac);
 
         let id = cipher.id.clone();
+        v.ensure_online().await?;
         v.client
             .as_mut()
             .ok_or(IpcError::Offline)?
@@ -455,6 +512,7 @@ impl AgentState {
     /// that surfaces as `IpcError::Network`.
     pub async fn resync(&mut self) -> Result<(), IpcError> {
         let v = self.vault.as_mut().ok_or(IpcError::Locked)?;
+        v.ensure_online().await?;
         let sync = v
             .client
             .as_mut()
@@ -1120,6 +1178,7 @@ mod tests {
                 memory_kib: None,
                 parallelism: None,
             },
+            refresh_token: None,
             device_id: "00000000-0000-0000-0000-000000000000".into(),
             last_sync: None,
         }
@@ -1147,6 +1206,22 @@ mod tests {
         assert!(s.list_entries().is_ok());
     }
 
+    #[test]
+    fn ensure_online_ok_with_client_offline_without() {
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .build()
+            .expect("rt");
+        // A live client → Ok with no network call (short-circuits).
+        let mut v = stub_vault();
+        assert!(rt.block_on(v.ensure_online()).is_ok());
+        // No client and no refresh token → Offline (can't establish a session).
+        let mut v = offline_vault();
+        assert!(matches!(
+            rt.block_on(v.ensure_online()),
+            Err(IpcError::Offline)
+        ));
+    }
+
     #[test]
     fn account_dir_name_is_filesystem_safe_and_distinct() {
         let a = account_dir_name("https://vault.example.org", "Me@Example.org");

crates/vault-agent/src/unlock.rs

@@ -87,6 +87,10 @@ async fn online_unlock(
     let sync = client.sync().await.map_err(api_err)?;
     let (ciphers, folders) = ciphers_and_folders(&sync, &user_enc, &user_mac);
 
+    // Capture the refresh token before the client is moved into the vault, so
+    // it can be persisted (encrypted) and reused after a cache/PIN unlock.
+    let refresh_token = client.refresh_token().map(|s| Zeroizing::new(s.to_owned()));
+
     // `client` holds the access token internally (`login_password` stashed it).
     // Hand it to the vault so Sync / Remove / Edit / Add reuse the session.
     let vault = Vault {
@@ -99,6 +103,7 @@ async fn online_unlock(
         client: Some(client),
         protected_user_key: encrypted_user_key.to_owned(),
         kdf: params,
+        refresh_token,
         device_id: device.to_string(),
         last_sync: now_iso(),
     };
@@ -194,6 +199,13 @@ pub fn vault_from_user_key(
     let kdf = cache
         .kdf
         .ok_or_else(|| IpcError::Internal("cached account has no KDF params".to_owned()))?;
+    // Recover the refresh token (encrypted under the user key) so this offline /
+    // PIN session can lazily go online. A decode failure just leaves it absent.
+    let refresh_token = cache.refresh_token.as_deref().and_then(|enc| {
+        let parsed = vault_core::EncString::parse(enc).ok()?;
+        let bytes = parsed.decrypt(&user_enc, &user_mac).ok()?;
+        String::from_utf8(bytes).ok().map(Zeroizing::new)
+    });
     Ok(Vault {
         server: server.to_owned(),
         email: email.trim().to_lowercase(),
@@ -204,6 +216,7 @@ pub fn vault_from_user_key(
         client: None,
         protected_user_key: cache.protected_user_key.clone().unwrap_or_default(),
         kdf,
+        refresh_token,
         device_id: cache.device_id.clone(),
         last_sync: cache.last_sync.clone(),
     })
@@ -525,9 +538,19 @@ mod tests {
             .unwrap();
         cache.protected_user_key = Some(protected);
         cache.kdf = Some(kdf);
+        // A refresh token, encrypted under the user key, must round-trip back
+        // into the recovered vault so an offline session can go online.
+        cache.refresh_token = Some(
+            vault_core::EncString::encrypt(&user_enc, &user_mac, b"my-refresh-token").serialize(),
+        );
 
         let vault = unlock_from_cache(&cache, "https://x", email, password).unwrap();
         assert!(vault.client.is_none(), "offline session has no token");
+        assert_eq!(
+            vault.refresh_token.as_deref().map(String::as_str),
+            Some("my-refresh-token"),
+            "refresh token recovered from cache"
+        );
         assert_eq!(vault.ciphers.len(), 1);
         assert_eq!(
             vault.ciphers[0]