pub struct PathGuard { /* private fields */ }Expand description
Confines file-tool path access to the workspace root plus any explicitly allowed extra roots.
Implementations§
Source§impl PathGuard
impl PathGuard
Sourcepub fn builder(root: &Path) -> PathGuardBuilder
pub fn builder(root: &Path) -> PathGuardBuilder
Start building a guard rooted at root, with the default blocked
prefixes and no extra allowed roots.
Sourcepub fn new(root: &Path) -> Result<Self, String>
pub fn new(root: &Path) -> Result<Self, String>
Minimal guard with no extra allowed roots — the workspace root only.
Shorthand for PathGuard::builder(root).build(); this is the form used
by tests and by callers with no path configuration.
Sourcepub fn configured(
root: &Path,
allowed: &[String],
home: Option<&Path>,
extra_blocked: &[String],
) -> Result<Self, String>
pub fn configured( root: &Path, allowed: &[String], home: Option<&Path>, extra_blocked: &[String], ) -> Result<Self, String>
Build a guard from already-resolved configuration in one call.
allowed entries follow the same rules as the allowed_paths setting:
absolute, ~-prefixed (expanded with home), or relative to root.
extra_blocked is appended to DEFAULT_BLOCKED_PREFIXES.
Sourcepub fn allowed_roots(&self) -> &[PathBuf]
pub fn allowed_roots(&self) -> &[PathBuf]
The extra allowed roots (the workspace root is implicit and first).
Sourcepub fn blocked_prefixes(&self) -> &[PathBuf]
pub fn blocked_prefixes(&self) -> &[PathBuf]
The blocked prefixes consulted for non-root paths.
Sourcepub fn resolve_contained(&self, raw: &str) -> Result<PathBuf, String>
pub fn resolve_contained(&self, raw: &str) -> Result<PathBuf, String>
Resolve raw (a path as supplied by a tool call) and verify it stays
within an allowed root.
Returns Ok(resolved) with the fully resolved absolute path on
success, or Err(message) describing the violation. Callers must use
the returned path rather than the raw argument: the raw string may be
relative, and a relative path means different things to this guard
(resolved against the workspace root) and to std::fs (resolved
against the process cwd).
Sourcepub fn contains(&self, raw: &str) -> bool
pub fn contains(&self, raw: &str) -> bool
Returns true if raw resolves to a path inside an allowed root.
Sourcepub fn open_read_contained(&self, path: &Path) -> Result<File, String>
pub fn open_read_contained(&self, path: &Path) -> Result<File, String>
Open path for reading, then verify the open descriptor is contained.
resolve_contained proves containment at check time, but the handler
opens the path later, and the kernel re-resolves every component at
open(2) — a racing process can swap a directory for a symlink in
between (the process sandbox mounts the workspace read-write, so a
sandboxed command can do exactly that). Verifying the descriptor’s
real path after the open closes that race.
Sourcepub fn create_contained(&self, path: &Path) -> Result<File, String>
pub fn create_contained(&self, path: &Path) -> Result<File, String>
Open path for writing (create/truncate), then verify containment.
Sourcepub fn open_dir_contained(&self, path: &Path) -> Result<File, String>
pub fn open_dir_contained(&self, path: &Path) -> Result<File, String>
Open path as a directory, then verify the open descriptor.
Sourcepub fn read_contained(&self, path: &Path) -> Result<String, String>
pub fn read_contained(&self, path: &Path) -> Result<String, String>
Read a file to a string through a verified descriptor.
Sourcepub fn write_contained(&self, path: &Path, content: &str) -> Result<(), String>
pub fn write_contained(&self, path: &Path, content: &str) -> Result<(), String>
Write a file through a verified descriptor, creating parent
directories one component at a time with each new directory verified
the same way (a plain create_dir_all would follow a symlink swapped
into place after the guard’s check).
Sourcepub fn create_dir_all_contained(&self, dir: &Path) -> Result<(), String>
pub fn create_dir_all_contained(&self, dir: &Path) -> Result<(), String>
create_dir_all with per-component descriptor verification, so a
symlink swapped in after the guard’s check cannot redirect directory
creation outside an allowed root.
Sourcepub fn check_glob_pattern(&self, pattern: &str) -> Result<(), String>
pub fn check_glob_pattern(&self, pattern: &str) -> Result<(), String>
Check a glob pattern against the guard: the static (non-wildcard) prefix of the pattern must resolve inside an allowed root.
Bare patterns like **/*.rs are anchored at the workspace root and
always pass. Absolute or ..-escaping prefixes are rejected.
Sourcepub fn violation_message(&self, raw: &str) -> String
pub fn violation_message(&self, raw: &str) -> String
Standard error message for a violation, usable as a tool result.