@photostructure/fs-metadata 0.6.1 → 0.7.0

package/src/darwin/path_security.h

@@ -0,0 +1,149 @@
+// src/darwin/path_security.h
+// Secure path validation for macOS using realpath()
+// Implements recommendations from Apple's Secure Coding Guide
+// https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Articles/RaceConditions.html
+
+#pragma once
+
+#include "../common/debug_log.h"
+#include "../common/error_utils.h"
+#include <cerrno>
+#include <cstring>
+#include <string>
+#include <sys/param.h> // For PATH_MAX
+#include <unistd.h>    // For realpath()
+
+namespace FSMeta {
+
+/**
+ * Validates a path for security issues and canonicalizes it using realpath().
+ *
+ * This function prevents directory traversal attacks by:
+ * 1. Checking for null bytes (path injection)
+ * 2. Using realpath() to resolve symbolic links and path references (../, ./)
+ * 3. Handling non-existent paths by validating the parent directory
+ *
+ * @param path The path to validate
+ * @param error Output parameter for error message if validation fails
+ * @param allow_nonexistent If true, allows paths that don't exist by validating
+ * parent
+ * @return The canonicalized path, or empty string if validation fails
+ */
+inline std::string ValidateAndCanonicalizePath(const std::string &path,
+                                               std::string &error,
+                                               bool allow_nonexistent = false) {
+  DEBUG_LOG("[ValidateAndCanonicalizePath] Validating path: %s "
+            "(allow_nonexistent: %d)",
+            path.c_str(), allow_nonexistent);
+
+  // Check for empty path
+  if (path.empty()) {
+    error = "Empty path provided";
+    DEBUG_LOG("[ValidateAndCanonicalizePath] %s", error.c_str());
+    return "";
+  }
+
+  // Security check #1: Reject paths with null bytes (path injection attack)
+  if (path.find('\0') != std::string::npos) {
+    error = "Invalid path containing null byte";
+    DEBUG_LOG("[ValidateAndCanonicalizePath] %s", error.c_str());
+    return "";
+  }
+
+  // Security check #2: Use realpath() to canonicalize and validate
+  // realpath() resolves symbolic links and eliminates ../, ./, redundant
+  // slashes
+  char resolved_path[PATH_MAX];
+  if (realpath(path.c_str(), resolved_path) != nullptr) {
+    // Path exists and was successfully canonicalized
+    std::string canonical_path(resolved_path);
+    DEBUG_LOG("[ValidateAndCanonicalizePath] Canonicalized: %s -> %s",
+              path.c_str(), canonical_path.c_str());
+    return canonical_path;
+  }
+
+  // realpath() failed - check if it's because the path doesn't exist
+  int realpath_error = errno;
+
+  if (realpath_error == ENOENT && allow_nonexistent) {
+    // For operations that create files (like setHidden), validate parent
+    // directory
+    DEBUG_LOG(
+        "[ValidateAndCanonicalizePath] Path doesn't exist, validating parent");
+
+    // Find the parent directory
+    size_t last_slash = path.find_last_of('/');
+    std::string parent_dir;
+
+    if (last_slash == std::string::npos) {
+      // No slash found - relative path, use current directory
+      parent_dir = ".";
+    } else if (last_slash == 0) {
+      // Root directory
+      parent_dir = "/";
+    } else {
+      parent_dir = path.substr(0, last_slash);
+    }
+
+    // Validate parent directory exists and is accessible
+    if (realpath(parent_dir.c_str(), resolved_path) == nullptr) {
+      int parent_error = errno;
+      error =
+          CreatePathErrorMessage("realpath (parent)", parent_dir, parent_error);
+      DEBUG_LOG("[ValidateAndCanonicalizePath] Parent validation failed: %s",
+                error.c_str());
+      return "";
+    }
+
+    // Parent is valid - construct the full path
+    std::string parent_canonical(resolved_path);
+    std::string filename =
+        (last_slash == std::string::npos) ? path : path.substr(last_slash + 1);
+
+    std::string result;
+    if (parent_canonical == "/") {
+      result = "/" + filename;
+    } else {
+      result = parent_canonical + "/" + filename;
+    }
+
+    DEBUG_LOG(
+        "[ValidateAndCanonicalizePath] Validated non-existent path: %s -> %s",
+        path.c_str(), result.c_str());
+    return result;
+  }
+
+  // realpath() failed for a different reason, or path doesn't exist and we
+  // don't allow it
+  error = CreatePathErrorMessage("realpath", path, realpath_error);
+  DEBUG_LOG("[ValidateAndCanonicalizePath] Failed: %s", error.c_str());
+  return "";
+}
+
+/**
+ * Validates that a path is secure for read operations.
+ * The path must exist and be accessible.
+ *
+ * @param path The path to validate
+ * @param error Output parameter for error message if validation fails
+ * @return The canonicalized path, or empty string if validation fails
+ */
+inline std::string ValidatePathForRead(const std::string &path,
+                                       std::string &error) {
+  return ValidateAndCanonicalizePath(path, error, false);
+}
+
+/**
+ * Validates that a path is secure for write operations.
+ * The path may not exist, but its parent directory must be valid.
+ *
+ * @param path The path to validate
+ * @param error Output parameter for error message if validation fails
+ * @return The canonicalized path, or empty string if validation fails
+ */
+inline std::string ValidatePathForWrite(const std::string &path,
+                                        std::string &error) {
+  return ValidateAndCanonicalizePath(path, error, true);
+}
+
+} // namespace FSMeta

