agentsec_core/plain_mode/

mod.rs

//! Plain Mode — temporarily disable MCP servers by renaming `.mcp.json`
//! files to `.mcp.json.suspect` and (optionally) writing an empty stub in
//! their place.
//!
//! ## When to use it
//!
//! User suspects a newly-installed MCP server is malicious and wants to
//! start a clean Agent session **right now**, without manually editing
//! configs. `agentsec plain enable` renames targets to `.suspect`; the
//! Agent then starts with an empty MCP world. `agentsec plain restore`
//! puts everything back.
//!
//! ## What gets renamed
//!
//! Plain Mode only touches **standalone `.mcp.json` files**. It never
//! edits `.claude.json` directly, because that file mixes MCP server
//! config with hooks / permissions / per-project state that we don't
//! want to wipe.
//!
//! Default target: `<cwd>/.mcp.json`. Callers can pass additional
//! absolute paths (typically per-project `.mcp.json` discovered from a
//! scan).
//!
//! ## Ledger
//!
//! [`PLAIN_LEDGER_FILENAME`] under [`crate::Paths::home`] tracks which
//! files were renamed so [`restore`] can put them back. The ledger
//! existing with non-empty `entries` is the canonical signal that Plain
//! Mode is active.
//!
//! ## Invariants
//!
//! - [`enable`] is **idempotent within a session**: if the target's
//!   `.suspect` sibling already exists, enable skips that target (and
//!   reports the skip) rather than clobbering the prior backup.
//! - [`restore`] removes the ledger on success. Repeat calls with an
//!   absent ledger are no-ops.
//! - Dry-run mode performs zero filesystem mutation and returns the same
//!   shape of result so callers can preview.

use std::fs;
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};

use crate::Paths;
use crate::error::Result;

/// Filename of the ledger file under [`Paths::home`].
pub const PLAIN_LEDGER_FILENAME: &str = "plain-mode.json";

/// Suffix appended to a renamed file (so `.mcp.json` becomes
/// `.mcp.json.suspect`).
pub const SUSPECT_SUFFIX: &str = ".suspect";

/// Content of the stub written at the original path while Plain Mode is
/// active. Empty MCP world; the Agent sees zero servers configured.
pub const PLAIN_STUB_BODY: &str = "{\n  \"mcpServers\": {}\n}\n";

/// One row in the persisted ledger.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct LedgerEntry {
    /// Original absolute path of the renamed file (the one the Agent
    /// reads). After `enable`, a stub lives here.
    pub original: PathBuf,
    /// `<original><SUSPECT_SUFFIX>` — where the real file was moved to.
    pub suspect: PathBuf,
    /// `true` if a plain-config stub was written at `original` during
    /// enable (the common case; `false` only when the caller asked to
    /// skip stub creation).
    pub stub_created: bool,
}

/// Full ledger persisted to [`PLAIN_LEDGER_FILENAME`].
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PlainLedger {
    /// All ledger entries, in enable order.
    pub entries: Vec<LedgerEntry>,
}

/// One row of [`enable`]'s outcome.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct EnableRow {
    /// Original path the caller asked us to disable.
    pub original: PathBuf,
    /// Action actually taken for this target.
    pub action: EnableAction,
}

/// Outcome variants for a single target.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub enum EnableAction {
    /// File was renamed to `<original>.suspect` and a stub was written
    /// at `original`.
    Renamed,
    /// File was renamed to `<original>.suspect` and **no** stub was
    /// written (caller opted out).
    RenamedNoStub,
    /// `<original>.suspect` already existed; we did nothing to avoid
    /// clobbering a prior backup.
    SkippedAlreadySuspect,
    /// `original` does not exist; nothing to disable.
    SkippedMissing,
    /// `--dry-run`: would have renamed, but didn't.
    WouldRename,
    /// `--dry-run`: would have skipped (one of the Skipped reasons).
    WouldSkip { reason: String },
}

/// Outcome of [`enable`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EnableOutcome {
    /// Per-target action log.
    pub rows: Vec<EnableRow>,
    /// `true` when the call ran without `dry_run`.
    pub applied: bool,
    /// Ledger path that was (or would be) written.
    pub ledger_path: PathBuf,
}

