@photostructure/fs-metadata 0.6.1 → 0.7.0

package/doc/SECURITY_AUDIT_2025.md

@@ -0,0 +1,809 @@
+# Security Audit Report - October 22 2025
+
+**Project**: @photostructure/fs-metadata
+**Auditor**: Claude (Anthropic)
+**Scope**: Complete codebase review including API verification against official documentation
+
+## Executive Summary
+
+This comprehensive security audit examined all source files (12 C++ files, 21 headers, TypeScript bindings, and build configuration) and verified every external API call against official documentation from Microsoft.com, Apple.com, kernel.org, and gnome.org.
+
+**Overall Security Rating: B+ (Good with identified improvements needed)**
+
+### Strengths
+
+- ✅ Excellent RAII patterns preventing resource leaks
+- ✅ Comprehensive integer overflow protection
+- ✅ Strong Windows security compiler flags (/guard:cf, /sdl, /Qspectre)
+- ✅ Good input validation at API boundaries
+- ✅ Proper exception safety throughout
+
+### Areas Requiring Improvement
+
+- ✅ ~~Path validation can be bypassed (Critical)~~ → FIXED 2025-10-23
+- ⚠️ Thread safety issues with macOS DiskArbitration and Linux GIO (High) → Pending
+- ⚠️ Memory leak risks in error handling (High) → Pending
+- ✅ ~~CFStringGetCString silent failures (Medium)~~ → FIXED 2025-10-23
+- ✅ ~~TOCTOU race conditions on macOS (Medium)~~ → FIXED 2025-10-23
+
+---
+
+## Critical Priority Findings
+
+### Finding #1: Path Validation Bypass (macOS/Linux) ✅ FIXED
+
+**Severity**: 🔴 CRITICAL → ✅ RESOLVED
+**Files Affected**:
+
+- `src/darwin/hidden.cpp` (updated)
+- `src/darwin/volume_metadata.cpp` (updated)
+- `src/darwin/path_security.h` (new - secure path validation header)
+- `src/darwin-path-security.test.ts` (tests added)
+
+**Status**: Fixed on 2025-10-23
+
+**Issue**: Simple string-based path validation using `path.find("..")` could be bypassed with URL-encoded sequences, Unicode normalization attacks, redundant separators, or absolute path traversal.
+
+**Fix Applied**:
+
+- Created `src/darwin/path_security.h` with `realpath()`-based validation
+- Updated `src/darwin/hidden.cpp` and `src/darwin/volume_metadata.cpp`
+- Added 13 comprehensive security tests (all passing)
+
+**Security Improvements**:
+
+- ✅ Uses `realpath()` to canonicalize paths, eliminating `../`, `./`, and symbolic links
+- ✅ Validates parent directory for non-existent paths
+- ✅ Prevents null byte injection
+- ✅ Maintains backward compatibility (all 486 tests pass)
+
+---
+
+### Finding #2: Windows Path Length Restriction ✅ FIXED
+
+**Severity**: 🔴 CRITICAL → ✅ RESOLVED
+**Files Affected**:
+
+- `src/windows/security_utils.h:106-116` (updated)
+- `src/windows-input-security.test.ts` (tests added)
+- `doc/WINDOWS_API_REFERENCE.md` (documentation updated)
+- `doc/gotchas.md` (documentation added)
+
+**Status**: Fixed on 2025-10-23
+
+**Issue**: `PathCchCanonicalize` restricts paths to MAX_PATH (260 characters), preventing access to legitimate long paths that Windows 10+ supports (up to 32,768 characters).
+
+**Fix Applied**:
+
+- Migrated to `PathCchCanonicalizeEx` with `PATHCCH_ALLOW_LONG_PATHS` flag
+- Updated buffer sizes from MAX_PATH (260) to PATHCCH_MAX_CCH (32,768)
+- Added comprehensive test coverage for long paths
+- Updated documentation in `doc/WINDOWS_API_REFERENCE.md` and `doc/gotchas.md`
+
+**Note**: Applications must enable long path support via app manifest or registry configuration.
+
+---
+
+### Finding #3: Integer Overflow in String Conversion ✅ FIXED
+
+**Severity**: 🔴 CRITICAL → ✅ RESOLVED
+**Files Affected**:
+
+- `src/windows/string.h:9-103` (updated)
+- `src/windows-string-security.test.ts` (tests added)
+- `doc/WINDOWS_API_REFERENCE.md` (documentation updated)
+
+**Status**: Fixed on 2025-10-23
+
+**Issue**: `WideToUtf8()` and `ToWString()` didn't validate that conversion sizes were positive or check for integer overflow before allocation.
+
+**Fix Applied**:
+
+- Added overflow protection: validates `size > INT_MAX - 1` before subtraction
+- Enforced sanity limits: 1MB for general strings, PATHCCH_MAX_CCH for paths
+- Added input validation: checks input length fits in `int` type
+- Implemented error detection with `MB_ERR_INVALID_CHARS` flag
+- Added comprehensive debug logging for all failure paths
+
+**Test Coverage**: Overflow scenarios, size limits, invalid UTF-8, multi-byte characters, stress testing (100+ conversions)
+
+---
+
+## High Priority Findings
+
+### Finding #4: Memory Leak in Windows Error Formatting ✅ FIXED
+
+**Severity**: 🟠 HIGH → ✅ RESOLVED
+**Files Affected**:
+
+- `src/windows/error_utils.h:19-95` (updated)
+- `src/windows-error-utils-security.test.ts` (tests added)
+- `doc/WINDOWS_API_REFERENCE.md` (documentation updated)
+
+**Status**: Fixed on 2025-10-23
+
+**Issue**: `FormatMessageA` with `FORMAT_MESSAGE_ALLOCATE_BUFFER` requires `LocalFree`, but if the `std::string` constructor throws an exception, memory leaks.
+
+**Fix Applied**:
+
+- Implemented RAII `LocalFreeGuard` to ensure `LocalFree` is always called
+- Added null safety and error logging
+- Made exception-safe: memory freed regardless of code path
+- Added comprehensive test coverage (1000+ iterations, concurrent operations)
+
+**Impact**: Prevents memory leaks in error handling paths, critical for long-running services.
+
+---
+
+### Finding #5: Undocumented Thread Safety - DiskArbitration (macOS) ✅ FIXED
+
+**Severity**: 🟠 HIGH → ✅ RESOLVED
+**Files Affected**:
+
+- `src/darwin/volume_metadata.cpp` (updated)
+- `src/darwin/raii_utils.h` (DASessionRAII wrapper added)
+- `src/darwin-disk-arbitration-threading.test.ts` (tests added)
+
+**Status**: Fixed on 2025-10-23
+
+**Issue**:
+While the code uses a mutex to serialize DiskArbitration access, Apple's documentation doesn't explicitly guarantee thread safety for `DADiskCopyDescription`. The framework is designed for run loop/dispatch queue usage.
+
+**Research Findings**:
+
+- Apple Developer Forums show no explicit thread-safety guarantees
+- DiskArbitration is designed to work with CFRunLoop (main thread pattern)
+- No documented CVEs, but framework assumptions may not hold in worker threads
+
+**Official Documentation**:
+
+- [DADiskCopyDescription](<https://developer.apple.com/documentation/diskarbitration/dadiskcopydescription(_:)>)
+- Apple: [Thread Safety Summary](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Multithreading/ThreadSafetySummary/ThreadSafetySummary.html)
+
+**Current Code**:
+
+```cpp
+// src/darwin/volume_metadata.cpp:173
+// Use a global mutex to serialize DiskArbitration access
+std::lock_guard<std::mutex> lock(g_diskArbitrationMutex);
+
+CFReleaser<DASessionRef> session(DASessionCreate(kCFAllocatorDefault));
+// ... DA operations
+```
+
+**Implemented Fix**:
+
+Based on extensive research into Node.js threading and macOS APIs, we implemented a solution following Apple's DiskArbitration Programming Guide recommendations:
+
+**1. Created RAII wrapper for DASession** (`src/darwin/raii_utils.h`):
+
+```cpp
+class DASessionRAII {
+private:
+  CFReleaser<DASessionRef> session_;
+  bool is_scheduled_;
+
+public:
+  ~DASessionRAII() { unschedule(); }  // Ensures cleanup order
+
+  void scheduleOnQueue(dispatch_queue_t queue) {
+    DASessionSetDispatchQueue(session_.get(), queue);
+    is_scheduled_ = true;
+  }
+
+  void unschedule() {
+    if (is_scheduled_ && session_.isValid()) {
+      DASessionSetDispatchQueue(session_.get(), nullptr);  // Required before release
+      is_scheduled_ = false;
+    }
+  }
+};
+```
+
+**2. Updated implementation** (`src/darwin/volume_metadata.cpp`):
+
+```cpp
+void GetDiskArbitrationInfoSafe() {
+  // 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.
+  std::lock_guard<std::mutex> lock(g_diskArbitrationMutex);
+
+  // Create session with RAII wrapper
+  DASessionRAII session(DASessionCreate(kCFAllocatorDefault));
+
+  // Schedule on background serial queue (not main queue)
+  static dispatch_queue_t da_queue = dispatch_queue_create(
+      "com.photostructure.fs-metadata.diskarbitration",
+      DISPATCH_QUEUE_SERIAL);
+
+  session.scheduleOnQueue(da_queue);
+
+  // Use session...
+  CFReleaser<DADiskRef> disk(DADiskCreateFromBSDName(...));
+  CFReleaser<CFDictionaryRef> description(DADiskCopyDescription(disk.get()));
+
+  // RAII wrapper automatically unschedules and releases on scope exit
+}
+```
+
+**Why This Approach**:
+
+- ✅ Follows Apple's documented pattern: "create session, schedule it, use it"
+- ✅ Uses background dispatch queue (avoiding main queue deadlock in Node.js)
+- ✅ RAII ensures proper cleanup order (unschedule before release)
+- ✅ Compatible with Node.js/libuv threading model
+- ✅ Mutex still serializes for extra safety
+
+**Why NOT `dispatch_sync(dispatch_get_main_queue())`**:
+Research showed this would deadlock because Node.js doesn't pump CFRunLoop on its main thread.
+
+**Test Coverage**:
+
+- Existing concurrent tests in `volume_metadata.test.ts` (50 concurrent requests)
+- New threading stress tests in `darwin-disk-arbitration-threading.test.ts` (100+ rapid requests)
+- All 486 tests pass
+
+---
+
+### Finding #6: Thread Safety Violation - GVolumeMonitor (Linux) ✅ FIXED
+
+**Severity**: 🟠 HIGH → ✅ RESOLVED
+**Files Affected**:
+
+- `src/linux/gio_utils.cpp` (rewritten)
+- `src/linux/gio_utils.h` (updated)
+- `src/linux/gio_mount_points.cpp` (updated)
+- `src/linux/gio_volume_metadata.cpp` (updated)
+- `binding.gyp` (updated to include gio-unix-2.0)
+- `src/linux-gio-thread-safety.test.ts` (tests added)
+
+**Status**: Fixed on 2025-10-24
+
+**Issue**:
+The code accessed `GVolumeMonitor` from AsyncWorker threads, but GIO documentation explicitly states:
+
+> "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."
+
+**Official Documentation**:
+
+- [GVolumeMonitor](https://docs.gtk.org/gio/class.VolumeMonitor.html) - Thread safety restrictions
+- [g_unix_mounts_get](https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gunixmounts.c) - Thread-safe alternative
+
+**Fix Applied**:
+
+Implemented a **dual-path architecture**:
+
+1. **Primary Path (Thread-Safe)**: Uses `g_unix_mounts_get()` which is explicitly thread-safe
+   - Uses `getmntent_r()` when available (reentrant)
+   - Falls back to `getmntent()` with G_LOCK protection
+   - Provides mount path, device path, filesystem type
+   - Safe to call from worker threads ✅
+
+2. **Optional Enhancement (Best-Effort)**: GVolumeMonitor for rich metadata
+   - Volume labels from GVFS
+   - Network URIs
+   - Mount names
+   - Wrapped in try/catch - failure is acceptable
+
+**Security Improvements**:
+
+- ✅ Primary code path uses documented thread-safe API (`g_unix_mounts_get`)
+- ✅ No longer depends on GVolumeMonitor for core functionality
+- ✅ Degrades gracefully if GVolumeMonitor enrichment fails
+- ✅ Fixes Finding #7 (double-free) simultaneously
+- ✅ Updated binding.gyp to include `gio-unix-2.0` package
+
+**Test Coverage**:
+
+- 3 new tests in `src/linux-gio-thread-safety.test.ts`
+- 50 concurrent mount point requests (stress test)
+- 20 concurrent metadata queries
+- All existing tests pass (490 total)
+
+---
+
+### Finding #7: Potential Double-Free in GIO (Linux) ✅ FIXED
+
+**Severity**: 🟠 HIGH → ✅ RESOLVED
+**Files Affected**:
+
+- `src/linux/gio_utils.cpp` (rewritten - fixed as part of Finding #6)
+
+**Status**: Fixed on 2025-10-24 (resolved together with Finding #6)
+
+**Issue**:
+The original code called `g_object_ref(mount)` to take an extra reference, then called `g_object_unref(mount)` in multiple code paths (success, error, exception), and finally called `g_list_free_full(mounts, g_object_unref)` which would unref each mount again, causing a double-free.
+
+**Official Documentation**:
+
+- [g_list_free_full](https://docs.gtk.org/glib/func.list_free_full.html) - Calls the destroy function on each element
+
+**Fix Applied**:
+
+The rewrite for Finding #6 completely eliminates this issue:
+
+1. **New implementation uses `GUnixMountEntry`** instead of `GMount`
+   - No reference counting needed for GUnixMountEntry
+   - Freed with `g_unix_mount_free()` not `g_object_unref()`
+   - Clean separation: one `g_list_free_full()` call, no manual unrefs
+
+2. **Optional GVolumeMonitor path** (when used):
+   - Uses `g_list_free_full(mounts, g_object_unref)` exactly once
+   - No manual `g_object_ref()`/`g_object_unref()` pairs
+   - List owns all references
+
+**Why This Matters**:
+Double-unref can cause:
+
+1. Use-after-free vulnerabilities
+2. Crashes when GObject reaches ref count 0 prematurely
+3. Memory corruption if object is freed and reallocated
+
+**Test Coverage**:
+
+- Fixed implementation validated by all existing mount/metadata tests
+- 50+ concurrent requests stress test (would expose double-free under load)
+- All 490 tests pass
+
+---
+
+## Medium Priority Findings
+
+### Finding #8: CFStringGetCString Error Logging (macOS) ✅ FIXED
+
+**Severity**: 🟡 MEDIUM → ✅ RESOLVED
+**Files Affected**:
+
+- `src/darwin/volume_metadata.cpp` (updated)
+
+**Status**: Fixed on 2025-10-23
+
+**Issue**:
+The code correctly checks the return value of `CFStringGetCString`, but doesn't log why conversion failed, making debugging difficult.
+
+**Fix Applied**: Added debug logging to log conversion failures with buffer size and string length details.
+
+**Impact**: Improved debuggability with no performance impact.
+
+---
+
+### Finding #9: TOCTOU Race Condition in statvfs/statfs (macOS/Linux) ✅ FIXED
+
+**Severity**: 🟡 MEDIUM → ✅ RESOLVED
+**Files Affected**:
+
+- `src/darwin/volume_metadata.cpp` (updated - macOS)
+- `src/linux/volume_metadata.cpp` (updated - Linux)
+
+**Status**: macOS fixed on 2025-10-23, Linux fixed on 2025-10-24
+
+**Issue**:
+Time-of-check-time-of-use race condition: mount point could be unmounted or replaced between `statvfs` call and subsequent operations.
+
+**Official Documentation**:
+
+- [Apple: Race Conditions and Secure File Operations](https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Articles/RaceConditions.html)
+- [statvfs(2) man page](https://man7.org/linux/man-pages/man2/statvfs.2.html)
+- [fstatvfs(2) man page](https://man7.org/linux/man-pages/man2/fstatvfs.2.html)
+- [open(2) man page - O_DIRECTORY flag](https://man7.org/linux/man-pages/man2/open.2.html)
+
+**Fix Applied (macOS)**:
+
+- Use file descriptor-based approach: `open()` with `O_DIRECTORY`, then `fstatvfs()`/`fstatfs()`
+- Added RAII `FdGuard` to ensure file descriptor is always closed
+- File descriptor holds reference to filesystem, preventing mount changes during operation
+
+**Fix Applied (Linux)**:
+
+- Same file descriptor-based approach as macOS
+- `open()` with `O_DIRECTORY | O_RDONLY | O_CLOEXEC`
+- Use `fstatvfs()` on file descriptor instead of `statvfs()` on path
+- RAII `FdGuard` struct ensures file descriptor is always closed (exception-safe)
+- Added comprehensive inline documentation explaining TOCTOU prevention
+
+**Security Improvements**:
+
+- ✅ File descriptor holds reference to filesystem, preventing TOCTOU
+- ✅ `O_DIRECTORY` ensures we're opening a directory (fails otherwise)
+- ✅ `O_CLOEXEC` prevents fd leaks in multithreaded programs
+- ✅ RAII pattern guarantees resource cleanup
+
+**Impact**: Prevents race condition attacks; all 491 tests pass with no regressions.
+
+---
+
+### Finding #10: blkid Memory Management Documentation (Linux) ✅ FIXED
+
+**Severity**: 🟡 MEDIUM (Documentation) → ✅ RESOLVED
+**Files Affected**:
+
+- `src/linux/volume_metadata.cpp` (updated with comprehensive documentation)
+
+**Status**: Fixed on 2025-10-24
+
+**Issue**:
+The code correctly uses `free()` on strings returned by `blkid_get_tag_value`, but lacked comments explaining WHY `free()` must be used instead of `delete`.
+
+**Official Documentation**:
+
+- [libblkid source](https://github.com/util-linux/util-linux/blob/master/libblkid/src/resolve.c) shows `blkid_get_tag_value` uses `strdup()`
+
+**Fix Applied**:
+
+Added comprehensive inline documentation explaining:
+
+1. **Memory allocation**: `blkid_get_tag_value()` returns strings allocated with `strdup()` (uses `malloc()` internally)
+2. **Critical requirement**: Must use `free()`, NOT `delete` or `delete[]`
+3. **Why it matters**: Using wrong deallocator causes undefined behavior (likely crash)
+4. **Source reference**: Links to libblkid source code showing `strdup()` usage
+
+**Documentation Added**:
+
+```cpp
+// MEMORY MANAGEMENT: blkid_get_tag_value() returns strings allocated with strdup()
+//
+// CRITICAL: These strings MUST be freed with free(), NOT delete or delete[]
+// blkid is a C library (libblkid), and blkid_get_tag_value() uses strdup()
+// internally which allocates memory with malloc().
+//
+// Memory allocated with malloc() must be deallocated with free().
+// Using delete or delete[] would invoke the wrong deallocator and
+// cause undefined behavior (likely a crash).
+//
+// See: Finding #10 in SECURITY_AUDIT_2025.md
+// Reference: https://github.com/util-linux/util-linux/blob/master/libblkid/src/resolve.c
+
+char *uuid = blkid_get_tag_value(cache.get(), "UUID", options_.device.c_str());
+if (uuid) {
+  metadata.uuid = uuid;
+  free(uuid);  // IMPORTANT: Use free(), not delete (C API, uses malloc/strdup)
+  ...
+}
+```
+
+**Impact**: Prevents future maintenance errors where someone might incorrectly change `free()` to `delete`.
+
+---
+
+## Low Priority / Enhancements
+
+### Finding #11: Thread Pool Shutdown Timeout Configuration (Windows) ✅ REVIEWED
+
+**Severity**: 🟢 LOW → ✅ NO ACTION NEEDED
+**Files Affected**:
+
+- `src/windows/thread_pool.h:147-178` (reviewed)
+
+**Status**: Reviewed on 2025-10-23
+
+**Issue**:
+Hard-coded 5-second timeout for thread shutdown may be insufficient for slow I/O operations (network drives, slow HDDs).
+
+**Assessment**:
+
+The current implementation already has appropriate timeout handling:
+
+```cpp
+// src/windows/thread_pool.h:169-174
+DWORD result = WaitForMultipleObjects(static_cast<DWORD>(handles.size()),
+                                      handles.data(), TRUE, 5000);
+
+if (result == WAIT_TIMEOUT) {
+  DEBUG_LOG("[ThreadPool] WARNING: %zu threads did not exit within 5s",
+            handles.size());
+  // Note: TerminateThread is dangerous and not recommended
+  // Threads will be forcefully terminated when process exits
+}
+```
+
+**Rationale for No Changes**:
+
+1. **5-second timeout is sufficient**: Most I/O operations complete within milliseconds; 5 seconds provides ample margin
+2. **Configuration would be ungainly**: Exposing this to JavaScript requires:
+   - New NativeBindings interface method
+   - Modifications to binding.cpp
+   - Changing global singleton pattern
+   - New TypeScript types and documentation
+   - Additional test coverage
+3. **Low priority**: This is a LOW severity finding for a rare edge case
+4. **Debug logging exists**: Timeout warnings are logged for diagnostics
+5. **Graceful degradation**: Process exit handles forced termination safely
+
+**Conclusion**:
+
+The complexity of making this configurable outweighs the benefit for this LOW priority finding. The current implementation is sufficient for all realistic use cases
+
+---
+
+### Finding #12: ARM64 Security Flag Documentation (Windows) ✅ FIXED
+
+**Severity**: 🟢 LOW (Documentation) → ✅ RESOLVED
+**Files Affected**:
+
+- `binding.gyp:108-141` (inline comments added)
+- `doc/WINDOWS_ARM64_SECURITY.md` (comprehensive guide created)
+
+**Status**: Fixed on 2025-10-23
+
+**Issue**:
+ARM64 builds exclude `/Qspectre` and `/CETCOMPAT` without explaining why.
+
+**Implemented Fix**:
+
+1. **Inline Comments in `binding.gyp`**:
+   - Added explanatory comments for each ARM64 compiler flag
+   - Documented why `/Qspectre` is omitted (x64/x86-specific)
+   - Documented why `/CETCOMPAT` is omitted (Intel CET is x64-specific)
+   - Referenced comprehensive documentation
+
+2. **Comprehensive Documentation**: `doc/WINDOWS_ARM64_SECURITY.md`
+
+Comprehensive documentation explaining:
+
+1. **Why `/Qspectre` is omitted**:
+   - x64/x86-specific compiler mitigation
+   - Not available for ARM64 architecture
+   - ARM64 has hardware-level mitigations built into CPU
+
+2. **Why `/CETCOMPAT` is omitted**:
+   - Intel CET (Control-flow Enforcement Technology) is x64-specific
+   - ARM64 has equivalent features: PAC (Pointer Authentication) and BTI (Branch Target Identification)
+   - Different hardware security approach
+
+3. **ARM64 Security Features Documented**:
+   - **PAC (Pointer Authentication Codes)**: Cryptographic pointer signing
+   - **BTI (Branch Target Identification)**: Control flow integrity
+   - **MTE (Memory Tagging Extension)**: Future hardware memory safety
+   - **Control Flow Guard**: Fully supported, same as x64
+   - **ASLR**: Fully supported, same as x64
+
+4. **Security Comparison Table**: x64 vs ARM64 feature parity
+5. **Future Considerations**: ARM64 shadow stack when compiler support stabilizes
+
+**Result**: ARM64 builds have equivalent or better security than x64 builds, just using different (ARM-specific) hardware features.
+
+**Reference**:
+
+- [ARM64 Security Features](https://learn.microsoft.com/en-us/windows/arm/arm64-security-features)
+- [Spectre Mitigations](https://learn.microsoft.com/en-us/cpp/build/reference/qspectre)
+
+---
+
+## API Usage Verification Matrix
+
+| API/Function            | Platform    | Documentation Verified | Status                       | Finding # |
+| ----------------------- | ----------- | ---------------------- | ---------------------------- | --------- |
+| `MultiByteToWideChar`   | Windows     | ✅ Microsoft           | ⚠️ Needs overflow checks     | #3        |
+| `WideCharToMultiByte`   | Windows     | ✅ Microsoft           | ⚠️ Needs overflow checks     | #3        |
+| `FormatMessageA`        | Windows     | ✅ Microsoft           | ⚠️ Memory leak risk          | #4        |
+| `PathCchCanonicalize`   | Windows     | ✅ Microsoft           | ⚠️ Use Ex version            | #2        |
+| `PathCchCanonicalizeEx` | Windows     | ✅ Microsoft           | ✅ Recommended               | #2        |
+| `GetVolumeInformationW` | Windows     | ✅ Microsoft           | ✅ Correct                   | -         |
+| `WNetGetConnectionA`    | Windows     | ✅ Microsoft           | ✅ Correct                   | -         |
+| `FindFirstFileExA`      | Windows     | ✅ Microsoft           | ✅ Correct                   | -         |
+| `GetDriveTypeA`         | Windows     | ✅ Microsoft           | ✅ Correct                   | -         |
+| `GetDiskFreeSpaceExA`   | Windows     | ✅ Microsoft           | ✅ Correct                   | -         |
+| `DADiskCopyDescription` | macOS       | ✅ Apple               | ⚠️ Thread safety unclear     | #5        |
+| `CFStringGetCString`    | macOS       | ✅ Apple               | ✅ Correct (enhance logging) | #8        |
+| `statvfs`               | macOS/Linux | ✅ man7.org/Apple      | ⚠️ TOCTOU risk               | #9        |
+| `statfs`                | macOS       | ✅ Apple               | ⚠️ TOCTOU risk               | #9        |
+| `fstatvfs`              | macOS/Linux | ✅ man7.org/Apple      | ✅ Recommended               | #9        |
+| `realpath`              | macOS/Linux | ✅ man7.org/Apple      | ✅ Recommended               | #1        |
+| `blkid_get_tag_value`   | Linux       | ✅ kernel.org/GitHub   | ✅ Correct                   | #10       |
+| `g_volume_monitor_get`  | Linux       | ✅ gnome.org           | ⚠️ Thread safety violation   | #6        |
+| `g_object_unref`        | Linux       | ✅ gnome.org           | ⚠️ Double-free risk          | #7        |
+
+---
+
+## Testing Recommendations
+
+### Memory Leak Detection
+
+```bash
+# Linux
+valgrind --leak-check=full --show-leak-kinds=all npm test
+
+# macOS
+export MallocStackLogging=1
+leaks --atExit -- npm test
+
+# Windows
+# Already configured: npm run check:memory
+```
+
+### Thread Safety Testing
+
+```bash
+# ThreadSanitizer (Linux/macOS)
+export CC=clang
+export CXX=clang++
+export CXXFLAGS="-fsanitize=thread -g"
+npm rebuild
+npm test
+
+# Stress test
+for i in {1..100}; do npm test & done; wait
+```
+
+### Path Traversal Testing
+
+```typescript
+// Add to test suite
+describe("Security: Path Validation", () => {
+  it("rejects directory traversal attempts", async () => {
+    await expect(isHidden("/tmp/../etc/passwd")).rejects.toThrow(
+      /invalid path/i,
+    );
+    await expect(isHidden("/home/user/./../root")).rejects.toThrow(
+      /invalid path/i,
+    );
+    await expect(isHidden("/../../../etc/shadow")).rejects.toThrow(
+      /invalid path/i,
+    );
+  });
+
+  it("rejects null byte injection", async () => {
+    await expect(isHidden("/tmp\0/../../etc/passwd")).rejects.toThrow(
+      /invalid path/i,
+    );
+  });
+});
+```
+
+---
+
+## Priority Action Plan
+
+### Week 1: Critical Fixes ✅ COMPLETE
+
+- [x] Fix #1: Implement `realpath()` validation (macOS/Linux) - ✅ Completed 2025-10-23
+- [x] Fix #2: Switch to `PathCchCanonicalizeEx` (Windows) - ✅ Completed 2025-10-23
+- [x] Fix #3: Add overflow checks to string conversion (Windows) - ✅ Completed 2025-10-23
+
+### Week 2: High Priority Fixes ✅ COMPLETE
+
+- [x] Fix #4: Add RAII to `FormatMessageA` (Windows) - ✅ Completed 2025-10-23
+- [x] Fix #5: Document/fix DiskArbitration threading (macOS) - ✅ Completed 2025-10-23
+- [x] Fix #6: Rewrite GIO to use thread-safe g_unix_mounts_get() (Linux) - ✅ Completed 2025-10-24
+- [x] Fix #7: Fix double-free in GIO iteration (Linux) - ✅ Completed 2025-10-24 (with #6)
+
+### Week 3: Medium Priority Improvements ✅ COMPLETE
+
+- [x] Fix #8: Add CFString error logging (macOS) - ✅ Completed 2025-10-23
+- [x] Fix #9: Use `fstatvfs()` with fd (macOS) - ✅ Completed 2025-10-23
+- [x] Fix #9: Use `fstatvfs()` with fd (Linux) - ✅ Completed 2025-10-24
+- [x] Fix #10: Add blkid documentation (Linux) - ✅ Completed 2025-10-24
+
+### Week 4: Testing & Documentation ✅ COMPLETE (macOS)
+
+- [x] Add path traversal tests - ✅ Completed (13 tests, all passing)
+- [ ] Run ThreadSanitizer on all platforms - ⚠️ PENDING
+- [ ] Run memory leak detection - ⚠️ PENDING
+- [x] Update security documentation - ✅ Completed 2025-10-23
+
+## Summary of Completed Work
+
+### 2025-10-24: Linux Security Fixes (Complete)
+
+**Linux Platform**: 4 findings resolved (2 high, 2 medium)
+
+**High Priority**:
+
+- ✅ Finding #6 (HIGH): GVolumeMonitor thread safety - **FIXED**
+  - Rewrote GIO implementation to use thread-safe `g_unix_mounts_get()`
+  - GVolumeMonitor now optional best-effort enrichment
+  - Dual-path architecture: thread-safe primary + optional rich metadata
+- ✅ Finding #7 (HIGH): Double-free in GIO - **FIXED**
+  - Eliminated by using `GUnixMountEntry` instead of `GMount`
+  - Clean reference counting, no manual ref/unref pairs
+
+**Medium Priority**:
+
+- ✅ Finding #9 (MEDIUM): TOCTOU race condition in statvfs - **FIXED**
+  - File descriptor-based approach: `open()` + `fstatvfs()`
+  - RAII `FdGuard` ensures resource cleanup
+  - Prevents mount point changes during operation
+- ✅ Finding #10 (MEDIUM): blkid memory management - **DOCUMENTED**
+  - Comprehensive inline documentation added
+  - Explains `free()` vs `delete` requirement
+  - Prevents future maintenance errors
+
+**Test Coverage**: All 491 tests passing (3 new tests added)
+
+**Code Quality**: No regressions, maintains backward compatibility
+
+### 2025-10-23: macOS and Windows Security Fixes
+
+**macOS Platform**: 3 critical/medium findings resolved
+
+- ✅ Finding #1 (CRITICAL): Path validation bypass - **FIXED**
+- ✅ Finding #5 (HIGH): DiskArbitration threading - **FIXED**
+- ✅ Finding #8 (MEDIUM): CFString error logging - **FIXED**
+- ✅ Finding #9 (MEDIUM): TOCTOU race condition - **FIXED**
+
+**Windows Platform**: 4 critical/high findings resolved
+
+- ✅ Finding #2 (CRITICAL): Path length restriction - **FIXED**
+- ✅ Finding #3 (CRITICAL): Integer overflow in string conversion - **FIXED**
+- ✅ Finding #4 (HIGH): Memory leak in error formatting - **FIXED**
+- ✅ Finding #11 (LOW): Thread pool timeout - **REVIEWED (no changes needed)**
+- ✅ Finding #12 (LOW): ARM64 security documentation - **DOCUMENTED**
+
+**Remaining Work**:
+
+- None! All critical, high, and medium priority findings have been resolved ✅
+
+---
+
+## References
+
+### Official Documentation Sources
+
+- **Windows APIs**: [Microsoft Learn](https://learn.microsoft.com/en-us/windows/win32/)
+- **macOS APIs**: [Apple Developer Documentation](https://developer.apple.com/documentation/)
+- **Linux System Calls**: [man7.org](https://man7.org/linux/man-pages/)
+- **GIO/GLib**: [GNOME Developer](https://developer.gnome.org/)
+- **libblkid**: [util-linux GitHub](https://github.com/util-linux/util-linux)
+
+### Security Resources
+
+- [OWASP Path Traversal](https://owasp.org/www-community/attacks/Path_Traversal)
+- [CWE-22: Path Traversal](https://cwe.mitre.org/data/definitions/22.html)
+- [CWE-362: TOCTOU Race Condition](https://cwe.mitre.org/data/definitions/362.html)
+- [CWE-415: Double Free](https://cwe.mitre.org/data/definitions/415.html)
+
+---
+
+## Document Maintenance
+
+**Last Updated**: October 24, 2025
+**Next Review**: April 2026 (or after major dependency updates)
+
+**Change Log**:
+
+- 2025-10-24: **Linux Security Fixes (Part 2)**
+  - Fixed Finding #9 (MEDIUM) - TOCTOU race condition in statvfs (Linux portion)
+    - Updated `src/linux/volume_metadata.cpp` to use file descriptor-based approach
+    - Use `open()` with `O_DIRECTORY | O_RDONLY | O_CLOEXEC`, then `fstatvfs()`
+    - Added RAII `FdGuard` to ensure file descriptor is always closed
+    - Added comprehensive inline documentation explaining TOCTOU prevention
+  - Fixed Finding #10 (MEDIUM) - blkid memory management documentation
+    - Added extensive inline documentation in `src/linux/volume_metadata.cpp`
+    - Explains why `free()` must be used (not `delete`) for blkid strings
+    - Includes source references and technical rationale
+    - Prevents future maintenance errors
+- 2025-10-24: **Linux GIO Thread Safety Fixes (Part 1)**
+  - Fixed Finding #6 (HIGH) - GVolumeMonitor thread safety violation
+    - Rewrote `src/linux/gio_utils.cpp` to use thread-safe `g_unix_mounts_get()`
+    - Updated `src/linux/gio_utils.h`, `gio_mount_points.cpp`, `gio_volume_metadata.cpp`
+    - Updated `binding.gyp` to include `gio-unix-2.0` package
+    - Implemented dual-path architecture: thread-safe primary + optional GVolumeMonitor enrichment
+    - Added 3 comprehensive tests in `src/linux-gio-thread-safety.test.ts`
+  - Fixed Finding #7 (HIGH) - Double-free in GIO iteration (resolved with #6)
+    - Eliminated by using `GUnixMountEntry` instead of `GMount`
+    - Clean reference counting with single `g_list_free_full()` call
+    - No manual `g_object_ref()`/`g_object_unref()` pairs
+- 2025-10-23: Fixed Finding #12 - Comprehensive ARM64 security documentation created
+- 2025-10-23: Fixed Finding #11 - Thread pool shutdown timeout (reviewed, no changes needed)
+- 2025-10-23: Fixed Finding #4 - RAII LocalFreeGuard for FormatMessageA memory leak prevention
+- 2025-10-23: Fixed Finding #3 - Integer overflow protection in string conversions (WideToUtf8, ToWString)
+- 2025-10-23: Fixed Finding #2 - PathCchCanonicalizeEx implementation with comprehensive tests
+- 2025-10-23: **macOS Security Fixes**
+  - Fixed Finding #1 (CRITICAL) - Path Validation Bypass using realpath() canonicalization
+    - Created `src/darwin/path_security.h` with secure path validation
+    - Updated `src/darwin/hidden.cpp` and `src/darwin/volume_metadata.cpp`
+    - Added 13 comprehensive security tests (all passing)
+    - Prevents directory traversal, null byte injection, and symbolic link attacks
+  - Fixed Finding #5 (HIGH) - DiskArbitration threading
+    - Created DASessionRAII wrapper in `src/darwin/raii_utils.h`
+    - Updated `src/darwin/volume_metadata.cpp` to use dispatch queue pattern
+    - Follows Apple's documented DiskArbitration Programming Guide
+  - Fixed Finding #8 (MEDIUM) - Added CFStringGetCString error logging
+    - Improves debuggability of string conversion failures
+  - Fixed Finding #9 (MEDIUM) - TOCTOU race condition prevention (macOS)
+    - Implemented file descriptor-based approach with `fstatvfs()`/`fstatfs()`
+    - RAII FdGuard ensures no resource leaks
+- 2025-10-22: Initial comprehensive security audit completed