Merge pull request #50 from Gerharddc/multiple-enter

Support multiple enter

Author: Gerharddc

ARCHITECTURE.md

@@ -0,0 +1,97 @@
+# Architecture
+
+## Core Components
+
+### The Daemon
+
+A long-running daemon process manages each Litterbox. It is started automatically when entering a Litterbox and persists until the container is stopped.
+
+**Responsibilities:**
+
+- Manages the SSH agent server for key access
+- Monitors active sessions via lockfiles
+- Automatically stops the container when all sessions close
+
+**Lockfiles** in `~/Litterbox/`:
+
+- `.daemon-{LBX_NAME}.lock` - Contains the daemon's PID. Prevents multiple daemons from running simultaneously.
+- `.session-{LBX_NAME}.lock` - Contains PIDs of all active terminal sessions. The daemon periodically cleans stale PIDs and stops the container when this file becomes empty.
+
+### SSH Key Architecture
+
+Litterbox implements a custom SSH agent to control key access.
+
+**Components:**
+
+1. **Key Storage** - Keys are stored in `~/Litterbox/keys.ron`, encrypted with a user-provided password.
+
+2. **SSH Agent Server** - A custom agent implementation built on russh that:
+   - Runs inside the daemon as an async task
+   - Listens on a Unix socket mounted into the container
+   - Decrypts keys only when needed and registers them with the agent
+
+3. **Confirmation System** - Before any key operation (sign, list, add, remove), the agent spawns a GUI confirmation dialog using. Users can:
+   - Approve the single request
+   - Approve for the entire session (subsequent requests of the same type are auto-approved)
+   - Decline the request
+
+A new short-livived process is spawned for each confirmation dialog. This is mainly to work around threading issues with the GUI system.
+
+### Container Lifecycle
+
+**Building:**
+
+- Litterbox uses Dockerfile templates to build images
+- Images are tagged with `work.litterbox.name` label for discovery
+- Each Litterbox has both an image and a container
+
+**Starting:**
+
+- The container entrypoint is `/litterbox wait`, which blocks until the session lock file is empty
+- This is detected using inotify for efficient watching
+
+**Stopping:**
+
+- When the daemon detects no active sessions, it exits
+- This triggers the container's entrypoint to return
+- Podman automatically stops the container
+
+### File System Isolation
+
+The isolation model restricts what the container can access:
+
+**Mounted Paths:**
+
+- `~/Litterbox/homes/{name}` → `/home/user` (user's home inside container)
+- `/litterbox` (binary, read-only) → Container entrypoint
+- `/session.lock` (host's session lock, read-only) → Used for waiting
+- `/tmp/ssh-agent.sock` → SSH agent socket for key access
+- `/tmp/pipewire-0` (optional) → PipeWire socket for audio
+- Wayland socket → Host's Wayland display
+
+**Isolation Boundaries:**
+
+- User namespace is set to `keep-id` to match host user
+- Root filesystem is fully isolated (no access to host except mounted paths)
+- Network mode defaults to `pasta` (user-mode networking stack)
+
+### Session Tracking
+
+Each terminal session is tracked via PID:
+
+1. When `litterbox enter` runs, it adds the terminal's PID to the session lockfile
+2. When the terminal exits, the PID is removed from the lockfile
+3. The daemon periodically checks and cleans up PIDs for dead processes
+4. When the lockfile is empty, the container stops
+
+This allows multiple concurrent sessions (e.g., multiple terminals) to share one container.
+
+### Entry Flow
+
+When a user runs `litterbox enter NAME`:
+
+1. **Container Check** - Verify container exists; start if not running
+2. **Daemon Start** - If daemon not running, spawn it with the key password via stdin
+3. **Session Registration** - Add terminal PID to session lockfile
+4. **Home Setup** - Run `/litterbox setup-home` to initialize user's home directory (only on first entry)
+5. **Shell Launch** - Start user's shell inside the container

Cargo.lock

@@ -83,7 +83,7 @@ During the build process, you will be asked various questions related to how you
 
 ### 3. Enter
 
-Finally you can then enter your Litterbox by running `litterbox enter LBX_NAME`. Once inside the Litterbox you can then start working on your projects!
+Finally you can then enter your Litterbox by running `litterbox enter LBX_NAME`. Once inside the Litterbox you can then start working on your projects! You can enter the same Litterbox multiple times from different terminals - all terminals share the same running container and this container will automatically stop when the last terminal exits.
 
 ### 4. Keys
 
@@ -109,6 +109,10 @@ Litterbox is very similar to DevContainers in that is uses Dockerfiles and conta
 
 Litterbox is most similar to Distrobox in terms of its design and functionality. The primary difference is that Distrobox does not aim to provide any isolation/sandboxing at all whereas Litterbox has a strong emphasis on providing it. Distrobox avoids sandboxing in order to provide more seamless integration between applications running inside the Distrobox and the host system. It tries to solve the problem of running software intended for a different distro as if it is running natively. Litterbox instead sacrificies much of the convenience that Distrobox provides in exchange for some isolation/sandboxing capabilities.
 
+## Stability
+
+Litterbox is still early in its development lifecycle and not particularly stable yet.
+
 ## TODO
 
 Litterbox is still very much WIP with many missing features or required improvements. Following is a list of some important pieces that are still missing:
@@ -119,6 +123,7 @@ Litterbox is still very much WIP with many missing features or required improvem
 - [x] Add function to approve some SSH agent requests for the duration of the session.
 - [x] Add optional support for using host network.
 - [x] Add optional support for port forwarding with the default "pasta" networking.
+- [x] Support entering a Litterbox multiple times.
 - [ ] Add a "prune" command to get rid of dangling images.
 - [ ] Add support for more granular network settings.
 - [ ] Show SSH key name when prompting for approval. (Currently blocked by https://github.com/Eugeny/russh/issues/602)

README.md

@@ -8,7 +8,7 @@ default-run = "litterbox"
 names = { path = "../names" }
 clap = { version = "4.5", features = ["derive"] }
 serde = { version = "1.0", features = ["derive"] }
-nix = { version = "0.31", features = ["fs"] }
+nix = { version = "0.31", features = ["fs", "signal", "inotify"] }
 serde_json = "1.0"
 tabled = "0.20"
 inquire = "0.9"
@@ -23,5 +23,6 @@ tokio-stream = { version = "0.1", features = ["net"] }
 eframe = "0.33"
 egui_extras = { version="0.33", features=["svg"] }
 futures = "0.3"
-strum = "0.27"
-strum_macros = "0.27"
+strum = "0.28"
+strum_macros = "0.28"
+anyhow = "1.0"

litterbox/Cargo.toml

@@ -1,3 +1,4 @@
+use anyhow::Result;
 use eframe::egui;
 use futures::Future;
 use russh::keys::*;
@@ -7,7 +8,7 @@ use std::sync::atomic::{AtomicBool, Ordering};
 use strum_macros::{Display, EnumString};
 use tokio::process::Command;
 
-use crate::errors::LitterboxError;
+use crate::env::litterbox_binary_path;
 use crate::extract_stdout;
 use crate::files::SshSockFile;
 
@@ -157,7 +158,7 @@ impl eframe::App for ConfirmationDialog<'_> {
 }
 
 pub struct AgentState {
-    /// When the agent is locked, uesrs will need to approve requests
+    /// When the agent is locked, users will need to approve requests
     pub locked: AtomicBool,
 
     /// When set, users no longer need to approve requests to list keys
@@ -173,12 +174,8 @@ impl Default for AgentState {
     }
 }
 
-pub async fn start_ssh_agent(
-    lbx_name: &str,
-    agent_state: Arc<AgentState>,
-) -> Result<PathBuf, LitterboxError> {
-    let mut args = std::env::args();
-    let litterbox_path = args.next().expect("Binary path should be defined.");
+pub async fn start_ssh_agent(lbx_name: &str, agent_state: Arc<AgentState>) -> Result<PathBuf> {
+    let litterbox_path = litterbox_binary_path();
 
     let ssh_sock = SshSockFile::new(lbx_name, false)?;
     let agent_path = ssh_sock.path().to_owned();

litterbox/src/agent.rs

@@ -0,0 +1,76 @@
+use anyhow::{Context, Result};
+use log::info;
+use nix::sys::signal::kill;
+use nix::unistd::Pid;
+
+use crate::Keys;
+use crate::files;
+use crate::podman::is_container_running;
+
+pub async fn run(lbx_name: &str, password: &str) -> Result<()> {
+    let daemon_lock = files::daemon_lock_path(lbx_name)?;
+
+    if daemon_lock.exists() {
+        let pid_str =
+            std::fs::read_to_string(&daemon_lock).context("Failed to read daemon lock file")?;
+
+        if let Ok(pid) = pid_str.trim().parse::<u32>() {
+            let pid = Pid::from_raw(pid as i32);
+            if kill(pid, None).is_ok() {
+                info!("Daemon already running for {}", lbx_name);
+                return Ok(());
+            }
+        }
+
+        info!("Stale daemon lock file found, removing");
+        std::fs::remove_file(&daemon_lock).context("Failed to remove stale daemon lock file")?;
+    }
+
+    let my_pid = std::process::id();
+    std::fs::write(&daemon_lock, my_pid.to_string()).context("Failed to write daemon lock file")?;
+
+    let keys = Keys::load()?;
+    keys.start_ssh_server(lbx_name, password).await?;
+
+    let session_path = files::session_lock_path(lbx_name)?;
+
+    loop {
+        tokio::time::sleep(std::time::Duration::from_secs(5)).await;
+
+        files::cleanup_dead_pids_from_session_lockfile(&session_path)?;
+
+        if !is_container_running(lbx_name)? {
+            info!("Container no longer running, daemon will stop.");
+            break;
+        }
+    }
+
+    if session_path.exists() {
+        info!("Cleaning up session lockfile.");
+        std::fs::remove_file(&session_path).context("Failed to remove session lock file")?;
+    }
+
+    std::fs::remove_file(&daemon_lock).context("Failed to remove daemon lock file")?;
+    info!("Daemon exiting for {}", lbx_name);
+    Ok(())
+}
+
+pub fn is_running(lbx_name: &str) -> Result<bool> {
+    use std::fs::read_to_string;
+
+    let daemon_lock = files::daemon_lock_path(lbx_name)?;
+    let running = daemon_lock.exists() && {
+        if let Ok(pid_str) = read_to_string(&daemon_lock) {
+            if let Ok(pid) = pid_str.trim().parse::<u32>() {
+                let pid = Pid::from_raw(pid as i32);
+                kill(pid, None).is_ok()
+            } else {
+                false
+            }
+        } else {
+            false
+        }
+    };
+
+    Ok(running)
+}

litterbox/src/daemon.rs

@@ -1,17 +1,13 @@
+use anyhow::{Context, Result, ensure};
 use log::{debug, info};
 use nix::sys::stat::{SFlag, major, minor, stat};
 use std::fs;
 use std::path::{Path, PathBuf};
 use std::process::Command;
 
-use crate::{errors::LitterboxError, files::lbx_home_path};
+use crate::files::lbx_home_path;
 
-fn mknod(
-    major_num: u64,
-    minor_num: u64,
-    dev_type: &str,
-    path: &Path,
-) -> Result<(), LitterboxError> {
+fn mknod(major_num: u64, minor_num: u64, dev_type: &str, path: &Path) -> Result<()> {
     println!(
         "Root permissions are required to create a device node. Please enter your password if prompted."
     );
@@ -25,31 +21,26 @@ fn mknod(
             &minor_num.to_string(),
         ])
         .spawn()
-        .map_err(|e| LitterboxError::RunCommand(e, "mknod"))?;
+        .context("Failed to run mknod command")?;
 
-    let res = child
-        .wait()
-        .map_err(|e| LitterboxError::RunCommand(e, "mknod"))?;
+    let res = child.wait().context("Failed to run mknod command")?;
 
-    if !res.success() {
-        Err(LitterboxError::CommandFailed(res, "mknod"))
-    } else {
-        Ok(())
-    }
+    ensure!(res.success(), "mknod command failed");
+    Ok(())
 }
 
-pub fn attach_device(lbx_name: &str, device_path: &str) -> Result<PathBuf, LitterboxError> {
+pub fn attach_device(lbx_name: &str, device_path: &str) -> Result<PathBuf> {
     let sub_path = device_path
         .strip_prefix("/dev/")
-        .ok_or(LitterboxError::InvalidDevicePath(device_path.to_string()))?;
+        .with_context(|| format!("Invalid device path: {device_path}"))?;
     debug!("sub_path: {:#?}", sub_path);
 
     let lbx_path = lbx_home_path(lbx_name)?;
     debug!("lbx_path: {:#?}", lbx_path);
     let dest_path = lbx_path.join("dev").join(sub_path);
     debug!("dest_path: {:#?}", dest_path);
 
-    let metadata = stat(device_path).map_err(LitterboxError::Nix)?;
+    let metadata = stat(device_path).context("Failed to stat device")?;
     let rdev = metadata.st_rdev;
     let kind = SFlag::from_bits_truncate(metadata.st_mode);
 
@@ -71,8 +62,7 @@ pub fn attach_device(lbx_name: &str, device_path: &str) -> Result<PathBuf, Litte
     let output_dir = dest_path
         .parent()
         .expect("Destination path should have parent.");
-    fs::create_dir_all(output_dir)
-        .map_err(|e| LitterboxError::DirUncreatable(e, output_dir.to_path_buf()))?;
+    fs::create_dir_all(output_dir).context("Failed to create output directory")?;
     debug!("Output dir ready!");
 
     mknod(major_num, minor_num, dev_type, &dest_path)?;

litterbox/src/devices.rs

@@ -1,20 +1,29 @@
-use crate::errors::LitterboxError;
+use anyhow::{Context, Result};
 
-fn get_env(lbx_name: &'static str) -> Result<String, LitterboxError> {
-    std::env::var_os(lbx_name)
-        .ok_or(LitterboxError::EnvVarUndefined(lbx_name))?
-        .into_string()
-        .map_err(|value| LitterboxError::EnvVarInvalid(lbx_name, value))
+fn get_env(lbx_name: &'static str) -> Result<String> {
+    let value = std::env::var(lbx_name)
+        .with_context(|| format!("Environment variable {lbx_name} is not defined"))?;
+    Ok(value)
 }
 
-pub fn home_dir() -> Result<String, LitterboxError> {
+pub fn home_dir() -> Result<String> {
     get_env("HOME")
 }
 
-pub fn wayland_display() -> Result<String, LitterboxError> {
+pub fn wayland_display() -> Result<String> {
     get_env("WAYLAND_DISPLAY")
 }
 
-pub fn xdg_runtime_dir() -> Result<String, LitterboxError> {
+pub fn xdg_runtime_dir() -> Result<String> {
     get_env("XDG_RUNTIME_DIR")
 }
+
+pub fn shell() -> Result<String> {
+    get_env("SHELL")
+}
+
+pub fn litterbox_binary_path() -> String {
+    std::env::args()
+        .next()
+        .expect("Binary path should be defined.")
+}