> **Independent project:** Cageforge is not affiliated with, sponsored by, or endorsed by OpenAI.
This crate is a supporting component of the [`cageforge`](https://crates.io/crates/cageforge) crate, a cross-platform Rust sandbox for AI agents and untrusted code.
# cageforge-path
Read the shared [configuration guide](https://github.com/m62624/cageforge/blob/main/crates/cageforge-config/examples/CONFIGURATION_GUIDE.md) 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.
| `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.
| 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
```rust
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](https://docs.rs/cageforge-path/latest/cageforge_path/).
Repository: [github.com/m62624/cageforge](https://github.com/m62624/cageforge).