craft-cloud-local: confine every path through a Dir capability, not a path string

benandez's re-review reproduced three escapes the first confinement fix still
left open. A dangling symlink: canonicalize reported it as missing, so the
old confine_to_root walked up to root and accepted it, and write created the
symlink's target for real, outside root. A check-then-use race: confine_to_root
checked one path string and a later fs::read or fs::write resolved that same
string again, a second lookup a concurrently swapped link could land in
between. A hard link: write truncated the shared inode in place, with nothing
in a canonicalized path to show that another name pointed at the same file
outside root.

list, read, write and create now resolve every already segment-checked
relative path through a cap_std::fs::Dir capability opened on root, instead
of joining an absolute OS path and handing it to plain std::fs. cap_std
resolves one path component at a time against real, already-open directory
handles, so a symlink or a Windows junction cannot walk resolution above
root, dangling or not, and there is no separate check with a window for the
directory tree to change underneath it: the one resolution is the open. This
is the same family of guarantee craft-font-store already depends on through
cap-primitives, which cap_std is built on.

write no longer truncates its target in place either way: it writes a new
sibling file and renames it over the target, so a hard link's directory
entry is replaced rather than its shared content being overwritten.

Per that review's non-blocking notes: a name that already exists on disk
with an ordinary ':' or '\' byte (macOS stores a typed '/' as ':') stays
reachable by list and read, since neither character is a path separator on
any platform's filesystem; the stricter refusal now applies only to a name
being chosen by Create. Create also goes back to bringing a fresh root into
existence, matching its behaviour before the first confinement fix. A
Windows reserved device name (CON, COM1, CONIN$, with or without an
extension) is refused in a chosen name on every platform.

Regression tests reproduce all three escapes (dangling symlink, swapped-link
race, hard link), plus the previously missing coverage: a link in the folder
a Create targets, and a write test that actually reaches disk instead of
being refused for an unrelated reason before confinement ever ran. Verified
by hand that each of the three new write-path tests fails against the
pre-fix pattern (an absolute OS path joined by string concatenation) before
trusting them.
This commit is contained in:
William Dunn committed 2026-11-17 00:51:58 -05:00
1 parent e5e9433413
commit aa4647a777
5 files changed
+469 -170

No files matched your search

