exarch-core 0.7.0

//! Hardlink security validation and tracking.

use std::collections::HashMap;
use std::path::Path;
use std::path::PathBuf;

use crate::ArchiveError;
use crate::PolicySetting;
use crate::Result;
use crate::SecurityConfig;
use crate::config::Validated;
use crate::security::fs_view::FsView;
use crate::security::fs_view::HostFs;
use crate::types::DestDir;
use crate::types::SafePath;
use crate::types::safe_path::check_windows_component;
use crate::types::safe_symlink::resolve_through_symlinks_in;

/// Error for a hardlink whose target is absent when the link is created.
pub fn hardlink_target_missing(target: &Path) -> ArchiveError {
    ArchiveError::InvalidArchive(format!(
        "hardlink target does not exist: {}",
        target.display()
    ))
}

/// Fails with the hardlink-policy refusal unless `config` allows hardlinks.
///
/// # Errors
///
/// Returns `SecurityViolation` ("hardlinks not allowed") when hardlinks are
/// disabled.
pub fn require_hardlinks_allowed(config: &SecurityConfig<Validated>) -> Result<()> {
    if config.allowed.hardlinks {
        Ok(())
    } else {
        Err(ArchiveError::relaxable_violation(
            PolicySetting::Hardlinks,
            "hardlinks not allowed".into(),
        ))
    }
}

/// Tracks hardlink targets during extraction.
///
/// Hardlinks in archives can be used for attacks:
/// 1. Link to files outside the extraction directory
/// 2. Create multiple hardlinks to the same file (resource exhaustion)
/// 3. Link to sensitive files (if absolute paths allowed)
///
/// This tracker ensures:
/// - Hardlinks are allowed in the security configuration
/// - Targets are relative paths
/// - Targets resolve within the destination directory
/// - Duplicate hardlinks are detected
///
/// # Two-Pass Validation
///
/// Hardlinks require two-pass validation:
/// 1. **First pass (during validation):** Track target paths, verify they're
///    within bounds
/// 2. **Second pass (after extraction):** Verify targets actually exist
///
/// This is necessary because hardlink targets may appear later in the archive.
///
/// # Examples
///
/// ```ignore
/// use exarch_core::SecurityConfig;
/// use exarch_core::security::HardlinkTracker;
/// use exarch_core::types::DestDir;
/// use exarch_core::types::SafePath;
/// use std::path::Path;
/// use std::path::PathBuf;
///
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let dest = DestDir::new(PathBuf::from("/tmp"))?;
/// let mut config = SecurityConfig::default();
/// config.allowed.hardlinks = true;
///
/// let mut tracker = HardlinkTracker::new();
/// let link = SafePath::validate(&PathBuf::from("link"), &dest, &config)?;
/// let target = Path::new("target.txt");
///
/// tracker.validate_hardlink(&link, target, &dest, &config)?;
/// # Ok(())
/// # }
/// ```
#[derive(Debug, Default)]
pub struct HardlinkTracker {
    /// Maps target path to the first link path that referenced it
    seen_targets: HashMap<PathBuf, PathBuf>,
}

impl HardlinkTracker {
    /// Creates a new hardlink tracker.
    #[must_use]
    pub fn new() -> Self {
        Self {
            seen_targets: HashMap::new(),
        }
    }

