use std::io::Write as _;
use std::path::{Component, Path, PathBuf};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use cap_std::ambient_authority;
use cap_std::fs::Dir;
use super::authority::AuthorityRefusal;
static NEXT_ROOT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
static NEXT_TEMP: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
#[cfg(unix)]
fn sync_directory_beneath_capability(dir: &Dir) -> std::io::Result<()> {
let mut options = cap_std::fs::OpenOptions::new();
options.read(true);
dir.open_with(".", &options)?.sync_all()
}
const MAX_TEMP_ATTEMPTS: u32 = 16;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct PhysicalRootIdentity(std::num::NonZeroU64);
impl PhysicalRootIdentity {
pub fn fresh() -> Self {
let raw = NEXT_ROOT.fetch_add(1, Ordering::Relaxed);
Self(std::num::NonZeroU64::new(raw).expect("root counter starts at 1"))
}
pub fn as_u64(self) -> u64 {
self.0.get()
}
pub fn from_stored(raw: u64) -> Option<Self> {
std::num::NonZeroU64::new(raw).map(Self)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct PhysicalRootAnchor {
dev: u64,
ino: u64,
}
impl PhysicalRootAnchor {
pub(crate) fn stable_key(self) -> [u8; 16] {
let mut key = [0_u8; 16];
key[..8].copy_from_slice(&self.dev.to_le_bytes());
key[8..].copy_from_slice(&self.ino.to_le_bytes());
key
}
pub fn observe(path: &Path) -> Option<Self> {
observe_physical_root_anchor(path)
}
fn observe_opened(dir: &Dir) -> Option<Self> {
observe_opened_physical_root_anchor(dir)
}
}
#[cfg(unix)]
fn observe_opened_physical_root_anchor(dir: &Dir) -> Option<PhysicalRootAnchor> {
use cap_std::fs::MetadataExt as _;
let metadata = dir.dir_metadata().ok()?;
Some(PhysicalRootAnchor {
dev: metadata.dev(),
ino: metadata.ino(),
})
}
#[cfg(windows)]
#[allow(unsafe_code)]
fn observe_opened_physical_root_anchor(dir: &Dir) -> Option<PhysicalRootAnchor> {
use std::os::windows::io::AsRawHandle;
use windows::Win32::Foundation::HANDLE;
use windows::Win32::Storage::FileSystem::{
BY_HANDLE_FILE_INFORMATION, GetFileInformationByHandle,
};
let mut info = BY_HANDLE_FILE_INFORMATION::default();
unsafe { GetFileInformationByHandle(HANDLE(dir.as_raw_handle()), &mut info) }.ok()?;
Some(PhysicalRootAnchor {
dev: u64::from(info.dwVolumeSerialNumber),
ino: (u64::from(info.nFileIndexHigh) << 32) | u64::from(info.nFileIndexLow),
})
}
#[cfg(not(any(unix, windows)))]
fn observe_opened_physical_root_anchor(_dir: &Dir) -> Option<PhysicalRootAnchor> {
None
}
#[cfg(unix)]
fn observe_physical_root_anchor(path: &Path) -> Option<PhysicalRootAnchor> {
use std::os::unix::fs::MetadataExt;
let metadata = std::fs::metadata(path).ok()?;
Some(PhysicalRootAnchor {
dev: metadata.dev(),
ino: metadata.ino(),
})
}
#[cfg(windows)]
#[allow(unsafe_code)]
fn observe_physical_root_anchor(path: &Path) -> Option<PhysicalRootAnchor> {
use std::os::windows::fs::OpenOptionsExt;
use std::os::windows::io::AsRawHandle;
use windows::Win32::Foundation::HANDLE;
use windows::Win32::Storage::FileSystem::{
BY_HANDLE_FILE_INFORMATION, FILE_FLAG_BACKUP_SEMANTICS, FILE_READ_ATTRIBUTES,
FILE_SHARE_DELETE, FILE_SHARE_READ, FILE_SHARE_WRITE, GetFileInformationByHandle,
};
let opened = std::fs::OpenOptions::new()
.access_mode(FILE_READ_ATTRIBUTES.0)
.share_mode((FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE).0)
.attributes(FILE_FLAG_BACKUP_SEMANTICS.0)
.open(path)
.ok()?;
let mut info = BY_HANDLE_FILE_INFORMATION::default();
let queried = unsafe { GetFileInformationByHandle(HANDLE(opened.as_raw_handle()), &mut info) };
queried.ok()?;
Some(PhysicalRootAnchor {
dev: u64::from(info.dwVolumeSerialNumber),
ino: (u64::from(info.nFileIndexHigh) << 32) | u64::from(info.nFileIndexLow),
})
}
#[cfg(not(any(unix, windows)))]
fn observe_physical_root_anchor(_path: &Path) -> Option<PhysicalRootAnchor> {
None
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RootRefusal {
LeaseRevoked,
EscapesRoot {
requested: PathBuf,
},
LinkComponent {
component: PathBuf,
},
Unreadable {
path: PathBuf,
message: String,
},
}
impl From<RootRefusal> for AuthorityRefusal {
fn from(_: RootRefusal) -> Self {
AuthorityRefusal::PhysicalRootReplaced
}
}
#[derive(Debug)]
pub struct PhysicalRootLease {
identity: PhysicalRootIdentity,
root: PathBuf,
dir: Option<Dir>,
revoked: Arc<AtomicBool>,
}
impl PhysicalRootLease {
pub(crate) fn opened_stable_key(&self) -> Option<[u8; 16]> {
PhysicalRootAnchor::observe_opened(self.dir.as_ref()?).map(PhysicalRootAnchor::stable_key)
}
pub fn take(root: impl Into<PathBuf>) -> Self {
let root = root.into();
let dir = Dir::open_ambient_dir(&root, ambient_authority()).ok();
Self {
identity: PhysicalRootIdentity::fresh(),
root,
dir,
revoked: Arc::new(AtomicBool::new(false)),
}
}
pub(crate) fn take_matching_anchor(
root: &Path,
expected: Option<PhysicalRootAnchor>,
) -> Result<Self, RootRefusal> {
let lease = Self::take(root);
let dir = lease.capability()?;
if expected.is_none() || PhysicalRootAnchor::observe_opened(dir) != expected {
return Err(RootRefusal::LeaseRevoked);
}
Ok(lease)
}
pub fn parked(&self) -> Self {
Self {
identity: self.identity,
root: self.root.clone(),
dir: None,
revoked: Arc::clone(&self.revoked),
}
}
pub fn reopened(&self) -> Self {
Self {
identity: self.identity,
root: self.root.clone(),
dir: Dir::open_ambient_dir(&self.root, ambient_authority()).ok(),
revoked: Arc::clone(&self.revoked),
}
}
pub(crate) fn reopened_matching_stable_key(
&self,
expected: [u8; 16],
) -> Result<Self, RootRefusal> {
let opened = self.reopened();
if opened.opened_stable_key() != Some(expected) {
return Err(RootRefusal::LeaseRevoked);
}
Ok(opened)
}
#[cfg(feature = "embed")]
pub(crate) fn duplicated(&self) -> Result<Self, RootRefusal> {
let dir = self
.capability()?
.try_clone()
.map_err(|error| RootRefusal::Unreadable {
path: self.root.clone(),
message: error.to_string(),
})?;
Ok(Self {
identity: self.identity,
root: self.root.clone(),
dir: Some(dir),
revoked: Arc::clone(&self.revoked),
})
}
pub(crate) fn child_directory(
&self,
relative: &Path,
create: bool,
) -> Result<Self, RootRefusal> {
let target = self.resolve_beneath(relative)?;
self.refuse_link_relative(target.relative())?;
let parent = self.capability()?;
if create {
parent
.create_dir_all(target.relative())
.map_err(|error| RootRefusal::Unreadable {
path: target.path(),
message: error.to_string(),
})?;
}
self.refuse_link_relative(target.relative())?;
let dir = parent
.open_dir(target.relative())
.map_err(|error| RootRefusal::Unreadable {
path: target.path(),
message: error.to_string(),
})?;
Ok(Self {
identity: self.identity,
root: target.path(),
dir: Some(dir),
revoked: Arc::clone(&self.revoked),
})
}
pub(crate) fn directory_capability(&self) -> Result<&Dir, RootRefusal> {
self.capability()
}
#[cfg(unix)]
pub(crate) fn sync_directory(&self) -> Result<(), RootRefusal> {
sync_directory_beneath_capability(self.capability()?).map_err(|error| {
RootRefusal::Unreadable {
path: self.root.clone(),
message: error.to_string(),
}
})
}
#[cfg(windows)]
pub(crate) fn sync_directory(&self) -> Result<(), RootRefusal> {
self.capability().map(|_| ())
}
fn capability(&self) -> Result<&Dir, RootRefusal> {
if !self.is_live() {
return Err(RootRefusal::LeaseRevoked);
}
self.dir.as_ref().ok_or_else(|| RootRefusal::Unreadable {
path: self.root.clone(),
message: "the leased root could not be opened as a directory capability".to_owned(),
})
}
pub fn identity(&self) -> PhysicalRootIdentity {
self.identity
}
pub fn root(&self) -> &Path {
&self.root
}
pub fn is_live(&self) -> bool {
!self.revoked.load(Ordering::Acquire)
}
pub fn revoke(&self) {
self.revoked.store(true, Ordering::Release);
}
fn revocation(&self) -> &Arc<AtomicBool> {
&self.revoked
}
pub fn resolve_beneath(&self, relative: &Path) -> Result<ResolvedTarget, RootRefusal> {
let dir = self.capability()?;
let mut components = Vec::new();
for component in relative.components() {
match component {
Component::Normal(part) => components.push(part.to_os_string()),
Component::CurDir => {}
Component::ParentDir | Component::RootDir | Component::Prefix(_) => {
return Err(RootRefusal::EscapesRoot {
requested: relative.to_path_buf(),
});
}
}
}
let Some((leaf, parents)) = components.split_last() else {
return Err(RootRefusal::EscapesRoot {
requested: relative.to_path_buf(),
});
};
let mut walked = PathBuf::new();
let mut parent = self.root.clone();
for part in parents {
walked.push(part);
parent.push(part);
match dir.symlink_metadata(&walked) {
Ok(metadata) if metadata.is_symlink() => {
return Err(RootRefusal::LinkComponent { component: parent });
}
Ok(_) => {}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => {
return Err(RootRefusal::Unreadable {
path: parent,
message: error.to_string(),
});
}
}
}
let mut relative_path = walked.clone();
relative_path.push(leaf);
Ok(ResolvedTarget {
parent,
leaf: leaf.clone(),
relative: relative_path,
})
}
fn refuse_link_relative(&self, relative: &Path) -> Result<(), RootRefusal> {
let dir = self.capability()?;
match dir.symlink_metadata(relative) {
Ok(metadata) if metadata.is_symlink() => Err(RootRefusal::LinkComponent {
component: self.root.join(relative),
}),
Ok(_) => Ok(()),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
Err(error) => Err(RootRefusal::Unreadable {
path: self.root.join(relative),
message: error.to_string(),
}),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedTarget {
parent: PathBuf,
leaf: std::ffi::OsString,
relative: PathBuf,
}
impl ResolvedTarget {
pub fn parent(&self) -> &Path {
&self.parent
}
pub fn leaf(&self) -> &std::ffi::OsStr {
&self.leaf
}
pub fn path(&self) -> PathBuf {
self.parent.join(&self.leaf)
}
pub fn relative(&self) -> &Path {
&self.relative
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReplacementStep {
TempCreated,
Replaced,
DelegatedVerified,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WriteReceipt {
steps: Vec<ReplacementStep>,
target: PathBuf,
lease: PhysicalRootIdentity,
}
impl WriteReceipt {
pub fn steps(&self) -> &[ReplacementStep] {
&self.steps
}
pub fn target(&self) -> &Path {
&self.target
}
pub fn lease(&self) -> PhysicalRootIdentity {
self.lease
}
}
pub fn replace_beneath(
lease: &PhysicalRootLease,
relative: &Path,
contents: &[u8],
) -> Result<WriteReceipt, RootRefusal> {
stage_replacement(lease, relative, contents)?.commit()
}
pub(crate) fn replace_owner_only_beneath(
lease: &PhysicalRootLease,
relative: &Path,
contents: &[u8],
) -> Result<WriteReceipt, RootRefusal> {
stage_replacement_with_policy(lease, relative, contents, true)?.commit()
}
pub fn verify_replacement_beneath(
lease: &PhysicalRootLease,
relative: &Path,
expected: &[u8],
) -> Result<Option<WriteReceipt>, RootRefusal> {
let target = lease.resolve_beneath(relative)?;
lease.refuse_link_relative(target.relative())?;
let dir = lease.capability()?;
let observed = dir
.read(target.relative())
.map_err(|error| RootRefusal::Unreadable {
path: target.path(),
message: error.to_string(),
})?;
if observed != expected {
return Ok(None);
}
Ok(Some(WriteReceipt {
steps: vec![ReplacementStep::DelegatedVerified],
target: target.path(),
lease: lease.identity(),
}))
}
pub(crate) fn matches_optional_image_beneath(
lease: &PhysicalRootLease,
relative: &Path,
expected: Option<&[u8]>,
) -> Result<bool, RootRefusal> {
let target = lease.resolve_beneath(relative)?;
lease.refuse_link_relative(target.relative())?;
let dir = lease.capability()?;
match dir.read(target.relative()) {
Ok(observed) => Ok(expected.is_some_and(|bytes| observed == bytes)),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(expected.is_none()),
Err(error) => Err(RootRefusal::Unreadable {
path: target.path(),
message: error.to_string(),
}),
}
}
pub(crate) fn open_regular_beneath(
lease: &PhysicalRootLease,
relative: &Path,
) -> Result<Option<(cap_std::fs::File, PathBuf)>, RootRefusal> {
let target = lease.resolve_beneath(relative)?;
lease.refuse_link_relative(target.relative())?;
let dir = lease.capability()?;
let metadata = match dir.symlink_metadata(target.relative()) {
Ok(metadata) => metadata,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(error) => {
return Err(RootRefusal::Unreadable {
path: target.path(),
message: error.to_string(),
});
}
};
if !metadata.is_file() {
return Err(RootRefusal::Unreadable {
path: target.path(),
message: "not a regular file".to_string(),
});
}
let mut options = cap_std::fs::OpenOptions::new();
options.read(true);
#[cfg(unix)]
{
use cap_std::fs::OpenOptionsExt;
options.custom_flags(libc::O_NONBLOCK | libc::O_NOFOLLOW);
}
let file = match dir.open_with(target.relative(), &options) {
Ok(file) => file,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(error) => {
return Err(RootRefusal::Unreadable {
path: target.path(),
message: error.to_string(),
});
}
};
if !file.metadata().is_ok_and(|metadata| metadata.is_file()) {
return Err(RootRefusal::Unreadable {
path: target.path(),
message: "not a regular file".to_string(),
});
}
Ok(Some((file, target.path())))
}
#[cfg(any(feature = "server", feature = "embed"))]
pub(crate) struct AnchoredEntryMetadata {
pub len: u64,
pub modified_secs: u64,
}
#[cfg(any(feature = "server", feature = "embed"))]
pub(crate) fn entry_metadata_beneath(
lease: &PhysicalRootLease,
relative: &Path,
) -> Result<Option<AnchoredEntryMetadata>, RootRefusal> {
use std::time::UNIX_EPOCH;
let target = lease.resolve_beneath(relative)?;
lease.refuse_link_relative(target.relative())?;
let metadata = match lease.capability()?.symlink_metadata(target.relative()) {
Ok(metadata) => metadata,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(error) => {
return Err(RootRefusal::Unreadable {
path: target.path(),
message: error.to_string(),
});
}
};
if metadata.is_symlink() {
return Err(RootRefusal::LinkComponent {
component: target.path(),
});
}
let modified = metadata
.modified()
.map_err(|error| RootRefusal::Unreadable {
path: target.path(),
message: error.to_string(),
})?;
Ok(Some(AnchoredEntryMetadata {
len: metadata.len(),
modified_secs: modified
.into_std()
.duration_since(UNIX_EPOCH)
.unwrap_or_default()
.as_secs(),
}))
}
#[cfg(any(feature = "server", feature = "embed"))]
pub(crate) fn exact_spelling_beneath(
lease: &PhysicalRootLease,
relative: &Path,
) -> Result<bool, RootRefusal> {
let target = lease.resolve_beneath(relative)?;
exact_spelling_from_dir(
lease.capability()?,
target.relative().components(),
&target.path(),
)
}
#[cfg(any(feature = "server", feature = "embed"))]
fn exact_spelling_from_dir(
directory: &Dir,
mut components: std::path::Components<'_>,
target: &Path,
) -> Result<bool, RootRefusal> {
let Some(Component::Normal(name)) = components.next() else {
return Err(RootRefusal::EscapesRoot {
requested: target.to_path_buf(),
});
};
let mut exact = false;
for entry in directory
.read_dir(".")
.map_err(|error| RootRefusal::Unreadable {
path: target.to_path_buf(),
message: error.to_string(),
})?
{
if entry
.map_err(|error| RootRefusal::Unreadable {
path: target.to_path_buf(),
message: error.to_string(),
})?
.file_name()
.as_os_str()
== name
{
exact = true;
break;
}
}
if !exact {
return match directory.symlink_metadata(name) {
Ok(_) => Err(RootRefusal::Unreadable {
path: target.to_path_buf(),
message: "path spelling differs from the on-disk name".to_owned(),
}),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false),
Err(error) => Err(RootRefusal::Unreadable {
path: target.to_path_buf(),
message: error.to_string(),
}),
};
}
if components.clone().next().is_none() {
return Ok(true);
}
let metadata = directory
.symlink_metadata(name)
.map_err(|error| RootRefusal::Unreadable {
path: target.to_path_buf(),
message: error.to_string(),
})?;
if metadata.is_symlink() {
return Err(RootRefusal::LinkComponent {
component: target.to_path_buf(),
});
}
if !metadata.is_dir() {
return Err(RootRefusal::Unreadable {
path: target.to_path_buf(),
message: "path component is not a directory".to_owned(),
});
}
let child = directory
.open_dir(name)
.map_err(|error| RootRefusal::Unreadable {
path: target.to_path_buf(),
message: error.to_string(),
})?;
exact_spelling_from_dir(&child, components, target)
}
#[cfg(any(feature = "server", feature = "embed"))]
pub(crate) struct AnchoredRegularObservation {
pub metadata: std::fs::Metadata,
pub len: u64,
pub bytes: Option<Vec<u8>>,
}
#[cfg(any(feature = "server", feature = "embed"))]
pub(crate) fn observe_regular_beneath(
lease: &PhysicalRootLease,
relative: &Path,
read_limit: Option<usize>,
) -> Result<Option<AnchoredRegularObservation>, RootRefusal> {
use std::io::Read;
let Some((file, path)) = open_regular_beneath(lease, relative)? else {
return Ok(None);
};
let mut file = file.into_std();
let before = file.metadata().map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?;
let modified = before.modified().map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?;
let bytes = if let Some(max_bytes) = read_limit {
let limit = max_bytes
.checked_add(1)
.ok_or_else(|| RootRefusal::Unreadable {
path: path.clone(),
message: "bounded read limit overflow".to_owned(),
})?;
if before.len() > max_bytes as u64 {
return Err(RootRefusal::Unreadable {
path,
message: "regular file exceeds bounded read limit".to_owned(),
});
}
let mut bytes = Vec::new();
Read::by_ref(&mut file)
.take(limit as u64)
.read_to_end(&mut bytes)
.map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?;
if bytes.len() > max_bytes {
return Err(RootRefusal::Unreadable {
path,
message: "regular file changed during bounded read".to_owned(),
});
}
Some(bytes)
} else {
None
};
let after = file.metadata().map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?;
if before.len() != after.len() || after.modified().ok() != Some(modified) {
return Err(RootRefusal::Unreadable {
path,
message: "regular file changed during observation".to_owned(),
});
}
Ok(Some(AnchoredRegularObservation {
metadata: before.clone(),
len: before.len(),
bytes,
}))
}
#[cfg(any(feature = "server", feature = "embed"))]
pub(crate) fn probe_regular_beneath(
lease: &PhysicalRootLease,
relative: &Path,
prefix_limit: usize,
) -> Result<Option<(std::fs::Metadata, Vec<u8>)>, RootRefusal> {
use std::io::Read;
if prefix_limit > 1_048_576 {
return Err(RootRefusal::Unreadable {
path: lease.root().join(relative),
message: "source probe exceeds bounded prefix limit".to_owned(),
});
}
let Some((file, path)) = open_regular_beneath(lease, relative)? else {
return Ok(None);
};
let mut file = file.into_std();
let before = file.metadata().map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?;
let before_modified = before.modified().map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?;
let mut bytes = Vec::new();
Read::by_ref(&mut file)
.take(prefix_limit as u64)
.read_to_end(&mut bytes)
.map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?;
let after = file.metadata().map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?;
let after_modified = after.modified().map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?;
if before.len() != after.len() || before_modified != after_modified {
return Err(RootRefusal::Unreadable {
path,
message: "regular file changed during prefix probe".to_owned(),
});
}
Ok(Some((before, bytes)))
}
#[cfg(any(feature = "server", feature = "embed"))]
#[derive(Clone, Copy, PartialEq, Eq)]
pub(crate) enum AnchoredEntryKind {
Regular,
Directory,
Link,
Other,
}
#[cfg(any(feature = "server", feature = "embed"))]
pub(crate) struct AnchoredDirectoryEntry {
pub relative: PathBuf,
pub kind: AnchoredEntryKind,
}
#[cfg(any(feature = "server", feature = "embed"))]
pub(crate) fn list_directory_beneath(
lease: &PhysicalRootLease,
relative: &Path,
max_entries: usize,
) -> Result<Option<Vec<AnchoredDirectoryEntry>>, RootRefusal> {
let directory = if relative == Path::new(".") {
lease.directory_capability()?
} else {
let root = lease.directory_capability()?;
match root.symlink_metadata(relative) {
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Ok(metadata) if metadata.is_symlink() => {
return Err(RootRefusal::LinkComponent {
component: lease.root().join(relative),
});
}
Ok(metadata) if metadata.is_dir() => {}
Ok(_) => {
return Err(RootRefusal::Unreadable {
path: lease.root().join(relative),
message: "not a directory".to_owned(),
});
}
Err(error) => {
return Err(RootRefusal::Unreadable {
path: lease.root().join(relative),
message: error.to_string(),
});
}
}
return list_opened_directory(
&lease.child_directory(relative, false)?,
relative,
max_entries,
)
.map(Some);
};
list_entries_from_dir(directory, lease.root(), relative, max_entries).map(Some)
}
#[cfg(any(feature = "server", feature = "embed"))]
fn list_opened_directory(
opened: &PhysicalRootLease,
relative: &Path,
max_entries: usize,
) -> Result<Vec<AnchoredDirectoryEntry>, RootRefusal> {
list_entries_from_dir(
opened.directory_capability()?,
opened.root(),
relative,
max_entries,
)
}
#[cfg(any(feature = "server", feature = "embed"))]
fn list_entries_from_dir(
directory: &Dir,
root: &Path,
relative: &Path,
max_entries: usize,
) -> Result<Vec<AnchoredDirectoryEntry>, RootRefusal> {
let mut entries = Vec::new();
for entry in directory
.read_dir(".")
.map_err(|error| RootRefusal::Unreadable {
path: root.to_path_buf(),
message: error.to_string(),
})?
{
let entry = entry.map_err(|error| RootRefusal::Unreadable {
path: root.to_path_buf(),
message: error.to_string(),
})?;
let name = entry.file_name();
let metadata =
directory
.symlink_metadata(&name)
.map_err(|error| RootRefusal::Unreadable {
path: root.join(&name),
message: error.to_string(),
})?;
let kind = if metadata.is_symlink() {
AnchoredEntryKind::Link
} else if metadata.is_dir() {
AnchoredEntryKind::Directory
} else if metadata.is_file() {
AnchoredEntryKind::Regular
} else {
AnchoredEntryKind::Other
};
entries.push(AnchoredDirectoryEntry {
relative: if relative == Path::new(".") {
PathBuf::from(name)
} else {
relative.join(name)
},
kind,
});
if entries.len() > max_entries {
return Err(RootRefusal::Unreadable {
path: root.to_path_buf(),
message: "directory enumeration exceeds its bounded chunk".to_owned(),
});
}
}
entries.sort_by(|left, right| left.relative.cmp(&right.relative));
Ok(entries)
}
pub(crate) fn read_regular_beneath(
lease: &PhysicalRootLease,
relative: &Path,
max_bytes: usize,
) -> Result<Option<Vec<u8>>, RootRefusal> {
use std::io::Read;
let Some((file, path)) = open_regular_beneath(lease, relative)? else {
return Ok(None);
};
let length = file
.metadata()
.map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?
.len();
if length > max_bytes as u64 {
return Err(RootRefusal::Unreadable {
path,
message: "regular file exceeds byte limit".to_string(),
});
}
let mut bytes = Vec::new();
file.take((max_bytes as u64).saturating_add(1))
.read_to_end(&mut bytes)
.map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?;
if bytes.len() > max_bytes {
return Err(RootRefusal::Unreadable {
path,
message: "regular file exceeds byte limit".to_string(),
});
}
Ok(Some(bytes))
}
#[cfg(feature = "embed")]
pub(crate) fn digest_regular_beneath(
lease: &PhysicalRootLease,
relative: &Path,
) -> Result<Option<String>, RootRefusal> {
use sha2::{Digest as _, Sha256};
use std::fmt::Write as _;
use std::io::Read as _;
let Some((mut file, path)) = open_regular_beneath(lease, relative)? else {
return Ok(None);
};
let expected_len = file
.metadata()
.map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?
.len();
let mut hasher = Sha256::new();
let mut observed_len = 0_u64;
let mut buffer = [0_u8; 64 * 1024];
loop {
let count = file
.read(&mut buffer)
.map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?;
if count == 0 {
break;
}
observed_len =
observed_len
.checked_add(count as u64)
.ok_or_else(|| RootRefusal::Unreadable {
path: path.clone(),
message: "regular file length changed during hash".to_string(),
})?;
if observed_len > expected_len {
return Err(RootRefusal::Unreadable {
path,
message: "regular file length changed during hash".to_string(),
});
}
hasher.update(&buffer[..count]);
}
let final_len = file
.metadata()
.map_err(|error| RootRefusal::Unreadable {
path: path.clone(),
message: error.to_string(),
})?
.len();
if observed_len != expected_len || final_len != expected_len {
return Err(RootRefusal::Unreadable {
path,
message: "regular file length changed during hash".to_string(),
});
}
let mut digest = String::with_capacity(64);
for byte in hasher.finalize() {
write!(digest, "{byte:02x}").expect("hex writes to String");
}
Ok(Some(digest))
}
pub(crate) fn read_regular_beneath_root(
root: &Path,
relative: &Path,
max_bytes: usize,
) -> Result<Option<Vec<u8>>, RootRefusal> {
let lease = PhysicalRootLease::take(root);
read_regular_beneath(&lease, relative, max_bytes)
}
#[cfg(all(test, feature = "embed"))]
pub(crate) fn regular_file_size_beneath_root(
root: &Path,
relative: &Path,
) -> Result<Option<u64>, RootRefusal> {
let lease = PhysicalRootLease::take(root);
regular_file_size_beneath(&lease, relative)
}
#[cfg(feature = "embed")]
pub(crate) fn regular_file_size_beneath(
lease: &PhysicalRootLease,
relative: &Path,
) -> Result<Option<u64>, RootRefusal> {
let Some((file, path)) = open_regular_beneath(lease, relative)? else {
return Ok(None);
};
let opened = file.metadata().map_err(|error| RootRefusal::Unreadable {
path,
message: error.to_string(),
})?;
Ok(Some(opened.len()))
}
pub(crate) fn sync_root_file_beneath(
lease: &PhysicalRootLease,
relative: &Path,
) -> Result<(), RootRefusal> {
let target = lease.resolve_beneath(relative)?;
if target
.relative()
.parent()
.is_some_and(|parent| !parent.as_os_str().is_empty())
{
return Err(RootRefusal::EscapesRoot {
requested: relative.to_path_buf(),
});
}
let Some((file, path)) = open_regular_beneath(lease, relative)? else {
return Err(RootRefusal::Unreadable {
path: target.path(),
message: "committed source file is absent".to_owned(),
});
};
file.sync_all().map_err(|error| RootRefusal::Unreadable {
path,
message: error.to_string(),
})?;
#[cfg(unix)]
sync_directory_beneath_capability(lease.capability()?).map_err(|error| {
RootRefusal::Unreadable {
path: lease.root().to_path_buf(),
message: error.to_string(),
}
})?;
#[cfg(not(any(unix, windows)))]
return Err(RootRefusal::Unreadable {
path: lease.root().to_path_buf(),
message: "parent durability unsupported".to_owned(),
});
Ok(())
}
#[cfg(unix)]
fn verify_owner_only(file: &cap_std::fs::File) -> std::io::Result<()> {
use cap_std::fs::PermissionsExt;
let mode = file.metadata()?.permissions().mode() & 0o777;
if mode == 0o600 {
Ok(())
} else {
Err(std::io::Error::other("owner-only mode was not preserved"))
}
}
#[cfg(unix)]
fn protect_owner_only(file: &cap_std::fs::File) -> std::io::Result<()> {
verify_owner_only(file)
}
#[cfg(windows)]
#[allow(unsafe_code)]
mod owner_only_windows {
use std::ffi::c_void;
use std::io;
use std::mem::size_of;
use std::os::windows::io::AsRawHandle;
use windows::Win32::Foundation::{CloseHandle, HANDLE};
use windows::Win32::Security::{
ACCESS_ALLOWED_ACE, ACL, ACL_REVISION, ACL_SIZE_INFORMATION, AclSizeInformation,
AddAccessAllowedAce, DACL_SECURITY_INFORMATION, EqualSid, GetAce, GetAclInformation,
GetKernelObjectSecurity, GetLengthSid, GetSecurityDescriptorControl,
GetSecurityDescriptorDacl, GetTokenInformation, InitializeAcl,
InitializeSecurityDescriptor, PROTECTED_DACL_SECURITY_INFORMATION, PSECURITY_DESCRIPTOR,
PSID, SE_DACL_PROTECTED, SECURITY_DESCRIPTOR, SetKernelObjectSecurity,
SetSecurityDescriptorControl, SetSecurityDescriptorDacl, TOKEN_QUERY, TOKEN_USER,
TokenUser,
};
use windows::Win32::Storage::FileSystem::FILE_ALL_ACCESS;
use windows::Win32::System::Threading::{GetCurrentProcess, OpenProcessToken};
fn io_error(error: windows::core::Error) -> io::Error {
io::Error::other(error)
}
fn current_user_sid() -> io::Result<(Vec<u64>, PSID)> {
let mut token = HANDLE::default();
unsafe { OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &mut token) }
.map_err(io_error)?;
let result = (|| {
let mut len = 0_u32;
let _ = unsafe { GetTokenInformation(token, TokenUser, None, 0, &mut len) };
if len < size_of::<TOKEN_USER>() as u32 || len > 64 * 1024 {
return Err(io::Error::other("invalid current-user token size"));
}
let mut storage = vec![0_u64; (len as usize).div_ceil(8)];
unsafe {
GetTokenInformation(
token,
TokenUser,
Some(storage.as_mut_ptr().cast()),
len,
&mut len,
)
}
.map_err(io_error)?;
let sid = unsafe { (*(storage.as_ptr().cast::<TOKEN_USER>())).User.Sid };
if sid.0.is_null() {
return Err(io::Error::other("current-user SID is absent"));
}
Ok((storage, sid))
})();
let _ = unsafe { CloseHandle(token) };
result
}
fn handle(file: &cap_std::fs::File) -> HANDLE {
HANDLE(file.as_raw_handle())
}
pub(super) fn protect(file: &cap_std::fs::File) -> io::Result<()> {
let (_token_storage, sid) = current_user_sid()?;
let sid_len = unsafe { GetLengthSid(sid) as usize };
if sid_len == 0 || sid_len > 64 * 1024 {
return Err(io::Error::other("invalid current-user SID length"));
}
let acl_len =
size_of::<ACL>() + size_of::<ACCESS_ALLOWED_ACE>() - size_of::<u32>() + sid_len;
let mut acl_storage = vec![0_u64; acl_len.div_ceil(8)];
let acl = acl_storage.as_mut_ptr().cast::<ACL>();
let mut descriptor = SECURITY_DESCRIPTOR::default();
let descriptor_ptr =
PSECURITY_DESCRIPTOR((&mut descriptor as *mut SECURITY_DESCRIPTOR).cast());
unsafe {
InitializeAcl(acl, acl_len as u32, ACL_REVISION).map_err(io_error)?;
AddAccessAllowedAce(acl, ACL_REVISION, FILE_ALL_ACCESS.0, sid).map_err(io_error)?;
InitializeSecurityDescriptor(descriptor_ptr, 1).map_err(io_error)?;
SetSecurityDescriptorDacl(descriptor_ptr, true, Some(acl), false).map_err(io_error)?;
SetSecurityDescriptorControl(descriptor_ptr, SE_DACL_PROTECTED, SE_DACL_PROTECTED)
.map_err(io_error)?;
SetKernelObjectSecurity(
handle(file),
DACL_SECURITY_INFORMATION | PROTECTED_DACL_SECURITY_INFORMATION,
descriptor_ptr,
)
.map_err(io_error)?;
}
verify(file)
}
pub(super) fn verify(file: &cap_std::fs::File) -> io::Result<()> {
let (_token_storage, sid) = current_user_sid()?;
let mut len = 0_u32;
let _ = unsafe {
GetKernelObjectSecurity(handle(file), DACL_SECURITY_INFORMATION.0, None, 0, &mut len)
};
if len < size_of::<SECURITY_DESCRIPTOR>() as u32 || len > 64 * 1024 {
return Err(io::Error::other("invalid file security descriptor size"));
}
let mut storage = vec![0_u64; (len as usize).div_ceil(8)];
let descriptor = PSECURITY_DESCRIPTOR(storage.as_mut_ptr().cast());
unsafe {
GetKernelObjectSecurity(
handle(file),
DACL_SECURITY_INFORMATION.0,
Some(descriptor),
len,
&mut len,
)
.map_err(io_error)?;
}
let mut control = Default::default();
let mut revision = 0_u32;
let mut present = Default::default();
let mut defaulted = Default::default();
let mut acl = std::ptr::null_mut();
unsafe {
GetSecurityDescriptorControl(descriptor, &mut control, &mut revision)
.map_err(io_error)?;
GetSecurityDescriptorDacl(descriptor, &mut present, &mut acl, &mut defaulted)
.map_err(io_error)?;
}
if control & SE_DACL_PROTECTED.0 == 0 || !present.as_bool() || acl.is_null() {
return Err(io::Error::other("file DACL is not private"));
}
let mut info = ACL_SIZE_INFORMATION::default();
unsafe {
GetAclInformation(
acl,
(&mut info as *mut ACL_SIZE_INFORMATION).cast::<c_void>(),
size_of::<ACL_SIZE_INFORMATION>() as u32,
AclSizeInformation,
)
.map_err(io_error)?;
}
if info.AceCount != 1 {
return Err(io::Error::other("file DACL has unexpected entries"));
}
let mut ace_ptr = std::ptr::null_mut();
unsafe { GetAce(acl, 0, &mut ace_ptr) }.map_err(io_error)?;
let ace = unsafe { &*(ace_ptr.cast::<ACCESS_ALLOWED_ACE>()) };
if ace.Header.AceType != 0 || ace.Mask != FILE_ALL_ACCESS.0 {
return Err(io::Error::other("file DACL has unexpected rights"));
}
let ace_sid = PSID((&ace.SidStart as *const u32).cast_mut().cast());
unsafe { EqualSid(ace_sid, sid) }.map_err(io_error)?;
Ok(())
}
}
#[cfg(windows)]
fn protect_owner_only(file: &cap_std::fs::File) -> std::io::Result<()> {
owner_only_windows::protect(file)
}
#[cfg(windows)]
fn verify_owner_only(file: &cap_std::fs::File) -> std::io::Result<()> {
owner_only_windows::verify(file)
}
#[cfg(not(any(unix, windows)))]
fn protect_owner_only(_file: &cap_std::fs::File) -> std::io::Result<()> {
Err(std::io::Error::other(
"owner-only publication is unavailable",
))
}
#[cfg(not(any(unix, windows)))]
fn verify_owner_only(_file: &cap_std::fs::File) -> std::io::Result<()> {
Err(std::io::Error::other(
"owner-only publication is unavailable",
))
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum DurableReplaceStage {
TempWritten,
TempSynced,
Replaced,
ParentSynced,
}
pub(crate) enum DurableReplaceError<E> {
Root(RootRefusal),
Stage(E),
ImageMismatch,
}
pub(crate) fn durable_replace_root_file_beneath<E>(
lease: &PhysicalRootLease,
relative: &Path,
contents: &[u8],
prefix: &str,
mut stage: impl FnMut(DurableReplaceStage, &mut cap_std::fs::File) -> Result<(), E>,
) -> Result<(), DurableReplaceError<E>> {
use std::io::{Read as _, Seek as _, SeekFrom};
let target = lease
.resolve_beneath(relative)
.map_err(DurableReplaceError::Root)?;
if target
.relative()
.parent()
.is_some_and(|parent| !parent.as_os_str().is_empty())
{
return Err(DurableReplaceError::Root(RootRefusal::EscapesRoot {
requested: relative.to_path_buf(),
}));
}
lease
.refuse_link_relative(target.relative())
.map_err(DurableReplaceError::Root)?;
let dir = lease.capability().map_err(DurableReplaceError::Root)?;
let unreadable = |path: PathBuf, error: std::io::Error| {
DurableReplaceError::Root(RootRefusal::Unreadable {
path,
message: error.to_string(),
})
};
struct TempCleanup<'a> {
dir: &'a Dir,
relative: PathBuf,
armed: bool,
}
impl Drop for TempCleanup<'_> {
fn drop(&mut self) {
if self.armed {
let _ = self.dir.remove_file(&self.relative);
}
}
}
let mut opened = None;
for attempt in 0..MAX_TEMP_ATTEMPTS {
let candidate = PathBuf::from(format!(
"{prefix}{}-{}-{attempt}",
std::process::id(),
NEXT_TEMP.fetch_add(1, Ordering::Relaxed)
));
let mut options = cap_std::fs::OpenOptions::new();
options.read(true).write(true).create_new(true);
#[cfg(windows)]
{
use cap_std::fs::OpenOptionsExt;
use windows::Win32::Storage::FileSystem::{
DELETE, FILE_FLAG_WRITE_THROUGH, FILE_GENERIC_READ, FILE_GENERIC_WRITE,
FILE_SHARE_DELETE, FILE_SHARE_READ, FILE_SHARE_WRITE,
};
options.access_mode((FILE_GENERIC_READ | FILE_GENERIC_WRITE | DELETE).0);
options.share_mode((FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE).0);
options.custom_flags(FILE_FLAG_WRITE_THROUGH.0);
}
match dir.open_with(&candidate, &options) {
Ok(file) => {
opened = Some((candidate, file));
break;
}
Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
Err(error) => return Err(unreadable(lease.root().join(candidate), error)),
}
}
let (temp_relative, mut file) = opened.ok_or_else(|| {
DurableReplaceError::Root(RootRefusal::Unreadable {
path: lease.root().to_path_buf(),
message: "no unused curation temporary name was available".to_owned(),
})
})?;
let mut cleanup = TempCleanup {
dir,
relative: temp_relative.clone(),
armed: true,
};
let temp_path = lease.root().join(&temp_relative);
file.write_all(contents)
.and_then(|()| file.flush())
.map_err(|error| unreadable(temp_path.clone(), error))?;
stage(DurableReplaceStage::TempWritten, &mut file).map_err(DurableReplaceError::Stage)?;
file.seek(SeekFrom::Start(0))
.map_err(|error| unreadable(temp_path.clone(), error))?;
let mut observed = Vec::new();
(&mut file)
.take((contents.len() as u64).saturating_add(1))
.read_to_end(&mut observed)
.map_err(|error| unreadable(temp_path.clone(), error))?;
if observed != contents {
return Err(DurableReplaceError::ImageMismatch);
}
file.sync_all()
.map_err(|error| unreadable(lease.root().join(&temp_relative), error))?;
stage(DurableReplaceStage::TempSynced, &mut file).map_err(DurableReplaceError::Stage)?;
lease
.refuse_link_relative(target.relative())
.map_err(DurableReplaceError::Root)?;
if !lease.is_live() {
return Err(DurableReplaceError::Root(RootRefusal::LeaseRevoked));
}
#[cfg(windows)]
windows_write_through_replace_beneath(dir, &file, target.relative())
.map_err(|error| unreadable(target.path(), error))?;
#[cfg(not(windows))]
dir.rename(&temp_relative, dir, target.relative())
.map_err(|error| unreadable(target.path(), error))?;
cleanup.armed = false;
stage(DurableReplaceStage::Replaced, &mut file).map_err(DurableReplaceError::Stage)?;
file.sync_all()
.map_err(|error| unreadable(target.path(), error))?;
#[cfg(unix)]
sync_directory_beneath_capability(dir)
.map_err(|error| unreadable(lease.root().to_path_buf(), error))?;
#[cfg(not(any(unix, windows)))]
return Err(DurableReplaceError::Root(RootRefusal::Unreadable {
path: lease.root().to_path_buf(),
message: "parent durability unsupported".to_owned(),
}));
stage(DurableReplaceStage::ParentSynced, &mut file).map_err(DurableReplaceError::Stage)
}
#[cfg(windows)]
#[allow(unsafe_code)]
fn windows_write_through_replace_beneath(
dir: &Dir,
file: &cap_std::fs::File,
target: &Path,
) -> std::io::Result<()> {
use std::os::windows::ffi::OsStrExt;
use std::os::windows::io::AsRawHandle;
use windows::Wdk::Storage::FileSystem::{
FILE_RENAME_INFORMATION, FileRenameInformation, NtSetInformationFile,
};
use windows::Win32::Foundation::{HANDLE, RtlNtStatusToDosError};
use windows::Win32::System::IO::IO_STATUS_BLOCK;
let name = target.as_os_str().encode_wide().collect::<Vec<_>>();
let length = std::mem::offset_of!(FILE_RENAME_INFORMATION, FileName) + name.len() * 2;
let mut storage = vec![0_u64; length.div_ceil(8)];
let info = storage.as_mut_ptr().cast::<FILE_RENAME_INFORMATION>();
unsafe {
(*info).Anonymous.ReplaceIfExists = true;
(*info).RootDirectory = HANDLE(dir.as_raw_handle());
(*info).FileNameLength = (name.len() * 2) as u32;
std::ptr::copy_nonoverlapping(name.as_ptr(), (*info).FileName.as_mut_ptr(), name.len());
let mut io_status = IO_STATUS_BLOCK::default();
let status = NtSetInformationFile(
HANDLE(file.as_raw_handle()),
&mut io_status,
info.cast(),
length as u32,
FileRenameInformation,
);
if status.0 < 0 {
Err(std::io::Error::from_raw_os_error(
RtlNtStatusToDosError(status) as i32,
))
} else {
Ok(())
}
}
}
pub fn stage_replacement(
lease: &PhysicalRootLease,
relative: &Path,
contents: &[u8],
) -> Result<StagedReplacement, RootRefusal> {
stage_replacement_with_policy(lease, relative, contents, false)
}
fn stage_replacement_with_policy(
lease: &PhysicalRootLease,
relative: &Path,
contents: &[u8],
owner_only: bool,
) -> Result<StagedReplacement, RootRefusal> {
let target = lease.resolve_beneath(relative)?;
lease.refuse_link_relative(target.relative())?;
let dir = lease.capability()?;
let staged_dir = dir.try_clone().map_err(|error| RootRefusal::Unreadable {
path: lease.root().to_path_buf(),
message: error.to_string(),
})?;
let mut steps = Vec::new();
if let Some(parent) = target.relative().parent()
&& !parent.as_os_str().is_empty()
{
dir.create_dir_all(parent)
.map_err(|error| RootRefusal::Unreadable {
path: target.parent().to_path_buf(),
message: error.to_string(),
})?;
}
let mut temp_relative = PathBuf::new();
let mut file = None;
for attempt in 0..MAX_TEMP_ATTEMPTS {
let mut name = target.leaf().to_os_string();
name.push(format!(
".symforge-tmp-{}-{}-{attempt}",
std::process::id(),
NEXT_TEMP.fetch_add(1, Ordering::Relaxed)
));
let candidate = match target.relative().parent() {
Some(parent) if !parent.as_os_str().is_empty() => parent.join(&name),
_ => PathBuf::from(&name),
};
let mut options = cap_std::fs::OpenOptions::new();
options.write(true).create_new(true);
#[cfg(unix)]
if owner_only {
use cap_std::fs::OpenOptionsExt;
options.mode(0o600);
}
#[cfg(windows)]
if owner_only {
use cap_std::fs::OpenOptionsExt;
use windows::Win32::Storage::FileSystem::{
FILE_GENERIC_WRITE, READ_CONTROL, WRITE_DAC,
};
options.access_mode((FILE_GENERIC_WRITE | READ_CONTROL | WRITE_DAC).0);
options.share_mode(0);
}
match dir.open_with(&candidate, &options) {
Ok(handle) => {
temp_relative = candidate;
file = Some(handle);
break;
}
Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue,
Err(error) => {
return Err(RootRefusal::Unreadable {
path: lease.root().join(&candidate),
message: error.to_string(),
});
}
}
}
let Some(mut handle) = file else {
return Err(RootRefusal::Unreadable {
path: target.parent().to_path_buf(),
message: "no unused temporary name was available beneath the leased root".to_owned(),
});
};
if owner_only && let Err(error) = protect_owner_only(&handle) {
drop(handle);
let _ = dir.remove_file(&temp_relative);
return Err(RootRefusal::Unreadable {
path: lease.root().join(&temp_relative),
message: error.to_string(),
});
}
let written = handle.write_all(contents).and_then(|()| handle.sync_all());
drop(handle);
if let Err(error) = written {
let _ = dir.remove_file(&temp_relative);
return Err(RootRefusal::Unreadable {
path: lease.root().join(&temp_relative),
message: error.to_string(),
});
}
steps.push(ReplacementStep::TempCreated);
let temp_path = lease.root().join(&temp_relative);
Ok(StagedReplacement {
temp_relative,
temp_path,
target_relative: target.relative().to_path_buf(),
target: target.path(),
lease: lease.identity(),
revoked: Arc::clone(lease.revocation()),
dir: staged_dir,
steps,
owner_only,
})
}
#[derive(Debug)]
pub struct StagedReplacement {
temp_relative: PathBuf,
temp_path: PathBuf,
target_relative: PathBuf,
target: PathBuf,
lease: PhysicalRootIdentity,
revoked: Arc<AtomicBool>,
dir: Dir,
steps: Vec<ReplacementStep>,
owner_only: bool,
}
impl StagedReplacement {
pub fn temp_path(&self) -> &Path {
&self.temp_path
}
pub fn target(&self) -> &Path {
&self.target
}
pub fn commit(mut self) -> Result<WriteReceipt, RootRefusal> {
if self.revoked.load(Ordering::Acquire) {
return Err(RootRefusal::LeaseRevoked);
}
if let Err(error) = self
.dir
.rename(&self.temp_relative, &self.dir, &self.target_relative)
{
let _ = self.dir.remove_file(&self.temp_relative);
self.steps.clear();
return Err(RootRefusal::Unreadable {
path: self.target.clone(),
message: error.to_string(),
});
}
if self.owner_only {
let verified = self
.dir
.open(&self.target_relative)
.and_then(|file| verify_owner_only(&file));
if let Err(error) = verified {
return Err(RootRefusal::Unreadable {
path: self.target.clone(),
message: error.to_string(),
});
}
}
let receipt = WriteReceipt {
steps: {
let mut steps = std::mem::take(&mut self.steps);
steps.push(ReplacementStep::Replaced);
steps
},
target: self.target.clone(),
lease: self.lease,
};
self.temp_relative = PathBuf::new();
self.temp_path = PathBuf::new();
Ok(receipt)
}
}
impl Drop for StagedReplacement {
fn drop(&mut self) {
if !self.temp_relative.as_os_str().is_empty() {
let _ = self.dir.remove_file(&self.temp_relative);
}
}
}
#[cfg(test)]
mod capability_read_tests {
use super::*;
#[test]
fn bounded_read_distinguishes_absent_regular_and_invalid_targets() {
let root = tempfile::tempdir().expect("temporary root");
std::fs::write(root.path().join("present"), b"source bytes").expect("source");
std::fs::create_dir(root.path().join("directory")).expect("directory");
assert_eq!(
read_regular_beneath_root(root.path(), Path::new("missing/nested"), 64)
.expect("absent target"),
None
);
assert_eq!(
read_regular_beneath_root(root.path(), Path::new("present"), 64).expect("regular file"),
Some(b"source bytes".to_vec())
);
assert!(read_regular_beneath_root(root.path(), Path::new("present"), 4).is_err());
assert!(read_regular_beneath_root(root.path(), Path::new("directory"), 64).is_err());
assert!(read_regular_beneath_root(root.path(), Path::new("../escape"), 64).is_err());
}
#[cfg(feature = "embed")]
#[test]
fn regular_size_observes_large_file_without_reading_its_content() {
let root = tempfile::tempdir().expect("temporary root");
let path = root.path().join("large");
std::fs::File::create(&path)
.expect("create sparse file")
.set_len(4 * 1024 * 1024 + 1)
.expect("size sparse file");
assert_eq!(
regular_file_size_beneath_root(root.path(), Path::new("large"))
.expect("size regular file"),
Some(4 * 1024 * 1024 + 1)
);
assert_eq!(
regular_file_size_beneath_root(root.path(), Path::new("missing")).expect("absent file"),
None
);
assert!(regular_file_size_beneath_root(root.path(), Path::new("../escape")).is_err());
}
#[cfg(feature = "embed")]
#[test]
fn anchored_prefix_probe_accepts_a_large_file_without_reading_past_limit() {
let root = tempfile::tempdir().expect("temporary root");
let path = root.path().join("large");
std::fs::write(&path, vec![b'x'; 2 * 1024 * 1024]).expect("large source");
let lease = PhysicalRootLease::take(root.path());
let (metadata, prefix) = probe_regular_beneath(&lease, Path::new("large"), 1024)
.expect("bounded prefix probe")
.expect("regular file");
assert_eq!(metadata.len(), 2 * 1024 * 1024);
assert_eq!(prefix, vec![b'x'; 1024]);
assert!(probe_regular_beneath(&lease, Path::new("../escape"), 1024).is_err());
}
#[cfg(feature = "embed")]
#[test]
fn anchored_directory_listing_preserves_relative_names_and_bounds() {
let root = tempfile::tempdir().expect("temporary root");
std::fs::create_dir(root.path().join("nested")).expect("nested directory");
std::fs::write(root.path().join("nested/file.rs"), b"fn example() {}")
.expect("nested source");
let lease = PhysicalRootLease::take(root.path());
let entries = list_directory_beneath(&lease, Path::new("."), 1)
.expect("root listing")
.expect("root directory");
assert_eq!(entries.len(), 1);
assert_eq!(entries[0].relative, Path::new("nested"));
assert!(entries[0].kind == AnchoredEntryKind::Directory);
let nested = list_directory_beneath(&lease, Path::new("nested"), 1)
.expect("nested listing")
.expect("nested directory");
assert_eq!(nested[0].relative, Path::new("nested/file.rs"));
assert!(nested[0].kind == AnchoredEntryKind::Regular);
assert!(list_directory_beneath(&lease, Path::new("nested"), 0).is_err());
}
#[cfg(feature = "embed")]
#[test]
fn streamed_digest_covers_large_regular_file_and_refuses_invalid_targets() {
let root = tempfile::tempdir().expect("temporary root");
let bytes = vec![b'x'; 4 * 1024 * 1024 + 17];
std::fs::write(root.path().join("large"), &bytes).expect("large source");
std::fs::create_dir(root.path().join("directory")).expect("directory");
let lease = PhysicalRootLease::take(root.path());
assert_eq!(
digest_regular_beneath(&lease, Path::new("large")).expect("stream digest"),
Some(crate::hash::digest_hex(&bytes))
);
assert_eq!(
digest_regular_beneath(&lease, Path::new("missing")).expect("absent target"),
None
);
assert!(digest_regular_beneath(&lease, Path::new("directory")).is_err());
assert!(digest_regular_beneath(&lease, Path::new("../escape")).is_err());
}
}
#[cfg(all(test, any(unix, windows)))]
mod owner_only_tests {
use super::*;
#[test]
fn staged_sensitive_image_is_private_before_publication_and_after_rename() {
let root = tempfile::tempdir().expect("temporary root");
let lease = PhysicalRootLease::take(root.path());
let target = Path::new(".env");
let stage = stage_replacement_with_policy(&lease, target, b"fixture", true)
.expect("owner-only stage");
assert!(!root.path().join(target).exists());
let temp = stage.temp_path().to_path_buf();
let staged_file = std::fs::File::open(&temp).expect("staged private image");
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
assert_eq!(
staged_file.metadata().unwrap().permissions().mode() & 0o777,
0o600
);
}
#[cfg(windows)]
{
let opened = lease
.capability()
.unwrap()
.open(stage.temp_relative.as_path())
.unwrap();
verify_owner_only(&opened).expect("staged protected DACL");
}
drop(staged_file);
stage.commit().expect("published owner-only image");
assert!(!temp.exists());
assert_eq!(std::fs::read(root.path().join(target)).unwrap(), b"fixture");
let published = lease.capability().unwrap().open(target).unwrap();
verify_owner_only(&published).expect("published private image");
}
}
#[cfg(all(test, any(unix, windows)))]
mod anchor_tests {
use super::PhysicalRootAnchor;
use std::fs;
fn temp_root() -> tempfile::TempDir {
tempfile::tempdir().expect("temporary root directory")
}
#[test]
fn distinct_directories_yield_distinct_anchors() {
let root = temp_root();
let a = root.path().join("a");
let b = root.path().join("b");
fs::create_dir(&a).unwrap();
fs::create_dir(&b).unwrap();
let anchor_a = PhysicalRootAnchor::observe(&a).expect("anchor for a");
let anchor_b = PhysicalRootAnchor::observe(&b).expect("anchor for b");
assert_ne!(
anchor_a, anchor_b,
"distinct directories at distinct paths must not share an anchor"
);
}
#[test]
fn same_directory_observed_twice_yields_same_anchor() {
let root = temp_root();
let a = root.path().join("a");
fs::create_dir(&a).unwrap();
let first = PhysicalRootAnchor::observe(&a).expect("first observation");
let second = PhysicalRootAnchor::observe(&a).expect("second observation");
assert_eq!(
first, second,
"a stable directory must not change identity between observations"
);
}
#[test]
fn directory_replaced_at_same_path_yields_new_anchor() {
let root = temp_root();
let a = root.path().join("a");
fs::create_dir_all(a.join("occupied")).unwrap();
let b = root.path().join("b");
fs::create_dir(&b).unwrap();
let before = PhysicalRootAnchor::observe(&a).expect("anchor before replacement");
fs::remove_dir_all(&a).unwrap();
fs::rename(&b, &a).unwrap();
let after = PhysicalRootAnchor::observe(&a).expect("anchor after replacement");
assert_ne!(
before, after,
"a different directory installed at the same path must change the anchor (ABA)"
);
}
#[test]
fn missing_path_yields_none() {
let root = temp_root();
let missing = root.path().join("does-not-exist");
assert_eq!(
PhysicalRootAnchor::observe(&missing),
None,
"a nonexistent path must observe to None, not error or panic"
);
}
#[test]
fn file_yields_some_stable_anchor() {
let root = temp_root();
let f = root.path().join("file.txt");
fs::write(&f, b"payload").unwrap();
let first = PhysicalRootAnchor::observe(&f).expect("file must observe to Some");
let second = PhysicalRootAnchor::observe(&f).expect("re-observation of file");
assert_eq!(
first, second,
"file identity must be stable across observations"
);
}
}