Module containment 

Workspace path containment.

Ensures that file operations stay within a designated workspace directory, preventing path traversal attacks via ../ or symlinks that point outside the workspace root.

Two-layer defense:

1. Syntactic check (no I/O): rejects ../ traversal that goes beyond root depth
2. Symlink-aware check: canonicalizes and verifies the resolved path is contained

Policy choices for different use cases

Policy	Use when	Example
Reject	MCP server or untrusted agent output (default for safety)	CLI tools exposed over network
AllowIfContained	Trusted library use, absolute paths inside workspace only	Standard agent in project dir
AllowAdditionalRoots(...) or builder	Agents needing /tmp (incl. macOS symlinks), build artifacts, scratch dirs while keeping guard for sensitive paths	Bline --yolo or experiment mode

Threat model note: MCP uses untrusted LLM-generated paths, so strict Reject. Direct library embedding (e.g. Bline) can use relaxed policies because the host controls the agent. Even with extra roots, escapes out of allowed roots are still blocked.

Example

use patchloom::containment::{PathGuard, AbsolutePathPolicy};
use std::path::PathBuf;

let guard = PathGuard::new(
    PathBuf::from("/home/user/project"),
    AbsolutePathPolicy::Reject,
).unwrap();

// OK: relative path within workspace
let resolved = guard.check_path("src/main.rs").unwrap();

// Error: escapes workspace
assert!(guard.check_path("../../etc/passwd").is_err());

Builder for agents

use patchloom::containment::PathGuard;

let guard = PathGuard::builder(std::env::current_dir().unwrap())
    .allow_temp_directory()           // /tmp + std temp (handles macOS symlinks)
    .allow_root("/tmp/my-experiments")
    .build()
    .unwrap();

Structs

PathGuard

Workspace path guard with cached canonical root.

PathGuardBuilder

Builder for PathGuard to ergonomically configure flexible policies (useful for library users like agents that need temp dirs or extra roots).

Enums

AbsolutePathPolicy

Policy for handling absolute paths.

ContainmentError

Errors from workspace path validation.