/// One row of [`restore`]'s outcome.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct RestoreRow {
    /// The `original` path from the ledger.
    pub original: PathBuf,
    /// Action actually taken.
    pub action: RestoreAction,
}

/// Outcome variants for restoring a single ledger entry.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub enum RestoreAction {
    /// `<original>.suspect` was renamed back to `original`. Any stub
    /// previously at `original` was overwritten.
    Restored,
    /// The `.suspect` file was not found; the ledger entry is stale.
    SuspectMissing,
    /// `--dry-run`: would have restored.
    WouldRestore,
    /// `--dry-run`: would have skipped (suspect missing).
    WouldSkip { reason: String },
}

/// Outcome of [`restore`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RestoreOutcome {
    /// Per-entry action log.
    pub rows: Vec<RestoreRow>,
    /// `true` when the call ran without `dry_run`.
    pub applied: bool,
    /// Ledger path that was (or would be) removed.
    pub ledger_path: PathBuf,
}

/// Resolved Plain Mode status — what the on-disk ledger says right now.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PlainStatus {
    /// `true` when the ledger exists and has at least one entry.
    pub active: bool,
    /// All ledger entries (empty when `active == false`).
    pub entries: Vec<LedgerEntry>,
    /// Ledger path that was read (whether or not it exists).
    pub ledger_path: PathBuf,
}

/// Read [`PlainStatus`] from disk.
///
/// # Errors
///
/// - [`crate::Error::Io`] on ledger read failure.
/// - [`crate::Error::Json`] on ledger parse failure.
pub fn status(paths: &Paths) -> Result<PlainStatus> {
    let ledger_path = paths.home.join(PLAIN_LEDGER_FILENAME);
    let entries = if ledger_path.exists() {
        let body = fs::read_to_string(&ledger_path)?;
        serde_json::from_str::<PlainLedger>(&body)?.entries
    } else {
        Vec::new()
    };
    Ok(PlainStatus {
        active: !entries.is_empty(),
        entries,
        ledger_path,
    })
}

/// Enable Plain Mode for the given target paths.
///
/// Each target is processed independently; failures on one target don't
/// abort the others (they get a `Skipped*` action in the outcome). The
/// ledger is written only after every target has been processed and only
/// when `dry_run` is false.
///
/// # Errors
///
/// - [`crate::Error::Io`] on ledger directory creation or write failure.
/// - [`crate::Error::Json`] on ledger serialization failure.
pub fn enable(
    paths: &Paths,
    targets: &[PathBuf],
    dry_run: bool,
    write_stub: bool,
) -> Result<EnableOutcome> {
    let ledger_path = paths.home.join(PLAIN_LEDGER_FILENAME);
    let mut rows = Vec::with_capacity(targets.len());
    let mut new_entries = Vec::new();

    for target in targets {
        let suspect = suspect_path(target);
        let action = if !target.exists() {
            if dry_run {
                EnableAction::WouldSkip {
                    reason: "target does not exist".into(),
                }
            } else {
                EnableAction::SkippedMissing
            }
        } else if suspect.exists() {
            if dry_run {
                EnableAction::WouldSkip {
                    reason: "suspect backup already present".into(),
                }
            } else {
                EnableAction::SkippedAlreadySuspect
            }
        } else if dry_run {
            EnableAction::WouldRename
        } else {
            fs::rename(target, &suspect)?;
            if write_stub {
                fs::write(target, PLAIN_STUB_BODY)?;
            }
            new_entries.push(LedgerEntry {
                original: target.clone(),
                suspect: suspect.clone(),
                stub_created: write_stub,
            });
            if write_stub {
                EnableAction::Renamed
            } else {
                EnableAction::RenamedNoStub
            }
        };
        rows.push(EnableRow {
            original: target.clone(),
            action,
        });
    }

    if !dry_run && !new_entries.is_empty() {
        fs::create_dir_all(&paths.home)?;
        // Merge with any prior ledger so we don't lose earlier entries
        // (idempotent enable across sessions).
        let mut ledger = if ledger_path.exists() {
            let body = fs::read_to_string(&ledger_path)?;
            serde_json::from_str::<PlainLedger>(&body).unwrap_or_default()
        } else {
            PlainLedger::default()
        };
        ledger.entries.extend(new_entries);
        let body = serde_json::to_string_pretty(&ledger)?;
        fs::write(&ledger_path, body)?;
    }

    Ok(EnableOutcome {
        rows,
        applied: !dry_run,
        ledger_path,
    })
}

