hfs_recovery.cpp

Go to the documentation of this file.

// hfs_recovery.cpp -- session 1: open volume, validate header, parse
// special-file fork data, emit diagnostics. recover() returns false
// with a clear "session 1 only" message; nothing is exported yet.
//
// Session 2 will add the B-tree walk over the catalog file. Session 3
// will materialize file content via inline extents. Subsequent
// sessions cover the Extents Overflow file and decmpfs compression.
 
#include "hfs_recovery.hpp"
#include "hfs_format.hpp"
#include "hfs_btree.hpp"
#include "hfs_fork_io.hpp"
#include "hfs_catalog.hpp"
#include "hfs_decmpfs.hpp"
#include "hfs_attributes.hpp"
#include "i18n.hpp"
 
#include <algorithm>
#include <array>
#include <cstdint>
#include <filesystem>
#include <fstream>
#include <functional>
#include <iomanip>
#include <map>
#include <set>
#include <sstream>
#include <string>
#include <vector>
 
namespace {
 
bool read_exact(DiskReader& reader, uint64_t off, void* dst, size_t n) {
    return reader.read_at(off, dst, n);
}
 
// Validate that the volume offset + declared volume size doesn't exceed
// the disk extents. A small 64 KiB slack accounts for the occasional
// image where the volume reports a slightly larger size than the
// containing partition.
bool validate_geometry(DiskReader& reader, uint64_t volume_offset,
                       const hfs::VolumeHeader& vh, std::string& err) {
    const uint64_t disk_size = reader.size();
    if (volume_offset >= disk_size) {
        err = "Volume offset beyond disk end";
        return false;
    }
    const uint64_t fs_size = vh.volume_size_bytes();
    if (volume_offset + fs_size > disk_size + 64u * 1024) {
        err = "Filesystem extends past end of disk";
        return false;
    }
    return true;
}
 
} // anonymous namespace
 
HfsRecovery::HfsRecovery(DiskReader& reader) : reader_(reader) {}
 