    /// Validates that a hardlink target is safe and tracks it.
    ///
    /// # Performance
    ///
    /// Typical execution time: ~1-5 μs (`HashMap` insert + path validation)
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - Hardlinks are not allowed in configuration
    /// - Target is empty or contains NUL bytes
    /// - Target is an absolute path (including Windows drive/UNC prefixes)
    /// - Target would escape the destination directory
    ///
    /// # Examples
    ///
    /// ```ignore
    /// use exarch_core::SecurityConfig;
    /// use exarch_core::security::HardlinkTracker;
    /// use exarch_core::types::DestDir;
    /// use exarch_core::types::SafePath;
    /// use std::path::Path;
    /// use std::path::PathBuf;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let dest = DestDir::new(PathBuf::from("/tmp"))?;
    /// let mut config = SecurityConfig::default();
    /// config.allowed.hardlinks = true;
    ///
    /// let mut tracker = HardlinkTracker::new();
    /// let link = SafePath::validate(&PathBuf::from("link"), &dest, &config)?;
    /// let target = Path::new("target.txt");
    ///
    /// tracker.validate_hardlink(&link, target, &dest, &config)?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn validate_hardlink(
        &mut self,
        link_path: &SafePath,
        target: &Path,
        dest: &DestDir,
        config: &SecurityConfig<Validated>,
    ) -> Result<()> {
        self.validate_hardlink_in(link_path, target, dest, config, &HostFs)
    }

    /// Validates against `view` instead of the real filesystem.
    #[expect(
        clippy::items_after_statements,
        reason = "the import is placed next to its only use"
    )]
    pub(crate) fn validate_hardlink_in<V: FsView>(
        &mut self,
        link_path: &SafePath,
        target: &Path,
        dest: &DestDir,
        config: &SecurityConfig<Validated>,
        view: &V,
    ) -> Result<()> {
        require_hardlinks_allowed(config)?;

        // Reject empty targets: they do not point anywhere.
        if target.is_empty() {
            return Err(ArchiveError::violation("hardlink target is empty".into()));
        }

        // Reject null bytes in the target before any error message can be
        // built from it. Without this check, a NUL byte either falls
        // through to the OS as a raw `io::Error`, or gets embedded verbatim
        // into a formatted `InvalidArchive` message further downstream (e.g.
        // "hardlink target does not exist: {target}"). The message here
        // intentionally omits the raw target bytes.
        if crate::types::safe_path::has_null_bytes(target) {
            return Err(ArchiveError::violation(
                "hardlink target contains null bytes".into(),
            ));
        }

        use std::path::Component;

        // H-SEC-2: Reject Windows-specific absolute path components in target
        // (before resolution) This prevents bypasses on Windows like
        // C:\ or \\server\share
        for component in target.components() {
            if matches!(component, Component::Prefix(_) | Component::RootDir) {
                return Err(ArchiveError::HardlinkEscape {
                    path: link_path.as_path().to_path_buf(),
                });
            }
        }

        if cfg!(windows) {
            for component in target.components() {
                if let Component::Normal(comp) = component {
                    check_windows_component(comp, config)?;
                }
            }
        }

        // Also reject absolute targets (redundant with above, but keeps
        // existing check)
        if target.is_absolute() {
            return Err(ArchiveError::HardlinkEscape {
                path: link_path.as_path().to_path_buf(),
            });
        }

        // Resolve target against destination, following any on-disk symlinks
        // encountered during traversal.
        //
        // String-based normalization is insufficient: if a previously extracted
        // symlink lies on the target path, a hardlink target can escape the
        // extraction root via on-disk resolution even though string
        // normalization would pass (two-hop chain bypass,
        // GHSA-83g3-92jg-28cx variant — #116).
        let resolved = resolve_through_symlinks_in(
            dest.as_path(),
            target,
            dest.as_path(),
            link_path.as_path(),
            view,
        )
        .map_err(|_| ArchiveError::HardlinkEscape {
            path: link_path.as_path().to_path_buf(),
        })?;

        // Track this hardlink target (H-PERF-6: use entry API)
        self.seen_targets
            .entry(resolved)
            .or_insert_with(|| link_path.as_path().to_path_buf());

        Ok(())
    }

    /// Returns the number of tracked hardlinks.
    #[inline]
    #[must_use]
    pub fn count(&self) -> usize {
        self.seen_targets.len()
    }
}

#[cfg(test)]
impl HardlinkTracker {
    pub(crate) fn has_target(&self, target: &Path) -> bool {
        self.seen_targets.contains_key(target)
    }
}

#[cfg(test)]
#[allow(
    clippy::unwrap_used,
    clippy::expect_used,
    clippy::field_reassign_with_default
)]
mod tests {
    use super::*;
    use std::assert_matches;
    use tempfile::TempDir;

    fn create_test_dest() -> (TempDir, DestDir) {
        let temp = TempDir::new().expect("failed to create temp dir");
        let dest = DestDir::new(temp.path().to_path_buf()).expect("failed to create dest");
        (temp, dest)
    }

    #[test]
    fn test_hardlink_tracker_new() {
        let tracker = HardlinkTracker::new();
        assert_eq!(tracker.count(), 0);
    }