/// Restore everything in the ledger.
///
/// For each entry: rename `suspect` back to `original` (overwriting any
/// stub that lived there), then drop the entry. Entries whose suspect
/// file is missing are surfaced as `SuspectMissing` but don't abort the
/// rest. On success the ledger file is removed.
///
/// # Errors
///
/// - [`crate::Error::Io`] on rename / write / delete failure.
/// - [`crate::Error::Json`] on ledger parse failure.
pub fn restore(paths: &Paths, dry_run: bool) -> Result<RestoreOutcome> {
    let ledger_path = paths.home.join(PLAIN_LEDGER_FILENAME);
    if !ledger_path.exists() {
        return Ok(RestoreOutcome {
            rows: Vec::new(),
            applied: !dry_run,
            ledger_path,
        });
    }

    let body = fs::read_to_string(&ledger_path)?;
    let ledger: PlainLedger = serde_json::from_str(&body)?;
    let mut rows = Vec::with_capacity(ledger.entries.len());

    for entry in &ledger.entries {
        let action = if !entry.suspect.exists() {
            if dry_run {
                RestoreAction::WouldSkip {
                    reason: "suspect file missing".into(),
                }
            } else {
                RestoreAction::SuspectMissing
            }
        } else if dry_run {
            RestoreAction::WouldRestore
        } else {
            // Remove any stub / file currently at `original` so the rename
            // below succeeds on platforms that don't overwrite atomically.
            if entry.original.exists() {
                fs::remove_file(&entry.original)?;
            }
            fs::rename(&entry.suspect, &entry.original)?;
            RestoreAction::Restored
        };
        rows.push(RestoreRow {
            original: entry.original.clone(),
            action,
        });
    }

    if !dry_run {
        fs::remove_file(&ledger_path)?;
    }

    Ok(RestoreOutcome {
        rows,
        applied: !dry_run,
        ledger_path,
    })
}

/// Compute the suspect-sidecar path for a given original path.
fn suspect_path(original: &Path) -> PathBuf {
    let mut s = original.as_os_str().to_os_string();
    s.push(SUSPECT_SUFFIX);
    PathBuf::from(s)
}

/// Default Plain Mode targets — currently just `<cwd>/.mcp.json`.
/// Callers can extend this list with their own absolute paths.
pub fn default_targets() -> Vec<PathBuf> {
    vec![PathBuf::from(".mcp.json")]
}

#[cfg(test)]
mod tests {
    use super::*;

    fn paths_for(tmp: &tempfile::TempDir) -> Paths {
        Paths {
            home: tmp.path().to_path_buf(),
            user_home: tmp.path().to_path_buf(),
        }
    }

    fn write(p: &Path, body: &str) {
        std::fs::write(p, body).unwrap();
    }

    #[test]
    fn enable_dry_run_does_not_touch_filesystem() {
        let tmp = tempfile::tempdir().unwrap();
        let target = tmp.path().join(".mcp.json");
        write(&target, "{\"mcpServers\":{\"x\":1}}");
        let original_body = std::fs::read_to_string(&target).unwrap();

        let outcome = enable(&paths_for(&tmp), &[target.clone()], true, true).unwrap();
        assert!(!outcome.applied);
        assert_eq!(outcome.rows[0].action, EnableAction::WouldRename);
        // Original file untouched, suspect not created, no ledger.
        assert!(target.exists());
        assert_eq!(std::fs::read_to_string(&target).unwrap(), original_body);
        assert!(!suspect_path(&target).exists());
        assert!(!outcome.ledger_path.exists());
    }

