refs_core/lib.rs
1//! `refs-core` — a pure-Rust, from-scratch ReFS (Resilient File System) reader.
2//!
3//! Parses the ReFS on-disk structures a forensic tool needs, starting from the
4//! boot Volume Boot Record (VBR) and superblock. Imports as `refs_core` (the
5//! bare `refs` crate name is taken by an unrelated third party on crates.io):
6//! `use refs_core::BootSector;`.
7//!
8//! # Reverse-engineered format — no official specification
9//!
10//! ReFS is **undocumented**: Microsoft publishes no on-disk specification. Every
11//! structural fact this reader encodes comes from third-party **reverse
12//! engineering** — primarily libyal's `libfsrefs` and Prade's academic work.
13//! Correctness is therefore **Tier-2 at best** for structural metadata (there is
14//! no ground-truth forensic corpus); only *file content* can reach Tier-1, by
15//! hashing against the live Windows ReFS driver. ReFS is also
16//! **version-fragmented** — the layout differs materially between v1.x (Server
17//! 2012 / 8.1) and v3.x (Server 2016+/Win10+/Win11), and each Windows release
18//! tweaks it. This reader targets **v3.x** and **fails loud** (naming the
19//! version bytes) on any other major version rather than silently misparsing.
20//!
21//! # Safety and robustness
22//!
23//! This crate parses untrusted, attacker-controllable disk images. It is
24//! `#![forbid(unsafe_code)]` and every integer is read through bounds-checked
25//! little-endian helpers that yield `0`/`None` out of range rather than panic
26//! (the Paranoid Gatekeeper standard). ReFS is little-endian.
27
28#![forbid(unsafe_code)]
29#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
30
31mod boot;
32pub mod bytes;
33mod checkpoint;
34mod container;
35mod directory;
36mod error;
37mod metablock;
38mod minstore;
39mod superblock;
40
41pub use boot::{BootSector, REFS_FSRS, REFS_SIGNATURE};
42pub use checkpoint::Checkpoint;
43pub use container::{decompose_virtual_block, ContainerRecord, ContainerResolver, ContainerTable};
44pub use directory::{
45 find_by_path, list_dir, parse_directory, walk_directory, DirEntry, FileMetadata,
46};
47pub use error::RefsError;
48pub use metablock::{crc32c, crc64_ecma, MetaBlock, REFS_METADATA_PAGE_SIZE};
49pub use minstore::{MinstorePage, MinstoreRow, ObjectTable, PageRef, REFS_ROOT_DIRECTORY_ID};
50pub use superblock::{MetadataBlockRef, Superblock, REFS_SUPERBLOCK_CLUSTER, SUPB_SIGNATURE};