    #[test]
    fn test_validate_hardlink_allowed() {
        let (_temp, dest) = create_test_dest();
        let mut config = SecurityConfig::default();
        config.allowed.hardlinks = true;
        let config = config.validate().expect("valid config");

        let mut tracker = HardlinkTracker::new();
        let link = SafePath::validate(&PathBuf::from("link"), &dest, &config).unwrap();
        let target = PathBuf::from("target.txt");

        assert!(
            tracker
                .validate_hardlink(&link, &target, &dest, &config)
                .is_ok()
        );
        assert_eq!(tracker.count(), 1);
    }

    #[test]
    fn test_validate_hardlink_disabled() {
        let (_temp, dest) = create_test_dest();
        let config = SecurityConfig::default().validate().expect("valid config"); // hardlinks disabled by default

        let mut tracker = HardlinkTracker::new();
        let link = SafePath::validate(&PathBuf::from("link"), &dest, &config).unwrap();
        let target = PathBuf::from("target.txt");

        assert!(
            tracker
                .validate_hardlink(&link, &target, &dest, &config)
                .is_err()
        );
    }

    #[test]
    fn test_validate_hardlink_absolute_target() {
        let (_temp, dest) = create_test_dest();
        let mut config = SecurityConfig::default();
        config.allowed.hardlinks = true;
        let config = config.validate().expect("valid config");

        let mut tracker = HardlinkTracker::new();
        let link = SafePath::validate(&PathBuf::from("link"), &dest, &config).unwrap();
        let target = PathBuf::from("/etc/passwd");

        let result = tracker.validate_hardlink(&link, &target, &dest, &config);
        assert_matches!(result, Err(ArchiveError::HardlinkEscape { .. }));
    }

    #[test]
    fn test_validate_hardlink_escape() {
        let (_temp, dest) = create_test_dest();
        let mut config = SecurityConfig::default();
        config.allowed.hardlinks = true;
        let config = config.validate().expect("valid config");

        let mut tracker = HardlinkTracker::new();
        let link = SafePath::validate(&PathBuf::from("link"), &dest, &config).unwrap();
        let target = PathBuf::from("../../etc/passwd");

        let result = tracker.validate_hardlink(&link, &target, &dest, &config);
        assert_matches!(result, Err(ArchiveError::HardlinkEscape { .. }));
    }

    #[test]
    fn test_hardlink_tracker_multiple() {
        let (_temp, dest) = create_test_dest();
        let mut config = SecurityConfig::default();
        config.allowed.hardlinks = true;
        let config = config.validate().expect("valid config");

        let mut tracker = HardlinkTracker::new();

        let link1 = SafePath::validate(&PathBuf::from("link1"), &dest, &config).unwrap();
        let link2 = SafePath::validate(&PathBuf::from("link2"), &dest, &config).unwrap();

        tracker
            .validate_hardlink(&link1, &PathBuf::from("target1.txt"), &dest, &config)
            .unwrap();
        tracker
            .validate_hardlink(&link2, &PathBuf::from("target2.txt"), &dest, &config)
            .unwrap();

        assert_eq!(tracker.count(), 2);
    }

    #[test]
    fn test_hardlink_tracker_has_target() {
        let (_temp, dest) = create_test_dest();
        let mut config = SecurityConfig::default();
        config.allowed.hardlinks = true;
        let config = config.validate().expect("valid config");

        let mut tracker = HardlinkTracker::new();
        let link = SafePath::validate(&PathBuf::from("link"), &dest, &config).unwrap();
        let target = PathBuf::from("target.txt");

        tracker
            .validate_hardlink(&link, &target, &dest, &config)
            .unwrap();

        let resolved_target = dest.as_path().join(&target);
        assert!(tracker.has_target(&resolved_target));
    }

    #[test]
    fn test_hardlink_tracker_relative_safe() {
        let (_temp, dest) = create_test_dest();
        let mut config = SecurityConfig::default();
        config.allowed.hardlinks = true;
        let config = config.validate().expect("valid config");

        let mut tracker = HardlinkTracker::new();
        let link = SafePath::validate(&PathBuf::from("foo/link"), &dest, &config).unwrap();
        // Safe relative path within destination
        let target = PathBuf::from("target.txt");

        let result = tracker.validate_hardlink(&link, &target, &dest, &config);
        assert!(result.is_ok());
    }

