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.

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.

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.

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.
• 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.