forensic-vfs 0.7.0

//! [`Locator`] — the recursive, self-describing access-route locator.
//!
//! A chain of [`Layer`] nodes, each naming one layer, its location within that
//! layer, and its parent. It is the cache key, the reproducibility record, and
//! what a report cites. It carries **no credentials** — an address, not a
//! keychain. Identity is the structured enum (derived `Hash`/`Eq`), never a
//! stringification, so raw path bytes containing a delimiter cannot collide two
//! locators. Two text forms exist (see [`crate::uri`]): a lossless canonical URI
//! and a lossy human `Display`.

use std::path::PathBuf;

use crate::encryption::EncryptionScheme;
use crate::fs::{FileId, FsKind, StreamId};
use crate::registry::ContainerFormat;
use crate::volume::VolumeScheme;

/// A 16-byte GUID (GPT partition type/id, volume identifier).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Guid(pub [u8; 16]);

/// A reference to one snapshot within a snapshot set.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum SnapshotRef {
    /// VSS store index.
    VssStore(usize),
    /// APFS snapshot transaction id.
    ApfsXid(u64),
}

/// How a node is addressed within a filesystem.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum NodeAddr {
    /// Raw path components — filesystem names are bytes, not guaranteed UTF-8.
    Path(Vec<Vec<u8>>),
    /// The filesystem-specific stable id (survives a reallocated slot).
    File(FileId),
    /// Both: resolve by id, keep the observed path for context.
    Both { path: Vec<Vec<u8>>, id: FileId },
}

/// One layer in the locator chain.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum Layer {
    /// The base file path — the only parentless layer (a real file: local disk,
    /// USB, network share, FUSE mount).
    File { path: PathBuf },
    /// A byte window of the parent.
    Range { start: u64, len: u64 },
    /// Decode a container (Auto = sniffed).
    Container { format: ContainerFormat },
    /// A volume within a volume system.
    Volume {
        scheme: VolumeScheme,
        index: usize,
        guid: Option<Guid>,
    },
    /// A full-disk-encryption translation (credentials supplied out-of-band).
    Encryption { scheme: EncryptionScheme },
    /// A snapshot/shadow store.
    Snapshot { store: SnapshotRef },
    /// A mounted filesystem, addressing one node.
    Fs { kind: FsKind, at: NodeAddr },
    /// A named data stream (ADS / resource fork) of the addressed node.
    Stream { id: StreamId },
    /// A peeled archive/compression wrapper. `member: None` is a 1→1 stream peel
    /// (a bare gzip/bzip2 wrapper re-entering resolution like a container decode);
    /// `member: Some(i)` is the `i`-th member of a multi-member archive (tar/zip/7z).
    Archive { member: Option<usize> },
}

/// The recursive locator. Constructed via [`Locator::file`] + [`Locator::push`],
/// so a new `Layer` variant is an additive change and callers never build the
/// chain by hand-nesting `Box`es.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Locator {
    pub layer: Layer,
    pub parent: Option<Box<Locator>>,
}

impl Locator {
    /// A base locator rooted at a real file path (local disk, USB, network
    /// share, FUSE mount — medium-agnostic).
    #[must_use]
    pub fn file(path: impl Into<PathBuf>) -> Self {
        Self {
            layer: Layer::File { path: path.into() },
            parent: None,
        }
    }

    /// Deprecated alias for [`Locator::file`] (renamed in forensic-vfs 0.6).
    #[deprecated(note = "renamed to file()")]
    #[must_use]
    pub fn os(path: impl Into<PathBuf>) -> Self {
        Self::file(path)
    }

    /// A raw base locator for any layer (no parent). Prefer [`Locator::file`] for
    /// the root; this exists for tests and re-parenting.
    #[must_use]
    pub fn root(layer: Layer) -> Self {
        Self {
            layer,
            parent: None,
        }
    }

    /// Extend the chain: `self` becomes the parent of a new node carrying `layer`.
    #[must_use]
    pub fn push(self, layer: Layer) -> Self {
        Self {
            layer,
            parent: Some(Box::new(self)),
        }
    }

    /// The number of layers in the chain (the root counts as one).
    #[must_use]
    pub fn depth(&self) -> usize {
        1 + self.parent.as_ref().map_or(0, |p| p.depth())
    }

    /// The root (parentless) locator of this chain.
    #[must_use]
    pub fn base(&self) -> &Locator {
        match &self.parent {
            Some(p) => p.base(),
            None => self,
        }
    }

    /// The chain from root to this node, root first.
    #[must_use]
    pub fn layers(&self) -> Vec<&Layer> {
        let mut out = match &self.parent {
            Some(p) => p.layers(),
            None => Vec::new(),
        };
        out.push(&self.layer);
        out
    }
}

#[cfg(test)]
mod tests {
    use super::{Layer, Locator};

    #[test]
    #[allow(deprecated)]
    fn deprecated_os_alias_matches_file() {
        // The one-release compat shim (ADR 0013): `Locator::os()` must behave
        // identically to the renamed `Locator::file()`, including seeding the
        // renamed `Layer::File` base variant.
        let via_os = Locator::os("/evidence/DC01.E01");
        assert_eq!(via_os, Locator::file("/evidence/DC01.E01"));
        assert!(matches!(via_os.layer, Layer::File { .. }));
    }
}