@photostructure/fs-metadata 1.1.0 → 1.3.0

package/doc/SECURITY_AUDIT_2026.md

@@ -190,6 +190,7 @@ A caller could theoretically provide a malicious pattern causing ReDoS.
 **Files**: `src/windows/volume_mount_points.cpp`, `src/windows/volume_metadata.cpp`, `src/windows/system_volume.h`
 
 **Issue**: `GetVolumeInformationW` was called redundantly:
+
 - In `volume_mount_points.cpp`: once for `fstype`/`isReadOnly`, then again inside `IsSystemVolume()`
 - In `volume_metadata.cpp`: `IsSystemVolume()` queried the API, then `VolumeInfo` queried it again 5 lines later
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photostructure/fs-metadata",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Cross-platform native filesystem metadata retrieval for Node.js",
   "homepage": "https://photostructure.github.io/fs-metadata/",
   "types": "./dist/index.d.ts",
@@ -91,7 +91,7 @@
     "cross-platform"
   ],
   "dependencies": {
-    "node-addon-api": "^8.6.0",
+    "node-addon-api": "^8.7.0",
     "node-gyp-build": "^4.8.4"
   },
   "devDependencies": {
@@ -108,7 +108,7 @@
     "jest-environment-node": "^30.3.0",
     "jest-extended": "^7.0.0",
     "node-gyp": "^12.2.0",
-    "npm-check-updates": "^19.6.5",
+    "npm-check-updates": "^19.6.6",
     "npm-run-all2": "8.0.4",
     "prebuildify": "^6.0.1",
     "prettier": "^3.8.1",
@@ -117,8 +117,8 @@
     "ts-jest": "^29.4.6",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
-    "typedoc": "^0.28.17",
+    "typedoc": "^0.28.18",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.57.1"
+    "typescript-eslint": "^8.57.2"
   }
 }

package/src/binding.cpp

@@ -8,6 +8,7 @@
 #include "windows/hidden.h"
 #elif defined(__APPLE__)
 #include "darwin/fs_meta.h"
+#include "darwin/get_mount_point.h"
 #include "darwin/hidden.h"
 #elif defined(__linux__)
 #include "common/volume_metadata.h"
@@ -60,6 +61,12 @@ Napi::Value GetVolumeMetadata(const Napi::CallbackInfo &info) {
   return FSMeta::GetVolumeMetadata(info);
 }
 
