feat(vault): M4 slice 4 — --json on lifecycle verbs + real vault sync

Close the two remaining M4 items.

--json on unlock/lock/sync/stop-agent: all four stay silent on success in
human mode (existing pipelines unchanged) and emit a small envelope under
--json ({"unlocked":true}, {"locked":true}, {"stopped":true}, and for sync
{"synced":true,"items":N,"last_sync":"…"}). cmd_simple is retired in favour
of cmd_ack (Ok-only acks) and a dedicated cmd_sync.

vault sync now actually re-pulls /sync over the unlock-time session and
replaces the in-memory ciphers, folder map, and last_sync stamp (it was an
M3 stub that only checked the unlocked flag). The agent answers a successful
re-sync with a fresh Status snapshot so --json can report the new item count.
Parity with unlock: only the in-memory vault is refreshed — the agent still
doesn't write the on-disk vault-store cache. A sync long after unlock can 401
once the access token expires (no refresh-token flow in M4); it surfaces as
IpcError::Network, same as add/edit/remove.

The /sync → (ciphers, folders) decode is factored out of perform_unlock into
a shared unlock::ciphers_and_folders, now the single spine of both unlock and
resync, with two direct unit tests (typed-view decode + malformed-folder skip).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: UnbreakableMJ

CHANGELOG.md

@@ -10,6 +10,29 @@ range may break in any release.
 
 ### Added
 
+- **M4 (slice 4) — `--json` on the lifecycle verbs + a real `vault sync`.**
+  Closes the two remaining M4 items.
+  - `unlock`, `lock`, `sync`, and `stop-agent` now take `--json`. They stay
+    **silent on success in human mode** (unchanged — existing pipelines keep
+    working); under `--json` each emits a small envelope: `{"unlocked":true}`,
+    `{"locked":true}`, `{"stopped":true}`, and for sync
+    `{"synced":true,"items":N,"last_sync":"…"}`.
+  - `vault sync` now actually re-pulls `/sync` over the unlock-time session and
+    replaces the in-memory ciphers, folder map, and `last_sync` stamp (it was an
+    M3 stub that only checked the unlocked flag). The agent answers a successful
+    re-sync with a fresh `Status` snapshot, so `--json` can report the new item
+    count. Parity with `unlock`: only the in-memory vault is refreshed — the
+    agent still doesn't write the on-disk `vault-store` cache. Known limitation:
+    a `sync` long after `unlock` can `401` once the access token expires (no
+    refresh-token flow yet in M4); it surfaces as `IpcError::Network`, same as
+    `add`/`edit`/`remove`.
+  - The `/sync` → `(ciphers, folders)` decode is factored out of
+    `perform_unlock` into a shared `unlock::ciphers_and_folders`, now the single
+    spine of both `unlock` and `resync`. Tests: two direct unit tests on that
+    function (typed-view decode + malformed-folder skipping); the CLI's
+    `cmd_simple` was retired in favour of `cmd_ack` (Ok-only acks) and a
+    dedicated `cmd_sync`.
+
 - **M4 (slice 3) — `vault add` + `vault edit`.** The two remaining write verbs,
   the inverse of the read path: caller-supplied plaintext fields are encrypted
   **inside the agent** (the user key never leaves it) and `POST`/`PUT` to the
@@ -34,8 +57,10 @@ range may break in any release.
     `apply_cipher_edits` cases proving a secondary URI survives an edit (agent);
     and `#[ignore]`d wiremock create/update + secure-note-marker tests (api).
 
-  (`add` + `edit` complete the write verbs; remaining M4: `--json` on
-  `unlock`/`lock`/`sync`/`stop-agent`, and a real re-pull `vault sync`.)
+  (`add` + `edit` complete the write verbs; `--json` on the lifecycle verbs and
+  the real `vault sync` landed in slice 4 above. M4 feature work is complete —
+  the remaining M4 gate is the end-to-end `add → list/get → edit → get → remove`
+  run against a real Vaultwarden per `docs/m2-vaultwarden.md`.)
 
 ### Fixed
 

crates/vault-agent/src/server.rs

