@photostructure/fs-metadata 1.0.1 → 1.1.0

package/doc/system-volume-detection.md

@@ -0,0 +1,268 @@
+# System Volume Detection
+
+## Overview
+
+`fs-metadata` uses a two-layer detection strategy across all platforms:
+
+1. **Layer 1 (C++, native)** — platform-specific APIs detect system volumes at
+   enumeration time. Each `MountPoint` gets `isSystemVolume` set by native code.
+2. **Layer 2 (TypeScript, heuristic)** — path patterns and filesystem type lists
+   catch pseudo-filesystems, container runtimes, and platform-specific system
+   paths. Heuristics **never downgrade** a native `true` — they only upgrade
+   `false` to `true`.
+
+The `isSystemVolume` field is exposed on both `MountPoint` and `VolumeMetadata`.
+
+By default, system volumes are **excluded** from `getAllVolumeMetadata()` results
+on Linux and macOS (`includeSystemVolumes: false`), but **included** on Windows
+because `C:\` is both a system drive and the primary user storage location.
+
+---
+
+## macOS
+
+### Background
+
+On macOS 10.15 (Catalina) and later, the boot volume is split into multiple
+APFS volumes within a single container:
+
+| Volume              | Mount Point                  | APFS Role | Description                                               |
+| ------------------- | ---------------------------- | --------- | --------------------------------------------------------- |
+| Macintosh HD        | `/` (snapshot)               | System    | Sealed, read-only OS snapshot                             |
+| Macintosh HD - Data | `/System/Volumes/Data`       | Data      | User data (firmlinked to `/Users`, `/Applications`, etc.) |
+| VM                  | `/System/Volumes/VM`         | VM        | Virtual memory swap                                       |
+| Preboot             | `/System/Volumes/Preboot`    | Preboot   | Boot-time resources                                       |
+| Recovery            | `/System/Volumes/Recovery`   | Recovery  | Recovery OS                                               |
+| Update              | `/System/Volumes/Update`     | Update    | OS update staging                                         |
+| Hardware            | `/System/Volumes/Hardware`   | Hardware  | Hardware-specific data                                    |
+| xarts               | `/System/Volumes/xarts`      | xART      | Secure token storage                                      |
+| iSCPreboot          | `/System/Volumes/iSCPreboot` | Prelogin  | Pre-login resources                                       |
+
+### The Root Volume UUID Problem
+
+The volume mounted at `/` is an **APFS sealed system snapshot** — a
+cryptographically signed, read-only image of the OS. Its UUID changes on
+every macOS update. This makes it unsuitable for persistent identification
+(e.g., licensing fingerprints, asset URIs).
+
+The **Data volume** at `/System/Volumes/Data` has a stable UUID and contains
+all user data. Users access it transparently through APFS firmlinks (`/Users`,
+`/Applications`, `/Library`, etc.).
+
+### Native detection (Layer 1)
+
+Detection uses a combined formula:
+
+```
+isSystemVolume = MNT_SNAPSHOT || (MNT_DONTBROWSE && hasApfsRole && role != "Data")
+```
+
+This is implemented in `ClassifyMacVolume()` in `src/darwin/system_volume.h`.
+
+Each APFS volume has a **role** stored in its superblock (an unsigned 16-bit
+integer). We read this via:
+
+1. `DADiskCreateFromBSDName()` to get a DiskArbitration disk ref
+2. `DADiskCopyIOMedia()` to get the IOKit IOMedia service
+3. `IORegistryEntryCreateCFProperty(media, "Role")` to read the role array
+
+For APFS snapshots (e.g., `/` is `disk3s7s1`, a snapshot of `disk3s7`), the
+snapshot's IOMedia entry has no `Role` property — we walk one parent up in
+the IOService plane to find the parent volume's role.
+
+The role string is exposed as `volumeRole` in both `MountPoint` and
+`VolumeMetadata` (e.g., `"System"`, `"Data"`, `"VM"`).
+
+**System volume classification** combines two signals:
+
+- **`MNT_SNAPSHOT`** alone marks a volume as system. This catches sealed APFS
+  snapshots (`/` and Recovery).
+- **`MNT_DONTBROWSE`** combined with a non-`"Data"` APFS role marks a volume
+  as system. This catches all infrastructure volumes (VM, Preboot, Update,
+  Hardware, xART, etc.) while correctly excluding the Data volume.
+
+**Why this works**: `MNT_DONTBROWSE` means "hidden from Finder" and is set on
+all `/System/Volumes/*` infrastructure mounts. The only false positive would
+be `/System/Volumes/Data`, which has `MNT_DONTBROWSE` but a `"Data"` role —
+so the role check excludes it.
+
+**Why not a role whitelist?** The previous approach maintained a whitelist of
+13 system role strings. The flags+exclusion approach is simpler and
+future-proof: if Apple adds new infrastructure roles with `MNT_DONTBROWSE`,
+they're auto-detected without code changes.
+
+**Non-APFS `MNT_DONTBROWSE` mounts** (e.g., `devfs` at `/dev`, or a
+hypothetical NFS mount with `nobrowse`) have no APFS role, so the
+`MNT_DONTBROWSE` branch doesn't fire. These fall through to TypeScript
+heuristics (Layer 2).
+
+### Native fallback: `MNT_SNAPSHOT` only
+
+If a DiskArbitration session can't be created, we fall back to checking only
+`MNT_SNAPSHOT` in the `statfs` `f_flags`. This catches the sealed system
+snapshots (`/` and `/System/Volumes/Recovery`) but misses the other
+infrastructure volumes (VM, Preboot, etc.).
+
+### Flag and role summary (observed on macOS 26 Tahoe)
+
+| Mount Point                  | APFS Role           | MNT_SNAPSHOT | MNT_DONTBROWSE | isSystemVolume   |
+| ---------------------------- | ------------------- | ------------ | -------------- | ---------------- |
+| `/`                          | System (via parent) | **yes**      | no             | **yes**          |
+| `/System/Volumes/Data`       | Data                | no           | **yes**        | no               |
+| `/System/Volumes/VM`         | VM                  | no           | **yes**        | **yes**          |
+| `/System/Volumes/Preboot`    | Preboot             | no           | **yes**        | **yes**          |
+| `/System/Volumes/Recovery`   | Recovery            | **yes**      | no             | **yes**          |
+| `/System/Volumes/Update`     | Update              | no           | **yes**        | **yes**          |
+| `/System/Volumes/xarts`      | xART                | no           | **yes**        | **yes**          |
+| `/System/Volumes/iSCPreboot` | Prelogin            | no           | **yes**        | **yes**          |
+| `/System/Volumes/Hardware`   | Hardware            | no           | **yes**        | **yes**          |
+| `/dev`                       | _(no IOMedia)_      | no           | **yes**        | **yes** (fstype) |
+| `/Volumes/sandisk-extreme`   | _(no role)_         | no           | no             | no               |
+
+---
+
+## Linux
+
+### Background
+
+Linux has no unified "system volume" concept. Instead, the kernel exposes
+dozens of pseudo-filesystems for kernel interfaces, and distributions mount
+various infrastructure paths at boot. Container runtimes add additional
+overlay and bind mounts.
+
+There is **no native C++ system volume detection** on Linux. All
+classification happens in TypeScript (Layer 2) using filesystem type matching
+and path pattern globs.
+
+### Why no native detection?
+
+Unlike macOS (which has APFS roles and `MNT_SNAPSHOT`/`MNT_DONTBROWSE` flags)
+or Windows (which has `CSIDL_WINDOWS` and volume capability flags), Linux has
+no kernel API that directly identifies "this is a system volume." The closest
+signal is the filesystem type from `/proc/self/mounts`, which is already
+available in TypeScript without a native call.
+
+### Filesystem type detection
+
+The `SystemFsTypesDefault` list in `src/options.ts` identifies pseudo-filesystems
+that don't represent real storage:
+
+| Category                  | Filesystem Types                                                       |
+| ------------------------- | ---------------------------------------------------------------------- |
+| Process/kernel interfaces | `proc`, `sysfs`, `debugfs`, `tracefs`, `configfs`, `securityfs`, `bpf` |
+| Device pseudo-filesystems | `devpts`, `devtmpfs`                                                   |
+| Memory/temporary          | `tmpfs`, `ramfs`, `rootfs`, `hugetlbfs`                                |
+| Cgroups                   | `cgroup`, `cgroup2`                                                    |
+| Boot/firmware             | `efivarfs`, `pstore`, `binfmt_misc`                                    |
+| Automount                 | `autofs`, `fusectl`                                                    |
+| Container/sandbox         | `fuse.lxcfs`, `fuse.portal`, `fuse.snapfuse`, `squashfs`               |
+| Kernel internal           | `nsfs`, `mqueue`, `rpc_pipefs`, `none`                                 |
+
+### Path pattern detection
+
+The `SystemPathPatternsDefault` list in `src/options.ts` catches system mount
+points by path glob:
+
+| Category           | Patterns                                                                                                                                                      |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Core system        | `/boot`, `/boot/efi`, `/dev`, `/dev/**`, `/proc/**`, `/sys/**`                                                                                                |
+| Runtime            | `/run`, `/run/lock`, `/run/credentials/**`                                                                                                                    |
+| Temporary          | `/tmp`, `/var/tmp`                                                                                                                                            |
+| Container runtimes | `/run/docker/**`, `/var/lib/docker/**`, `/run/containerd/**`, `/var/lib/containerd/**`, `/run/containers/**`, `/var/lib/containers/**`, `/var/lib/kubelet/**` |
+| Linux containers   | `/var/lib/lxc/**`, `/var/lib/lxd/**`                                                                                                                          |
+| Snap/Flatpak       | `/snap/**`, `/run/snapd/**`, `/run/flatpak/**`, `/run/user/*/doc`, `/run/user/*/gvfs`                                                                         |
+| WSL infrastructure | `/mnt/wslg/distro`, `/mnt/wslg/doc`, `/usr/lib/wsl/drivers`                                                                                                   |
+| Snapshot dirs      | `**/#snapshot`                                                                                                                                                |
+
+### Typical detection results
+
+| Mount Point                    | fstype     | Detected By   | isSystemVolume |
+| ------------------------------ | ---------- | ------------- | -------------- |
+| `/`                            | `ext4`     | _(none)_      | no             |
+| `/boot`                        | `ext4`     | path          | **yes**        |
+| `/boot/efi`                    | `vfat`     | path          | **yes**        |
+| `/dev`                         | `devtmpfs` | fstype + path | **yes**        |
+| `/proc`                        | `proc`     | fstype + path | **yes**        |
+| `/sys`                         | `sysfs`    | fstype + path | **yes**        |
+| `/run`                         | `tmpfs`    | fstype + path | **yes**        |
+| `/tmp`                         | `tmpfs`    | fstype + path | **yes**        |
+| `/home`                        | `ext4`     | _(none)_      | no             |
+| `/var/lib/docker/overlay2/...` | `overlay`  | path          | **yes**        |
+| `/mnt/data`                    | `ext4`     | _(none)_      | no             |
+
+### Customization
+
+Both lists are configurable via `Options.systemFsTypes` and
+`Options.systemPathPatterns`, allowing callers to add or replace detection
+rules for specialized environments.
+
+---
+
+## Windows
+
+### Background
+
+Windows has a simpler model: drives are identified by letter (`C:\`, `D:\`,
+etc.), and one drive is the "system drive" containing the Windows
+installation. Unlike macOS's split-volume architecture, the system drive also
+holds user data (`C:\Users`).
+
+### Native detection (Layer 1)
+
+`IsSystemVolume()` in `src/windows/system_volume.h` uses two checks:
+
+1. **`SHGetFolderPathW(CSIDL_WINDOWS)`** — retrieves the Windows system
+   folder path (e.g., `C:\Windows`), extracts the drive letter, and compares
+   it against the volume being tested. This is the primary detection method.
+
+2. **Volume capability flags** — calls `GetVolumeInformationW()` and checks
+   for `FILE_SUPPORTS_SYSTEM_PATHS` (0x00100000) and
+   `FILE_SUPPORTS_SYSTEM_FILES` (0x00200000). These are modern (Windows 10+)
+   volume flags that indicate system volume capabilities.
+
+### TypeScript detection (Layer 2)
+
+The TypeScript layer (`src/system_volume.ts`) provides a redundant check using
+`process.env.SystemDrive` (typically `"C:"`), normalized to `"C:\"` for
+comparison.
+
+### Why `includeSystemVolumes` defaults to `true` on Windows
+
+On macOS and Linux, system volumes (pseudo-filesystems, sealed snapshots) are
+genuinely uninteresting to most callers. On Windows, `C:\` is both the system
+drive _and_ the primary user storage location — excluding it would hide the
+most important volume. So `IncludeSystemVolumesDefault = true` on Windows
+(see `src/options.ts`).
+
+### Typical detection results
+
+| Mount Point      | Detection Method            | isSystemVolume |
+| ---------------- | --------------------------- | -------------- |
+| `C:\`            | CSIDL_WINDOWS + SystemDrive | **yes**        |
+| `D:\`            | _(none)_                    | no             |
+| `E:\`            | _(none)_                    | no             |
+| `\\server\share` | _(none)_                    | no             |
+
+---
+
+## Layer 2: TypeScript heuristics (all platforms)
+
+The `assignSystemVolume()` function in `src/system_volume.ts` runs after native
+enumeration and applies the shared heuristic layer:
+
+1. On Windows, checks `process.env.SystemDrive`
+2. Checks `fstype` against `SystemFsTypesDefault` (configurable)
+3. Checks `mountPoint` against `SystemPathPatternsDefault` glob patterns
+   (configurable)
+
+Native `isSystemVolume: true` is **never downgraded** — only upgraded from
+`false` to `true`.
+
+## Related Files
+
+- `src/darwin/system_volume.h` — `ClassifyMacVolume()`: macOS flags + APFS role detection
+- `src/darwin/raii_utils.h` — RAII wrappers for DA/CF/IOKit resources
+- `src/windows/system_volume.h` — `IsSystemVolume()`: Windows CSIDL + volume flags
+- `src/options.ts` — `SystemFsTypesDefault`, `SystemPathPatternsDefault`, `IncludeSystemVolumesDefault`
+- `src/system_volume.ts` — `isSystemVolume()`, `assignSystemVolume()`: TypeScript heuristic layer
+- `src/types/mount_point.ts` — `MountPoint.volumeRole` / `isSystemVolume` / `isReadOnly` fields

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photostructure/fs-metadata",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Cross-platform native filesystem metadata retrieval for Node.js",
   "homepage": "https://photostructure.github.io/fs-metadata/",
   "types": "./dist/index.d.ts",
@@ -58,7 +58,7 @@
     "fmt:pkg": "npm pkg fix",
     "update": "run-p update:*",
     "update:deps": "ncu -u",
-    "install:pinact": "go install github.com/suzuki-shunsuke/pinact/cmd/pinact@latest",
+    "install:pinact": "go install github.com/suzuki-shunsuke/pinact/v3/cmd/pinact@latest",
     "update:actions": "pinact run -u || echo \"problem with pinact\"",
     "// precommit": "should be manually run by developers before they run `git commit`",
     "precommit": "npx --yes tsx scripts/precommit.ts",
@@ -91,34 +91,34 @@
     "cross-platform"
   ],
   "dependencies": {
-    "node-addon-api": "^8.5.0",
+    "node-addon-api": "^8.6.0",
     "node-gyp-build": "^4.8.4"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.5.0",
     "@types/semver": "^7.7.1",
     "cross-env": "^10.1.0",
     "del-cli": "^7.0.0",
     "eslint": "9.39.1",
-    "eslint-plugin-regexp": "^3.0.0",
+    "eslint-plugin-regexp": "^3.1.0",
     "eslint-plugin-security": "^4.0.0",
-    "globals": "^17.3.0",
-    "jest": "^30.2.0",
-    "jest-environment-node": "^30.2.0",
+    "globals": "^17.4.0",
+    "jest": "^30.3.0",
+    "jest-environment-node": "^30.3.0",
     "jest-extended": "^7.0.0",
     "node-gyp": "^12.2.0",
-    "npm-check-updates": "^19.4.1",
+    "npm-check-updates": "^19.6.5",
     "npm-run-all2": "8.0.4",
     "prebuildify": "^6.0.1",
     "prettier": "^3.8.1",
     "prettier-plugin-organize-imports": "4.3.0",
-    "terser": "^5.46.0",
+    "terser": "^5.46.1",
     "ts-jest": "^29.4.6",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typedoc": "^0.28.17",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1"
+    "typescript-eslint": "^8.57.1"
   }
 }

package/src/common/volume_metadata.h

@@ -40,9 +40,9 @@ struct VolumeMetadataOptions {
 struct VolumeMetadata {
   std::string label;
   std::string fstype;
-  double size;
-  double used;
-  double available;
+  double size = 0.0;
+  double used = 0.0;
+  double available = 0.0;
   std::string uuid;
   std::string mountFrom;
   std::string mountName;
@@ -52,6 +52,8 @@ struct VolumeMetadata {
   std::string remoteHost;
   std::string remoteShare;
   bool isSystemVolume = false;
+  bool isReadOnly = false;
+  std::string volumeRole;
   std::string error;
 
   Napi::Object ToObject(Napi::Env env) const {
@@ -120,6 +122,11 @@ struct VolumeMetadata {
     }
 
     result.Set("isSystemVolume", Napi::Boolean::New(env, isSystemVolume));
+    result.Set("isReadOnly", Napi::Boolean::New(env, isReadOnly));
+
+    if (!volumeRole.empty()) {
+      result.Set("volumeRole", Napi::String::New(env, volumeRole));
+    }
 
     return result;
   }

package/src/common/volume_mount_points.h

@@ -22,7 +22,9 @@ struct MountPoint {
   std::string mountPoint;
   std::string fstype;
   std::string status;
-  bool isSystemVolume = false; // Default to false
+  bool isSystemVolume = false;
+  bool isReadOnly = false;
+  std::string volumeRole;
   std::string error;
 
   Napi::Object ToObject(Napi::Env env) const {
@@ -38,6 +40,10 @@ struct MountPoint {
       obj.Set("status", status);
     }
     obj.Set("isSystemVolume", isSystemVolume);
+    obj.Set("isReadOnly", isReadOnly);
+    if (!volumeRole.empty()) {
+      obj.Set("volumeRole", volumeRole);
+    }
     obj.Set("error", error);
     return obj;
   }

package/src/darwin/da_mutex.h

@@ -0,0 +1,23 @@
+// src/darwin/da_mutex.h
+//
+// Shared mutex for DiskArbitration operations.
+//
+// Apple's DiskArbitration framework does not document thread safety for
+// concurrent DASession usage across threads. To prevent data races, all DA
+// operations (session creation, disk description, IOKit queries via
+// ClassifyMacVolume) must be serialized through this mutex.
+//
+// See: Finding #5 in SECURITY_AUDIT_2025.md (original)
+//      Finding #2 in SECURITY_AUDIT_2026.md (mount points regression)
+
+#pragma once
+
+#include <mutex>
+
+namespace FSMeta {
+
+// Defined in volume_metadata.cpp. Serializes all DiskArbitration + IOKit
+// operations across both getVolumeMetadata and getVolumeMountPoints workers.
+extern std::mutex g_diskArbitrationMutex;
+
+} // namespace FSMeta

package/src/darwin/raii_utils.h

@@ -2,6 +2,7 @@
 
 #include <CoreFoundation/CoreFoundation.h>
 #include <DiskArbitration/DiskArbitration.h>
+#include <IOKit/IOKitLib.h>
 #include <sys/mount.h>
 
 // RAII (Resource Acquisition Is Initialization) utilities for macOS APIs.
@@ -127,6 +128,44 @@ public:
   }
 };
 
+// RAII wrapper for IOKit io_object_t handles (io_service_t,
+// io_registry_entry_t). IOKit objects must be released with IOObjectRelease(),
+// not CFRelease().
+class IOObjectGuard {
+private:
+  io_object_t obj_;
+
+public:
+  explicit IOObjectGuard(io_object_t obj = 0) noexcept : obj_(obj) {}
+  ~IOObjectGuard() noexcept {
+    if (obj_) {
+      IOObjectRelease(obj_);
+    }
+  }
+
+  io_object_t get() const noexcept { return obj_; }
+  bool isValid() const noexcept { return obj_ != 0; }
+
+  // Prevent copying
+  IOObjectGuard(const IOObjectGuard &) = delete;
+  IOObjectGuard &operator=(const IOObjectGuard &) = delete;
+
+  // Allow moving
+  IOObjectGuard(IOObjectGuard &&other) noexcept : obj_(other.obj_) {
+    other.obj_ = 0;
+  }
+  IOObjectGuard &operator=(IOObjectGuard &&other) noexcept {
+    if (this != &other) {
+      if (obj_) {
+        IOObjectRelease(obj_);
+      }
+      obj_ = other.obj_;
+      other.obj_ = 0;
+    }
+    return *this;
+  }
+};
+
 // Specialized RAII wrapper for DASession that handles dispatch queue lifecycle.
 // DASessionSetDispatchQueue must be called with NULL before the session is
 // released. This wrapper ensures proper cleanup order: unschedule then release.

package/src/darwin/system_volume.h

@@ -0,0 +1,156 @@
+// src/darwin/system_volume.h
+//
+// Shared macOS system volume detection.
+//
+// Detection uses two signals combined:
+//   1. MNT_SNAPSHOT (statfs f_flags) — catches sealed APFS system snapshots
+//      ("/" and /System/Volumes/Recovery on macOS Catalina+).
+//   2. MNT_DONTBROWSE + APFS volume role — catches infrastructure volumes
+//      under /System/Volumes/* that are hidden from Finder. The "Data" role
+//      is excluded because /System/Volumes/Data is the primary user data
+//      volume (photos, documents, application data).
+//
+// Formula: MNT_SNAPSHOT || (MNT_DONTBROWSE && hasApfsRole && role != "Data")
+//
+// This is future-proof: new Apple infrastructure roles with MNT_DONTBROWSE
+// are auto-detected without maintaining a whitelist.
+//
+// Non-APFS MNT_DONTBROWSE mounts (e.g., devfs at /dev) fall through to
+// TypeScript fstype/path heuristics.
+//
+// See doc/system-volume-detection.md for the full rationale.
+// See: mount(2), sys/mount.h, IOKit/IOKitLib.h
+
+#pragma once
+
+#include "../common/debug_log.h"
+#include "raii_utils.h"
+#include <DiskArbitration/DiskArbitration.h>
+#include <IOKit/IOKitLib.h>
+#include <string>
+#include <sys/mount.h>
+
+namespace FSMeta {
+
+// Result of APFS volume role detection + system volume classification.
+struct VolumeRoleResult {
+  bool isSystemVolume = false;
+  std::string role; // e.g., "System", "Data", "VM", "" if unknown
+};
+
+// Extract the APFS volume role string via IOKit for a given DiskArbitration
+// disk ref. For snapshots (e.g., disk3s7s1), walks one parent up in the
+// IOService plane to find the parent volume's role.
+// Returns the first role string found, or "" if no role can be determined.
+inline std::string GetApfsVolumeRole(DADiskRef disk) {
+  if (!disk) {
+    return "";
+  }
+
+  IOObjectGuard media(DADiskCopyIOMedia(disk));
+  if (!media.isValid()) {
+    DEBUG_LOG("[GetApfsVolumeRole] Failed to get IOMedia");
+    return "";
+  }
+
+  // Check the volume's own Role property first
+  CFReleaser<CFArrayRef> role(
+      static_cast<CFArrayRef>(IORegistryEntryCreateCFProperty(
+          media.get(), CFSTR("Role"), kCFAllocatorDefault, 0)));
+
+  // If no Role on this entry, try the parent (handles snapshot → volume case:
+  // disk3s7s1 (snapshot) → disk3s7 (volume with System role))
+  IOObjectGuard parent;
+  if (!role.isValid()) {
+    io_registry_entry_t parentRef = 0;
+    kern_return_t kr =
+        IORegistryEntryGetParentEntry(media.get(), kIOServicePlane, &parentRef);
+    if (kr == KERN_SUCCESS) {
+      parent = IOObjectGuard(parentRef);
+      role.reset(static_cast<CFArrayRef>(IORegistryEntryCreateCFProperty(
+          parent.get(), CFSTR("Role"), kCFAllocatorDefault, 0)));
+    }
+  }
+
+  std::string result;
+  if (role.isValid() && CFGetTypeID(role.get()) == CFArrayGetTypeID()) {
+    CFIndex count = CFArrayGetCount(role.get());
+    if (count > 0) {
+      CFStringRef roleStr =
+          static_cast<CFStringRef>(CFArrayGetValueAtIndex(role.get(), 0));
+      if (roleStr && CFGetTypeID(roleStr) == CFStringGetTypeID()) {
+        char buf[64];
+        if (CFStringGetCString(roleStr, buf, sizeof(buf),
+                               kCFStringEncodingUTF8)) {
+          DEBUG_LOG("[GetApfsVolumeRole] Role: %s", buf);
+          result = buf;
+        }
+      }
+    }
+  }
+
+  // IOObjectGuard destructors automatically release media and parent
+  return result;
+}
+
+// Classify a macOS volume as system or user using mount flags and APFS role.
+//
+// Detection formula:
+//   MNT_SNAPSHOT || (MNT_DONTBROWSE && hasApfsRole && role != "Data")
+//
+// - MNT_SNAPSHOT alone catches sealed APFS system snapshots (/ and Recovery)
+// - MNT_DONTBROWSE combined with an APFS role catches infrastructure volumes
+//   (VM, Preboot, Update, Hardware, xART, etc.) while excluding the Data
+//   volume which contains user files
+// - Non-APFS MNT_DONTBROWSE mounts (devfs, NFS with nobrowse) are left for
+//   TypeScript heuristics
+inline VolumeRoleResult ClassifyMacVolume(const char *bsdDeviceName,
+                                          uint32_t f_flags,
+                                          DASessionRef session) {
+  VolumeRoleResult result;
+
+  // Layer 1: MNT_SNAPSHOT alone → system (sealed APFS snapshot)
+  if (f_flags & MNT_SNAPSHOT) {
+    result.isSystemVolume = true;
+  }
+
+  // Layer 2: APFS role via IOKit (if DA session available)
+  if (session && bsdDeviceName) {
+    // Strip "/dev/" prefix if present
+    const char *bsdName = bsdDeviceName;
+    if (strncmp(bsdName, "/dev/", 5) == 0) {
+      bsdName += 5;
+    }
+
+    CFReleaser<DADiskRef> disk(
+        DADiskCreateFromBSDName(kCFAllocatorDefault, session, bsdName));
+    if (disk.isValid()) {
+      result.role = GetApfsVolumeRole(disk.get());
+
+      // MNT_DONTBROWSE + known APFS role that isn't Data → system
+      if (!result.role.empty() && result.role != "Data" &&
+          (f_flags & MNT_DONTBROWSE)) {
+        result.isSystemVolume = true;
+      }
+    } else {
+      DEBUG_LOG("[ClassifyMacVolume] Failed to create disk ref for %s",
+                bsdName);
+    }
+  }
+
+  DEBUG_LOG("[ClassifyMacVolume] %s -> role=%s, isSystem=%s",
+            bsdDeviceName ? bsdDeviceName : "(null)", result.role.c_str(),
+            result.isSystemVolume ? "true" : "false");
+
+  return result;
+}
+
+// Lightweight fallback using only statfs f_flags (no DA/IOKit needed).
+// MNT_SNAPSHOT catches sealed APFS system snapshots ("/" and Recovery).
+inline VolumeRoleResult ClassifyMacVolumeByFlags(uint32_t f_flags) {
+  VolumeRoleResult result;
+  result.isSystemVolume = (f_flags & MNT_SNAPSHOT) != 0;
+  return result;
+}
+
+} // namespace FSMeta