monty_fs/lib.rs
1//! Filesystem mounting system for sandboxed execution.
2//!
3//! Provides [`MountTable`], which maps virtual paths to real host directories
4//! with configurable access modes. When sandbox code calls filesystem methods
5//! like `Path.read_text()`, the mount table intercepts the operation, resolves
6//! the virtual path, and executes it according to the mount mode.
7//!
8//! This crate is HOST-side code: it performs real `std::fs` I/O and is linked
9//! only by host/parent crates (`monty-pool`, the CLI, bindings). The `monty`
10//! interpreter crate deliberately does not depend on it — sandboxed code can
11//! only *request* filesystem operations by suspending with an
12//! [`OsFunctionCall`](monty_types::OsFunctionCall), which a host holding a
13//! [`MountTable`] services via [`MountTable::handle_os_call`].
14//!
15//! # Security
16//!
17//! **The monty runtime MUST NEVER read, write, or obtain any information about
18//! any file or directory outside the specific directory that is mounted.**
19//!
20//! Enforced by the operating system, not by path arithmetic: each mount holds
21//! a `cap_std::fs::Dir` opened once at mount time, and every operation is
22//! performed relative to that descriptor, which refuses to resolve past its
23//! own root. `path_security` only normalizes the virtual path and strips the
24//! mount prefix — it is path policy, not the boundary.
25//! Each mount has an aggregate memory budget, defaulting to
26//! [`DEFAULT_MEMORY_USAGE_LIMIT`], for retained overlay data and results.
27//!
28//! # Mount Modes
29//!
30//! - [`MountMode::ReadWrite`] — full read/write access to the host directory
31//! - [`MountMode::ReadOnly`] — reads work, writes raise `PermissionError`
32//! - [`MountMode::OverlayMemory`] — reads fall through to host; writes stored in memory
33
34pub use error::MountError;
35pub use mount_mode::MountMode;
36pub use mount_table::{DEFAULT_MEMORY_USAGE_LIMIT, Mount, MountCallOutcome, MountRoot, MountTable};
37pub use overlay_state::OverlayState;
38
39mod common;
40mod direct;
41mod dispatch;
42mod error;
43mod mount_mode;
44mod mount_table;
45mod overlay;
46mod overlay_state;
47mod path_security;