Merge pull request #15 from Spacecraft-Software/session-resume

feat(vault-agent): session resume across restart via kernel keyring (opt-in)

Author: UnbreakableMJ

CHANGELOG.md

@@ -10,6 +10,32 @@ range may break in any release.
 
 ### Added
 
+- **Session resume across agent restart (opt-in, Linux).** With the new
+  `agent.session_keyring` config key, an unlock mirrors the user key into the
+  Linux **kernel session keyring** (kernel memory — never on disk, never
+  swapped, possessor-gated, evicted on logout). A restarted agent (crash,
+  `SIGTERM`, `stop-agent` + auto-spawn) reads it back and resumes **unlocked
+  without the master password**, bounded by the idle-lock TTL: the keyring entry
+  carries a kernel timeout (refreshed on activity, throttled), so a dead agent's
+  session self-expires.
+  - Lock semantics split: explicit `vault lock` and idle-lock **clear** the
+    keyring (durably locked); `stop-agent`/`SIGTERM`/crash leave it so the next
+    agent resumes. `AgentState::lock` (in-memory wipe) vs the new
+    `lock_and_clear_session`.
+  - New `crates/vault-agent/src/session.rs` over the pure-Rust `linux-keyutils`
+    crate (`[target.'cfg(target_os = "linux")']`, MIT/Apache-2.0); a no-op stub
+    elsewhere. `main.rs` attempts resume at startup via the existing
+    `unlock::load_cache` + `vault_from_user_key` path.
+  - `vault config set agent.session_keyring true` (flows to the auto-spawned
+    agent as `--session-keyring`, mirroring `idle_lock_secs`).
+  - This is the sole, **default-off** carve-out to PRD §7.3 / G4 ("master key
+    never resident outside the agent process"); documented in PRD §7.3. Off, the
+    key never leaves the process. Linux-only — a no-op everywhere else.
+  - Tests: `SessionBlob` serde round-trip (cross-platform) + a keyring
+    store/load/clear round-trip that skips gracefully where no keyring exists;
+    `vault-config` `agent.session_keyring` get/set/unset + `agent_args` flag
+    emission.
+
 - **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

Cargo.lock

@@ -73,6 +73,10 @@ reqwest = { version = "0.12", default-features = false, features = ["rustls-tls"
 url = "2"
 uuid = { version = "1", features = ["v4", "serde"] }
 dirs = "5"
+# Linux kernel keyring (pure Rust, no C lib — avoids the ring/-flto link
+# breakage). MIT/Apache-2.0; GPL-3.0-or-later compatible. Linux-only, gated
+# behind `cfg(target_os = "linux")` in vault-agent.
+linux-keyutils = "0.2"
 time = { version = "0.3", features = ["serde", "serde-well-known"] }
 fs2 = "0.4"
 

Cargo.toml

@@ -52,7 +52,7 @@ keeps the crypto, sync, and storage code consolidated and auditable.
 | G1  | Fully functional Bitwarden client offline once initially synced.                                  |
 | G2  | TUI usable as a daily driver; sub-100 ms perceived latency on local operations.                   |
 | G3  | CLI achieves practical parity with `rbw`'s read+write surface and accepts/emits JSON everywhere.  |
-| G4  | Master key never resident outside the agent process; locked on idle, signal, or explicit `lock`.  |
+| G4  | Master key never resident outside the agent process; locked on idle, signal, or explicit `lock`. (Opt-in carve-out: §7.3 `session_keyring`.) |
 | G5  | Works against both `bitwarden.com` and self-hosted Vaultwarden, including cert pinning.           |
 | G6  | Headless install (`--no-default-features --features cli`) ships a single binary, no TUI deps.     |
 | G7  | Conformance with the Spacecraft Software Standard (§3 priority hierarchy, §4 license, §5 posture, §6.3 signed commits, §12 timestamps, §13 attribution). |
@@ -146,6 +146,15 @@ envelope; exit codes documented in `docs/exit_codes.md`.
 - Holds: unwrapped master key, derived item-encryption keys, current sync revision.
 - Locks on: idle timeout (default 15 min, configurable), `vault lock`, `SIGTERM`, screen-lock dbus signal where available.
 - Auto-spawned by any client on first use; never run as root; socket mode `0600`.
+- **Session resume (opt-in, Linux).** With `agent.session_keyring` enabled, the
+  unwrapped user key may *also* reside in the Linux kernel **session keyring** —
+  kernel memory, never on disk, never swapped, possessor-gated, evicted on
+  logout — so a restarted agent (crash / `SIGTERM` / `stop-agent` + auto-spawn)
+  resumes unlocked without the master password, bounded by the idle-lock TTL
+  (the keyring entry carries a kernel timeout). Explicit `vault lock` and
+  idle-lock clear it; `SIGTERM`/`stop-agent` leave it for resume. This is the
+  sole, default-off carve-out to G4's "master key never resident outside the
+  agent process"; off, the key never leaves the process.
 
 ### 7.4 Storage
 

PRD.md

@@ -111,6 +111,26 @@ 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.
 
+### Stay unlocked across restarts (Linux, opt-in)
+
+By default the agent holds the key only in its own memory, so any restart
+(crash, `stop-agent`, logout) means a fresh unlock. On Linux you can opt into
+resuming a session across an agent restart:
+
+```sh
+vault config set agent.session_keyring true
+```
+
+With this on, an unlock also mirrors the key into the Linux **kernel session
+keyring** (kernel memory, never on disk, never swapped, evicted on logout). A
+restarted agent reads it back and comes up unlocked — but only within the
+idle-lock window (`agent.idle_lock_secs`): the keyring entry self-expires, so a
+dead agent's session doesn't linger. An explicit `vault lock` (or idle-lock)
+forgets it and forces a full unlock; a plain `stop-agent`/`SIGTERM` leaves it so
+the next auto-spawn resumes. This is an opt-in relaxation of Vault's "key never
+leaves the agent" posture (PRD §7.3); it's off by default and a no-op on
+non-Linux.
+
 ## Configuration
 
 Persistent settings live at `$XDG_CONFIG_HOME/vault/config.toml`, managed with
@@ -123,8 +143,9 @@ vault config set agent.idle_lock_secs 600
 vault config unset clipboard.clear_secs
 ```
 
-Recognised keys: `clipboard.clear_secs` (auto-clear window, `0` disables) and
-`agent.idle_lock_secs` (idle-lock timeout, `0` disables). When the CLI
+Recognised keys: `clipboard.clear_secs` (auto-clear window, `0` disables),
+`agent.idle_lock_secs` (idle-lock timeout, `0` disables), and
+`agent.session_keyring` (resume across restarts; see above). When the CLI
 auto-starts the agent, these populate its launch flags. Wipe the on-disk item
 cache (and drop a running agent's keys) with `vault purge`.
 

README.md

@@ -32,6 +32,7 @@ clipboard = ["dep:arboard"]
 anyhow = { workspace = true }
 tokio = { workspace = true }
 clap = { workspace = true }
+serde = { workspace = true }
 serde_json = { workspace = true }
 zeroize = { workspace = true }
 uuid = { workspace = true }
@@ -43,5 +44,10 @@ vault-ipc = { path = "../vault-ipc" }
 vault-store = { path = "../vault-store" }
 vault-api = { path = "../vault-api" }
 
+# Linux kernel session keyring — backs the opt-in `agent.session_keyring`
+# session-resume feature. Pure Rust (no libkeyutils C dep). Linux-only.
+[target.'cfg(target_os = "linux")'.dependencies]
+linux-keyutils = { workspace = true }
+
 [dev-dependencies]
 tempfile = { workspace = true }

crates/vault-agent/Cargo.toml

@@ -22,6 +22,7 @@ use vault_ipc::default_socket_path;
 #[cfg(feature = "clipboard")]
 mod clipboard;
 mod server;
+mod session;
 mod state;
 mod unlock;
 
@@ -65,6 +66,11 @@ struct Args {
     /// build without clipboard support.
     #[arg(long)]
     clipboard_clear_secs: Option<u64>,
+    /// Mirror the user key into the Linux kernel session keyring on unlock so a
+    /// restarted agent resumes without the master password, within the
+    /// idle-lock TTL (opt-in; PRD §7.3 carve-out). No effect on non-Linux.
+    #[arg(long)]
+    session_keyring: bool,
 }
 
 #[tokio::main(flavor = "current_thread")]
@@ -82,6 +88,11 @@ async fn main() -> anyhow::Result<()> {
     };
     #[cfg(not(feature = "clipboard"))]
     let agent = AgentState::new(args.idle_lock_secs);
+    let mut agent = agent;
+    agent.session_keyring = args.session_keyring;
+    // Opt-in: resume an unlocked session left in the kernel keyring by a prior
+    // agent (e.g. after a crash / restart), within its idle-lock deadline.
+    try_resume(&mut agent);
     let state = Arc::new(Mutex::new(agent));
 
     if args.idle_lock_secs > 0 {
@@ -117,6 +128,40 @@ fn resolve_clear_secs(flag: Option<u64>, env: Option<&str>) -> u64 {
         .unwrap_or(30)
 }
 
+/// Opt-in session resume: if a prior agent left an unlocked session in the
+/// kernel keyring and it hasn't passed its idle-lock deadline, rebuild the
+/// vault from it + the on-disk cache so the agent comes up unlocked. Any
+/// failure (disabled, no entry, expired, missing cache) leaves it locked.
+fn try_resume(agent: &mut AgentState) {
+    if !agent.session_keyring {
+        return;
+    }
+    let Some(blob) = session::load() else {
+        return;
+    };
+    let now = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map_or(0, |d| d.as_secs());
+    // deadline_unix == 0 means "no expiry" (idle-lock disabled).
+    if blob.deadline_unix != 0 && now >= blob.deadline_unix {
+        session::clear();
+        return;
+    }
+    let Some(cache) = unlock::load_cache(&blob.server, &blob.email) else {
+        return;
+    };
+    let user_enc = zeroize::Zeroizing::new(blob.user_enc);
+    let user_mac = zeroize::Zeroizing::new(blob.user_mac);
+    match unlock::vault_from_user_key(&cache, &blob.server, &blob.email, user_enc, user_mac) {
+        Ok(vault) => {
+            agent.vault = Some(vault);
+            agent.touch();
+            eprintln!("vault-agent: resumed session from kernel keyring");
+        }
+        Err(e) => eprintln!("vault-agent: keyring resume failed: {e}"),
+    }
+}
+
 fn pick_socket(cli: Option<PathBuf>) -> anyhow::Result<PathBuf> {
     if let Some(p) = cli {
         return Ok(p);

crates/vault-agent/src/main.rs

@@ -98,6 +98,7 @@ async fn dispatch(req: Request, state: &Arc<Mutex<AgentState>>) -> Response {
                 Ok(vault) => {
                     let mut s = state.lock().await;
                     s.vault = Some(vault);
+                    s.persist_session();
                     s.touch();
                     Response::Ok
                 }
@@ -112,6 +113,7 @@ async fn dispatch(req: Request, state: &Arc<Mutex<AgentState>>) -> Response {
                 Ok(vault) => {
                     let mut s = state.lock().await;
                     s.vault = Some(vault);
+                    s.persist_session();
                     s.touch();
                     Response::Ok
                 }
@@ -149,7 +151,8 @@ async fn dispatch(req: Request, state: &Arc<Mutex<AgentState>>) -> Response {
         }
         Request::Lock => {
             let mut s = state.lock().await;
-            s.lock();
+            // Explicit lock: also forget any persisted keyring session.
+            s.lock_and_clear_session();
             s.touch();
             Response::Ok
         }
@@ -367,7 +370,8 @@ pub async fn idle_lock_loop(state: Arc<Mutex<AgentState>>) {
         sleep(Duration::from_secs(15)).await;
         let mut s = state.lock().await;
         if s.idle_lock_due() {
-            s.lock();
+            // Idle-lock is a security event: forget the keyring session too.
+            s.lock_and_clear_session();
             eprintln!("vault-agent: idle-lock triggered");
         }
         if s.shutdown_requested {