forensic_vfs/
lib.rs

1//! # forensic-vfs
2//!
3//! The read-only forensic virtual-filesystem **contracts** — the KNOWLEDGE leaf
4//! every disk/container/filesystem reader in the fleet implements. It defines the
5//! layered model and nothing else: no format parsing, no I/O beyond the thin
6//! [`adapters`] that wrap an OS file, no reader dependencies.
7//!
8//! ## The layered model
9//!
10//! ```text
11//! Locator (recursive locator)
12//!    │ resolves (a per-node transform graph, in the engine)
13//!    ▼
14//! ImageSource  ── the universal edge: read-only positioned bytes ──────────┐
15//!    ├── ContainerOpen : E01/VMDK/VHDX/… → ImageSource                   │  any of these
16//!    ├── VolumeSystem     : MBR/GPT/VSS/…    → ImageSource                   │  transforms may
17//!    ├── EncryptionLayer      : BitLocker/LUKS/… → ImageSource                   │  apply, in any
18//!    └── FileSystem       : NTFS/ext4/APFS/… → FsNode tree                   ┘  order, per node
19//! ```
20//!
21//! ## Load-bearing decisions
22//!
23//! - **[`ImageSource`] is a positioned-read `&self` byte source with no write
24//!   method.** Parallel-safe by construction (workers share one `Arc<dyn
25//!   ImageSource>`), and read-only in the type system — a write is uncompilable.
26//! - **[`FileSystem`] reads are `&self`** over interior mutability, so one mounted
27//!   handle serves N workers; bulk enumerations are owned `Send` streams.
28//! - **[`Locator`] identity is the structured enum**, with a lossless canonical
29//!   URI ([`uri`]) for reports and a lossy human `Display`.
30//! - **True leaf.** Base deps are `thiserror` (+ optional `serde`); the
31//!   [`forensicnomicon`](https://docs.rs/forensicnomicon) findings bridge and the
32//!   history bridge are non-default features, so a bare reader inherits neither.
33//!
34//! Panic-free (Paranoid Gatekeeper): `unsafe_code = forbid`, no
35//! `unwrap`/`expect`/`panic!` in production, bounded readers over every
36//! attacker-controllable length/offset.
37
38// Tests may unwrap/expect freely; production code may not.
39#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
40
41pub mod adapters;
42pub mod archive;
43pub mod encryption;
44pub mod error;
45pub mod fs;
46pub mod locator;
47pub mod read;
48pub mod registry;
49pub mod source;
50pub mod uri;
51pub mod volume;
52
53pub use archive::{ArchiveContents, Member};
54pub use encryption::{
55    Credential, CredentialSource, EncryptionLayer, EncryptionScheme, NoCredentials,
56};
57pub use error::{SmallHex, VfsError, VfsResult};
58pub use fs::{
59    Allocation, ByteRun, DeletedNode, DeletedStream, DirEntry, DirStream, DynFs, ExtentStream,
60    FileId, FileSystem, FsKind, FsMeta, HardLink, MacbTimes, NodeKind, NodeStream, ResidencyKind,
61    RunAlloc, RunFlags, RunInfo, SectorSizes, StreamId, StreamInfo, StreamKind, TimeResolution,
62    TimeSource, TimeStamp, TimeZonePolicy,
63};
64pub use locator::{Guid, Layer, Locator, NodeAddr, SnapshotRef};
65
66/// Deprecated alias for [`Locator`] (renamed in forensic-vfs 0.6).
67#[deprecated(note = "renamed to Locator (forensic-vfs 0.6)")]
68pub type PathSpec = Locator;
69pub use registry::{
70    ArchiveOpen, Confidence, ContainerFormat, ContainerOpen, EncryptionOpen, FileSystemOpen,
71    Openers, SniffWindow, VolumeSystemOpen,
72};
73pub use source::{read_exact_at, DynSource, Extent, Extents, ImageSource, SourceId, SourceView};
74pub use volume::{VolumeDesc, VolumeKind, VolumeScheme, VolumeSystem};
forensic_vfs/lib.rs

forensic_vfs/
lib.rs
