@photostructure/fs-metadata 0.7.1 → 0.8.1

package/src/linux/gio_utils.h

@@ -18,7 +18,8 @@ template <typename T> struct GObjectDeleter {
   }
 };
 
-// Custom deleter for g_free
+// Custom deleter for g_free (used for strings from GIO APIs like
+// g_file_get_path)
 struct GFreeDeleter {
   void operator()(void *ptr) const {
     if (ptr) {
@@ -27,18 +28,18 @@ struct GFreeDeleter {
   }
 };
 
-// Add this before any existing smart pointer definitions
-struct GFileInfoDeleter {
-  void operator()(GFileInfo *ptr) {
-    if (ptr)
-      g_object_unref(ptr);
-  }
-};
-using GFileInfoPtr = std::unique_ptr<GFileInfo, GFileInfoDeleter>;
-
-// Smart pointer aliases
+// Smart pointer aliases for RAII management of GIO resources
+// These ensure proper cleanup even when exceptions occur
 template <typename T> using GObjectPtr = std::unique_ptr<T, GObjectDeleter<T>>;
 
+// Common GIO object types
+using GFilePtr = GObjectPtr<GFile>;
+using GMountPtr = GObjectPtr<GMount>;
+using GVolumePtr = GObjectPtr<GVolume>;
+using GVolumeMonitorPtr = GObjectPtr<GVolumeMonitor>;
+using GFileInfoPtr = GObjectPtr<GFileInfo>;
+
+// For strings allocated by GIO (g_file_get_path, g_file_get_uri, etc.)
 using GCharPtr = std::unique_ptr<char, GFreeDeleter>;
 
 namespace FSMeta {
@@ -55,37 +56,12 @@ public:
   // This is safe to call from worker threads
   static void forEachMount(const MountCallback &callback);
 
-  // OPTIONAL: Try to get GVolumeMonitor for metadata enrichment
-  // Returns nullptr if unavailable (that's OK, not required)
-  // WARNING: Violates thread-safety when called from worker threads
-  // Only use for best-effort enrichment
-  static GVolumeMonitor *tryGetMonitor() noexcept;
+  // NOTE: tryGetMonitor() has been removed because GVolumeMonitor is NOT
+  // thread-safe. See: https://docs.gtk.org/gio/class.VolumeMonitor.html
 };
 
-// Helper class for scoped GIO resource management
-template <typename T> class GioResource {
-public:
-  explicit GioResource(T *resource) : resource_(resource) {}
-  ~GioResource() {
-    if (resource_) {
-      g_object_unref(resource_);
-    }
-  }
-
-  T *get() const { return resource_; }
-  T *release() {
-    T *temp = resource_;
-    resource_ = nullptr;
-    return temp;
-  }
-
-  // Prevent copying
-  GioResource(const GioResource &) = delete;
-  GioResource &operator=(const GioResource &) = delete;
-
-private:
-  T *resource_;
-};
+// Note: GioResource<T> has been removed in favor of GObjectPtr<T> above,
+// which provides equivalent RAII semantics with std::unique_ptr.
 
 } // namespace gio
 } // namespace FSMeta

package/src/linux/gio_volume_metadata.cpp

@@ -49,94 +49,22 @@ void addMountMetadata(const std::string &mountPoint, VolumeMetadata &metadata) {
       }
     }
 
