Module policy 

Path access policy for sandboxing filesystem operations.

Implement PathPolicy to control which paths Lua scripts can access.

Built-in policies

Policy	Behaviour
Unrestricted	No checks (default)
[Sandboxed]	Capability-based sandbox via [cap_std]

Security architecture

The sandbox uses a two-layer design:

1. Routing layer (normalize_for_matching) — best-effort path resolution to select the correct Dir handle. This layer resolves platform symlinks (e.g. /tmp → /private/tmp on macOS) but is not the security boundary.

2. Enforcement layer ([cap_std]) — all actual I/O goes through cap_std::fs::Dir, which uses openat2 + RESOLVE_BENEATH on Linux 5.6+ and manual per-component resolution on other platforms. This prevents symlink escapes, .. traversal, and absolute-path breakout at the OS level.

TOCTOU note

There is an inherent window between normalize_for_matching (which may call canonicalize()) and the subsequent cap_std I/O. A symlink replaced in that window cannot escape the sandbox because cap_std re-validates the path at I/O time, but it may cause unexpected errors or access a different file within the same sandbox.

Encoding — UTF-8 only (by design)

All path arguments are received as Rust String (UTF-8). Non-UTF-8 Lua strings are rejected at the FromLua boundary. Returned paths use to_string_lossy, replacing any non-UTF-8 bytes with U+FFFD.

Raw byte (OsStr) round-tripping is intentionally unsupported — see crate-level docs for rationale. Ref: https://docs.rs/mlua/latest/mlua/struct.String.html

Structs

EnvAllowList

Allow access only to listed environment variable names.

FsAccess

Opaque handle to a policy-resolved filesystem path.

HttpAllowList

Allow only requests to hosts matching the given patterns.

LlmAllowList

Allow only requests to listed LLM providers.

PolicyError

Error type returned by policy check / resolve methods.

Unrestricted

No restrictions — every path is allowed as-is.

Enums

PathOp

Filesystem operation kind.

Traits

EnvPolicy

Policy that decides whether a given environment variable may be accessed.

HttpPolicy

Policy that decides whether a given URL may be accessed.

LlmPolicy

Policy that decides whether a given LLM request may be sent.

PathPolicy

Policy that decides whether a given path may be accessed.