wowlab_fs/

containment.rs

//! Resolution of existing paths within reviewed filesystem boundaries.

use crate::{
    directory, error,
    path::{Component, Path, PathBuf},
};

/// An owned diagnostic for a path that is not below a required root.
#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
#[error("{} is outside {}", path.display(), root.display())]
pub struct OutsideRoot {
    root: PathBuf,
    path: PathBuf,
}

impl OutsideRoot {
    /// Return the required root.
    #[must_use]
    pub fn root(&self) -> &Path {
        &self.root
    }

    /// Return the path found outside the root.
    #[must_use]
    pub fn path(&self) -> &Path {
        &self.path
    }
}

/// Require `path` to be lexically below `root` and return its relative suffix.
///
/// This operation is lexical; use [`resolve_existing`] when the boundary must also hold after symbolic-link resolution.
///
/// # Errors
///
/// Returns an owned diagnostic when `path` is not below `root`.
pub fn relative_to<'a>(root: &Path, path: &'a Path) -> Result<&'a Path, OutsideRoot> {
    match path.strip_prefix(root) {
        Ok(relative) => Ok(relative),
        Err(_) => Err(OutsideRoot {
            root: root.to_path_buf(),
            path: path.to_path_buf(),
        }),
    }
}

/// Failure to resolve an existing relative path within a root.
#[derive(Debug, thiserror::Error)]
#[error("{kind}")]
pub struct ResolveError {
    root: PathBuf,
    path: PathBuf,
    #[source]
    kind: Box<ResolveErrorKind>,
}

#[derive(Debug, thiserror::Error)]
enum ResolveErrorKind {
    #[error(
        "{} is not a non-empty relative path without parent traversal",
        path.display()
    )]
    InvalidRelativePath { path: PathBuf },
    #[error(transparent)]
    Filesystem(error::Error),
    #[error(transparent)]
    OutsideRoot(OutsideRoot),
}

impl ResolveError {
    /// Return the root used for resolution.
    #[must_use]
    pub fn root(&self) -> &Path {
        &self.root
    }

    /// Return the requested or resolved path associated with the failure.
    #[must_use]
    pub fn path(&self) -> &Path {
        &self.path
    }

    /// Return the confinement failure when the path resolved outside the root.
    #[must_use]
    pub fn outside_root(&self) -> Option<&OutsideRoot> {
        match self.kind.as_ref() {
            ResolveErrorKind::OutsideRoot(source) => Some(source),
            ResolveErrorKind::InvalidRelativePath { .. } | ResolveErrorKind::Filesystem(_) => None,
        }
    }
}

/// Resolve an existing reviewed relative path while confining symbolic links.
///
/// The result is host-normalized, absolute, and below the canonical root.
/// Relative inputs may contain only ordinary or current-directory components.
///
/// # Errors
///
/// Returns an error when the input is invalid, canonicalization fails, or symbolic-link resolution escapes the root.
pub fn resolve_existing(root: &Path, relative: &Path) -> Result<PathBuf, ResolveError> {
    if relative.is_empty()
        || !relative
            .components()
            .all(|component| matches!(component, Component::Normal(_) | Component::Current))
    {
        return Err(ResolveError {
            root: root.to_path_buf(),
            path: relative.to_path_buf(),
            kind: Box::new(ResolveErrorKind::InvalidRelativePath {
                path: relative.to_path_buf(),
            }),
        });
    }

    let canonical_root = directory::canonicalize(root).map_err(|source| ResolveError {
        root: root.to_path_buf(),
        path: root.to_path_buf(),
        kind: Box::new(ResolveErrorKind::Filesystem(source)),
    })?;
    let candidate = root.join(relative);
    let canonical_candidate =
        directory::canonicalize(&candidate).map_err(|source| ResolveError {
            root: canonical_root.clone(),
            path: candidate,
            kind: Box::new(ResolveErrorKind::Filesystem(source)),
        })?;

    relative_to(&canonical_root, &canonical_candidate).map_err(|source| ResolveError {
        root: canonical_root,
        path: canonical_candidate.clone(),
        kind: Box::new(ResolveErrorKind::OutsideRoot(source)),
    })?;

    Ok(canonical_candidate)
}

#[cfg(all(test, not(target_family = "wasm")))]
mod tests {
    use googletest::prelude::*;

    use super::{relative_to, resolve_existing};
    use crate::{directory, file, link, temporary::Directory};

    #[gtest]
    fn relative_paths_retain_native_components() -> Result<()> {
        let root = crate::path::Path::new("repository");
        let path = crate::path::Path::new("repository/specs/class/manifest.toml");

        verify_that!(
            relative_to(root, path).or_fail()?,
            eq(crate::path::Path::new("specs/class/manifest.toml"))
        )?;

        Ok(())
    }

    #[gtest]
    fn existing_paths_are_canonical_and_confined() -> Result<()> {
        let directory = Directory::new().or_fail()?;
        let root = directory.path().join("repository");
        let component = root.join("parts/core.toml");

        directory::ensure(component.parent().or_fail()?).or_fail()?;
        file::write_text(&component, "[auras]").or_fail()?;

        verify_eq!(
            resolve_existing(&root, crate::path::Path::new("parts/core.toml")).or_fail()?,
            directory::canonicalize(&component).or_fail()?
        )?;

        Ok(())
    }

    #[gtest]
    fn file_links_cannot_escape_the_canonical_root() -> Result<()> {
        let directory = Directory::new().or_fail()?;
        let root = directory.path().join("repository");
        let component = root.join("parts/core.toml");
        let outside = directory.path().join("outside.toml");

        directory::ensure(component.parent().or_fail()?).or_fail()?;
        file::write_text(&outside, "[auras]").or_fail()?;
        link::file(&outside, &component).or_fail()?;

        let error = resolve_existing(&root, crate::path::Path::new("parts/core.toml"))
            .err()
            .or_fail()?;

        verify_eq!(
            error.outside_root().map(super::OutsideRoot::path),
            Some(directory::canonicalize(&outside).or_fail()?.as_ref())
        )?;

        Ok(())
    }
}