@photostructure/fs-metadata 0.6.0 → 0.7.0

package/src/darwin/hidden.cpp

@@ -2,6 +2,9 @@
 #include "hidden.h"
 #include "../common/debug_log.h"
 #include "../common/error_utils.h"
+#include "path_security.h"
+#include <string.h> // for strcmp
+#include <sys/mount.h>
 #include <sys/stat.h>
 #include <unistd.h>
 
@@ -9,35 +12,51 @@ namespace FSMeta {
 
 GetHiddenWorker::GetHiddenWorker(std::string path,
                                  Napi::Promise::Deferred deferred)
-    : Napi::AsyncWorker(deferred.Env()), path_(path), deferred_(deferred),
-      is_hidden_(false) {
+    : Napi::AsyncWorker(deferred.Env()), path_(std::move(path)),
+      deferred_(deferred), is_hidden_(false) {
   DEBUG_LOG("[GetHiddenWorker] created for path: %s", path_.c_str());
 }
 
 void GetHiddenWorker::Execute() {
   DEBUG_LOG("[GetHiddenWorker] checking hidden status for: %s", path_.c_str());
 
-  // Add path validation to prevent directory traversal
-  if (path_.find("..") != std::string::npos) {
-    SetError("Invalid path containing '..'");
+  // Validate and canonicalize path using realpath() to prevent directory
+  // traversal This follows Apple's Secure Coding Guide recommendations For
+  // isHidden(), we allow non-existent paths (they will fail stat() below)
+  std::string error;
+  std::string validated_path = ValidateAndCanonicalizePath(path_, error, true);
+  if (validated_path.empty()) {
+    // If validation failed, check if it's because the path doesn't exist
+    // In that case, return the expected "Path not found" error for TypeScript
+    // layer
+    if (error.find("realpath") != std::string::npos &&
+        error.find("No such file or directory") != std::string::npos) {
+      SetError("Path not found: '" + path_ + "'");
+    } else {
+      SetError(error);
+    }
     return;
   }
 
+  // Use the validated path for all subsequent operations
+  DEBUG_LOG("[GetHiddenWorker] Using validated path: %s",
+            validated_path.c_str());
+
   struct stat statbuf;
-  if (stat(path_.c_str(), &statbuf) != 0) {
+  if (stat(validated_path.c_str(), &statbuf) != 0) {
     int error = errno;
     if (error == ENOENT) {
-      DEBUG_LOG("[GetHiddenWorker] path not found: %s", path_.c_str());
-      SetError("Path not found: '" + path_ + "'");
+      DEBUG_LOG("[GetHiddenWorker] path not found: %s", validated_path.c_str());
+      SetError("Path not found: '" + validated_path + "'");
     } else {
       DEBUG_LOG("[GetHiddenWorker] failed to stat path %s: %s (%d)",
-                path_.c_str(), strerror(error), error);
-      SetError(CreatePathErrorMessage("stat", path_, error));
+                validated_path.c_str(), strerror(error), error);
+      SetError(CreatePathErrorMessage("stat", validated_path, error));
     }
     return;
   }
   is_hidden_ = (statbuf.st_flags & UF_HIDDEN) != 0;
-  DEBUG_LOG("[GetHiddenWorker] path %s is %s", path_.c_str(),
+  DEBUG_LOG("[GetHiddenWorker] path %s is %s", validated_path.c_str(),
             is_hidden_ ? "hidden" : "not hidden");
 }
 
@@ -74,8 +93,8 @@ Napi::Promise GetHiddenAttribute(const Napi::CallbackInfo &info) {
 
 SetHiddenWorker::SetHiddenWorker(std::string path, bool hidden,
                                  Napi::Promise::Deferred deferred)
-    : Napi::AsyncWorker(deferred.Env()), path_(path), hidden_(hidden),
-      deferred_(deferred) {
+    : Napi::AsyncWorker(deferred.Env()), path_(std::move(path)),
+      hidden_(hidden), deferred_(deferred) {
   DEBUG_LOG("[SetHiddenWorker] created for path: %s, hidden: %d", path_.c_str(),
             hidden_);
 }
@@ -84,22 +103,34 @@ void SetHiddenWorker::Execute() {
   DEBUG_LOG("[SetHiddenWorker] setting hidden=%d for: %s", hidden_,
             path_.c_str());
 
-  // Add path validation to prevent directory traversal
-  if (path_.find("..") != std::string::npos) {
-    SetError("Invalid path containing '..'");
+  // macOS uses BSD file flags (UF_HIDDEN) to control file visibility.
+  // This is different from the dot-prefix convention used on Unix systems.
+  // The chflags() system call modifies these BSD-specific file flags.
+
+  // Validate and canonicalize path using realpath() to prevent directory
+  // traversal This follows Apple's Secure Coding Guide recommendations For
+  // setHidden, the file must exist, so we use ValidatePathForRead
+  std::string error;
+  std::string validated_path = ValidatePathForRead(path_, error);
+  if (validated_path.empty()) {
+    SetError(error);
     return;
   }
 
+  // Use the validated path for all subsequent operations
+  DEBUG_LOG("[SetHiddenWorker] Using validated path: %s",
+            validated_path.c_str());
+
   struct stat statbuf;
-  if (stat(path_.c_str(), &statbuf) != 0) {
+  if (stat(validated_path.c_str(), &statbuf) != 0) {
     int error = errno;
     if (error == ENOENT) {
-      DEBUG_LOG("[SetHiddenWorker] path not found: %s", path_.c_str());
-      SetError("Path not found: '" + path_ + "'");
+      DEBUG_LOG("[SetHiddenWorker] path not found: %s", validated_path.c_str());
+      SetError("Path not found: '" + validated_path + "'");
     } else {
       DEBUG_LOG("[SetHiddenWorker] failed to stat path %s: %s (%d)",
-                path_.c_str(), strerror(error), error);
-      SetError(CreatePathErrorMessage("stat", path_, error));
+                validated_path.c_str(), strerror(error), error);
+      SetError(CreatePathErrorMessage("stat", validated_path, error));
     }
     return;
   }
@@ -111,15 +142,32 @@ void SetHiddenWorker::Execute() {
     new_flags = statbuf.st_flags & ~UF_HIDDEN;
   }
 
-  if (chflags(path_.c_str(), new_flags) != 0) {
+  if (chflags(validated_path.c_str(), new_flags) != 0) {
     int error = errno;
     DEBUG_LOG("[SetHiddenWorker] failed to set flags for %s: %s (%d)",
-              path_.c_str(), strerror(error), error);
-    SetError(CreatePathErrorMessage("chflags", path_, error));
+              validated_path.c_str(), strerror(error), error);
+
+    // Check if this is an APFS filesystem issue
+    struct statfs fs;
+    bool is_apfs = false;
+    if (statfs(validated_path.c_str(), &fs) == 0) {
+      is_apfs = (strcmp(fs.f_fstypename, "apfs") == 0);
+      DEBUG_LOG("[SetHiddenWorker] filesystem type: %s", fs.f_fstypename);
+    }
+
+    // Provide more detailed error message for APFS
+    if (is_apfs && (error == EPERM || error == ENOTSUP)) {
+      SetError("Setting hidden attribute failed on APFS filesystem. "
+               "This is a known issue with some APFS volumes. "
+               "Error: " +
+               CreatePathErrorMessage("chflags", validated_path, error));
+    } else {
+      SetError(CreatePathErrorMessage("chflags", validated_path, error));
+    }
     return;
   }
   DEBUG_LOG("[SetHiddenWorker] successfully set hidden=%d for: %s", hidden_,
-            path_.c_str());
+            validated_path.c_str());
 }
 
 void SetHiddenWorker::OnOK() {

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