-    // OPTIONAL ENHANCEMENT: Try to get rich metadata from GVolumeMonitor
-    // This may fail (thread safety violation), but that's OK - we have basic
-    // data
-    try {
-      GVolumeMonitor *monitor = MountIterator::tryGetMonitor();
-      if (monitor) {
-        DEBUG_LOG(
-            "[gio::addMountMetadata] attempting GVolumeMonitor enrichment");
-
-        // Try to find matching GMount for this path
-        GList *mounts = g_volume_monitor_get_mounts(monitor);
-        if (mounts) {
-          for (GList *l = mounts; l != nullptr; l = l->next) {
-            GMount *mount = G_MOUNT(l->data);
-            if (!mount || !G_IS_MOUNT(mount)) {
-              continue;
-            }
-
-            GFile *root = g_mount_get_root(mount);
-            if (root) {
-              char *path = g_file_get_path(root);
-              if (path && mountPoint == path) {
-                // Found matching mount - try to get rich metadata
-
-                // Try to get volume label
-                if (metadata.label.empty()) {
-                  GVolume *volume = g_mount_get_volume(mount);
-                  if (volume) {
-                    char *label = g_volume_get_name(volume);
-                    if (label) {
-                      DEBUG_LOG("[gio::addMountMetadata] {mountPoint: %s, "
-                                "label: %s} (from GVolume)",
-                                path, label);
-                      metadata.label = label;
-                      g_free(label);
-                    }
-                    g_object_unref(volume);
-                  }
-                }
-
-                // Try to get mount name
-                if (metadata.mountName.empty()) {
-                  char *mount_name = g_mount_get_name(mount);
-                  if (mount_name) {
-                    metadata.mountName = mount_name;
-                    g_free(mount_name);
-                  }
-                }
-
-                // Try to get URI
-                if (metadata.uri.empty()) {
-                  GFile *location = g_mount_get_default_location(mount);
-                  if (location) {
-                    char *uri = g_file_get_uri(location);
-                    if (uri) {
-                      DEBUG_LOG("[gio::addMountMetadata] {mountPoint: %s, uri: "
-                                "%s} (from GMount)",
-                                path, uri);
-                      metadata.uri = uri;
-                      g_free(uri);
-                    }
-                    g_object_unref(location);
-                  }
-                }
-
-                g_free(path);
-                g_object_unref(root);
-                break; // Found our mount
-              }
-              if (path)
-                g_free(path);
-              g_object_unref(root);
-            }
-          }
-
-          // Clean up mounts list - this time correctly without double-free
-          g_list_free_full(mounts,
-                           reinterpret_cast<GDestroyNotify>(g_object_unref));
-        }
-
-        // Note: Don't unref monitor - it's a singleton
-      }
-    } catch (const std::exception &e) {
-      DEBUG_LOG("[gio::addMountMetadata] GVolumeMonitor enrichment failed "
-                "(expected, not critical): %s",
-                e.what());
-      // Ignore - we have basic metadata from Unix mount API
-    }
+    // NOTE: GVolumeMonitor enrichment has been removed.
+    //
+    // According to GIO documentation:
+    // https://docs.gtk.org/gio/class.VolumeMonitor.html
+    // "GVolumeMonitor is not thread-default-context aware and so should not
+    // be used other than from the main thread, with no thread-default-context
+    // active."
+    //
+    // This function is called from Napi::AsyncWorker::Execute() which runs
+    // on a worker thread. Using GVolumeMonitor here causes race conditions
+    // leading to GLib-GObject-CRITICAL errors like:
+    //   "g_object_ref: assertion '!object_already_finalized' failed"
+    //
+    // The basic metadata (fstype, mountFrom) from g_unix_mounts_get() is
+    // sufficient and thread-safe. Rich metadata (label, mountName, uri) can
+    // be obtained from blkid or other thread-safe sources.
 
     return false; // Stop iteration, we found our mount
   });

package/src/linux/volume_metadata.cpp

@@ -2,12 +2,15 @@
 #include "../common/volume_metadata.h"
 #include "../common/debug_log.h"
 #include "../common/error_utils.h"
+#include "../common/fd_guard.h"
 #include "../common/metadata_worker.h"
+#include "../common/path_security.h"
+#include "../common/volume_utils.h"
 #include "blkid_cache.h"
 #include <fcntl.h> // for open(), O_DIRECTORY, O_RDONLY, O_CLOEXEC
 #include <memory>
 #include <sys/statvfs.h>
-#include <unistd.h> // for close()
+#include <unistd.h>
 
 #ifdef ENABLE_GIO
 #include "gio_volume_metadata.h"
@@ -32,6 +35,18 @@ public:
       DEBUG_LOG("[LinuxMetadataWorker] starting statvfs for %s",
                 mountPoint.c_str());
 
+      // Validate and canonicalize mount point using realpath()
+      // This prevents directory traversal attacks and resolves symlinks
+      std::string error;
+      std::string validated_mount_point =
+          ValidatePathForRead(mountPoint, error);
+      if (validated_mount_point.empty()) {
+        throw FSException(error);
+      }
+
+      DEBUG_LOG("[LinuxMetadataWorker] Using validated mount point: %s",
+                validated_mount_point.c_str());
+
       // SECURITY: Use file descriptor-based approach to prevent TOCTOU race
       // condition
       //