package/src/darwin/raii_utils.h

@@ -1,11 +1,18 @@
 #pragma once
 
 #include <CoreFoundation/CoreFoundation.h>
+#include <DiskArbitration/DiskArbitration.h>
 #include <sys/mount.h>
 
+// RAII (Resource Acquisition Is Initialization) utilities for macOS APIs.
+// These wrappers ensure proper cleanup of system resources even in the
+// presence of exceptions, preventing memory leaks and resource exhaustion.
+
 namespace FSMeta {
 
-// Generic RAII wrapper for resources that need free()
+// Generic RAII wrapper for resources that need free().
+// This is used for C-style allocations that must be freed with free().
+// Common usage: buffers returned by system APIs like getmntinfo_r_np().
 template <typename T> class ResourceRAII {
 private:
   T *resource_;
@@ -41,10 +48,48 @@ public:
   ResourceRAII &operator=(const ResourceRAII &) = delete;
 };
 
-// Specialized for mount info
-using MountBufferRAII = ResourceRAII<struct statfs>;
+// Specialized RAII wrapper for mount buffer from getmntinfo_r_np().
+// getmntinfo_r_np() allocates a buffer that the caller must free.
+// This wrapper ensures the buffer is freed even if exceptions occur.
+class MountBufferRAII {
+private:
+  struct statfs *buffer_;
+
+public:
+  MountBufferRAII() : buffer_(nullptr) {}
+  ~MountBufferRAII() {
+    if (buffer_) {
+      free(buffer_);
+    }
+  }
 
-// CoreFoundation RAII wrapper
+  struct statfs **ptr() { return &buffer_; }
+  struct statfs *get() { return buffer_; }
+
+  // Add move operations for better resource management
+  MountBufferRAII(MountBufferRAII &&other) noexcept : buffer_(other.buffer_) {
+    other.buffer_ = nullptr;
+  }
+
+  MountBufferRAII &operator=(MountBufferRAII &&other) noexcept {
+    if (this != &other) {
+      if (buffer_)
+        free(buffer_);
+      buffer_ = other.buffer_;
+      other.buffer_ = nullptr;
+    }
+    return *this;
+  }
+
+  // Prevent copying
+  MountBufferRAII(const MountBufferRAII &) = delete;
+  MountBufferRAII &operator=(const MountBufferRAII &) = delete;
+};
+
+// CoreFoundation RAII wrapper following the Create/Copy/Get rule.
+// Any CF object obtained via Create or Copy functions must be released.
+// This wrapper automatically calls CFRelease() in the destructor,
+// preventing memory leaks from Core Foundation objects.
 template <typename T> class CFReleaser {
 private:
   T ref_;
@@ -82,4 +127,59 @@ public:
   }
 };
 
