strict-path

Secure path handling for untrusted input. Paths from users, config files, archives, or AI agents can't escape the directory you put them in — regardless of symlinks, encoding tricks, or platform quirks. 19+ real-world CVEs covered.

Prepared statements prevent SQL injection. strict-path prevents path injection.

🔍 Why String Checking Isn't Enough

You strip .. and check for /. But attackers have a dozen other vectors:

How it works: strict-path resolves the path on disk — follows symlinks, expands short names, normalizes encoding — then proves the resolved path is inside the boundary. The input string is irrelevant. Only where the path actually leads matters.

⚡ Get Secure in 30 Seconds

[dependencies]

strict-path = "0.2"

use strict_path::StrictPath;

// Untrusted input: user upload, API param, config value, AI agent output, archive entry...
let file = StrictPath::with_boundary("/var/app/downloads")?
    .strict_join(&untrusted_user_input)?; // Every attack vector above → Err(PathEscapesBoundary)

let contents = file.read()?; // Built-in safe I/O — stays within the secure API

// Third-party crate needs AsRef<Path>?
third_party::process(file.interop_path()); // &OsStr (implements AsRef<Path>)

If the input resolves outside the boundary — by any mechanism — strict_join returns Err.

What you get beyond path validation:

• 🛡️ Built-in I/O — read(), write(), create_dir_all(), read_dir() — no need to drop to std::fs
• 📐 Compile-time markers — StrictPath<UserUploads> vs StrictPath<SystemConfig> can't be mixed up
• ⚡ Dual modes — StrictPath (detect & reject escapes) or VirtualPath (clamp & contain)
• 🤖 LLM-ready — doc comments and context files designed for AI agents with function calling

Why the API looks the way it does:

This crate combines Rust's type system with Python's "one obvious way to do it" philosophy to build an API that LLMs and humans physically cannot misuse — wrong code doesn't compile, and the compiler itself teaches you the fix.

• No AsRef<Path>, no Deref — if StrictPath implemented these, any code could silently call std::fs::read(path) and skip the boundary check entirely. There is no "quick shortcut" that compiles yet bypasses security. The type system rules it out.
• interop_path() returns &OsStr, not &Path — Path has .join() and .parent(), which let you build new unvalidated paths. OsStr has none of that — it's a one-way exit to third-party crates with no way to accidentally re-enter path manipulation.
• One method per operation — every operation has exactly one method. An LLM scanning the API can't pick the wrong overload because there isn't one. No aliases, no convenience wrappers, no "which one is the secure version?" Even the weakest model gets it right on the first try.
• #[must_use] with instructions, not just warnings — the compiler becomes the documentation. When an LLM generates code and forgets to handle a strict_join() result, it doesn't get a generic "unused Result" — it gets a message like "always handle the Result to detect path traversal attacks". The LLM reads the compiler output, self-corrects, and gets it right on the next pass. No docs lookup needed.
• Doc comments explain why, not just what — every non-trivial function documents the reasoning behind the code, what attack a check prevents, or what invariant it enforces. An LLM working with just the source file can reason about design intent without any external context.
• Context7 and LLM context files — machine-readable API references that ship with the crate, sized for different context windows. Critical mistakes front-loaded so an LLM agent hits the important stuff first.

Is this overkill for my use case? If you accept paths from users, config files, archives, databases, or AI agents — no, this is the minimum. If all your paths are hardcoded constants — use std::path. See choosing canonicalized vs lexical.

📖 New to strict-path? Start with the Tutorial: Chapter 1 - The Basic Promise →

Our doc comments and LLM_CONTEXT_FULL.md are designed for LLMs with function calling — enabling AI agents to use this crate safely for file operations.

LLM agent prompt (copy/paste):

Fetch and follow this reference (single source of truth):
https://github.com/DK26/strict-path-rs/blob/main/LLM_CONTEXT_FULL.md

Context7 style:

Fetch and follow this reference (single source of truth):
https://github.com/DK26/strict-path-rs/blob/main/LLM_CONTEXT.md