@@ -45,23 +60,18 @@ public:
       // O_DIRECTORY: Ensures we're opening a directory, fails if not
       // O_RDONLY: Read-only access (sufficient for fstatvfs)
       // O_CLOEXEC: Close on exec (prevents fd leaks in multithreaded programs)
-      int fd = open(mountPoint.c_str(), O_DIRECTORY | O_RDONLY | O_CLOEXEC);
+      int fd = open(validated_mount_point.c_str(),
+                    O_DIRECTORY | O_RDONLY | O_CLOEXEC);
       if (fd < 0) {
         int error = errno;
         DEBUG_LOG("[LinuxMetadataWorker] open failed for %s: %s (%d)",
-                  mountPoint.c_str(), strerror(error), error);
-        throw FSException(CreatePathErrorMessage("open", mountPoint, error));
+                  validated_mount_point.c_str(), strerror(error), error);
+        throw FSException(
+            CreatePathErrorMessage("open", validated_mount_point, error));
       }
 
       // RAII guard to ensure file descriptor is always closed
-      struct FdGuard {
-        int fd;
-        ~FdGuard() {
-          if (fd >= 0) {
-            close(fd);
-          }
-        }
-      } fd_guard{fd};
+      FdGuard fd_guard(fd);
 
       // Use fstatvfs on the file descriptor instead of statvfs on the path
       // The fd holds a reference to the filesystem, preventing TOCTOU issues
@@ -69,9 +79,9 @@ public:
       if (fstatvfs(fd, &vfs) != 0) {
         int error = errno;
         DEBUG_LOG("[LinuxMetadataWorker] fstatvfs failed for %s: %s (%d)",
-                  mountPoint.c_str(), strerror(error), error);
+                  validated_mount_point.c_str(), strerror(error), error);
         throw FSException(
-            CreatePathErrorMessage("fstatvfs", mountPoint, error));
+            CreatePathErrorMessage("fstatvfs", validated_mount_point, error));
       }
 
       // fd_guard will automatically close the file descriptor when this
@@ -83,16 +93,14 @@ public:
       const uint64_t freeBlocks = static_cast<uint64_t>(vfs.f_bfree);
 
       // Check for overflow before multiplication
-      if (blockSize > 0) {
-        if (totalBlocks > std::numeric_limits<uint64_t>::max() / blockSize) {
-          throw FSException("Total volume size calculation would overflow");
-        }
-        if (availBlocks > std::numeric_limits<uint64_t>::max() / blockSize) {
-          throw FSException("Available space calculation would overflow");
-        }
-        if (freeBlocks > std::numeric_limits<uint64_t>::max() / blockSize) {
-          throw FSException("Free space calculation would overflow");
-        }
+      if (WouldOverflow(blockSize, totalBlocks)) {
+        throw FSException("Total volume size calculation would overflow");
+      }
+      if (WouldOverflow(blockSize, availBlocks)) {
+        throw FSException("Available space calculation would overflow");
+      }
+      if (WouldOverflow(blockSize, freeBlocks)) {
+        throw FSException("Free space calculation would overflow");
       }
 
       metadata.remote = false;
@@ -108,11 +116,11 @@ public:
 #ifdef ENABLE_GIO
       try {
         DEBUG_LOG("[LinuxMetadataWorker] collecting GIO metadata for %s",
-                  mountPoint.c_str());
-        gio::addMountMetadata(mountPoint, metadata);
+                  validated_mount_point.c_str());
+        gio::addMountMetadata(validated_mount_point, metadata);
       } catch (const std::exception &e) {
         DEBUG_LOG("[LinuxMetadataWorker] GIO error for %s: %s",
-                  mountPoint.c_str(), e.what());
+                  validated_mount_point.c_str(), e.what());
         metadata.status = std::string("GIO warning: ") + e.what();
       }
 #endif

package/src/options.ts

@@ -1,17 +1,30 @@
 // src/options.ts
 
 import { availableParallelism } from "node:os";
+import { env } from "node:process";
 import { compactValues, isObject } from "./object";
 import { isWindows } from "./platform";
 import type { Options } from "./types/options";
 
+const DefaultTimeoutMs = 5_000;
+
 /**
- * Default timeout in milliseconds for {@link Options.timeoutMs}.
+ * Get the default timeout in milliseconds for {@link Options.timeoutMs}.
+ *
+ * This can be overridden by setting the `FS_METADATA_TIMEOUT_MS` environment
+ * variable to a positive integer.
  *
  * Note that this timeout may be insufficient for some devices, like spun-down
  * optical drives or network shares that need to spin up or reconnect.
+ *
+ * @returns The timeout from env var if valid, otherwise 5000ms
  */
