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.

String-matching libraries maintain lists of dangerous patterns — .., %2e%2e, %c0%ae (overlong UTF-8), . (HTML entities), full-width Unicode dots, zero-width characters, and dozens more. Every new encoding trick requires a new blocklist entry, and a single miss is a bypass.

strict-path doesn't play that game. It asks the OS to resolve the path, then checks where it landed. URL-encoded %2e%2e isn't decoded — it's a literal directory name containing percent signs. Overlong UTF-8 sequences, HTML entities, code-page homoglyphs (¥→\ in CP932, ₩→\ in CP949) — none of these matter because the OS never interprets them as path separators or traversal sequences. The canonicalized result either falls inside the boundary or it doesn't.

This is the same principle behind SQL prepared statements: instead of escaping every dangerous character (and inevitably missing one), you separate code from data structurally. strict-path separates path resolution from path text, making the entire class of encoding-bypass attacks irrelevant by design.

⚡ Get Secure in 30 Seconds

[dependencies]

strict-path = "0.2"  # every dependency closes a security gap — see "Zero Idle Dependencies" below

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)
• 🔒 Thread-safe — all types are Send + Sync; share across threads and async tasks
• 🤖 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 where LLMs and humans naturally reach for the correct pattern — wrong code either doesn't compile, or the compiler tells you exactly what to do instead.

• No AsRef<Path>, no Deref — if StrictPath implemented these, anything could call .join() on it and build a new path that bypasses boundary validation entirely. That one method on Path undoes everything strict_join() enforces. The type system makes it unreachable.
• 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 names the trust anchor explicitly: it holds the canonicalized boundary directory and can be passed by name in function signatures. Every path produced via strict_join is proven to stay within it. Naming the boundary in the signature makes the security contract compile-time-visible — the type itself proves the caller provided a vetted anchor.

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 can escape the tenant root.
// 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. The example below gives a function that only accepts public assets — handing it a user-uploaded file is a compile error, not a runtime check:

use strict_path::{PathBoundary, StrictPath};

struct PublicAssets;
struct UserUploads;

fn serve_public_asset(file: &StrictPath<PublicAssets>) { /* safe to stream to any caller */ }

let assets  = PathBoundary::<PublicAssets>::try_new_create("./assets")?;
let uploads = PathBoundary::<UserUploads>::try_new_create("./uploads")?;

// Untrusted input from request parameters, form data, database, etc.
let requested_css   = "style.css";   // From request: /static/style.css
let uploaded_avatar = "avatar.jpg";  // From form: <input type="file">

let css:    StrictPath<PublicAssets> = assets.strict_join(requested_css)?;
let avatar: StrictPath<UserUploads>  = uploads.strict_join(uploaded_avatar)?;

serve_public_asset(&css);       // ✅ OK — PublicAssets matches
// serve_public_asset(&avatar); // ❌ Compile error — UserUploads is not PublicAssets

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

🔒 Zero Idle Dependencies

Every runtime dependency exists to close a specific security gap. Each is audited, tested against attack payloads, and covered by cargo audit in CI.

On Unix the total runtime tree is 2 crates (soft-canonicalize + proc-canonicalize). On Windows it adds dunce (zero transitive deps). No idle dependencies — if a crate is in the tree, it has a security job.

• 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