+// 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.
+class DASessionRAII {
+private:
+  CFReleaser<DASessionRef> session_;
+  bool is_scheduled_;
+
+public:
+  explicit DASessionRAII(DASessionRef session = nullptr) noexcept
+      : session_(session), is_scheduled_(false) {}
+
+  ~DASessionRAII() { unschedule(); }
+
+  // Schedule the session on a dispatch queue
+  void scheduleOnQueue(dispatch_queue_t queue) {
+    if (session_.isValid() && queue != nullptr) {
+      DASessionSetDispatchQueue(session_.get(), queue);
+      is_scheduled_ = true;
+    }
+  }
+
+  // Unschedule the session (must be called before session is released)
+  void unschedule() {
+    if (is_scheduled_ && session_.isValid()) {
+      DASessionSetDispatchQueue(session_.get(), nullptr);
+      is_scheduled_ = false;
+    }
+  }
+
+  DASessionRef get() const noexcept { return session_.get(); }
+  bool isValid() const noexcept { return session_.isValid(); }
+
+  // Prevent copying
+  DASessionRAII(const DASessionRAII &) = delete;
+  DASessionRAII &operator=(const DASessionRAII &) = delete;
+
+  // Allow moving
+  DASessionRAII(DASessionRAII &&other) noexcept
+      : session_(std::move(other.session_)),
+        is_scheduled_(other.is_scheduled_) {
+    other.is_scheduled_ = false;
+  }
+
+  DASessionRAII &operator=(DASessionRAII &&other) noexcept {
+    if (this != &other) {
+      unschedule();
+      session_ = std::move(other.session_);
+      is_scheduled_ = other.is_scheduled_;
+      other.is_scheduled_ = false;
+    }
+    return *this;
+  }
+};
+
 } // namespace FSMeta

package/src/darwin/volume_metadata.cpp

@@ -1,22 +1,27 @@
 // src/darwin/volume_metadata.cpp
+// Thread-safe implementation with DiskArbitration mutex synchronization
 
 #include "../common/debug_log.h"
 #include "./fs_meta.h"
+#include "./path_security.h"
 #include "./raii_utils.h"
 
 #include <CoreFoundation/CoreFoundation.h>
 #include <DiskArbitration/DiskArbitration.h>
-#include <IOKit/IOBSD.h>
-#include <IOKit/storage/IOMedia.h>
-#include <IOKit/storage/IOStorageProtocolCharacteristics.h>
+#include <fcntl.h> // For open(), O_RDONLY, O_DIRECTORY
 #include <memory>
+#include <mutex>
 #include <string>
 #include <sys/mount.h>
 #include <sys/param.h>
 #include <sys/statvfs.h>