-export const TimeoutMsDefault = 5_000 as const;
+export function getTimeoutMsDefault(): number {
+  const value = env["FS_METADATA_TIMEOUT_MS"];
+  if (value == null) return DefaultTimeoutMs;
+  const parsed = parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DefaultTimeoutMs;
+}
 
 /**
  * System paths and globs that indicate system volumes
@@ -35,6 +48,25 @@ export const SystemPathPatternsDefault = [
   // we aren't including /tmp/**, as some people temporarily mount volumes there, like /tmp/project.
   "**/#snapshot", // Synology and Kubernetes volume snapshots
 
+  // Container runtime paths - these are internal infrastructure paths that are
+  // inaccessible to non-root processes and should never be scanned.
+  //
+  // Docker: https://docs.docker.com/engine/storage/drivers/overlayfs-driver/
+  // - /var/lib/docker contains overlay2 filesystems, container layers, images
+  // - /run/docker contains runtime data like network namespaces
+  "/run/docker/**",
+  "/var/lib/docker/**",
+  //
+  // containerd: https://github.com/containerd/containerd/blob/main/docs/ops.md
+  // - Used by Kubernetes, Docker (as backend), and standalone
+  "/run/containerd/**",
+  "/var/lib/containerd/**",
+  //
+  // Podman/CRI-O: https://podman.io/docs/installation#storage
+  // - Rootless and rootful container storage
+  "/run/containers/**",
+  "/var/lib/containers/**",
+
   // windows for linux:
   "/mnt/wslg/distro",
   "/mnt/wslg/doc",
