Crate apfs_core 

apfs-core — a pure-Rust, from-scratch, panic-free reader for the Apple File System (APFS).

APFS is a copy-on-write, transactional, object-oriented filesystem. Every on-disk object carries a 32-byte object::ObjPhys header with a Fletcher-64 checksum, an object identifier (oid), and a transaction identifier (xid). Navigation is two-staged compared to NTFS: the object map (omap) resolves a virtual oid at a given xid to a physical block address, and the checkpoint ring (checkpoint) locates the live container superblock.

container (NXSB) → checkpoint ring → live nx_superblock (highest valid xid)
  → container omap → volume superblock (APSB) per volume
     → volume omap → root fs-tree (FSTREE)
        → j_key lookup: name → DIR_REC → INODE → DSTREAM_ID
           → FILE_EXTENT records → blocks → bytes → (decmpfs?) → content

This is the APFS analogue of NTFS name → inode → runs → bytes. The reader exposes this over any std::io::Read + std::io::Seek source and never panics on malformed input (Paranoid Gatekeeper: bounds-checked reads, range-checked length/offset/count fields, capped allocations, cycle-guarded tree walks).

Forensic format constants (magics, object-type codes, the decmpfs type map) live in the KNOWLEDGE leaf forensicnomicon; this crate holds the parsing algorithms, not the constant tables.

Scaffold notice

Implements phases P1–P8 of docs/plans/2026-06-21-apfs-forensic-design.md: container open + checkpoint, object map / B-tree, volume superblock, inode / directory navigation, file extents + decmpfs + xattrs, snapshots + point-in- time view, the space manager (allocation bitmap) + reaper, and keybag / sealed-volume metadata parsing. Full Fusion address translation is the one remaining gap (rejected loudly at open until a Fusion fixture exists).

Modules

btree

Generic B-tree node walker (btree_node_phys_t, types OBJECT_TYPE_BTREE 0x2 / OBJECT_TYPE_BTREE_NODE 0x3).

checkpoint

Checkpoint descriptor + data ring, and resolution of the live container superblock.

compression

Transparent decmpfs decompression (REUSE — not reinvented).

container

Container superblock (nx_superblock_t, magic NX_MAGIC = 'BSXN' → “NXSB” → LE 0x4253584E) and container geometry.

dir

Directory records (APFS_TYPE_DIR_REC 9) and name→inode navigation.

encryption

Encryption: keybag parsing and crypto-state records — state surfacing only (no key cracking, no hand-rolled crypto).

extent

File extents (APFS_TYPE_FILE_EXTENT 8, value j_file_extent_val_t) and file byte assembly.

fsrecord

File-system record keys (j_key_t) and record-type dispatch.

fusion

Fusion (SSD + HDD) support.

inode

Inode records (APFS_TYPE_INODE 3, value j_inode_val_t).

object

Object header (obj_phys_t) parsing and Fletcher-64 checksum verification.

omap

Object map (omap_phys_t, type OBJECT_TYPE_OMAP 0xb) and virtual-oid resolution.

reaper

Reaper (nx_reaper_phys_t, type OBJECT_TYPE_NX_REAPER 0x11) — lazy object deletion state.

sealed

Sealed / signed system volume: integrity metadata and file-info records — parse + accessors only (hash recomputation + seal validation live in the analyzer, apfs-forensic::sealed).

snapshot

Snapshots: the snapshot-metadata tree, the snapshot-name tree, and the point-in-time volume view.

spaceman

Space manager (spaceman_phys_t, type OBJECT_TYPE_SPACEMAN 0x5) and allocation bitmaps.

volume

Volume superblock (apfs_superblock_t, magic APFS_MAGIC = 'BSPA' → “APSB” → LE 0x42535041) and per-volume navigation roots.

xattr

Extended attributes (APFS_TYPE_XATTR 4, value j_xattr_val_t) and symlink targets.

Structs

ApfsContainer

An open APFS container, the entry point for navigation.

Enums

ApfsError

Errors surfaced by the reader. Bootstrap failures (no valid superblock, omap unresolvable) are loud, named variants — never silently absorbed into an empty result (fleet fail-loud-on-bootstrap rule).

Type Aliases

Result

Result alias for the crate.