+#if defined(__APPLE__)
+Napi::Value GetMountPointForPath(const Napi::CallbackInfo &info) {
+  return FSMeta::GetMountPoint(info);
+}
+#endif
+
 #if defined(_WIN32) || defined(__APPLE__)
 Napi::Value GetHiddenAttribute(const Napi::CallbackInfo &info) {
   return FSMeta::GetHiddenAttribute(info);
@@ -81,6 +88,10 @@ Napi::Object Init(Napi::Env env, Napi::Object exports) {
 
   exports.Set("getVolumeMetadata", Napi::Function::New(env, GetVolumeMetadata));
 
+#if defined(__APPLE__)
+  exports.Set("getMountPoint", Napi::Function::New(env, GetMountPointForPath));
+#endif
+
 #ifdef ENABLE_GIO
   exports.Set("getGioMountPoints", Napi::Function::New(env, GetGioMountPoints));
 #endif

package/src/darwin/get_mount_point.cpp

@@ -0,0 +1,96 @@
+// src/darwin/get_mount_point.cpp
+// Lightweight mount point lookup using fstatfs() only.
+// Returns f_mntonname without DiskArbitration, IOKit, or space calculations.
+
+#include "./get_mount_point.h"
+#include "../common/debug_log.h"
+#include "../common/error_utils.h"
+#include "../common/fd_guard.h"
+#include "../common/path_security.h"
+
+#include <fcntl.h>
+#include <string>
+#include <sys/mount.h>
+#include <sys/param.h>
+#include <unistd.h>
+
+namespace FSMeta {
+
+class GetMountPointWorker : public Napi::AsyncWorker {
+public:
+  GetMountPointWorker(const std::string &path,
+                      const Napi::Promise::Deferred &deferred)
+      : Napi::AsyncWorker(deferred.Env()), path_(path), deferred_(deferred) {}
+
+  void Execute() override {
+    DEBUG_LOG("[GetMountPointWorker] Executing for path: %s", path_.c_str());
+    try {
+      std::string error;
+      std::string validated = ValidatePathForRead(path_, error);
+      if (validated.empty()) {
+        SetError(error);
+        return;
+      }
+
+      DEBUG_LOG("[GetMountPointWorker] Using validated path: %s",
+                validated.c_str());
+
+      int fd = open(validated.c_str(), O_RDONLY | O_DIRECTORY | O_CLOEXEC);
+      if (fd < 0) {
+        int err = errno;
+        DEBUG_LOG("[GetMountPointWorker] open failed: %s (%d)", strerror(err),
+                  err);
+        SetError(CreatePathErrorMessage("open", path_, err));
+        return;
+      }
+
+      FdGuard guard(fd);
+
+      struct statfs fs;
+      if (fstatfs(fd, &fs) != 0) {
+        int err = errno;
+        DEBUG_LOG("[GetMountPointWorker] fstatfs failed: %s (%d)",
+                  strerror(err), err);
+        SetError(CreatePathErrorMessage("fstatfs", path_, err));
+        return;
+      }
+
+      result_ = fs.f_mntonname;
+      DEBUG_LOG("[GetMountPointWorker] mount point: %s", result_.c_str());
+    } catch (const std::exception &e) {
+      DEBUG_LOG("[GetMountPointWorker] Exception: %s", e.what());
+      SetError(e.what());
+    }
+  }
+
+  void OnOK() override {
+    Napi::HandleScope scope(Env());
+    deferred_.Resolve(Napi::String::New(Env(), result_));
+  }
+
+  void OnError(const Napi::Error &error) override {
+    deferred_.Reject(error.Value());
+  }
+
+private:
+  std::string path_;
+  std::string result_;
+  Napi::Promise::Deferred deferred_;
+};
+
+Napi::Value GetMountPoint(const Napi::CallbackInfo &info) {
+  auto env = info.Env();
+  DEBUG_LOG("[GetMountPoint] called");
+
+  if (info.Length() < 1 || !info[0].IsString()) {
+    throw Napi::TypeError::New(env, "String argument expected");
+  }
+
+  std::string path = info[0].As<Napi::String>().Utf8Value();
+  auto deferred = Napi::Promise::Deferred::New(env);
+  auto *worker = new GetMountPointWorker(path, deferred);
+  worker->Queue();
+  return deferred.Promise();
+}
+
+} // namespace FSMeta

package/src/darwin/get_mount_point.h

@@ -0,0 +1,13 @@
+// src/darwin/get_mount_point.h
+// Lightweight mount point lookup using fstatfs() only.
+// Returns f_mntonname without DiskArbitration, IOKit, or space calculations.
+
+#pragma once
+
+#include <napi.h>
+
+namespace FSMeta {
+
+Napi::Value GetMountPoint(const Napi::CallbackInfo &info);
+
+} // namespace FSMeta

package/src/index.ts

@@ -12,6 +12,7 @@ import {
   isHiddenRecursiveImpl,
   setHiddenImpl,
 } from "./hidden";
+import { getMountPointForPathImpl } from "./mount_point_for_path";
 import {
   getTimeoutMsDefault,
   IncludeSystemVolumesDefault,
@@ -121,7 +122,9 @@ export function getVolumeMetadata(
  */
 export function getVolumeMetadataForPath(
   pathname: string,
-  opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>,
+  opts?: Partial<
+    Pick<Options, "timeoutMs" | "linuxMountTablePaths" | "mountPoints">
+  >,
 ): Promise<VolumeMetadata> {
   return getVolumeMetadataForPathImpl(
     pathname,
@@ -130,6 +133,34 @@ export function getVolumeMetadataForPath(
   );
 }
 
+/**
+ * Get the mount point path for an arbitrary file or directory path.
+ *
+ * This is a lightweight alternative to {@link getVolumeMetadataForPath} when
+ * you only need the mount point string. On macOS it uses a single fstatfs()
+ * call (no DiskArbitration, IOKit, or space calculations). On Linux/Windows
+ * it uses device ID matching against the mount table.
+ *
+ * Symlinks are resolved, and macOS APFS firmlinks (e.g. `/Users` →
+ * `/System/Volumes/Data`) are handled correctly.
+ *
+ * @param pathname Path to any file or directory
+ * @param opts Optional settings (timeoutMs, linuxMountTablePaths)
+ * @returns The mount point path (e.g., "/", "/System/Volumes/Data", "C:\\")
+ */
+export function getMountPointForPath(
+  pathname: string,
+  opts?: Partial<
+    Pick<Options, "timeoutMs" | "linuxMountTablePaths" | "mountPoints">
+  >,
+): Promise<string> {
+  return getMountPointForPathImpl(
+    pathname,
+    optionsWithDefaults(opts),
+    nativeFn,
+  );
+}
+
 /**
  * Retrieves metadata for all mounted volumes with optional filtering and
  * concurrency control.

package/src/mount_point_for_path.ts

@@ -0,0 +1,54 @@
+// src/mount_point_for_path.ts
+
+import { realpath } from "node:fs/promises";
+import { dirname } from "node:path";
+import { withTimeout } from "./async";
+import { debug } from "./debuglog";
+import { statAsync } from "./fs";
+import { isMacOS } from "./platform";
+import { isBlank, isNotBlank } from "./string";
+import type { NativeBindingsFn } from "./types/native_bindings";
+import type { Options } from "./types/options";
+import { findMountPointByDeviceId } from "./volume_metadata";
+
+export async function getMountPointForPathImpl(
+  pathname: string,
+  opts: Options,
+  nativeFn: NativeBindingsFn,
+): Promise<string> {
+  if (isBlank(pathname)) {
+    throw new TypeError("Invalid pathname: got " + JSON.stringify(pathname));
+  }
+
+  // realpath() resolves POSIX symlinks. APFS firmlinks are NOT resolved by
+  // realpath(), but fstatfs() follows them — handled below on macOS.
+  const resolved = await realpath(pathname);
+
+  const resolvedStat = await statAsync(resolved);
+  const dir = resolvedStat.isDirectory() ? resolved : dirname(resolved);
+
+  if (isMacOS) {
+    // Use the lightweight native getMountPoint which only does fstatfs —
+    // no DiskArbitration, IOKit, or space calculations.
+    const native = await nativeFn();
+    if (native.getMountPoint) {
+      debug("[getMountPointForPath] using native getMountPoint for %s", dir);
+      const p = native.getMountPoint(dir);
+      const mountPoint = await withTimeout({
+        desc: "getMountPoint()",
+        timeoutMs: opts.timeoutMs,
+        promise: p,
+      });
+      if (isNotBlank(mountPoint)) {
+        debug("[getMountPointForPath] resolved to %s", mountPoint);
+        return mountPoint;
+      }
+    }
+    // Fallback: should not happen on macOS, but defensive
+    throw new Error("getMountPoint native function unavailable");
+  }
+
+  // Linux/Windows: device ID matching + path prefix tiebreaker
+  debug("[getMountPointForPath] using device matching for %s", resolved);
+  return findMountPointByDeviceId(resolved, resolvedStat, opts, nativeFn);
+}

package/src/types/native_bindings.ts

@@ -54,6 +54,13 @@ export interface NativeBindings {
    * subsequent parsing and extraction logic.
    */
   getVolumeMetadata(options: GetVolumeMetadataOptions): Promise<VolumeMetadata>;
+
+  /**
+   * macOS only: lightweight mount point lookup using fstatfs().
+   * Returns the f_mntonname for the given directory path without fetching
+   * full volume metadata (no DiskArbitration, no IOKit, no space calculation).
+   */
+  getMountPoint?(path: string): Promise<string>;
 }
 
 export type GetVolumeMetadataOptions = {

package/src/types/options.ts

@@ -1,5 +1,7 @@
 // src/types/options.ts
 
+import type { MountPoint } from "./mount_point";
+
 /**
  * Configuration options for filesystem operations.
  *
@@ -7,6 +9,18 @@
  * @see {@link OptionsDefault} for the default values
  */
 export interface Options {
+  /**
+   * Pre-fetched mount points to use instead of querying the system.
+   *
+   * When provided, functions like {@link getMountPointForPath} and
+   * {@link getVolumeMetadataForPath} will use these mount points for device ID
+   * matching instead of calling {@link getVolumeMountPoints} internally. This
+   * avoids redundant system queries when resolving multiple paths.
+   *
+   * Obtain via `getVolumeMountPoints({ includeSystemVolumes: true })` — system
+   * volumes must be included for device ID matching to work correctly.
+   */
+  mountPoints?: MountPoint[];
   /**
    * Timeout in milliseconds for filesystem operations.
    *

package/src/volume_metadata.ts

@@ -1,5 +1,6 @@
 // src/volume_metadata.ts
 
+import type { Stats } from "node:fs";
 import { realpath } from "node:fs/promises";
 import { dirname } from "node:path";
 import { mapConcurrent, withTimeout } from "./async";
@@ -209,12 +210,38 @@ export async function getVolumeMetadataForPathImpl(
   // Linux/Windows: stat().dev is reliable (no firmlinks). Find the mount point
   // by comparing device IDs, using path prefix as a tiebreaker for bind mounts
   // or GIO mounts that share the same device id.
-  const targetDev = resolvedStat.dev;
-  const mountPoints = await getVolumeMountPointsImpl(
-    { ...opts, includeSystemVolumes: true },
+  const mountPoint = await findMountPointByDeviceId(
+    resolved,
+    resolvedStat,
+    opts,
     nativeFn,
   );
 
+  return getVolumeMetadataImpl({ ...opts, mountPoint }, nativeFn);
+}
+
+/**
+ * Find the mount point for a resolved path using device ID matching.
+ * Used on Linux and Windows where stat().dev is reliable (no firmlinks).
+ *
+ * Compares device IDs of mount points against the target path's device ID,
+ * using path prefix as a tiebreaker for bind mounts or GIO mounts that share
+ * the same device id. The longest prefix match wins.
+ */
+export async function findMountPointByDeviceId(
+  resolved: string,
+  resolvedStat: Stats,
+  opts: Options,
+  nativeFn: NativeBindingsFn,
+): Promise<string> {
+  const targetDev = resolvedStat.dev;
+  const mountPoints =
+    opts.mountPoints ??
+    (await getVolumeMountPointsImpl(
+      { ...opts, includeSystemVolumes: true },
+      nativeFn,
+    ));
+
   const prefixMatches: string[] = [];
   const deviceMatches: string[] = [];
 
@@ -234,18 +261,13 @@ export async function getVolumeMetadataForPathImpl(
     }),
   );
 
-  // Longest prefix match wins; fall back to device-only match.
   const candidates = prefixMatches.length > 0 ? prefixMatches : deviceMatches;
   if (candidates.length === 0) {
     throw new Error(
-      "No mount point found for path: " + JSON.stringify(pathname),
+      "No mount point found for path: " + JSON.stringify(resolved),
     );
   }
-  const mountPoint = candidates.reduce((a, b) =>
-    a.length >= b.length ? a : b,
-  );
-
-  return getVolumeMetadataImpl({ ...opts, mountPoint }, nativeFn);
+  return candidates.reduce((a, b) => (a.length >= b.length ? a : b));
 }
 
 export async function getAllVolumeMetadataImpl(