bool HfsRecovery::recover(uint64_t volume_offset,
                          const std::string& output_dir,
                          std::vector<RecoveredFileRecord>& recovered,
                          std::vector<std::string>& logs,
                          std::string& error) {
    logs.push_back(trs("HFS+ recovery (sessions 4+5: full extents + "
                       "hardlinks + decmpfs-zlib) starting at offset") + std::string(" ")
                   + std::to_string(volume_offset));
 
    // ---- Step 1: read 512 bytes at +1024 ----
    std::array<unsigned char, 512> sector{};
    const uint64_t header_off = volume_offset + hfs::HFSPLUS_VOLUME_HEADER_OFFSET;
    if (!read_exact(reader_, header_off, sector.data(), sector.size())) {
        error = trs("HFS+: cannot read volume header sector");
        return false;
    }
 
    hfs::VolumeHeader vh;
    if (!hfs::parse_volume_header(sector.data(), vh)) {
        error = trs("HFS+: not a valid volume header at this offset");
        return false;
    }
 
    {
        std::string ge;
        if (!validate_geometry(reader_, volume_offset, vh, ge)) {
            error = trs("HFS+: geometry inconsistent:") + std::string(" ") + ge;
            return false;
        }
    }
 
    // ---- Step 2: emit volume layout to logs ----
    {
        std::ostringstream m;
        m << "HFS+ volume identified: variant=" << vh.variant_name()
          << " version=" << vh.version
          << " block_size=" << vh.block_size
          << " total_blocks=" << vh.total_blocks
          << " free_blocks=" << vh.free_blocks
          << " size=" << (vh.volume_size_bytes() / (1024 * 1024)) << " MiB"
          << " files=" << vh.file_count
          << " folders=" << vh.folder_count
          << " journaled=" << (vh.is_journaled() ? "yes" : "no");
        logs.push_back(m.str());
    }
 
    // ---- Step 3: special files diagnostic ----
    auto log_fork = [&](const char* name, const hfs::ForkData& f) {
        std::ostringstream m;
        m << "  " << name << ": logical=" << f.logical_size
          << " B, total_blocks=" << f.total_blocks;
        if (f.total_blocks > 0) {
            m << ", inline_extents=[";
            bool first = true;
            for (size_t i = 0; i < 8; ++i) {
                const auto& e = f.extents[i];
                if (e.block_count == 0) continue;
                if (!first) m << ", ";
                m << "(blk=" << e.start_block
                  << ", count=" << e.block_count << ")";
                first = false;
            }
            m << "]";
        }
        logs.push_back(m.str());
    };
    logs.push_back("HFS+ special files:");
    log_fork("allocation", vh.allocation_file);
    log_fork("extents",    vh.extents_file);
    log_fork("catalog",    vh.catalog_file);
    log_fork("attributes", vh.attributes_file);
    log_fork("startup",    vh.startup_file);
 
    // ---- Step 4: read the catalog file into memory and walk its B-tree ----
    //
    // Session 2 strategy:
    //   1. Read the catalog file via inline extents (read_fork_inline)
    //   2. Parse node 0 (header node) -> get nodeSize, rootNode, depth
    //   3. Walk the B-tree, classifying every leaf record by its
    //      type-discriminator (first 2 bytes of the body): folder / file /
    //      folder-thread / file-thread
    //   4. Report counts per type in the log
    //
    // We do NOT yet decode record bodies (that's session 3). We DO
    // decode the catalog key (parent CNID + UTF-16BE name length) so we
    // can sanity-check that names look reasonable on a real volume.
 
    if (vh.catalog_file.total_blocks == 0 ||
        vh.catalog_file.extents[0].block_count == 0) {
        error = trs("HFS+: catalog file has no extents -- volume looks empty "
                    "or damaged");
        return false;
    }
 
    std::vector<unsigned char> catalog_bytes;
    if (!hfs::read_fork_inline(reader_, volume_offset, vh.block_size,
                                vh.catalog_file,
                                vh.catalog_file.logical_size,
                                catalog_bytes, logs)) {
        error = trs("HFS+: failed to read catalog file content");
        return false;
    }
    {
        std::ostringstream m;
        m << "HFS+ catalog file: " << catalog_bytes.size() << " bytes "
          << "loaded from " << vh.catalog_file.total_blocks
          << " allocation blocks";
        logs.push_back(m.str());
    }
 
    // Parse node 0 (header node) to get nodeSize & B-tree shape.
    if (catalog_bytes.size() < 14) {
        error = trs("HFS+: catalog file too small to contain a header node");
        return false;
    }
    hfs::NodeDescriptor n0;
    if (!hfs::parse_node_descriptor(catalog_bytes.data(), n0) ||
        n0.kind != hfs::kBTHeaderNode) {
        error = trs("HFS+: catalog node 0 is not a valid header node");
        return false;
    }
    hfs::HeaderRec catalog_hdr;
    if (!hfs::parse_header_rec(catalog_bytes.data() + 14, catalog_hdr)) {
        error = trs("HFS+: catalog B-tree header record parse failed");
        return false;
    }
    {
        std::ostringstream m;
        m << "HFS+ catalog B-tree: depth=" << catalog_hdr.treeDepth
          << " root_node=" << catalog_hdr.rootNode
          << " leaf_records=" << catalog_hdr.leafRecords
          << " node_size=" << catalog_hdr.nodeSize
          << " total_nodes=" << catalog_hdr.totalNodes
          << " key_compare=0x" << std::hex
          << static_cast<unsigned>(catalog_hdr.keyCompareType)
          << std::dec;
        logs.push_back(m.str());
    }
 
    // Validate that the catalog file is large enough to host the
    // declared total_nodes.
    const uint64_t expected_size =
        static_cast<uint64_t>(catalog_hdr.totalNodes) * catalog_hdr.nodeSize;
    if (expected_size > catalog_bytes.size()) {
        std::ostringstream m;
        m << "HFS+: catalog file size " << catalog_bytes.size()
          << " is smaller than declared total_nodes*node_size = "
          << expected_size << " -- some nodes lie in the Extents Overflow "
          << "file (session 4 will handle that). Walking what we have now.";
        logs.push_back(m.str());
    }
 
    // The B-tree walker uses an injectable NodeReader. For session 2 we
    // serve nodes from the in-memory catalog buffer.
    auto node_reader = [&](uint32_t node_index,
                           std::vector<unsigned char>& out) -> bool {
        const uint64_t off =
            static_cast<uint64_t>(node_index) * catalog_hdr.nodeSize;
        if (off + catalog_hdr.nodeSize > catalog_bytes.size()) return false;
        out.assign(catalog_bytes.begin() + off,
                   catalog_bytes.begin() + off + catalog_hdr.nodeSize);
        return true;
    };
 
    // Build a map parentCNID -> [child entries]. We do not store the
    // entire body in the map (memory waste); we keep only what's needed
    // to recurse and export: NFC name, recordType, CNID, and (for files)
    // dataFork + finderInfo + fileMode + flags + ownerFlags + special.
    std::map<uint32_t, std::vector<hfs::ChildEntry>> children_by_parent;
 
    // Hardlink resolution: while walking we identify
    //   1. The "HFS+ Private Data" folder under the root (CNID kept here)
    //   2. Each "iNode<N>" file under it -> map[N] = {dataFork, ...}
    uint32_t private_data_cnid = 0;
    std::map<uint32_t, hfs::ChildEntry> inode_to_target;
 
    // Per-type counters (kept from session 2)
    size_t folders = 0, files = 0, folder_threads = 0, file_threads = 0;
    size_t records_total = 0, key_parse_failures = 0, unknown_record_types = 0;
    size_t body_parse_failures = 0;
 
    auto on_leaf = [&](const unsigned char* rec, uint16_t rec_len) -> bool {
        ++records_total;
        // Parse the catalog key first
        hfs::CatalogKey key;
        if (!hfs::parse_catalog_key(rec, rec_len, key)) {
            ++key_parse_failures;
            return true;
        }
        // Body starts at 2-byte boundary after the key
        const uint32_t body_off = hfs::catalog_record_body_offset(rec, rec_len);
        if (body_off == 0 || body_off + 2 > rec_len) return true;
        const int16_t recordType = static_cast<int16_t>(hfs::be16(rec + body_off));
        // Body proper starts AFTER the 2-byte recordType
        const unsigned char* body = rec + body_off + 2;
        const uint32_t body_len = rec_len - body_off - 2;
 
        switch (recordType) {
            case hfs::kHFSPlusFolderRecord: {
                ++folders;
                hfs::CatalogFolder f;
                if (!hfs::parse_catalog_folder(body, body_len, f)) {
                    ++body_parse_failures;
                    return true;
                }
                // Detect "HFS+ Private Data" folder (parent = rootCNID,
                // raw name has 4 leading NUL units)
                if (key.parentID == hfs::kHFSRootFolderID &&
                    hfs::is_private_data_folder_name(key.name_utf16be,
                                                      key.nameLength)) {
                    private_data_cnid = f.folderID;
                    // Don't add it to children_by_parent: we don't want
                    // to walk it like a normal folder.
                    return true;
                }
                hfs::ChildEntry ch;
                ch.name_nfc = hfs::catalog_name_to_host(key.name_utf16be,
                                                        key.nameLength);
                ch.recordType = recordType;
                ch.cnid = f.folderID;
                ch.flags = f.flags;
                ch.fileMode = f.permissions.fileMode;
                ch.ownerFlags = f.permissions.ownerFlags;
                ch.special = f.permissions.special;
                children_by_parent[key.parentID].push_back(std::move(ch));
                break;
            }
            case hfs::kHFSPlusFileRecord: {
                ++files;
                hfs::CatalogFile f;
                if (!hfs::parse_catalog_file(body, body_len, f)) {
                    ++body_parse_failures;
                    return true;
                }
                // Build the entry in any case
                hfs::ChildEntry ch;
                ch.name_nfc = hfs::catalog_name_to_host(key.name_utf16be,
                                                        key.nameLength);
                ch.recordType = recordType;
                ch.cnid = f.fileID;
                ch.flags = f.flags;
                ch.dataFork = f.dataFork;
                ch.resourceFork = f.resourceFork;
                ch.userInfo = f.userInfo;
                ch.fileMode = f.permissions.fileMode;
                ch.ownerFlags = f.permissions.ownerFlags;
                ch.special = f.permissions.special;
 
                // If this file lives inside HFS+ Private Data and its
                // name matches "iNode<N>", record it as a hardlink target.
                if (private_data_cnid != 0 &&
                    key.parentID == private_data_cnid) {
                    const uint32_t inum =
                        hfs::parse_inode_filename(key.name_utf16be,
                                                   key.nameLength);
                    if (inum > 0) {
                        inode_to_target[inum] = ch;
                        // Skip adding to children_by_parent: we don't
                        // emit iNode files in the recovery output.
                        return true;
                    }
                }
                children_by_parent[key.parentID].push_back(std::move(ch));
                break;
            }
            case hfs::kHFSPlusFolderThreadRecord:  ++folder_threads; break;
            case hfs::kHFSPlusFileThreadRecord:    ++file_threads;   break;
            default:                                ++unknown_record_types; break;
        }
        return true;
    };
 
    {
        std::vector<std::string> walk_logs;
        std::string walk_err;
        if (!hfs::walk_btree(catalog_hdr, node_reader, on_leaf,
                              walk_logs, walk_err)) {
            for (auto& l : walk_logs) logs.push_back(std::move(l));
            logs.push_back("HFS+ catalog walk: " + walk_err);
        } else {
            for (auto& l : walk_logs) logs.push_back(std::move(l));
        }
    }
 
    {
        std::ostringstream m;
        m << "HFS+ catalog walk completed: "
          << records_total << " leaf records visited "
          << "(folders=" << folders
          << ", files=" << files
          << ", folder_threads=" << folder_threads
          << ", file_threads=" << file_threads
          << ", unknown_types=" << unknown_record_types
          << ", key_parse_failures=" << key_parse_failures
          << ", body_parse_failures=" << body_parse_failures << ").";
        logs.push_back(m.str());
        if (private_data_cnid != 0) {
            std::ostringstream m2;
            m2 << "HFS+ hardlinks: HFS+ Private Data folder found (CNID="
               << private_data_cnid << "), " << inode_to_target.size()
               << " iNode targets indexed.";
            logs.push_back(m2.str());
        }
        if (records_total != catalog_hdr.leafRecords) {
            std::ostringstream m2;
            m2 << "HFS+ note: visited " << records_total
               << " records but header reports " << catalog_hdr.leafRecords
               << " leaf records (difference may be in the Extents "
                  "Overflow file -- session 4)";
            logs.push_back(m2.str());
        }
    }
 
    // ---- Step 5: walk the directory tree from rootCNID and export ----
    //
    // Starting at kHFSPlusRootFolderID (= 2), recursively visit every
    // child entry. For folders, mkdir + recurse. For files, read the
    // dataFork via inline extents and write to disk. Symlinks (HFS+
    // marks them by Finder type/creator 'slnk'/'rhap' AND fileMode
    // S_IFLNK) write the link target as a real symlink (sidecar fallback
    // if the host filesystem rejects the link).
    //
    // What we DON'T handle in session 3:
    //   * Files whose data fork uses > 8 extents (overflow file --
    //     session 4). These are skipped with a log warning.
    //   * decmpfs-compressed files. These show up with size=0 in
    //     dataFork; the real content is in the Attributes file.
    //   * Hardlinks (iNode files in HFS+ Private Data folder) -- session 5.
 
    namespace fs = std::filesystem;
    constexpr int MAX_DEPTH = 64;
    constexpr size_t MAX_FILES = 200'000;
 
    fs::path hfs_out_root =
        fs::path(output_dir) / "filesystem_recovered" / "hfs" /
        ("offset_" + std::to_string(volume_offset));
    {
        std::error_code ec;
        fs::create_directories(hfs_out_root, ec);
        if (ec) {
            error = "Cannot create output directory: " + hfs_out_root.string();
            return false;
        }
    }
 
    std::set<uint32_t> visited_cnids;
    size_t files_exported = 0;
    size_t dirs_walked = 0;
    size_t skipped_unsupported = 0;
    size_t errors_logged = 0;
    size_t hardlinks_resolved = 0;
    size_t hardlinks_orphaned = 0;
    size_t decmpfs_decompressed = 0;
    size_t decmpfs_unsupported = 0;
    size_t overflow_files = 0;
 
    // Cache for the Extents Overflow B-tree content. Loaded lazily on
    // first use (only paid for if at least one file actually has > 8
    // extents and triggers read_fork_full's overflow path).
    std::vector<unsigned char> extents_btree_buffer;
 
    // Cache for the Attributes B-tree content (extended attributes).
    // Loaded lazily on the first decmpfs file that needs the xattr
    // path. Empty means "not yet loaded" or "tried and failed".
    std::vector<unsigned char> attributes_btree_buffer;
    bool attributes_load_attempted = false;
 
    // POSIX file mode helpers
    constexpr uint16_t S_IFLNK_BITS = 0xA000;
 
    std::function<bool(uint32_t, const fs::path&, int)> walk_tree =
        [&](uint32_t parent_cnid, const fs::path& out_dir, int depth) -> bool
    {
        if (depth >= MAX_DEPTH) {
            logs.push_back("HFS+: max recursion depth reached, stopping branch.");
            return true;
        }
        if (!visited_cnids.insert(parent_cnid).second) {
            return true;  // already visited (cycle defence)
        }
        if (files_exported >= MAX_FILES) {
            logs.push_back("HFS+: file export safety cap reached ("
                           + std::to_string(MAX_FILES) + ").");
            return false;
        }
 
        auto it = children_by_parent.find(parent_cnid);
        if (it == children_by_parent.end()) return true;
        ++dirs_walked;
 
        for (const auto& ch : it->second) {
            const fs::path child_path = out_dir / ch.name_nfc;
 
            if (ch.recordType == hfs::kHFSPlusFolderRecord) {
                std::error_code ec;
                fs::create_directories(child_path, ec);
                if (ec) {
                    ++errors_logged;
                    logs.push_back("HFS+: cannot mkdir " + child_path.string());
                    continue;
                }
                if (!walk_tree(ch.cnid, child_path, depth + 1)) return false;
            }
            else if (ch.recordType == hfs::kHFSPlusFileRecord) {
                // Symlink? Check Finder type/creator AND POSIX mode.
                const bool finder_says_symlink =
                    ch.userInfo.fileType == hfs::kSymLinkFileType &&
                    ch.userInfo.fileCreator == hfs::kSymLinkCreator;
                const bool mode_says_symlink =
                    (ch.fileMode & 0xF000) == S_IFLNK_BITS;
 
                if (finder_says_symlink || mode_says_symlink) {
                    // Read data fork content -- it IS the link target text
                    std::vector<unsigned char> link_data;
                    std::vector<std::string> rd_logs;
                    if (hfs::read_fork_inline(reader_, volume_offset,
                                              vh.block_size, ch.dataFork,
                                              ch.dataFork.logical_size,
                                              link_data, rd_logs)) {
                        std::string target(reinterpret_cast<const char*>(link_data.data()),
                                           link_data.size());
                        std::error_code ec;
                        fs::create_symlink(target, child_path, ec);
                        if (ec) {
                            // Fallback: sidecar file with the target text
                            std::ofstream out(child_path.string() + ".symlink",
                                              std::ios::binary | std::ios::trunc);
                            if (out) out << target;
                        }
                        recovered.push_back({
                            child_path.string(), "HFS+",
                            (out_dir / ch.name_nfc).lexically_relative(hfs_out_root).string(),
                            link_data.size(), "full", "symlink"});
                        ++files_exported;
                    } else {
                        ++errors_logged;
                        for (auto& l : rd_logs) logs.push_back(std::move(l));
                        logs.push_back("HFS+: failed to read symlink target for '"
                                       + ch.name_nfc + "'");
                    }
                    continue;
                }
 
                // ---- Hardlink resolution (session 5) ----
                //
                // A hardlink in HFS+ is a file with userInfo type='hlnk'
                // and creator='hfs+'. The link's BSDInfo.special holds
                // the iNode number. We look up the target ChildEntry in
                // inode_to_target and use ITS dataFork for the export.
                hfs::ChildEntry effective = ch;
                bool is_hardlink = (ch.userInfo.fileType == hfs::kHardLinkFileType &&
                                    ch.userInfo.fileCreator == hfs::kHFSPlusCreator);
                if (is_hardlink) {
                    auto it_t = inode_to_target.find(ch.special);
                    if (it_t != inode_to_target.end()) {
                        // Replace data/resource forks with the target's,
                        // but KEEP the link's name and mode/flags.
                        effective.dataFork = it_t->second.dataFork;
                        effective.resourceFork = it_t->second.resourceFork;
                        effective.userInfo = it_t->second.userInfo;
                        effective.flags = it_t->second.flags;
                        effective.ownerFlags = it_t->second.ownerFlags;
                        effective.cnid = it_t->second.cnid;
                        ++hardlinks_resolved;
                    } else {
                        ++hardlinks_orphaned;
                        ++errors_logged;
                        logs.push_back("HFS+: hardlink '" + ch.name_nfc
                            + "' references missing iNode "
                            + std::to_string(ch.special));
                        continue;
                    }
                }
 
                // ---- decmpfs compression (sessions 5 + 6) ----
                //
                // A file is decmpfs-compressed when:
                //   - permissions.ownerFlags has UF_COMPRESSED (0x20)
                //   - flags has kHFSHasAttributesBit (0x0004)
                //   - dataFork.logical_size == 0 (real content lives
                //     either in an xattr or in the resource fork)
                //
                // The compression TYPE determines where the data lives:
                //   - type 3 (zlib-xattr):  inline in com.apple.decmpfs xattr
                //                           (small files, < ~3.6 KB)
                //   - type 4 (zlib-rsrc):   in resource fork (chunked stream)
                //                           (larger files, file system uses
                //                            this when the compressed payload
                //                            doesn't fit in an inline xattr)
                //   - type 7 (lzvn-xattr): LZVN in xattr (out of scope)
                //   - type 8 (lzvn-rsrc):  LZVN in resource fork (out of scope)
                //   - type 11/12: LZFSE (out of scope)
                //
                // Strategy:
                //   * If a resource fork exists, try decompress_resource_fork
                //     first (= type 4). If it succeeds, done.
                //   * If resource fork absent OR decompression fails, AND we
                //     can load the Attributes file, look up
                //     com.apple.decmpfs and try decompress_xattr_zlib (= type 3).
                //   * If nothing works and there's a non-empty resource fork,
                //     save raw .compressed.rsrc placeholder.
                const bool decmpfs_marked =
                    (effective.ownerFlags & hfs::UF_COMPRESSED) != 0 &&
                    (effective.flags & hfs::kHFSHasAttributesBit) != 0 &&
                    effective.dataFork.logical_size == 0;
 
                if (decmpfs_marked) {
                    std::vector<unsigned char> data;
                    bool decompressed = false;
                    bool tried_rsrc = false;
                    bool tried_xattr = false;
 
                    // Path 1: resource fork (type 4 zlib-rsrc)
                    if (effective.resourceFork.total_blocks > 0) {
                        tried_rsrc = true;
                        std::vector<unsigned char> rsrc;
                        std::vector<std::string> rd_logs;
                        if (hfs::read_fork_full(reader_, volume_offset,
                                                  vh.block_size,
                                                  effective.resourceFork,
                                                  vh.extents_file,
                                                  hfs::kForkTypeResource,
                                                  effective.cnid,
                                                  effective.resourceFork.logical_size,
                                                  extents_btree_buffer,
                                                  rsrc, rd_logs)) {
                            for (auto& l : rd_logs) logs.push_back(std::move(l));
                            std::string dec_err;
                            if (hfs::decompress_resource_fork_zlib(
                                    rsrc.data(), rsrc.size(),
                                    /*expected=*/64u * 1024 * 1024,
                                    data, dec_err) && !data.empty()) {
                                decompressed = true;
                            }
                        } else {
                            for (auto& l : rd_logs) logs.push_back(std::move(l));
                        }
                    }
 
                    // Path 2: xattr (type 3 zlib-xattr)
                    if (!decompressed) {
                        // Lazy-load Attributes file
                        if (!attributes_load_attempted &&
                            vh.attributes_file.total_blocks > 0) {
                            attributes_load_attempted = true;
                            std::vector<std::string> ld_logs;
                            if (!hfs::read_fork_inline(reader_, volume_offset,
                                                        vh.block_size,
                                                        vh.attributes_file,
                                                        vh.attributes_file.logical_size,
                                                        attributes_btree_buffer,
                                                        ld_logs)) {
                                attributes_btree_buffer.clear();
                                logs.push_back("HFS+: Attributes file could not "
                                               "be loaded; xattr-based decmpfs "
                                               "files will not be decoded");
                                for (auto& l : ld_logs) logs.push_back(std::move(l));
                            } else {
                                logs.push_back("HFS+: Attributes file loaded "
                                               "(" + std::to_string(attributes_btree_buffer.size())
                                               + " bytes)");
                            }
                        }
 
                        if (!attributes_btree_buffer.empty()) {
                            tried_xattr = true;
                            std::vector<unsigned char> xattr_buf;
                            std::vector<std::string> attr_logs;
                            if (hfs::find_inline_attribute(
                                    attributes_btree_buffer,
                                    effective.cnid,
                                    "com.apple.decmpfs",
                                    xattr_buf, attr_logs)) {
                                std::string dec_err;
                                if (hfs::decompress_xattr_zlib(
                                        xattr_buf.data(), xattr_buf.size(),
                                        /*expected=*/0,  // header has it
                                        data, dec_err) && !data.empty()) {
                                    decompressed = true;
                                } else if (!dec_err.empty()) {
                                    logs.push_back("HFS+: decmpfs xattr '"
                                        + ch.name_nfc + "' decode failed: "
                                        + dec_err);
                                }
                            }
                            for (auto& l : attr_logs) logs.push_back(std::move(l));
                        }
                    }
 
                    if (decompressed) {
                        std::ofstream out(child_path,
                            std::ios::binary | std::ios::trunc);
                        if (!out) {
                            ++errors_logged;
                            logs.push_back("HFS+: cannot create decompressed "
                                           "file " + child_path.string());
                            continue;
                        }
                        out.write(reinterpret_cast<const char*>(data.data()),
                                  static_cast<std::streamsize>(data.size()));
                        std::string tag;
                        if (tried_xattr && !tried_rsrc) tag = "decmpfs-zlib-xattr";
                        else if (tried_rsrc) tag = "decmpfs-zlib";
                        else tag = "decmpfs-zlib-xattr";
                        if (is_hardlink) tag += "+hardlink";
                        recovered.push_back({
                            child_path.string(), "HFS+",
                            (out_dir / ch.name_nfc).lexically_relative(hfs_out_root).string(),
                            data.size(), "full", tag});
                        ++files_exported;
                        ++decmpfs_decompressed;
                        continue;
                    }
 
                    // Both paths failed -- this is an LZVN/LZFSE file or
                    // some other unsupported variant. If there's a
                    // resource fork, save it as placeholder.
                    if (effective.resourceFork.total_blocks > 0) {
                        std::vector<unsigned char> rsrc;
                        std::vector<std::string> rd_logs;
                        if (hfs::read_fork_full(reader_, volume_offset,
                                                  vh.block_size,
                                                  effective.resourceFork,
                                                  vh.extents_file,
                                                  hfs::kForkTypeResource,
                                                  effective.cnid,
                                                  effective.resourceFork.logical_size,
                                                  extents_btree_buffer,
                                                  rsrc, rd_logs)) {
                            const fs::path stub = child_path.string() +
                                                  ".compressed.rsrc";
                            std::ofstream out(stub,
                                std::ios::binary | std::ios::trunc);
                            if (out) {
                                out.write(reinterpret_cast<const char*>(rsrc.data()),
                                          static_cast<std::streamsize>(rsrc.size()));
                            }
                        }
                    }
                    ++decmpfs_unsupported;
                    logs.push_back("HFS+: decmpfs file '" + ch.name_nfc
                        + "' uses unsupported compression "
                        "(LZVN/LZFSE or non-inline xattr). "
                        "Raw resource fork saved if available.");
                    continue;
                }
 
                // Regular file: write data fork to disk.
                if (effective.dataFork.logical_size == 0 &&
                    effective.dataFork.total_blocks == 0) {
                    // Empty file -- still create it
                    std::ofstream out(child_path, std::ios::binary | std::ios::trunc);
                    if (out) {
                        recovered.push_back({
                            child_path.string(), "HFS+",
                            (out_dir / ch.name_nfc).lexically_relative(hfs_out_root).string(),
                            0, "full",
                            is_hardlink ? "hardlink-empty" : "empty-file"});
                        ++files_exported;
                    }
                    continue;
                }
 
                std::vector<unsigned char> data;
                std::vector<std::string> rd_logs;
                if (!hfs::read_fork_full(reader_, volume_offset, vh.block_size,
                                          effective.dataFork, vh.extents_file,
                                          hfs::kForkTypeData,
                                          effective.cnid,
                                          effective.dataFork.logical_size,
                                          extents_btree_buffer,
                                          data, rd_logs)) {
                    ++errors_logged;
                    for (auto& l : rd_logs) logs.push_back(std::move(l));
                    logs.push_back("HFS+: failed to read data fork for '"
                                   + ch.name_nfc + "'");
                    continue;
                }
                // Append rd_logs (e.g. "needs overflow file") to main log
                bool used_overflow = false;
                for (auto& l : rd_logs) {
                    if (l.find("Extents Overflow") != std::string::npos ||
                        l.find("overflow") != std::string::npos) {
                        used_overflow = true;
                    }
                    logs.push_back(std::move(l));
                }
                if (used_overflow) ++overflow_files;
 
                // Truncate to logical_size in case the fork covers more bytes
                // than the actual file size.
                if (data.size() > effective.dataFork.logical_size) {
                    data.resize(static_cast<size_t>(effective.dataFork.logical_size));
                }
 
                std::ofstream out(child_path, std::ios::binary | std::ios::trunc);
                if (!out) {
                    ++errors_logged;
                    logs.push_back("HFS+: cannot create file " + child_path.string());
                    continue;
                }
                out.write(reinterpret_cast<const char*>(data.data()),
                          static_cast<std::streamsize>(data.size()));
 
                std::string source_tag;
                if (is_hardlink && used_overflow) source_tag = "hardlink+overflow";
                else if (is_hardlink)             source_tag = "hardlink";
                else if (used_overflow)           source_tag = "overflow-extents";
                else                              source_tag = "inline-extents";
 
                recovered.push_back({
                    child_path.string(), "HFS+",
                    (out_dir / ch.name_nfc).lexically_relative(hfs_out_root).string(),
                    data.size(), "full", source_tag});
                ++files_exported;
            }
            else {
                ++skipped_unsupported;
            }
        }
        return true;
    };
 
    walk_tree(hfs::kHFSRootFolderID, hfs_out_root, 0);
 
    {
        std::ostringstream m;
        m << "HFS+ recovery completed. "
          << "Files exported: " << files_exported
          << " (hardlinks_resolved=" << hardlinks_resolved
          << ", hardlinks_orphaned=" << hardlinks_orphaned
          << ", decmpfs_decompressed=" << decmpfs_decompressed
          << ", decmpfs_unsupported=" << decmpfs_unsupported
          << ", overflow_files=" << overflow_files
          << "), directories walked: " << dirs_walked
          << ", skipped: " << skipped_unsupported
          << ", errors: " << errors_logged << ".";
        logs.push_back(m.str());
    }
 
    // Note for the user about residual unsupported items
    if (decmpfs_unsupported > 0) {
        logs.push_back("HFS+: " + std::to_string(decmpfs_unsupported)
            + " files use LZVN/LZFSE compression (out of scope). "
            "Their compressed resource forks were saved as "
            "*.compressed.rsrc placeholders for forensic analysis.");
    }
    if (hardlinks_orphaned > 0) {
        logs.push_back("HFS+: " + std::to_string(hardlinks_orphaned)
            + " hardlinks reference missing iNode targets "
            "(possibly corrupted Private Data folder).");
    }
 
    return files_exported > 0 || dirs_walked > 0;
}