📖 Security Methodology → | 📚 Built-in I/O Methods → | 📚 Anti-Patterns →

🎯 StrictPath vs VirtualPath: When to Use What

Which type should I use?

• Path/PathBuf (std): When the path comes from a safe source within your control, not external input.
• StrictPath: When you want to restrict paths to a specific boundary and error if they escape.
• VirtualPath: When you want to provide path freedom under isolation.

Choose StrictPath (90% of cases):

• Archive extraction, config loading
• File uploads to shared storage (admin panels, CMS assets, single-tenant apps)
• LLM/AI agent file operations
• Shared system resources (logs, cache, assets)
• Any case where escaping a path boundary, is considered malicious

Choose VirtualPath (10% of cases):

• Multi-tenant file uploads (SaaS per-user storage, isolated user directories)
• Multi-tenant isolation (per-user filesystem views)
• Malware analysis sandboxes
• Container-like plugins
• Any case where you would like to allow freedom of operations under complete isolation

📖 Complete Decision Matrix → | 📚 More Examples →

🚀 More Real-World Examples

Archive Extraction (Zip Slip Prevention)

PathBoundary is a special type that represents a boundary for paths. It is optional, and could be used to express parts in our code where we expect a path to represent a boundary path:

use strict_path::PathBoundary;

// Prevents CVE-2018-1000178 (Zip Slip) automatically (https://snyk.io/research/zip-slip-vulnerability)
fn extract_archive(
    extraction_dir: PathBoundary,
    archive_entries: impl IntoIterator<Item=(String, Vec<u8>)>) -> std::io::Result<()> {

    for (entry_path, data) in archive_entries {
        // Malicious paths like "../../../etc/passwd" → Err(PathEscapesBoundary)
        let safe_file = extraction_dir.strict_join(&entry_path)?;
        safe_file.create_parent_dir_all()?;
        safe_file.write(&data)?;
    }
    Ok(())
}

The equivalent PathBoundary for VirtualPath type is the VirtualRoot type.

Multi-Tenant Isolation

use strict_path::VirtualRoot;

// No path-traversal or symlinks, could escape a tenant. 
// Everything is clamped to the virtual root, including symlink resolutions.
fn handle_file_request(tenant_id: &str, requested_path: &str) -> std::io::Result<Vec<u8>> {
    let tenant_root = VirtualRoot::try_new_create(format!("./tenants/{tenant_id}"))?;
    
    // "../../other_tenant/secrets.txt" → clamped to "/other_tenant/secrets.txt" in THIS tenant
    let user_file = tenant_root.virtual_join(requested_path)?;
    user_file.read()
}

🧠 Compile-Time Safety with Markers

StrictPath<Marker> enables domain separation and authorization at compile time:

struct UserFiles;
struct SystemFiles;

fn process_user(f: &StrictPath<UserFiles>) -> Vec<u8> { f.read().unwrap() }

let user_boundary = PathBoundary::<UserFiles>::try_new_create("./data/users")?;
let sys_boundary = PathBoundary::<SystemFiles>::try_new_create("./system")?;

let user_input = get_filename_from_request();
let user_file = user_boundary.strict_join(user_input)?;
process_user(&user_file); // ✅ OK - correct marker type

let sys_file = sys_boundary.strict_join("config.toml")?;
// process_user(&sys_file); // ❌ Compile error - wrong marker type!

📖 Complete Marker Tutorial → - Authorization patterns, permission matrices, change_marker() usage

vs soft-canonicalize

Compared with manual soft-canonicalize path validations:

• soft-canonicalize = low-level path resolution engine (returns PathBuf)
• strict-path = high-level security API (returns StrictPath<Marker> with compile-time guarantees: fit for LLM era)

🔌 Ecosystem Integration

Compose with standard Rust crates for complete solutions:

📚 Complete Integration Guide →

📚 Learn More

📖 API Docs | 📚 User Guide | 📚 Anti-Patterns | 📖 Security Methodology | 🧭 Canonicalized vs Lexical | 🛠️ soft-canonicalize

📄 License

MIT OR Apache-2.0