+#include <unistd.h> // For close()
 
 namespace FSMeta {
 
+// Global mutex for DiskArbitration operations
+static std::mutex g_diskArbitrationMutex;
+
 // Helper function to convert CFString to std::string
 static std::string CFStringToString(CFStringRef cfString) {
   if (!cfString) {
@@ -24,16 +29,43 @@ static std::string CFStringToString(CFStringRef cfString) {
   }
 
   CFIndex length = CFStringGetLength(cfString);
+  if (length == 0) {
+    return "";
+  }
+
+  // Check for overflow when calculating buffer size
   CFIndex maxSize =
-      CFStringGetMaximumSizeForEncoding(length, kCFStringEncodingUTF8) + 1;
+      CFStringGetMaximumSizeForEncoding(length, kCFStringEncodingUTF8);
+  if (maxSize == kCFNotFound || maxSize > INT_MAX - 1) {
+    return "";
+  }
+  maxSize += 1; // For null terminator
+
   std::string result(maxSize, '\0');
 
-  if (!CFStringGetCString(cfString, &result[0], maxSize,
-                          kCFStringEncodingUTF8)) {
+  Boolean success =
+      CFStringGetCString(cfString, &result[0], maxSize, kCFStringEncodingUTF8);
+  if (!success) {
+    // Log the failure for debugging
+    // Common reasons: encoding issue, buffer too small, or malformed string
+    DEBUG_LOG("[CFStringToString] Conversion failed - likely encoding issue or "
+              "buffer too small");
+    DEBUG_LOG("[CFStringToString] maxSize: %ld, string length: %ld", maxSize,
+              CFStringGetLength(cfString));
     return "";
   }
 
-  result.resize(strlen(result.c_str()));
+  // Find actual string length by looking for null terminator
+  // This is safer than using strlen which could read past buffer
+  size_t actualLength = 0;
+  for (size_t i = 0; i < static_cast<size_t>(maxSize); ++i) {
+    if (result[i] == '\0') {
+      actualLength = i;
+      break;
+    }
+  }
+
+  result.resize(actualLength);
   return result;
 }
 
@@ -48,10 +80,32 @@ public:
     DEBUG_LOG("[GetVolumeMetadataWorker] Executing for mount point: %s",
               mountPoint.c_str());
     try {
+      // Validate and canonicalize mount point using realpath()
+      // This follows Apple's Secure Coding Guide recommendations
+      std::string error;
+      std::string validated_mount_point =
+          ValidatePathForRead(mountPoint, error);
+      if (validated_mount_point.empty()) {
+        SetError(error);
+        return;
+      }
+
+      // Use validated path for all subsequent operations
+      DEBUG_LOG("[GetVolumeMetadataWorker] Using validated mount point: %s",
+                validated_mount_point.c_str());
+
+      // Temporarily store original mountPoint and replace with validated one
+      std::string original_mount_point = mountPoint;
+      mountPoint = validated_mount_point;
+
       if (!GetBasicVolumeInfo()) {
+        mountPoint = original_mount_point; // Restore for error reporting
         return;
       }
-      GetDiskArbitrationInfo();
+      GetDiskArbitrationInfoSafe();
+
+      // Restore original for consistency
+      mountPoint = original_mount_point;
     } catch (const std::exception &e) {
       DEBUG_LOG("[GetVolumeMetadataWorker] Exception: %s", e.what());
       SetError(e.what());
@@ -64,23 +118,53 @@ private:
   bool GetBasicVolumeInfo() {
     DEBUG_LOG("[GetVolumeMetadataWorker] Getting basic volume info for: %s",
               mountPoint.c_str());
+
+    // Use file descriptors to prevent TOCTOU race conditions
+    // Open the mount point directory with O_DIRECTORY to ensure it's a
+    // directory
+    int fd = open(mountPoint.c_str(), O_RDONLY | O_DIRECTORY);
+    if (fd < 0) {
+      int error = errno;
+      DEBUG_LOG("[GetVolumeMetadataWorker] open failed: %s (%d)",
+                strerror(error), error);
+      SetError(CreatePathErrorMessage("open", mountPoint, error));
+      return false;
+    }
+
+    // RAII wrapper for file descriptor to ensure it's always closed
+    struct FdGuard {
+      int fd;
+      ~FdGuard() {
+        if (fd >= 0) {
+          close(fd);
+        }
+      }
+    } fd_guard{fd};
+
     struct statvfs vfs;
     struct statfs fs;
 
-    if (statvfs(mountPoint.c_str(), &vfs) != 0) {
-      DEBUG_LOG("[GetVolumeMetadataWorker] statvfs failed: %s (%d)",
-                strerror(errno), errno);
-      SetError(CreatePathErrorMessage("statvfs", mountPoint, errno));
+    // Use fstatvfs and fstatfs on the file descriptor to prevent TOCTOU
+    // The fd holds a reference to the filesystem, preventing mount changes
+    if (fstatvfs(fd, &vfs) != 0) {
+      int error = errno;
+      DEBUG_LOG("[GetVolumeMetadataWorker] fstatvfs failed: %s (%d)",
+                strerror(error), error);
+      SetError(CreatePathErrorMessage("fstatvfs", mountPoint, error));
       return false;
     }
 
-    if (statfs(mountPoint.c_str(), &fs) != 0) {
-      DEBUG_LOG("[GetVolumeMetadataWorker] statfs failed: %s (%d)",
-                strerror(errno), errno);
-      SetError(CreatePathErrorMessage("statfs", mountPoint, errno));
+    if (fstatfs(fd, &fs) != 0) {
+      int error = errno;
+      DEBUG_LOG("[GetVolumeMetadataWorker] fstatfs failed: %s (%d)",
+                strerror(error), error);
+      SetError(CreatePathErrorMessage("fstatfs", mountPoint, error));
       return false;
     }
 
+    // fd_guard will automatically close the file descriptor when this function
+    // returns
+
     // Calculate sizes using uint64_t to prevent overflow
     const uint64_t blockSize = vfs.f_frsize ? vfs.f_frsize : vfs.f_bsize;
     const uint64_t totalBlocks = static_cast<uint64_t>(vfs.f_blocks);
@@ -123,7 +207,7 @@ private:
     return true;
   }
 
-  void GetDiskArbitrationInfo() {
+  void GetDiskArbitrationInfoSafe() {
     DEBUG_LOG("[GetVolumeMetadataWorker] Getting Disk Arbitration info for: %s",
               mountPoint.c_str());
 
@@ -135,8 +219,18 @@ private:
       return;
     }
 
-    // Create session on current thread
-    CFReleaser<DASessionRef> session(DASessionCreate(kCFAllocatorDefault));
+    // THREAD SAFETY NOTE:
+    // Apple's DiskArbitration Programming Guide recommends scheduling DASession
+    // on a run loop or dispatch queue before using it. We use a dedicated
+    // serial dispatch queue (not the main queue) to avoid deadlock in Node.js
+    // context while following Apple's documented usage pattern.
+    //
+    // The mutex serializes DA operations across worker threads for extra
+    // safety.
+    std::lock_guard<std::mutex> lock(g_diskArbitrationMutex);
+
+    // Create session with RAII wrapper that handles unscheduling before release
+    DASessionRAII session(DASessionCreate(kCFAllocatorDefault));
     if (!session.isValid()) {
       DEBUG_LOG("[GetVolumeMetadataWorker] Failed to create DA session");
       metadata.status = "partial";
@@ -144,41 +238,18 @@ private:
       return;
     }
 
-    try {
-      // Get thread-local runloop or create new one if needed
-      CFRunLoopRef runLoop = CFRunLoopGetCurrent();
-      if (!runLoop) {
-        // If no runloop exists, create a new one for this thread
-        CFRunLoopRun();
-        runLoop = CFRunLoopGetCurrent();
-        if (!runLoop) {
-          throw std::runtime_error("Failed to create thread-local runloop");
-        }
-      }
-
-      // Schedule session with our runloop
-      DASessionScheduleWithRunLoop(session.get(), runLoop,
-                                   kCFRunLoopDefaultMode);
-
-      // Use RAII to ensure cleanup
-      struct RunLoopCleaner {
-        DASessionRef session;
-        CFRunLoopRef runLoop;
-        bool shouldStop;
-        RunLoopCleaner(DASessionRef s, CFRunLoopRef l, bool stop = false)
-            : session(s), runLoop(l), shouldStop(stop) {}
-        ~RunLoopCleaner() {
-          DASessionUnscheduleFromRunLoop(session, runLoop,
-                                         kCFRunLoopDefaultMode);
-          if (shouldStop) {
-            CFRunLoopStop(runLoop);
-          }
-        }
-      } scopeGuard(session.get(), runLoop, !CFRunLoopGetCurrent());
+    // Schedule session on a dedicated serial dispatch queue
+    // This follows Apple's documented pattern: create session, schedule it, use
+    // it. We use a background queue (not main queue) to avoid deadlock in
+    // Node.js. The RAII wrapper will automatically unschedule in its
+    // destructor.
+    static dispatch_queue_t da_queue =
+        dispatch_queue_create("com.photostructure.fs-metadata.diskarbitration",
+                              DISPATCH_QUEUE_SERIAL);
 
-      // Run the run loop briefly to ensure DA is ready
-      CFRunLoopRunInMode(kCFRunLoopDefaultMode, 0.1, true);
+    session.scheduleOnQueue(da_queue);
 
+    try {
       CFReleaser<DADiskRef> disk(DADiskCreateFromBSDName(
           kCFAllocatorDefault, session.get(), metadata.mountFrom.c_str()));
 
@@ -186,23 +257,22 @@ private:
         DEBUG_LOG("[GetVolumeMetadataWorker] Failed to create disk reference");
         metadata.status = "partial";
         metadata.error = "Failed to create disk reference";
+        // RAII wrapper will automatically unschedule on function exit
         return;
       }
 
+      // Now safe to call DADiskCopyDescription with properly scheduled session
       CFReleaser<CFDictionaryRef> description(
           DADiskCopyDescription(disk.get()));
       if (!description.isValid()) {
         DEBUG_LOG("[GetVolumeMetadataWorker] Failed to get disk description");
         metadata.status = "partial";
         metadata.error = "Failed to get disk description";
+        // RAII wrapper will automatically unschedule on function exit
         return;
       }
 
-      // Ensure we have a complete description before continuing
-      CFRunLoopRunInMode(kCFRunLoopDefaultMode, 0.1, false);
-
-      // Process description synchronously since we're already on the right
-      // thread
+      // Process description immediately
       ProcessDiskDescription(description.get());
 
       if (metadata.status != "partial") {
@@ -214,6 +284,8 @@ private:
       metadata.status = "error";
       metadata.error = e.what();
     }
+
+    // RAII wrapper automatically unschedules and releases session here
   }
 
   void ProcessDiskDescription(CFDictionaryRef description) {
@@ -248,7 +320,9 @@ private:
     DEBUG_LOG("[GetVolumeMetadataWorker] Processing network volume");
     CFBooleanRef isNetworkVolume = (CFBooleanRef)CFDictionaryGetValue(
         description, kDADiskDescriptionVolumeNetworkKey);
-    metadata.remote = CFBooleanGetValue(isNetworkVolume);
+    if (isNetworkVolume) {
+      metadata.remote = CFBooleanGetValue(isNetworkVolume);
+    }
 
     CFURLRef url = (CFURLRef)CFDictionaryGetValue(
         description, kDADiskDescriptionVolumePathKey);