    #[test]
    fn enable_renames_and_writes_stub() {
        let tmp = tempfile::tempdir().unwrap();
        let target = tmp.path().join(".mcp.json");
        write(
            &target,
            "{\"mcpServers\":{\"original\":{\"command\":\"x\"}}}",
        );
        let suspect = suspect_path(&target);

        let outcome = enable(&paths_for(&tmp), &[target.clone()], false, true).unwrap();
        assert!(outcome.applied);
        assert_eq!(outcome.rows[0].action, EnableAction::Renamed);
        assert!(suspect.exists(), "suspect file must be created");
        assert!(target.exists(), "stub must be at original path");
        let stub = std::fs::read_to_string(&target).unwrap();
        assert_eq!(stub, PLAIN_STUB_BODY);
        assert!(outcome.ledger_path.exists());
    }

    #[test]
    fn enable_skips_when_suspect_already_present() {
        let tmp = tempfile::tempdir().unwrap();
        let target = tmp.path().join(".mcp.json");
        write(&target, "{}");
        write(&suspect_path(&target), "prior-backup");

        let outcome = enable(&paths_for(&tmp), &[target.clone()], false, true).unwrap();
        assert_eq!(outcome.rows[0].action, EnableAction::SkippedAlreadySuspect);
        // The prior suspect must NOT be overwritten.
        assert_eq!(
            std::fs::read_to_string(suspect_path(&target)).unwrap(),
            "prior-backup"
        );
        // No ledger row was added (since nothing happened).
        assert!(!outcome.ledger_path.exists());
    }

    #[test]
    fn restore_round_trip_returns_original_content() {
        let tmp = tempfile::tempdir().unwrap();
        let target = tmp.path().join(".mcp.json");
        let body = "{\"mcpServers\":{\"real\":{\"command\":\"x\"}}}";
        write(&target, body);

        enable(&paths_for(&tmp), &[target.clone()], false, true).unwrap();
        assert_ne!(std::fs::read_to_string(&target).unwrap(), body);

        let restore_outcome = restore(&paths_for(&tmp), false).unwrap();
        assert!(restore_outcome.applied);
        assert_eq!(restore_outcome.rows[0].action, RestoreAction::Restored);
        // Original content is back, ledger gone.
        assert_eq!(std::fs::read_to_string(&target).unwrap(), body);
        assert!(!suspect_path(&target).exists());
        assert!(!restore_outcome.ledger_path.exists());
    }

    #[test]
    fn status_reflects_ledger_state() {
        let tmp = tempfile::tempdir().unwrap();
        let target = tmp.path().join(".mcp.json");
        write(&target, "{}");

        let before = status(&paths_for(&tmp)).unwrap();
        assert!(!before.active);
        assert!(before.entries.is_empty());

        enable(&paths_for(&tmp), &[target.clone()], false, true).unwrap();
        let during = status(&paths_for(&tmp)).unwrap();
        assert!(during.active);
        assert_eq!(during.entries.len(), 1);
        assert_eq!(during.entries[0].original, target);

        restore(&paths_for(&tmp), false).unwrap();
        let after = status(&paths_for(&tmp)).unwrap();
        assert!(!after.active);
        assert!(after.entries.is_empty());
    }

    #[test]
    fn restore_with_no_ledger_is_a_noop() {
        let tmp = tempfile::tempdir().unwrap();
        let outcome = restore(&paths_for(&tmp), false).unwrap();
        assert!(outcome.rows.is_empty());
        // No error, no ledger left behind.
        assert!(!outcome.ledger_path.exists());
    }

    #[test]
    fn missing_target_yields_skipped_missing() {
        let tmp = tempfile::tempdir().unwrap();
        let outcome = enable(
            &paths_for(&tmp),
            &[tmp.path().join("not-there.json")],
            false,
            true,
        )
        .unwrap();
        assert_eq!(outcome.rows[0].action, EnableAction::SkippedMissing);
        assert!(!outcome.ledger_path.exists());
    }
}