cageforge-path 0.6.1

Cross-platform native path validation for Rust sandbox policies
Documentation

Independent project: Cageforge is not affiliated with, sponsored by, or endorsed by OpenAI.

This crate is a supporting component of the cageforge crate, a cross-platform Rust sandbox for AI agents and untrusted code.

cageforge-path

Read the shared configuration guide for TOML profiles, symbolic paths, local IPC, and first-launch resource rules.

cageforge-path centralizes the small set of path comparisons that must agree across Cageforge crates. It treats path components case-sensitively on POSIX systems and case-insensitively on Windows. Windows drive, UNC, verbatim, and supported device aliases share one lexical identity; malformed native strings remain distinct instead of passing through lossy Unicode conversion.

Portable configuration uses [PathDialect] and [PlatformPathKey] when it validates or merges a path for a target platform other than the compiling host. This keeps a Windows overlay's drive, UNC, separator, and case rules intact even when the TOML is read on Linux or macOS.

The crate does not access the filesystem, resolve symlinks, or canonicalize paths. Native backends remain responsible for those operations.

When to use it

Use this crate when your own code stores, compares, or validates paths and must agree with Cageforge's policy and configuration layers. It is especially useful for workspace-root maps, protected metadata paths, and component-aware containment checks.

Use a native executor for filesystem enforcement. This crate answers lexical questions such as "is this path below that path?"; the executor adds symlink, junction/reparse-point, mount, and TOCTOU-safe checks before opening a file.

Workspace role

cageforge-path is the shared lexical path-semantics layer.

Crate Role in the relationship
cageforge-policy Uses component-aware equality, containment, and path-pattern comparison.
cageforge-command Validates command working-directory traversal.
cageforge-config Validates configured workspace-root declarations.
cageforge-policy-compose Deduplicates and compares effective workspace roots.
cageforge-upstream-review Validates repository-relative review paths.
cageforge Re-exports the path model through the application-facing crate.

The helpers define lexical relationships only. A backend still owns filesystem I/O, symlink resolution, canonicalization, and platform capability checks.

Case semantics

The following table is the single path-identity rule shared by the workspace. It is not configurable through TOML or the Rust API.

Value or operation POSIX (Linux/macOS) Windows
Absolute and workspace paths Case-sensitive Case-insensitive
workspace_roots Case-sensitive Case-insensitive
Protected paths such as .git Case-sensitive Case-insensitive
Unix socket paths Case-sensitive Case-insensitive path comparison
Filesystem glob components Case-sensitive Case-insensitive
Environment variable names and filters Case-insensitive by policy Case-insensitive by policy
Domain names and domain globs Case-insensitive by protocol Case-insensitive by protocol
Profile names and ordinary strings Exact comparison Exact comparison

Only the filesystem-related rows use this crate's native path helpers. The environment and domain rows intentionally have their own portable semantics.

API

  • is_within(path, root) checks component-aware containment and does not treat /work-other as a child of /work.
  • contains_component_path(path, needle) finds a complete relative component path such as .git without matching a partial component such as .github.
  • paths_equal(left, right) compares complete native path components.
  • NativePathKey supplies the same equality, hashing, and ordering identity for maps and sets.
  • PathDialect selects POSIX or Windows lexical syntax independently of the compiling host.
  • is_absolute_text and contains_parent_traversal_text validate path text for that explicit dialect.
  • PlatformPathKey supplies target-platform equality, hashing, and ordering for portable configuration merges.
  • resolve_lexical_path(base, declaration) resolves a relative or absolute declaration after applying the shared empty, NUL, and parent-traversal checks.
  • normalize_lexical_path(path) exposes supported native alias normalization without filesystem access.
  • strings_equal(left, right) and case_fold(value) expose the same native comparison rule for path-derived glob matching.
  • contains_parent_traversal(path) detects lexical .. components.

The helpers are used by policy evaluation, command working-directory validation, policy composition, and the upstream-review tool so those layers cannot silently develop different Windows behavior.

Smallest useful example

use cageforge_path::{is_within, paths_equal, NativePathKey};
use std::path::Path;

let workspace = Path::new("/work/project");
assert!(is_within(Path::new("/work/project/src/lib.rs"), workspace));
assert!(!is_within(Path::new("/work/project-old"), workspace));
assert!(paths_equal(workspace, Path::new("/work/project")));

let _map_key = NativePathKey::new(workspace);

The policy, command, config, and composition crates already use this layer internally. Depend on it directly when an integration layer builds native path maps or compares paths before handing values to those crates.

API reference: cageforge-path on docs.rs.

Repository: github.com/m62624/cageforge.