@@ -104,7 +136,7 @@ export const SkipNetworkVolumesDefault = false;
  * @see {@link optionsWithDefaults} for creating an options object with default values
  */
 export const OptionsDefault: Options = {
-  timeoutMs: TimeoutMsDefault,
+  timeoutMs: getTimeoutMsDefault(),
   maxConcurrency: availableParallelism(),
   systemPathPatterns: [...SystemPathPatternsDefault],
   systemFsTypes: [...SystemFsTypesDefault],

package/src/types/options.ts

@@ -12,7 +12,7 @@ export interface Options {
    *
    * Disable timeouts by setting this to 0.
    *
-   * @see {@link TimeoutMsDefault}.
+   * @see {@link getTimeoutMsDefault}.
    */
   timeoutMs: number;
 

package/src/windows/drive_status.h

@@ -4,13 +4,9 @@
 #include "security_utils.h"
 #include "thread_pool.h"
 #include "windows_arch.h"
-#include <atomic>
 #include <chrono>
-#include <condition_variable>
 #include <future>
-#include <mutex>
 #include <string>
-#include <thread>
 #include <vector>
 
 namespace FSMeta {
@@ -83,7 +79,10 @@ private:
     searchPath += "*";
 
     WIN32_FIND_DATAA findData;
-    HandleGuard findHandle(FindFirstFileExA(
+    // Use FindHandleGuard - search handles MUST be closed with FindClose,
+    // not CloseHandle. See:
+    // https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-findclose
+    FindHandleGuard findHandle(FindFirstFileExA(
         searchPath.c_str(), FindExInfoBasic, &findData, FindExSearchNameMatch,
         nullptr,
         FIND_FIRST_EX_LARGE_FETCH | FIND_FIRST_EX_ON_DISK_ENTRIES_ONLY));
@@ -96,69 +95,77 @@ private:
     }
 
     // Successfully opened - drive is healthy
-    FindClose(findHandle.release());
+    // FindHandleGuard destructor will call FindClose automatically
     DEBUG_LOG("[DriveStatusChecker] Drive %s is healthy", path.c_str());
     return DriveStatus::Healthy;
   }
 
 public:
-  static std::future<DriveStatus> CheckDriveAsync(const std::string &path,
-                                                  DWORD timeoutMs = 5000) {
+  // Submit a drive check to the thread pool and return a future.
+  // The caller is responsible for enforcing timeout via future.wait_for().
+  // This design avoids detached threads and race conditions.
+  static std::future<DriveStatus> CheckDriveAsync(const std::string &path) {
     auto promise = std::make_shared<std::promise<DriveStatus>>();
     auto future = promise->get_future();
 
-    // Use a shared state for timeout handling
-    auto state = std::make_shared<std::atomic<bool>>(false);
-
-    GetGlobalThreadPool().Submit([path, promise, state, timeoutMs]() {
-      // Set up timeout
-      auto startTime = std::chrono::steady_clock::now();
-
-      // Perform the check
-      DriveStatus status = CheckDriveInternal(path);
-
-      // Check if we've timed out
-      auto elapsed = std::chrono::steady_clock::now() - startTime;
-      if (elapsed > std::chrono::milliseconds(timeoutMs)) {
-        status = DriveStatus::Timeout;
-      }
-
-      // Only set the promise if we haven't been cancelled
-      if (!state->load()) {
+    GetGlobalThreadPool().Submit([path, promise]() {
+      try {
+        DriveStatus status = CheckDriveInternal(path);
         promise->set_value(status);
+      } catch (const std::exception &e) {
+        DEBUG_LOG("[DriveStatusChecker] Exception in CheckDriveInternal: %s",
+                  e.what());
+        // Set exception instead of value so caller can handle it
+        try {
+          promise->set_exception(std::current_exception());
+        } catch (...) {
+          // Promise may have been abandoned if caller timed out
+        }
+      } catch (...) {
+        DEBUG_LOG(
+            "[DriveStatusChecker] Unknown exception in CheckDriveInternal");
+        try {
+          promise->set_exception(std::current_exception());
+        } catch (...) {
+          // Promise may have been abandoned if caller timed out
+        }
       }
     });
 
-    // Handle timeout in the caller
-    if (timeoutMs != INFINITE) {
-      std::thread([promise, state, timeoutMs]() {
-        std::this_thread::sleep_for(std::chrono::milliseconds(timeoutMs));
-        if (!state->exchange(true)) {
-          try {
-            promise->set_value(DriveStatus::Timeout);
-          } catch (...) {
-            // Promise already satisfied
-          }
-        }
-      }).detach();
-    }
-
     return future;
   }
 
+  // Overload that accepts timeoutMs for API compatibility (timeout is enforced
+  // in CheckDrive, not here)
+  static std::future<DriveStatus> CheckDriveAsync(const std::string &path,
+                                                  DWORD /*timeoutMs*/) {
+    return CheckDriveAsync(path);
+  }
+
   static DriveStatus CheckDrive(const std::string &path,
                                 DWORD timeoutMs = 5000) {
     try {
-      auto future = CheckDriveAsync(path, timeoutMs);
+      auto future = CheckDriveAsync(path);
+
+      // Use wait_for to enforce timeout - no detached threads needed!
+      // The worker thread continues running but we return Timeout to caller.
+      // The promise will eventually be satisfied (or abandoned).
+      auto waitResult = future.wait_for(std::chrono::milliseconds(timeoutMs));
 
-      if (future.wait_for(std::chrono::milliseconds(timeoutMs)) ==
-          std::future_status::timeout) {
+      if (waitResult == std::future_status::timeout) {
+        DEBUG_LOG("[DriveStatusChecker] Timeout waiting for drive %s",
+                  path.c_str());
         return DriveStatus::Timeout;
       }
 
+      // Future is ready - get the result (may throw if worker set exception)
       return future.get();
+    } catch (const std::exception &e) {
+      DEBUG_LOG("[DriveStatusChecker] Exception checking drive %s: %s",
+                path.c_str(), e.what());
+      return DriveStatus::Unknown;
     } catch (...) {
-      DEBUG_LOG("[DriveStatusChecker] Exception checking drive %s",
+      DEBUG_LOG("[DriveStatusChecker] Unknown exception checking drive %s",
                 path.c_str());
       return DriveStatus::Unknown;
     }
@@ -172,24 +179,42 @@ public:
     futures.reserve(paths.size());
 
     // Launch all checks concurrently
+    auto startTime = std::chrono::steady_clock::now();
     for (const auto &path : paths) {
-      futures.push_back(CheckDriveAsync(path, timeoutMs));
+      futures.push_back(CheckDriveAsync(path));
     }
 
-    // Collect results
+    // Collect results with timeout
     std::vector<DriveStatus> results;
     results.reserve(paths.size());
 
     for (size_t i = 0; i < futures.size(); ++i) {
       try {
-        if (futures[i].wait_for(std::chrono::milliseconds(timeoutMs)) ==
-            std::future_status::timeout) {
+        // Calculate remaining time for this future
+        auto elapsed = std::chrono::steady_clock::now() - startTime;
+        auto elapsedMs =
+            std::chrono::duration_cast<std::chrono::milliseconds>(elapsed)
+                .count();
+        auto remainingMs = (elapsedMs < static_cast<long long>(timeoutMs))
+                               ? static_cast<DWORD>(timeoutMs - elapsedMs)
+                               : 0;
+
+        if (remainingMs == 0 ||
+            futures[i].wait_for(std::chrono::milliseconds(remainingMs)) ==
+                std::future_status::timeout) {
+          DEBUG_LOG("[DriveStatusChecker] Timeout waiting for drive %s",
+                    paths[i].c_str());
           results.push_back(DriveStatus::Timeout);
         } else {
           results.push_back(futures[i].get());
         }
+      } catch (const std::exception &e) {
+        DEBUG_LOG(
+            "[DriveStatusChecker] Exception getting result for drive %s: %s",
+            paths[i].c_str(), e.what());
+        results.push_back(DriveStatus::Unknown);
       } catch (...) {
-        DEBUG_LOG("[DriveStatusChecker] Exception getting result for drive %s",
+        DEBUG_LOG("[DriveStatusChecker] Unknown exception for drive %s",
                   paths[i].c_str());
         results.push_back(DriveStatus::Unknown);
       }

package/src/windows/error_utils.h

@@ -62,8 +62,8 @@ private:
     size_t size = FormatMessageA(
         FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM |
             FORMAT_MESSAGE_IGNORE_INSERTS,
-        NULL, error, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
-        (LPSTR)&messageBuffer, 0, NULL);
+        nullptr, error, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
+        (LPSTR)&messageBuffer, 0, nullptr);
 
     // RAII guard ensures LocalFree is called even if exception thrown
     LocalFreeGuard guard(messageBuffer);

package/src/windows/security_utils.h

@@ -124,7 +124,7 @@ public:
 
   // Check if process has required privileges
   static bool HasRequiredPrivileges() {
-    HANDLE token;
+    HANDLE token = nullptr;
     if (!OpenProcessToken(GetCurrentProcess(), TOKEN_QUERY, &token)) {
       return false;
     }
@@ -169,7 +169,8 @@ public:
   }
 };
 
-// RAII wrapper for HANDLE resources
+// RAII wrapper for HANDLE resources (uses CloseHandle)
+// For search handles from FindFirstFile*, use FindHandleGuard instead
 class HandleGuard {
   HANDLE handle;
 
@@ -213,6 +214,48 @@ public:
   }
 };
 
+// RAII wrapper for search handles from FindFirstFile/FindFirstFileEx
+// These handles MUST be closed with FindClose, not CloseHandle.
+// See:
+// https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-findclose
+class FindHandleGuard {
+  HANDLE handle;
+
+public:
+  explicit FindHandleGuard(HANDLE h) : handle(h) {}
+
+  ~FindHandleGuard() {
+    if (handle != INVALID_HANDLE_VALUE) {
+      FindClose(handle);
+    }
+  }
+
+  FindHandleGuard(FindHandleGuard &&other) noexcept : handle(other.handle) {
+    other.handle = INVALID_HANDLE_VALUE;
+  }
+
+  FindHandleGuard &operator=(FindHandleGuard &&other) noexcept {
+    if (this != &other) {
+      if (handle != INVALID_HANDLE_VALUE) {
+        FindClose(handle);
+      }
+      handle = other.handle;
+      other.handle = INVALID_HANDLE_VALUE;
+    }
+    return *this;
+  }
+
+  // Delete copy operations
+  FindHandleGuard(const FindHandleGuard &) = delete;
+  FindHandleGuard &operator=(const FindHandleGuard &) = delete;
+
+  HANDLE get() const { return handle; }
+
+  // Check if handle is valid (FindFirstFile returns INVALID_HANDLE_VALUE on
+  // failure, not NULL)
+  explicit operator bool() const { return handle != INVALID_HANDLE_VALUE; }
+};
+
 // RAII wrapper for critical sections
 class CriticalSectionGuard {
   CRITICAL_SECTION cs;
@@ -244,6 +287,8 @@ public:
     // Delete copy/move
     Lock(const Lock &) = delete;
     Lock &operator=(const Lock &) = delete;
+    Lock(Lock &&) = delete;
+    Lock &operator=(Lock &&) = delete;
   };
 };