feat(vault-agent, vault-ipc, vault-cli): M3 — agent state machine, UDS IPC, CLI subcommands

vault-ipc: CBOR-framed request/response protocol over a Unix domain socket
with proto, socket, and transport modules plus a length-prefix transport
round-trip test suite.

vault-agent: long-lived daemon that holds the unwrapped user key. New
state, server, and unlock modules implement lock/unlock state, an idle-lock
policy, and a one-task-per-connection accept loop bound at $XDG_RUNTIME_DIR/
vault/agent.sock with mode 0700 on the parent and 0600 on the socket.
Inline tests cover state transitions and an end-to-end Status → locked-Get
→ Quit drive against a tempfile socket.

vault-cli: vault binary gains status / unlock / lock / sync / list / get /
stop-agent subcommands that talk to the agent over the UDS protocol, with
--json output on the read paths and dedicated exit codes per IpcError
variant.

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

Author: UnbreakableMJ

Cargo.lock

@@ -71,6 +71,8 @@ time = { version = "0.3", features = ["serde", "serde-well-known"] }
 fs2 = "0.4"
 
 tempfile = "3"
+ciborium = "0.2"
+ciborium-io = "0.2"
 
 # Dev-only.
 wiremock = "0.6"

Cargo.toml

@@ -22,6 +22,16 @@ workspace = true
 [dependencies]
 anyhow = { workspace = true }
 tokio = { workspace = true }
+clap = { workspace = true }
+serde_json = { workspace = true }
+zeroize = { workspace = true }
+uuid = { workspace = true }
+url = { workspace = true }
+thiserror = { workspace = true }
 vault-core = { path = "../vault-core" }
 vault-ipc = { path = "../vault-ipc" }
 vault-store = { path = "../vault-store" }
+vault-api = { path = "../vault-api" }
+
+[dev-dependencies]
+tempfile = { workspace = true }

crates/vault-agent/Cargo.toml

@@ -1,9 +1,76 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-//! Vault agent — long-lived daemon holding the decrypted master key.
+//! Vault agent — long-lived daemon that holds the user symmetric key.
 //!
-//! Stub binary at M0. See PRD §7.3.
+//! Run with no arguments to bind the default socket
+//! (`$XDG_RUNTIME_DIR/vault/agent.sock`). Override with `--socket PATH` or
+//! `VAULT_AGENT_SOCK`. The agent does NOT yet daemonise itself — start it
+//! with `nohup vault-agent &` or run it under a systemd user unit. M5 adds
+//! auto-spawn from the CLI.
 
-fn main() {
-    eprintln!("vault-agent: stub binary (M0) — see PRD §7.3");
+#![forbid(unsafe_code)]
+
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use clap::Parser;
+use tokio::sync::Mutex;
+
+use vault_ipc::default_socket_path;
+
+mod server;
+mod state;
+mod unlock;
+
+use state::AgentState;
+
+const ATTRIBUTION: &str = "\
+Maintained by Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>
+Copyright (C) 2026 Mohamed Hammad & Spacecraft Software  |  License: GPL-3.0-or-later
+https://Vault.SpacecraftSoftware.org/";
+
+#[derive(Parser, Debug)]
+#[command(
+    name = "vault-agent",
+    version = env!("CARGO_PKG_VERSION"),
+    about = "Vault agent — holds the unwrapped user key behind a Unix socket",
+    after_help = ATTRIBUTION,
+    after_long_help = ATTRIBUTION,
+)]
+struct Args {
+    /// Bind path. Defaults to `$VAULT_AGENT_SOCK` or `$XDG_RUNTIME_DIR/vault/agent.sock`.
+    #[arg(long, short = 's')]
+    socket: Option<PathBuf>,
+    /// Idle-lock timeout in seconds. The agent zeroises its keys after this
+    /// many seconds with no client activity. `0` disables auto-lock.
+    #[arg(long, default_value_t = 900)]
+    idle_lock_secs: u64,
+}
+
+#[tokio::main(flavor = "current_thread")]
+async fn main() -> anyhow::Result<()> {
+    let args = Args::parse();
+    let path = pick_socket(args.socket)?;
+    let state = Arc::new(Mutex::new(AgentState::new(args.idle_lock_secs)));
+
+    if args.idle_lock_secs > 0 {
+        let st = state.clone();
+        tokio::spawn(server::idle_lock_loop(st));
+    }
+
+    server::run(path, state).await?;
+    Ok(())
+}
+
+fn pick_socket(cli: Option<PathBuf>) -> anyhow::Result<PathBuf> {
+    if let Some(p) = cli {
+        return Ok(p);
+    }
+    if let Ok(env_path) = std::env::var("VAULT_AGENT_SOCK") {
+        if let Some(p) = vault_ipc::sanitize_socket_path(&env_path) {
+            return Ok(p);
+        }
+        anyhow::bail!("VAULT_AGENT_SOCK is not an absolute path: {env_path}");
+    }
+    default_socket_path().ok_or_else(|| anyhow::anyhow!("no XDG_RUNTIME_DIR / TMPDIR available"))
 }