@@ -102,15 +102,18 @@ async fn dispatch(req: Request, state: &Arc<Mutex<AgentState>>) -> Response {
             Response::Ok
         }
         Request::Sync => {
-            // M3 keeps Sync minimal: the agent already pulled /sync during
-            // unlock. A standalone re-sync lands in M4 when the cache reload
-            // path is split out of the unlock flow.
-            let unlocked = state.lock().await.is_unlocked();
-            if unlocked {
-                Response::Ok
-            } else {
-                Response::Error(IpcError::Locked)
-            }
+            // Re-pull /sync over the unlock-time session and refresh the
+            // in-memory cache. Hold the mutex across the network call (as with
+            // Remove) — single-user / single-agent, so a coarse lock is fine.
+            let mut s = state.lock().await;
+            let res = s.resync().await;
+            s.touch();
+            let resp = match res {
+                Ok(()) => Response::Status(s.status_snapshot()),
+                Err(e) => Response::Error(e),
+            };
+            drop(s);
+            resp
         }
         Request::List => {
             let mut s = state.lock().await;

crates/vault-agent/src/state.rs

@@ -319,6 +319,30 @@ impl AgentState {
         Ok(Saved { id, name })
     }
 
+    /// Re-pull `/sync` over the existing authenticated session and replace the
+    /// in-memory ciphers, folder map, and `last_sync` stamp. Requires an
+    /// unlocked agent.
+    ///
+    /// Like `unlock`, this refreshes only the in-memory vault — the on-disk
+    /// encrypted cache is not (yet) written by the agent. Known limitation: a
+    /// `sync` long after `unlock` can fail with a `401` once the access token
+    /// expires; there is no refresh-token flow in M4, so that surfaces as
+    /// `IpcError::Network` (shared with `add`/`edit`/`remove`).
+    pub async fn resync(&mut self) -> Result<(), IpcError> {
+        let v = self.vault.as_mut().ok_or(IpcError::Locked)?;
+        let sync = v
+            .client
+            .sync()
+            .await
+            .map_err(|e| IpcError::Network(e.to_string()))?;
+        let (ciphers, folders) =
+            crate::unlock::ciphers_and_folders(&sync, &v.user_enc, &v.user_mac);
+        v.ciphers = ciphers;
+        v.folders = folders;
+        v.last_sync = crate::unlock::now_iso();
+        Ok(())
+    }
+
     /// Decrypt the named field on the cipher matching `query` (case-insensitive).
     pub fn get_item(&self, query: &str, field: Field) -> Result<Item, IpcError> {
         let v = self.vault.as_ref().ok_or(IpcError::Locked)?;

crates/vault-agent/src/unlock.rs

@@ -7,7 +7,7 @@ use std::collections::HashMap;
 use uuid::Uuid;
 use zeroize::Zeroizing;
 
-use vault_api::{BaseUrls, BitwardenClient};
+use vault_api::{BaseUrls, BitwardenClient, SyncResponse};
 use vault_core::cipher::{Cipher, decrypt_user_key};
 use vault_core::kdf::{derive_master_key, stretch_master_key};
 use vault_ipc::proto::Error as IpcError;
@@ -49,16 +49,42 @@ pub async fn perform_unlock(server: &str, email: &str, password: &[u8]) -> Resul
     let user_mac = Zeroizing::new(user_mac_arr);
 
     let sync = client.sync().await.map_err(api_err)?;
+    let (ciphers, folders) = ciphers_and_folders(&sync, &user_enc, &user_mac);
 
-    // Server returns Profile / Folders / Ciphers / etc as serde_json::Value
-    // at the vault-api layer — re-cast Ciphers and Folders into typed views.
+    // `client` holds the access token internally (`login_password` stashed
+    // it). Hand the client itself to the vault so subsequent Sync / Remove
+    // / Edit / Add reuse the same authenticated session.
+    Ok(Vault {
+        server: server.to_owned(),
+        email: email_lower,
+        user_enc,
+        user_mac,
+        ciphers,
+        folders,
+        client,
+        last_sync: now_iso(),
+    })
+}
+
+/// Re-cast a `/sync` payload into the typed views the agent caches: a list of
+/// [`Cipher`]s and an `id → decrypted-name` folder map. Shared by the initial
+/// [`perform_unlock`] and the standalone `resync` so both paths interpret the
+/// server response identically.
+///
+/// The server hands ciphers/folders to `vault-api` as `serde_json::Value`;
+/// here they are decoded into [`Cipher`] (dropping any that don't fit the
+/// schema) and folder names are decrypted eagerly — there are typically few.
+pub(crate) fn ciphers_and_folders(
+    sync: &SyncResponse,
+    user_enc: &[u8; 32],
+    user_mac: &[u8; 32],
+) -> (Vec<Cipher>, HashMap<String, String>) {
     let ciphers: Vec<Cipher> = sync
         .ciphers
         .iter()
         .filter_map(|v| serde_json::from_value(v.clone()).ok())
         .collect();
 
-    // Decrypt folder names eagerly — there are typically few.
     let mut folders = HashMap::new();
     for f in &sync.folders {
         let Some(obj) = f.as_object() else { continue };
@@ -69,26 +95,13 @@ pub async fn perform_unlock(server: &str, email: &str, password: &[u8]) -> Resul
             continue;
         };
         if let Ok(enc) = vault_core::EncString::parse(name_enc)
-            && let Ok(pt) = enc.decrypt(&user_enc, &user_mac)
+            && let Ok(pt) = enc.decrypt(user_enc, user_mac)
             && let Ok(name) = String::from_utf8(pt)
         {
             folders.insert(id.to_owned(), name);
         }
     }
-
-    // `client` holds the access token internally (`login_password` stashed
-    // it). Hand the client itself to the vault so subsequent Sync / Remove
-    // / Edit / Add reuse the same authenticated session.
-    Ok(Vault {
-        server: server.to_owned(),
-        email: email_lower,
-        user_enc,
-        user_mac,
-        ciphers,
-        folders,
-        client,
-        last_sync: now_iso(),
-    })
+    (ciphers, folders)
 }
 
 fn api_err(e: vault_api::Error) -> IpcError {
@@ -118,7 +131,7 @@ fn crypto_err(e: vault_core::Error) -> IpcError {
 }
 
 #[allow(clippy::many_single_char_names)] // h/m/s/y/d are the conventional date-field names
-fn now_iso() -> Option<String> {
+pub(crate) fn now_iso() -> Option<String> {
     use std::time::SystemTime;
     let now = SystemTime::now();
     let dur = now.duration_since(SystemTime::UNIX_EPOCH).ok()?;
@@ -152,3 +165,74 @@ fn days_to_ymd(days_since_epoch: u64) -> (i32, u32, u32) {
     let y = y_minus_2000 + i64::from(m <= 2) + 2000;
     (i32::try_from(y).unwrap_or(0), m as u32, d as u32)
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn enc_str(enc: &[u8; 32], mac: &[u8; 32], plain: &str) -> String {
+        vault_core::EncString::encrypt(enc, mac, plain.as_bytes()).serialize()
+    }
+
+    #[test]
+    fn ciphers_and_folders_decodes_typed_views() {
+        let enc = [1u8; 32];
+        let mac = [2u8; 32];
+
+        // Two well-formed ciphers and one folder with an encrypted name.
+        let sync = SyncResponse {
+            profile: serde_json::Value::Null,
+            folders: vec![serde_json::json!({
+                "Id": "fid-1",
+                "Name": enc_str(&enc, &mac, "Work"),
+            })],
+            collections: vec![],
+            ciphers: vec![
+                serde_json::json!({
+                    "Id": "c1",
+                    "Type": 1,
+                    "Name": enc_str(&enc, &mac, "github.com"),
+                }),
+                serde_json::json!({
+                    "Id": "c2",
+                    "Type": 2,
+                    "Name": enc_str(&enc, &mac, "note"),
+                }),
+            ],
+            domains: serde_json::Value::Null,
+            sends: vec![],
+        };
+
+        let (ciphers, folders) = ciphers_and_folders(&sync, &enc, &mac);
+
+        assert_eq!(ciphers.len(), 2);
+        assert_eq!(ciphers[0].id, "c1");
+        assert_eq!(
+            ciphers[0].decrypt_name(&enc, &mac).unwrap().as_deref(),
+            Some("github.com")
+        );
+        assert_eq!(folders.get("fid-1").map(String::as_str), Some("Work"));
+    }
+
+    #[test]
+    fn ciphers_and_folders_skips_malformed_folder_entries() {
+        let enc = [3u8; 32];
+        let mac = [4u8; 32];
+        let sync = SyncResponse {
+            profile: serde_json::Value::Null,
+            // Missing Name, and an undecryptable Name — both dropped silently.
+            folders: vec![
+                serde_json::json!({ "Id": "fid-missing-name" }),
+                serde_json::json!({ "Id": "fid-bad", "Name": "not-an-encstring" }),
+            ],
+            collections: vec![],
+            ciphers: vec![],
+            domains: serde_json::Value::Null,
+            sends: vec![],
+        };
+
+        let (ciphers, folders) = ciphers_and_folders(&sync, &enc, &mac);
+        assert!(ciphers.is_empty());
+        assert!(folders.is_empty());
+    }
+}