Generated
+13
View File
@@ -1074,6 +1074,18 @@ dependencies = [
"winx",
]
[[package]]
name = "cap-std"
version = "4.0.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c1ec78e242cfa2cfe276807ac2ecc00315a6c97786977414bcd1c3963b6c91b8"
dependencies = [
"cap-primitives",
"io-extras",
"io-lifetimes 3.0.1",
"rustix 1.1.5",
]
[[package]]
name = "cast"
version = "0.3.0"
@@ -1628,6 +1640,7 @@ dependencies = [
name = "craft-cloud-local"
version = "0.1.0"
dependencies = [
"cap-std",
"craft-cloud",
"craft-ui",
"egui",
+6
View File
@@ -11,6 +11,12 @@ description = "A reference CloudBackend over a local folder, proving the contrac
workspace = true
[dependencies]
# Resolution-time confinement: every path this crate resolves goes through a `Dir` capability
# opened on the configured root, never through an absolute OS path this crate builds itself.
# `craft-font-store` already depends on the lower-level `cap-primitives` for the same family of
# guarantee; this crate uses the ergonomic `cap-std` built on top of it instead of hand-rolling
# the equivalent `Dir`-style API again.
cap-std = "4"
craft-cloud = { workspace = true }
craft-ui = { workspace = true, features = ["cloud"] }
+29 -11
View File
@@ -6,16 +6,34 @@ no specific provider behind it.
## No-escape policy
Every path this crate is handed, a `Job::List`/`Read`/`Write` path or a `Job::Create` name, is
confined to the configured root before anything touches a filesystem.
confined to the configured root before anything touches a filesystem, in two layers.
A path's segments, and a `Create` name on its own, are accepted only when each one parses as a
single `Component::Normal`: no `..`, no `.`, no empty segment, no absolute form, and no Windows
drive letter, UNC path or backslash. That last group is refused on every platform this crate
builds for, not only on Windows, because a name reaches this backend from whatever platform the
UI runs on.
A path's segments are accepted only when each one parses as a single `Component::Normal`: no
`..`, no `.`, no empty segment, and no absolute form. A `Create` name goes through a stricter
check of its own, since it is one chosen name and not a path: it additionally refuses a
backslash, a colon, or a Windows reserved device name (`CON`, `COM1`, `CONIN$`, and so on), on
every platform this crate builds for, not only on Windows, because a chosen name reaches this
backend from whatever platform the UI runs on. An existing name that already has one of those
characters, discovered through `list`, stays reachable: `:` and `\` are not path separators on
any platform's filesystem, so refusing to read a real file back because of a byte in its name
(macOS stores a `/` typed in Finder as `:` on disk) would be a usability bug with no matching
security benefit.
Once a candidate path is built from nothing but checked names, it is still confirmed against a
symlink or (on Windows) a directory junction placed somewhere under the root: the nearest
ancestor that already exists is canonicalised and must stay under the canonicalised root. A path
that reaches outside the root this way is refused before any read, write, listing or creation
touches it.
The second layer is the one that actually keeps resolution inside the root: every already
segment-checked relative path is handed to a [`cap-std`](https://docs.rs/cap-std) `Dir`
capability opened on the root, never joined onto the root as an absolute OS path this crate
builds itself. `cap-std` resolves one path component at a time against real, already-open
directory handles, so a symlink or (on Windows) a directory junction anywhere under the root,
dangling or already pointing outside, cannot walk resolution above the root. There is no separate
"does this still look like it is inside the root" check with a window for the directory tree to
change underneath it between the check and the actual read or write; the one resolution is the
open.
## Hard links
A hard link is not a symlink, and this backend does not refuse one: from inside the sandbox the
inode it names is an ordinary file. What it protects instead is the shared inode's content: a
write never truncates its target in place. It writes a new sibling file and renames that sibling
over the target, so the target's directory entry is replaced rather than its bytes being
overwritten. A rename only ever changes one name; it does not reach through to any other name,
inside the root or out, that happens to point at the same inode.
+237 -117
View File
@@ -20,29 +20,55 @@
//! Every job answers on its own [`std::thread`]. [`CloudBackend::submit`]
//! must return before the file is opened, let alone read, or a twenty
//! megabyte document would freeze the window that called it.
//!
//! # The no-escape policy
//!
//! `Entry::id` and `Entry::path` are the same slash-separated path relative to
//! `root`, always starting with `/` below the root itself (the root's own
//! path is the empty string, matching [`Job::List`]'s contract), and a
//! [`Job::Create`] name is one plain file name, not a path at all. Neither is
//! an OS path string handed to `std::fs`. Confinement happens in two layers:
//!
//! 1. [`confine_segment`] (every path segment) and [`confine_name`] (a
//! `Create` name, stricter) reject `..`, `.`, an empty segment, an
//! absolute form, and anything that is not exactly one
//! [`std::path::Component::Normal`]. `confine_name` additionally refuses a
//! backslash, a colon, and a Windows reserved device name
//! (`CON`, `COM1`, `CONIN$`, ...) on every platform this crate builds for,
//! because a chosen name reaches this backend from whatever platform the
//! UI runs on. Browsing an *existing* name is more lenient: a literal `:`
//! or `\` already on disk (macOS stores a `/` typed in Finder as `:`) is
//! not itself a path separator on any platform's filesystem, so
//! `confine_segment` lets `list`, `read` and `write` keep such a name
//! reachable instead of discovering it and then refusing to open it.
//! 2. [`open_root`] opens `root` as a [`cap_std::fs::Dir`] capability once per
//! job. Every [`list`], [`read`], [`write`] and [`create`] routes its
//! already-segment-checked relative path through that one `Dir`, never
//! through an absolute OS path built by this crate. `cap_std` resolves one
//! component at a time against real, already-open directory handles, so a
//! symlink or a Windows junction anywhere under `root`, dangling or not,
//! cannot walk resolution above `root`: there is no separate "is this
//! still inside the root" check with a window for the directory tree to
//! change underneath it, because the one resolution *is* the open.
//!
//! A hard link is not a symlink and `cap_std` does not refuse one; the inode
//! it names is an ordinary file from inside the sandbox. [`write`] protects
//! it a different way: it always writes a sibling temporary file and renames
//! it over the target, rather than truncating the target in place. A rename
//! replaces one name's directory entry; it never reaches through to another
//! name that happens to point at the same inode outside `root`.
use std::ffi::OsStr;
use std::fs;
use std::io::Write as _;
use std::io::{Read as _, Write as _};
use std::path::{Component, Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use cap_std::fs::{Dir, OpenOptions};
use craft_cloud::{Capability, Entry, EntryKind};
use craft_ui::cloud::{Account, CloudBackend, Event, Fault, Job, Post};
/// Where "the cloud" lives for this backend: one directory on disk.
///
/// `Entry::id` and `Entry::path` are the same slash-separated path relative to
/// `root`, always starting with `/` below the root itself (the root's own
/// path is the empty string, matching [`Job::List`]'s contract). Neither is
/// an OS path; both go through [`resolve`] and then [`confine_to_root`]
/// before anything touches a filesystem. A [`Job::Create`] name is not a
/// path at all; it goes through the same per-segment check [`resolve`] uses,
/// [`confine_segment`], on its own. Together the two refuse `..`, an
/// absolute form, a Windows drive letter or UNC prefix, and a backslash,
/// regardless of which platform this crate is built for, since a name
/// reaches this backend from whatever platform the UI runs on. No-escape
/// through a symlink or a Windows junction is a separate policy, stated on
/// [`confine_to_root`] itself, and every one of [`list`], [`read`],
/// [`write`] and [`create`] applies it.
pub struct LocalBackend {
root: PathBuf,
/// Shown in the account badge. Nothing else reads it.
@@ -52,7 +78,10 @@ pub struct LocalBackend {
impl LocalBackend {
/// Treat `root` as the cloud. The directory is not created here; a
/// listing of a root that does not exist yet answers with a [`Fault`]
/// the same way a real provider's missing folder would.
/// the same way a real provider's missing folder would. [`Job::Create`]
/// is the one exception, and always has been: it brings a fresh root
/// into existence itself, the same way a first Save As does not require
/// the destination folder to already be there.
pub fn new(root: PathBuf) -> LocalBackend {
LocalBackend { root, display: "Local disk".to_owned() }
}
@@ -118,80 +147,84 @@ fn account(display: String) -> Account {
Account { display, capabilities: vec![Capability::Files, Capability::Etags], provider_linked: true }
}
/// Turns a [`Job`]'s slash-separated path into a real filesystem path under
/// `root`, refusing anything that is not a run of ordinary names.
/// Turns a [`Job`]'s slash-separated path into a path relative to `root`,
/// refusing anything that is not a run of ordinary names. The result is
/// never joined onto `root` as an OS path; every caller hands it to a
/// [`cap_std::fs::Dir`] opened on `root` instead, which is the layer that
/// actually keeps resolution from leaving `root`.
///
/// `.` and repeated or leading slashes are just an empty segment and are
/// skipped, the same way a browser's address bar collapses them. Every other
/// segment goes through [`confine_segment`], which is what actually refuses
/// `..`, an absolute form, a backslash or a drive letter, or anything else
/// that is not one ordinary name. This function never touches disk, so it
/// cannot see a symlink or a junction; [`confine_to_root`] is the other half
/// of the promise, and every caller of `resolve` runs both.
fn resolve(root: &Path, path: &str) -> Result<PathBuf, Fault> {
let mut real = root.to_path_buf();
/// segment goes through [`confine_segment`].
fn relative(path: &str) -> Result<PathBuf, Fault> {
let mut rel = PathBuf::new();
for segment in path.split('/') {
if segment.is_empty() || segment == "." {
continue;
}
real.push(confine_segment(segment)?);
rel.push(confine_segment(segment)?);
}
Ok(real)
Ok(rel)
}
/// Confines one path segment, or a whole [`Job::Create`] name, to a single
/// ordinary file or folder name.
/// Confines one path segment to a single ordinary file or folder name.
///
/// Accepted only when `segment` parses as exactly one [`Component::Normal`]
/// equal to `segment` itself: no empty name, no `.` or `..`, no absolute
/// form, and nothing left over for a second component to hide in. A
/// `std::path::Component` parse alone does not catch every one of those on
/// every platform; a Unix build's parser does not know what `C:` or
/// `\\server\share` mean, so it would wave a Windows drive letter or a UNC
/// prefix straight through as one ordinary name. A `:` or a `\` is refused
/// outright first, on every platform, for exactly that reason: a name
/// reaches this backend's public [`CloudBackend::submit`] from whatever
/// platform the UI happens to run on, and a Windows-shaped escape must not
/// slip past a Linux build's narrower native parser, or the reverse.
/// form, and nothing left over for a second component to hide in.
///
/// This is deliberately lenient about an ordinary character such as `:` or
/// `\` that is not, on its own, a path separator on any platform's
/// filesystem: `list` discovers real names from disk, and a name containing
/// one of those (macOS stores a `/` typed in Finder as `:` on disk) must stay
/// reachable by a later `read` or `write`, not become visible-but-unopenable.
/// [`confine_name`] is the stricter check for a name being chosen new, where
/// refusing those characters costs nothing and closes a real escape.
fn confine_segment(segment: &str) -> Result<&str, Fault> {
if segment.contains('\\') || segment.contains(':') {
return Err(Fault::Refused(format!("{segment} is not a plain file name")));
}
let mut components = Path::new(segment).components();
match (components.next(), components.next()) {
(Some(Component::Normal(name)), None) if name == std::ffi::OsStr::new(segment) => Ok(segment),
(Some(Component::Normal(name)), None) if name == OsStr::new(segment) => Ok(segment),
_ => Err(Fault::Refused(format!("{segment} is not a plain file name"))),
}
}
/// Confirms a path already built from nothing but [`confine_segment`]-checked
/// names still cannot have reached outside `root` through a symlink or, on
/// Windows, a directory junction.
/// Windows device names that name a device rather than a file, with or
/// without a trailing extension (`CON`, `con.txt`, ...). Checked on every
/// platform: a name chosen here can end up read on a Windows client too.
const WINDOWS_RESERVED_NAMES: &[&str] = &[
"CON", "PRN", "AUX", "NUL", "CONIN$", "CONOUT$", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "LPT1", "LPT2", "LPT3",
"LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
];
fn is_windows_reserved_name(name: &str) -> bool {
let stem = name.split('.').next().unwrap_or(name);
WINDOWS_RESERVED_NAMES.iter().any(|reserved| stem.eq_ignore_ascii_case(reserved))
}
/// Confines a [`Job::Create`] `name` to a single ordinary file name that is
/// safe to choose on any platform, not only the one this crate is built for.
///
/// The no-escape policy: `candidate` need not exist yet, since [`write`] and
/// [`create`] both route a path that may still be about to be created
/// through here. Starting at `candidate` and walking up through its
/// ancestors, the first one that does exist is canonicalised and compared
/// against the canonicalised `root`. Nothing below that ancestor exists
/// either, so a link cannot sit on any of the remaining components, and
/// every one of them is already known to be ordinary `Component::Normal`
/// text, never `..` or an absolute form, because [`confine_segment`] is what
/// built them. A canonical path that lands outside `root` is refused;
/// nothing here ever opens, reads or writes through it.
fn confine_to_root(root: &Path, candidate: &Path) -> Result<PathBuf, Fault> {
let real_root = fs::canonicalize(root).map_err(|error| io_fault(&error))?;
let mut probe = candidate;
loop {
match fs::canonicalize(probe) {
Ok(real) if real == real_root || real.starts_with(&real_root) => return Ok(candidate.to_path_buf()),
Ok(_) => return Err(Fault::Refused("that path leaves this folder".to_owned())),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => match probe.parent() {
Some(parent) => probe = parent,
None => return Err(io_fault(&error)),
},
Err(error) => return Err(io_fault(&error)),
}
/// Stricter than [`confine_segment`]: a backslash or colon is refused
/// outright first, because a Unix build's [`Component`] parser does not
/// treat either as a separator and would wave a Windows drive letter or UNC
/// prefix (`C:`, `\\server\share`) straight through as one ordinary name. A
/// Windows reserved device name is refused the same way. None of this costs
/// anything here, unlike applying it to a name `list` merely discovered.
fn confine_name(name: &str) -> Result<&str, Fault> {
if name.contains('\\') || name.contains(':') {
return Err(Fault::Refused(format!("{name} is not a plain file name")));
}
if is_windows_reserved_name(name) {
return Err(Fault::Refused(format!("{name} is a reserved device name on Windows")));
}
confine_segment(name)
}
/// Opens `root` as the one ambient-authority capability this crate holds.
/// Every other path in this crate is resolved relative to the [`Dir`] this
/// returns, never as an absolute OS path built by string concatenation.
fn open_root(root: &Path) -> Result<Dir, Fault> {
Dir::open_ambient_dir(root, cap_std::ambient_authority()).map_err(|error| io_fault(&error))
}
/// The path a listed child gets, given the folder it was found in.
@@ -204,8 +237,9 @@ fn child_path(folder: &str, name: &str) -> String {
/// Not a timestamp for a person to read (that would go through `chrono`, per
/// this workspace's rule); just enough to tell "the file I read" from "the
/// file as it is now" apart, which is all a conditional write needs.
fn etag_of(meta: &fs::Metadata) -> String {
let stamp = meta.modified().ok().and_then(|time| time.duration_since(std::time::UNIX_EPOCH).ok()).map(|d| d.as_nanos()).unwrap_or(0);
fn etag_of(meta: &cap_std::fs::Metadata) -> String {
let stamp =
meta.modified().ok().and_then(|time| time.duration_since(cap_std::time::SystemClock::UNIX_EPOCH).ok()).map(|d| d.as_nanos()).unwrap_or(0);
format!("{}-{stamp}", meta.len())
}
@@ -219,8 +253,10 @@ fn io_fault(error: &std::io::Error) -> Fault {
}
fn list(root: &Path, path: &str) -> Result<Vec<Entry>, Fault> {
let dir = confine_to_root(root, &resolve(root, path)?)?;
let read = fs::read_dir(&dir).map_err(|error| io_fault(&error))?;
let rel = relative(path)?;
let dir = open_root(root)?;
let read = if rel.as_os_str().is_empty() { dir.entries() } else { dir.read_dir(&rel) };
let read = read.map_err(|error| io_fault(&error))?;
let mut entries = Vec::new();
for item in read {
let item = item.map_err(|error| io_fault(&error))?;
@@ -247,15 +283,32 @@ fn list(root: &Path, path: &str) -> Result<Vec<Entry>, Fault> {
/// Reads a file's bytes together with the entry for the version just read.
///
/// The entry is built from a fresh [`fs::metadata`] call here, not handed back
/// The entry is built from a fresh metadata call here, not handed back
/// unchanged from what the caller already believed. A reload after a conflict
/// hands in the stale entry it is trying to get past; echoing that back would
/// carry the old etag into the reloaded document, so the very next save would
/// conflict again on a copy that is actually current.
///
/// Refuses outright if `entry.id` names a symlink, the same policy `write`
/// uses: this backend never reports the bytes of whatever a link happens to
/// point at, inside `root` or out.
fn read(root: &Path, entry: &Entry) -> Result<(Entry, Vec<u8>), Fault> {
let file = confine_to_root(root, &resolve(root, &entry.id)?)?;
let bytes = fs::read(&file).map_err(|error| io_fault(&error))?;
let meta = fs::metadata(&file).map_err(|error| io_fault(&error))?;
let rel = relative(&entry.id)?;
let dir = open_root(root)?;
// Stats without following only the last component; every component
// before it is still resolved, and sandboxed, normally, so a link
// earlier in `rel` is refused by `open_root`'s `Dir` itself when `open`
// below walks it, never silently followed here either way.
match dir.symlink_metadata(&rel) {
Ok(meta) if meta.is_symlink() => return Err(Fault::Refused("that path is a link, not a plain file".to_owned())),
Ok(_) => {}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => return Err(io_fault(&error)),
}
let mut file = dir.open(&rel).map_err(|error| io_fault(&error))?;
let mut bytes = Vec::new();
file.read_to_end(&mut bytes).map_err(|error| io_fault(&error))?;
let meta = file.metadata().map_err(|error| io_fault(&error))?;
let fresh = Entry { size: Some(meta.len()), etag: Some(etag_of(&meta)), ..entry.clone() };
Ok((fresh, bytes))
}
@@ -263,35 +316,97 @@ fn read(root: &Path, entry: &Entry) -> Result<(Entry, Vec<u8>), Fault> {
/// Saves back over `entry`, refusing the write when the file moved on since
/// `entry.etag` was read. A file that no longer exists has nothing to
/// conflict with, the same way a provider treats a deleted document.
///
/// Never truncates `entry.id`'s current bytes in place. [`write_replacing`]
/// writes a sibling temporary file and renames it over the target instead,
/// so a hard link sharing the target's inode keeps its own, unmodified copy:
/// the rename replaces `entry.id`'s directory entry, and never reaches
/// through to any other name pointing at the same inode.
fn write(root: &Path, entry: &Entry, bytes: &[u8]) -> Result<Entry, Fault> {
let file = confine_to_root(root, &resolve(root, &entry.id)?)?;
if let Ok(meta) = fs::metadata(&file)
&& Some(etag_of(&meta)) != entry.etag
{
return Err(Fault::Conflict);
let rel = relative(&entry.id)?;
let dir = open_root(root)?;
match dir.symlink_metadata(&rel) {
Ok(meta) if meta.is_symlink() => return Err(Fault::Refused("that path is a link, not a plain file".to_owned())),
Ok(meta) => {
if Some(etag_of(&meta)) != entry.etag {
return Err(Fault::Conflict);
}
}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => return Err(io_fault(&error)),
}
if let Some(parent) = file.parent() {
fs::create_dir_all(parent).map_err(|error| io_fault(&error))?;
if let Some(parent) = rel.parent() {
dir.create_dir_all(parent).map_err(|error| io_fault(&error))?;
}
fs::write(&file, bytes).map_err(|error| io_fault(&error))?;
let meta = fs::metadata(&file).map_err(|error| io_fault(&error))?;
write_replacing(&dir, &rel, bytes)?;
let meta = dir.metadata(&rel).map_err(|error| io_fault(&error))?;
Ok(Entry { size: Some(meta.len()), etag: Some(etag_of(&meta)), ..entry.clone() })
}
/// The next in a run of sibling temporary names, unique within this process.
/// Not meant to resist a second process picking the same name; the create
/// this writes with is exclusive (`create_new`), so a collision there is
/// just retried under a new counter value rather than silently overwritten.
static TEMP_SEQUENCE: AtomicU64 = AtomicU64::new(0);
/// Writes `bytes` to a new sibling of `rel` inside `dir`, then renames that
/// sibling over `rel`. See the module docs for why: a direct write would
/// truncate whatever `rel` currently names in place, and if that happens to
/// be a hard link to a file outside `root`, the outside copy would be
/// corrupted along with it. A rename only ever replaces `rel`'s own
/// directory entry.
fn write_replacing(dir: &Dir, rel: &Path, bytes: &[u8]) -> Result<(), Fault> {
let name = rel.file_name().ok_or_else(|| Fault::Refused("that path names no file".to_owned()))?;
let mut temp_name = OsStr::new(".").to_os_string();
temp_name.push(name);
temp_name.push(format!(".tmp-{}-{}", std::process::id(), TEMP_SEQUENCE.fetch_add(1, Ordering::Relaxed)));
let temp_rel = match rel.parent() {
Some(parent) if !parent.as_os_str().is_empty() => parent.join(&temp_name),
_ => PathBuf::from(&temp_name),
};
let mut options = OpenOptions::new();
options.write(true).create_new(true);
let written = (|| -> Result<(), Fault> {
let mut handle = dir.open_with(&temp_rel, &options).map_err(|error| io_fault(&error))?;
handle.write_all(bytes).map_err(|error| io_fault(&error))?;
handle.sync_all().map_err(|error| io_fault(&error))
})();
if let Err(fault) = written {
let _ = dir.remove_file(&temp_rel);
return Err(fault);
}
if let Err(error) = dir.rename(&temp_rel, dir, rel) {
let _ = dir.remove_file(&temp_rel);
return Err(io_fault(&error));
}
Ok(())
}
fn create(root: &Path, folder: &str, name: &str, bytes: &[u8]) -> Result<Entry, Fault> {
// `name` is never a path: it is one [`Job::Create`] field that names the
// new file, so it goes through `confine_segment` directly rather than
// through `resolve`, which only ever splits and confines a slash path.
let name = confine_segment(name)?;
let dir = confine_to_root(root, &resolve(root, folder)?)?;
fs::create_dir_all(&dir).map_err(|error| io_fault(&error))?;
let file = dir.join(name);
// `name` is never a path: it is one `Job::Create` field that names the
// new file, so it goes through `confine_name` directly rather than
// through `relative`, which only ever splits and confines a slash path.
let name = confine_name(name)?;
// `root` is the operator-configured boundary, never attacker input, so
// creating it directly with `std::fs` is safe; this is also the one
// place that has always brought a fresh root into existence (see
// `LocalBackend::new`'s docs), and `Dir::open_ambient_dir` below needs it
// to already exist.
fs::create_dir_all(root).map_err(|error| io_fault(&error))?;
let dir = open_root(root)?;
let rel_folder = relative(folder)?;
dir.create_dir_all(&rel_folder).map_err(|error| io_fault(&error))?;
let rel = rel_folder.join(name);
// Exclusive creation, not an `exists` check ahead of a separate write: two
// creates of the same name racing both see "not there yet" otherwise, and
// the second write silently replaces the first with neither ever refused.
// `create_new` asks the filesystem to open and create in one step, so the
// loser gets an error instead of a chance to overwrite the winner.
let mut handle = match fs::OpenOptions::new().write(true).create_new(true).open(&file) {
// loser gets an error instead of a chance to overwrite the winner. It also
// refuses outright when `name` already exists as a symlink, dangling or
// not: `O_EXCL` never follows one to decide whether it is "in the way".
let mut create_options = OpenOptions::new();
create_options.write(true).create_new(true);
let mut handle = match dir.open_with(&rel, &create_options) {
Ok(handle) => handle,
Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
return Err(Fault::Refused(format!("{name} already exists")));
@@ -300,7 +415,7 @@ fn create(root: &Path, folder: &str, name: &str, bytes: &[u8]) -> Result<Entry,
};
handle.write_all(bytes).map_err(|error| io_fault(&error))?;
drop(handle);
let meta = fs::metadata(&file).map_err(|error| io_fault(&error))?;
let meta = dir.metadata(&rel).map_err(|error| io_fault(&error))?;
let id = child_path(folder, name);
Ok(Entry {
room: format!("local:{id}"),
@@ -323,16 +438,14 @@ mod tests {
#[test]
fn a_parent_segment_cannot_walk_out_of_root() {
let root = PathBuf::from("/cloud/root");
assert!(resolve(&root, "../secrets").is_err());
assert!(resolve(&root, "Archive/../../../etc/passwd").is_err());
assert!(relative("../secrets").is_err());
assert!(relative("Archive/../../../etc/passwd").is_err());
}
#[test]
fn repeated_and_trailing_slashes_collapse_like_a_browser_address_bar() {
let root = PathBuf::from("/cloud/root");
assert_eq!(resolve(&root, "//Archive//2026/").unwrap(), root.join("Archive").join("2026"));
assert_eq!(resolve(&root, "").unwrap(), root);
assert_eq!(relative("//Archive//2026/").unwrap(), Path::new("Archive").join("2026"));
assert_eq!(relative("").unwrap(), PathBuf::new());
}
#[test]
@@ -356,28 +469,35 @@ mod tests {
assert!(confine_segment("/outside.txt").is_err());
}
/// The fix for the non-blocking finding that `list` made a real macOS
/// name (a literal `/`, stored on disk as `:`) visible but unreadable: an
/// existing name with an ordinary `:` byte is not refused by the lenient
/// per-segment check, only by `confine_name` for a chosen one. A literal
/// `\` is not tested the same way here: on a Windows build it really is
/// a second path component (`std::path::Component` already splits on
/// it), so there is no existing-name case for `confine_segment` to stay
/// lenient about cross-platform the way there is for `:`.
#[test]
fn confine_segment_refuses_windows_separators_and_prefixes_on_every_platform() {
fn confine_segment_tolerates_a_colon_already_on_disk() {
assert!(confine_segment("weird:name.txt").is_ok());
assert!(relative("weird:name.txt").is_ok());
}
#[test]
fn confine_name_refuses_backslash_and_colon_on_every_platform() {
for bad in ["..\\outside.txt", "C:\\x", "C:evil", "\\\\server\\share\\x"] {
assert!(confine_segment(bad).is_err(), "{bad:?} must be refused on every platform, not only on Windows");
assert!(confine_name(bad).is_err(), "{bad:?} must be refused on every platform, not only on Windows");
}
}
#[test]
fn confine_to_root_accepts_a_path_that_does_not_exist_yet_under_an_existing_root() {
let root = tempfile::tempdir().unwrap();
let candidate = root.path().join("not-written-yet.txt");
assert!(confine_to_root(root.path(), &candidate).is_ok());
}
#[test]
fn confine_to_root_refuses_a_candidate_that_canonicalises_outside_root() {
let root = tempfile::tempdir().unwrap();
let elsewhere = tempfile::tempdir().unwrap();
// Built from a path that never went through `confine_segment` (this
// helper is tested on its own merits), standing in for whatever a
// symlink or junction would otherwise have redirected into `root`.
assert!(confine_to_root(root.path(), elsewhere.path()).is_err());
fn confine_name_refuses_windows_reserved_device_names() {
for bad in ["CON", "con", "con.txt", "NUL", "COM1", "lpt9.log", "CONIN$"] {
assert!(confine_name(bad).is_err(), "{bad:?} names a Windows device, not a file");
}
for ordinary in ["console.txt", "NULLABLE.md", "COM10"] {
assert!(confine_name(ordinary).is_ok(), "{ordinary} only resembles a reserved name");
}
}
#[test]
@@ -1,9 +1,12 @@
//! The P1 from FredApps' re-review of #160: `resolve` only split on `/` and rejected a segment
//! equal to `..`; it did not constrain a Windows backslash, a drive letter or UNC prefix, or a
//! filesystem link, and `create` joined `name` onto the resolved folder with no validation of
//! `name` at all. Driven through `craft_ui::cloud`'s public functions the way an application
//! does, with a sentinel file and directory kept as a sibling of the configured root: every test
//! here must leave both untouched and unread.
//! Confinement regressions for `crates/cloud-local`. The first round (FredApps' re-review) found
//! that `resolve` only split on `/` and rejected a segment equal to `..`, with no constraint on a
//! Windows backslash, a drive letter or UNC prefix, or a filesystem link, and that `create`
//! joined `name` onto the resolved folder with no validation of `name` at all. The second round
//! (benandez's re-review) reproduced three escapes the first fix still left open: a dangling
//! symlink, a check-then-use race on a swapped link, and a hard link sharing a file's inode.
//! Driven through `craft_ui::cloud`'s public functions the way an application does, with a
//! sentinel file and directory kept as a sibling of the configured root: every test here must
//! leave both untouched and unread.
use std::path::PathBuf;
use std::sync::{Arc, Mutex};
@@ -101,8 +104,13 @@ fn settle(app: &mut Harness, ctx: &egui::Context, mut done: impl FnMut(&Harness)
}
}
/// Clears both event sinks, then waits for the next job to land in either one. Clearing first
/// matters for a test that submits several jobs in a loop: without it, a stale `said` from two
/// iterations ago would satisfy `settle` immediately, before the new job had actually answered.
fn said(app: &mut Harness, ctx: &egui::Context) -> Vec<String> {
settle(app, ctx, |app| !app.said.lock().unwrap().is_empty());
app.opened.lock().unwrap().clear();
app.said.lock().unwrap().clear();
settle(app, ctx, |app| !app.said.lock().unwrap().is_empty() || !app.opened.lock().unwrap().is_empty());
app.said.lock().unwrap().clone()
}
@@ -117,27 +125,26 @@ struct Sentinels {
sentinel_dir: PathBuf,
}
const SENTINEL_FILE_BYTES: &[u8] = b"a sibling file this backend must never read or write";
const SENTINEL_DIR_FILE_BYTES: &[u8] = b"a sibling directory this backend must never list";
fn sentinels() -> Sentinels {
let arena = tempfile::tempdir().unwrap();
let root = arena.path().join("root");
std::fs::create_dir(&root).unwrap();
let sentinel_file = arena.path().join("sentinel.txt");
std::fs::write(&sentinel_file, b"a sibling file this backend must never read or write").unwrap();
std::fs::write(&sentinel_file, SENTINEL_FILE_BYTES).unwrap();
let sentinel_dir = arena.path().join("sentinel-dir");
std::fs::create_dir(&sentinel_dir).unwrap();
std::fs::write(sentinel_dir.join("secret.txt"), b"a sibling directory this backend must never list").unwrap();
std::fs::write(sentinel_dir.join("secret.txt"), SENTINEL_DIR_FILE_BYTES).unwrap();
Sentinels { _arena: arena, root, sentinel_file, sentinel_dir }
}
fn assert_sentinels_untouched(sentinels: &Sentinels) {
assert_eq!(
std::fs::read(&sentinels.sentinel_file).unwrap(),
b"a sibling file this backend must never read or write",
"the sentinel file outside the root was changed"
);
assert_eq!(std::fs::read(&sentinels.sentinel_file).unwrap(), SENTINEL_FILE_BYTES, "the sentinel file outside the root was changed");
assert_eq!(
std::fs::read(sentinels.sentinel_dir.join("secret.txt")).unwrap(),
b"a sibling directory this backend must never list",
SENTINEL_DIR_FILE_BYTES,
"the sentinel directory's file outside the root was changed"
);
}
@@ -165,28 +172,13 @@ fn create_refuses_every_escaping_name_and_the_sentinels_stay_untouched() {
}
}
/// A folder path for `Job::List` can carry the same Windows-shaped escape a `Create` name can;
/// `resolve` must refuse it through the identical [`confine_segment`] check, not a weaker one.
#[test]
fn listing_a_windows_shaped_folder_path_is_refused_on_every_platform() {
let sentinels = sentinels();
let (mut app, ctx) = wired(sentinels.root.clone());
cloud::browse(&mut app, "..\\sentinel-dir");
settle(&mut app, &ctx, |app| app.cloud().mine.loaded);
assert!(app.cloud().mine.error.is_some(), "a backslash-separated folder path must be refused");
assert!(app.cloud().mine.entries.is_empty());
assert_sentinels_untouched(&sentinels);
}
// ------------------------------------------------------------------- link-based escapes
//
// `escape(&sentinels)` places one link named `escape` inside the cloud root, pointing out to
// `sentinels.sentinel_dir`: a symlink on Unix, a directory junction on Windows, which needs no
// elevated privilege, unlike a Windows symlink. The Linux gate runs the symlink half of every
// test below; CI's windows-latest lanes run the junction half. Either way `root/escape/secret.txt`
// is the same sentinel file reached through the link.
// test below; CI's windows-latest lanes run the junction half. Either way `root/escape/...`
// reaches into the sentinel directory through the link.
/// Nothing to clean up on Unix: `tempfile`'s own recursive removal of the arena directory
/// removes a plain symlink entry without following it. This exists only so `escape` returns the
@@ -228,13 +220,14 @@ fn escape(sentinels: &Sentinels) -> Junction {
Junction(link)
}
#[cfg(any(unix, windows))]
fn leaked_entry() -> Entry {
/// An [`Entry`] stub naming `id`, for a [`Job::Read`] or [`Job::Write`] this file submits
/// directly rather than through an entry the backend itself handed back.
fn leaked_entry(id: &str, name: &str) -> Entry {
Entry {
id: "/escape/secret.txt".to_owned(),
room: "local:/escape/secret.txt".to_owned(),
name: "secret.txt".to_owned(),
path: "/escape/secret.txt".to_owned(),
id: id.to_owned(),
room: format!("local:{id}"),
name: name.to_owned(),
path: id.to_owned(),
kind: EntryKind::File,
size: None,
modified: None,
@@ -267,23 +260,172 @@ fn reading_through_a_linked_folder_cannot_return_bytes_from_outside_the_root() {
let (mut app, ctx) = wired(sentinels.root.clone());
let _escape = escape(&sentinels);
cloud::submit(&app, Job::Read { entry: leaked_entry(), into: None });
cloud::submit(&app, Job::Read { entry: leaked_entry("/escape/secret.txt", "secret.txt"), into: None });
said(&mut app, &ctx);
assert!(app.opened.lock().unwrap().is_empty(), "a read through a symlink or junction out of the root must not deliver bytes");
assert_sentinels_untouched(&sentinels);
}
/// benandez's finding 4: the original version of this test targeted the pre-existing
/// `secret.txt`, with `etag: None`. `write` refused that for an unrelated reason, a version
/// mismatch, before confinement ever ran, so the test passed whether or not confinement worked.
/// Targeting a name that does not exist yet under the link reaches the code that actually
/// matters, and the oracle (the file must never be created) is one confinement failing would
/// actually flip.
#[cfg(any(unix, windows))]
#[test]
fn writing_through_a_linked_folder_cannot_change_a_file_outside_the_root() {
fn writing_through_a_linked_folder_cannot_create_a_file_outside_the_root() {
let sentinels = sentinels();
let (mut app, ctx) = wired(sentinels.root.clone());
let _escape = escape(&sentinels);
cloud::submit(&app, Job::Write { uid: 1, entry: leaked_entry(), bytes: b"pwned".to_vec() });
cloud::submit(&app, Job::Write { uid: 1, entry: leaked_entry("/escape/not-yet-created.txt", "not-yet-created.txt"), bytes: b"pwned".to_vec() });
said(&mut app, &ctx);
assert!(app.cloud().conflict.is_none(), "this must be refused outright, not treated as a stale-version conflict");
assert!(!sentinels.sentinel_dir.join("not-yet-created.txt").exists(), "a write through a link must not create a file outside the root");
assert_sentinels_untouched(&sentinels);
}
/// benandez's finding 5: nothing previously exercised a link in the `folder` a `Create` targets.
#[cfg(any(unix, windows))]
#[test]
fn creating_through_a_linked_folder_cannot_create_a_file_outside_the_root() {
let sentinels = sentinels();
let (mut app, ctx) = wired(sentinels.root.clone());
let _escape = escape(&sentinels);
cloud::submit(&app, Job::Create { uid: 1, folder: "escape".to_owned(), name: "new.txt".to_owned(), bytes: b"pwned".to_vec() });
let messages = said(&mut app, &ctx);
assert!(cloud::origin(&app).is_none(), "a create into a linked folder must not be reported as created");
assert!(!messages.is_empty(), "a create into a linked folder must be refused, not silently dropped");
assert!(!sentinels.sentinel_dir.join("new.txt").exists(), "a create through a link must not create a file outside the root");
assert_sentinels_untouched(&sentinels);
}
// ------------------------------------------------------------------- Unix-only reproductions
//
// Directory junctions cannot be dangling (`mklink /J` requires the target to exist) and the
// race and hard-link reproductions below are exactly benandez's own repros, run on Linux only,
// as stated in that review. The structural fix (resolving through a `cap_std::fs::Dir`, and
// writing through a temporary file and rename) is the same code on every platform; these three
// just do not have a Windows-shaped equivalent worth a separate repro.
/// benandez's finding 1, reproduced exactly: `root/doc.txt` is a symlink to a file that does not
/// exist yet, outside the root. The old code's `confine_to_root` canonicalised the dangling link
/// to `NotFound`, walked up to `root`, accepted it, found no file to conflict with, and `write`
/// created the target for real, outside the root.
#[cfg(unix)]
#[test]
fn writing_through_a_dangling_symlink_cannot_create_a_file_outside_the_root() {
let sentinels = sentinels();
let outside_target = sentinels._arena.path().join("outside-planted.txt");
std::os::unix::fs::symlink(&outside_target, sentinels.root.join("doc.txt")).unwrap();
let (mut app, ctx) = wired(sentinels.root.clone());
cloud::submit(&app, Job::Write { uid: 1, entry: leaked_entry("/doc.txt", "doc.txt"), bytes: b"pwned".to_vec() });
said(&mut app, &ctx);
assert!(!outside_target.exists(), "a write through a dangling symlink must not create its target outside the root");
assert_sentinels_untouched(&sentinels);
}
/// benandez's finding 3, reproduced exactly: `root/hl` is a hard link sharing an inode with a
/// file outside the root. Reading it through the backend is legitimate (it is, from inside the
/// sandbox, an ordinary file), which is also how this test gets a real, matching etag to write
/// with, the same way a real caller would after opening the document. The old code's `write`
/// truncated the shared inode in place; `write_replacing` must instead replace `hl`'s own
/// directory entry, leaving the sentinel file's inode, and its other name, untouched.
#[cfg(unix)]
#[test]
fn writing_through_a_hard_link_replaces_the_entry_without_touching_the_shared_file() {
let sentinels = sentinels();
std::fs::hard_link(&sentinels.sentinel_file, sentinels.root.join("hl")).unwrap();
let (mut app, ctx) = wired(sentinels.root.clone());
cloud::submit(&app, Job::Read { entry: leaked_entry("/hl", "hl"), into: None });
settle(&mut app, &ctx, |app| !app.opened.lock().unwrap().is_empty());
let real_entry = app.cloud().origins.get(&1).expect("the read registered an origin for uid 1").entry.clone();
// A successful write answers through `cloud.status`, not through `said` or `opened`, so it
// needs its own wait condition rather than the `said` helper used everywhere else in this
// file for a refusal. The read above already set `status` once (`Opened hl from the
// cloud.`), so that has to be cleared first or this would observe the read's own status and
// never actually wait for the write to finish.
app.cloud_mut().status = None;
cloud::submit(&app, Job::Write { uid: 1, entry: real_entry, bytes: b"replaced via rename, not truncated in place".to_vec() });
settle(&mut app, &ctx, |app| app.cloud().status.is_some() || app.cloud().conflict.is_some() || !app.said.lock().unwrap().is_empty());
assert!(app.cloud().conflict.is_none(), "the write through the hard-linked name should succeed, not conflict");
assert!(
app.said.lock().unwrap().is_empty(),
"the write through the hard-linked name should succeed, not be refused: {:?}",
app.said.lock().unwrap()
);
assert_eq!(
std::fs::read(sentinels.root.join("hl")).unwrap(),
b"replaced via rename, not truncated in place",
"the write through the hard-linked name should still succeed"
);
assert_sentinels_untouched(&sentinels);
}
/// benandez's finding 2, reproduced at a smaller scale: a background thread swaps `root/d`
/// between a symlink into an inside folder and a symlink to the sentinel directory, as fast as
/// it can, with no coordination with the reads below. The old code's `confine_to_root` checked
/// one path string and then `fs::read` resolved that path again, a second, later lookup a swap
/// could land in between; out of 3000 such reads benandez's own run returned the outside file's
/// bytes 347 times. `cap_std::fs::Dir::open` resolves and opens `d` as one operation with no
/// such second lookup, so this must come back empty every time, not merely most of the time.
#[cfg(unix)]
#[test]
fn reading_through_a_link_being_swapped_never_observes_the_outside_target() {
use std::sync::atomic::{AtomicBool, Ordering};
let sentinels = sentinels();
let inside = sentinels.root.join("inside");
std::fs::create_dir(&inside).unwrap();
std::fs::write(inside.join("secret.txt"), b"inside bytes, always safe to read").unwrap();
let link = sentinels.root.join("d");
std::os::unix::fs::symlink(&inside, &link).unwrap();
let stop = Arc::new(AtomicBool::new(false));
let swapper = {
let stop = stop.clone();
let link = link.clone();
let outside = sentinels.sentinel_dir.clone();
std::thread::spawn(move || {
let temp = link.with_extension("swap");
let mut toward_outside = false;
while !stop.load(Ordering::Relaxed) {
let target = if toward_outside { &outside } else { &inside };
// A stale `temp` from a rename that did not happen (should not occur, but a
// leftover `temp` would otherwise wedge every later iteration's `symlink` call,
// silently stopping the swap rather than failing the test loudly) is cleared
// first so this loop cannot get stuck.
let _ = std::fs::remove_file(&temp);
if std::os::unix::fs::symlink(target, &temp).is_ok() {
let _ = std::fs::rename(&temp, &link);
}
toward_outside = !toward_outside;
}
})
};
let (mut app, ctx) = wired(sentinels.root.clone());
let mut leaked = false;
for _ in 0..200 {
cloud::submit(&app, Job::Read { entry: leaked_entry("/d/secret.txt", "secret.txt"), into: None });
said(&mut app, &ctx);
if let Some((_, bytes)) = app.opened.lock().unwrap().first() {
leaked |= bytes.as_slice() == SENTINEL_DIR_FILE_BYTES;
}
}
stop.store(true, Ordering::Relaxed);
swapper.join().unwrap();
assert!(!leaked, "a read observed the outside target's bytes while the link was being swapped underneath it");
assert_sentinels_untouched(&sentinels);
}