Crate forensic_vfs 

forensic-vfs

The read-only forensic virtual-filesystem contracts — the KNOWLEDGE leaf every disk/container/filesystem reader in the fleet implements. It defines the layered model and nothing else: no format parsing, no I/O beyond the thin adapters that wrap an OS file, no reader dependencies.

The layered model

Locator (recursive locator)
   │ resolves (a per-node transform graph, in the engine)
   ▼
ImageSource  ── the universal edge: read-only positioned bytes ──────────┐
   ├── ContainerOpen : E01/VMDK/VHDX/… → ImageSource                   │  any of these
   ├── VolumeSystem     : MBR/GPT/VSS/…    → ImageSource                   │  transforms may
   ├── EncryptionLayer      : BitLocker/LUKS/… → ImageSource                   │  apply, in any
   └── FileSystem       : NTFS/ext4/APFS/… → FsNode tree                   ┘  order, per node

Load-bearing decisions

• ImageSource is a positioned-read &self byte source with no write method. Parallel-safe by construction (workers share one Arc<dyn ImageSource>), and read-only in the type system — a write is uncompilable.
• FileSystem reads are &self over interior mutability, so one mounted handle serves N workers; bulk enumerations are owned Send streams.
• Locator identity is the structured enum, with a lossless canonical URI (uri) for reports and a lossy human Display.
• True leaf. Base deps are thiserror (+ optional serde); the forensicnomicon findings bridge and the history bridge are non-default features, so a bare reader inherits neither.

Panic-free (Paranoid Gatekeeper): unsafe_code = forbid, no unwrap/expect/panic! in production, bounded readers over every attacker-controllable length/offset.

Re-exports

pub use archive::ArchiveContents;

pub use archive::Member;

pub use encryption::Credential;

pub use encryption::CredentialSource;

pub use encryption::EncryptionLayer;

pub use encryption::EncryptionScheme;

pub use encryption::NoCredentials;

pub use error::SmallHex;

pub use error::VfsError;

pub use error::VfsResult;

pub use fs::Allocation;

pub use fs::ByteRun;

pub use fs::DeletedNode;

pub use fs::DeletedStream;

pub use fs::DirEntry;

pub use fs::DirStream;

pub use fs::DynFs;

pub use fs::ExtentStream;

pub use fs::FileSystem;

pub use fs::FsMeta;

pub use fs::HardLink;

pub use fs::MacbTimes;

pub use fs::NodeKind;

pub use fs::NodeStream;

pub use fs::ResidencyKind;

pub use fs::RunAlloc;

pub use fs::RunFlags;

pub use fs::RunInfo;

pub use fs::SectorSizes;

pub use fs::StreamId;

pub use fs::StreamInfo;

pub use fs::StreamKind;

pub use fs::TimeResolution;

pub use fs::TimeSource;

pub use fs::TimeStamp;

pub use fs::TimeZonePolicy;

pub use locator::Guid;

pub use locator::Layer;

pub use locator::Locator;

pub use locator::NodeAddr;

pub use locator::SnapshotRef;

pub use registry::ArchiveOpen;

pub use registry::Confidence;

pub use registry::ContainerFormat;

pub use registry::ContainerOpen;

pub use registry::EncryptionOpen;

pub use registry::FileSystemOpen;

pub use registry::Openers;

pub use registry::SniffWindow;

pub use registry::VolumeSystemOpen;

pub use source::read_exact_at;

pub use source::DynSource;

pub use source::Extent;

pub use source::Extents;

pub use source::ImageSource;

pub use source::SourceId;

pub use source::SourceView;

pub use volume::VolumeDesc;

pub use volume::VolumeKind;

pub use volume::VolumeScheme;

pub use volume::VolumeSystem;

Modules

adapters

Concrete crate::ImageSource adapters: a positioned-read OS file, a byte sub-range of a parent source, and a legacy Read + Seek cursor view.

archive

The archive-layer result contract — ArchiveContents and Member.

encryption

EncryptionLayer — full-disk-encryption translation, a distinct layer between volume and filesystem.

error

The one error type for the whole VFS stack.

fs

The filesystem navigation contract and its unified forensic metadata.

locator

Locator — the recursive, self-describing access-route locator.

read

Panic-free bounded integer readers over an untrusted byte slice.

registry

The plugin contracts and the compiled-in dispatch Openers.

source

ImageSource — the universal read-only byte edge every layer speaks.

uri

The lossless canonical URI form of a crate::Locator and its parser.

volume

VolumeSystem — a partitioning/volume scheme over one crate::ImageSource.

Structs

FsKind

The filesystem family — the canonical identity newtype from forensicnomicon-core (FsKind::NTFS, FsKind::EXT, …). Canonical identity of a filesystem, content-addressed by a stable lowercase name.

Enums

FileId

Filesystem-specific stable identity, re-exported from forensicnomicon-core (ADR 0009). The type moved down to the zero-dep KNOWLEDGE leaf so state-history-forensic can reuse it verbatim in the [P] evidential-address key without a wrong-direction dependency on this VFS layer. The re-export keeps every existing forensic_vfs::FileId import working unchanged — the address domain still matches each FS’s real identity primitive, so a reused slot is never confused with the original. Filesystem-specific stable identity. The address domain matches each FS’s real identity primitive, so a reused slot is never confused with the original.

Type Aliases

PathSpecDeprecated

Deprecated alias for Locator (renamed in forensic-vfs 0.6).