    // H-TEST-2: Duplicate hardlink to same target test
    #[test]
    fn test_duplicate_hardlink_to_same_target() {
        let (_temp, dest) = create_test_dest();
        let mut config = SecurityConfig::default();
        config.allowed.hardlinks = true;
        let config = config.validate().expect("valid config");

        let mut tracker = HardlinkTracker::new();
        let target = PathBuf::from("target.txt");

        // Create multiple hardlinks to the same target
        for i in 0..3 {
            let link =
                SafePath::validate(&PathBuf::from(format!("link{i}")), &dest, &config).unwrap();

            let result = tracker.validate_hardlink(&link, &target, &dest, &config);
            assert!(
                result.is_ok(),
                "multiple hardlinks to same target should be allowed"
            );
        }

        // All three links point to the same target, so only 1 unique target
        // tracked
        assert_eq!(
            tracker.count(),
            1,
            "should track unique targets, not individual links"
        );
    }

    #[test]
    fn test_hardlink_different_targets() {
        let (_temp, dest) = create_test_dest();
        let mut config = SecurityConfig::default();
        config.allowed.hardlinks = true;
        let config = config.validate().expect("valid config");

        let mut tracker = HardlinkTracker::new();

        // Create hardlinks to different targets
        for i in 0..3 {
            let link =
                SafePath::validate(&PathBuf::from(format!("link{i}")), &dest, &config).unwrap();
            let target = PathBuf::from(format!("target{i}.txt"));

            tracker
                .validate_hardlink(&link, &target, &dest, &config)
                .unwrap();
        }

        // Three different targets
        assert_eq!(tracker.count(), 3, "should track each unique target");
    }

    /// Hardlink target that traverses through an already-extracted symlink must
    /// be rejected (two-hop chain, GHSA-83g3-92jg-28cx variant — issue #116).
    ///
    /// Entry 2 (symlink a/b/c/up -> ../..) is on disk when hardlink is
    /// validated. Target a/b/escape/../../etc/passwd: string normalization
    /// → dest/a/etc/passwd (looks safe), but if a/b/escape is an on-disk
    /// symlink resolving outside dest, the hardlink must be rejected.
    #[test]
    #[cfg(unix)]
    #[allow(clippy::unwrap_used)]
    fn test_hardlink_two_hop_chain_rejected() {
        use std::fs;
        use std::os::unix;

        let (temp, dest) = create_test_dest();
        let mut config = SecurityConfig::default();
        config.allowed.hardlinks = true;
        let config = config.validate().expect("valid config");

        // Simulate on-disk state after extracting the two symlink entries.
        let a = temp.path().join("a");
        let b = a.join("b");
        let c = b.join("c");
        fs::create_dir_all(&c).unwrap();
        // a/b/c/up -> ../..  (first hop: resolves to a/)
        unix::fs::symlink("../..", c.join("up")).unwrap();
        // a/b/escape -> c/up/../..  (second hop: resolves outside dest on disk)
        unix::fs::symlink("c/up/../..", b.join("escape")).unwrap();

        let mut tracker = HardlinkTracker::new();
        let link = SafePath::validate(&PathBuf::from("exfil"), &dest, &config).unwrap();
        // Target traverses through the escape symlink
        let target = PathBuf::from("a/b/escape/../../etc/passwd");

        let result = tracker.validate_hardlink(&link, &target, &dest, &config);
        assert_matches!(
            result,
            Err(ArchiveError::HardlinkEscape { .. }),
            "hardlink through two-hop symlink chain must be rejected"
        );
    }

    #[test]
    #[cfg(windows)]
    fn test_hardlink_rejects_windows_hazards_in_target() {
        let (_temp, dest) = create_test_dest();
        let mut config = SecurityConfig::default();
        config.allowed.hardlinks = true;
        let config = config.validate().expect("valid config");
        let link = SafePath::validate(&PathBuf::from("link"), &dest, &config).unwrap();

        for target in ["dir/foo.", "dir/foo ", "dir/a:b", "sub/NUL"] {
            let mut tracker = HardlinkTracker::new();
            assert_matches!(
                tracker.validate_hardlink(&link, &PathBuf::from(target), &dest, &config),
                Err(ArchiveError::SecurityViolation { .. }),
                "{target}"
            );
        }
    }
}