@photostructure/fs-metadata 0.6.1 → 0.7.0

package/doc/SSH_RELEASE_HOWTO.md

@@ -7,6 +7,7 @@ This document explains how to set up SSH commit signing for the GitHub Actions r
 For professional projects, create a dedicated bot account rather than using your personal account:
 
 ### Create the Bot Account
+
 1. Sign out of your personal GitHub account
 2. Go to https://github.com/join
 3. Create account with username like `photostructure-bot`
@@ -14,6 +15,7 @@ For professional projects, create a dedicated bot account rather than using your
 5. Verify the email address
 
 ### Add Bot as Repository Collaborator
+
 1. Go to your repo: `https://github.com/photostructure/fs-metadata`
 2. Click **Settings** tab
 3. Click **Collaborators** in the left sidebar
@@ -23,6 +25,7 @@ For professional projects, create a dedicated bot account rather than using your
 7. Send invitation
 
 ### Bot Accepts Invitation
+
 1. Sign in as the bot account
 2. Check notifications or email for repository invitation
 3. Accept the invitation
@@ -74,27 +77,26 @@ cat ~/.ssh/photostructure-bot-signing | clip
 2. Navigate to Settings → Secrets and variables → Actions
 3. Add these secrets:
 
-| Secret Name | Value |
-|-------------|-------|
+| Secret Name       | Value                         |
+| ----------------- | ----------------------------- |
 | `SSH_SIGNING_KEY` | Paste the private key content |
-| `GIT_USER_NAME` | `photostructure-bot` |
-| `GIT_USER_EMAIL` | `bot@photostructure.com` |
-| `NPM_TOKEN` | Your npm authentication token |
+| `GIT_USER_NAME`   | `photostructure-bot`          |
+| `GIT_USER_EMAIL`  | `bot@photostructure.com`      |
+| `NPM_TOKEN`       | Your npm authentication token |
 
 ## 4. How SSH Signing Works in Actions
 
-The SSH signing setup uses two composite actions:
+The SSH signing setup uses the [photostructure/git-ssh-signing-action](https://github.com/marketplace/actions/git-ssh-signing-action):
+
+### Features
 
-### setup-ssh-bot
 - Installs the SSH private key
 - Configures Git to use SSH signing format
 - Sets up commit and tag signing
 - Creates allowed signers file for verification
-
-### cleanup-ssh-bot
-- Removes SSH keys from the runner
-- Clears Git signing configuration
-- Ensures no secrets remain after workflow
+- Automatically cleans up keys and configuration after workflow
+- Supports Linux and macOS runners
+- Requires Git 2.34.0+
 
 ## 5. Using SSH Signing in Workflows
 
@@ -111,7 +113,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: ./.github/actions/setup-ssh-bot
+      - uses: photostructure/git-ssh-signing-action@v1
         with:
           ssh-signing-key: ${{ secrets.SSH_SIGNING_KEY }}
           git-user-name: ${{ secrets.GIT_USER_NAME }}
@@ -122,8 +124,7 @@ jobs:
       - run: npm version patch
       - run: git push origin main --follow-tags
 
-      - uses: ./.github/actions/cleanup-ssh-bot
-        if: always()
+      # Note: Cleanup is handled automatically by the action
 ```
 
 ## 6. Testing SSH Signing
@@ -152,14 +153,14 @@ Before triggering a release:
 
 ## 8. Advantages of SSH Signing
 
-| Feature | SSH Signing | GPG Signing |
-|---------|-------------|-------------|
-| Setup complexity | Simple | Complex |
-| Key generation | One command | Multiple steps |
-| Passphrase handling | Not required | Required |
-| Wrapper scripts | Not needed | Required |
-| GitHub verification | ✓ Supported | ✓ Supported |
-| Maintenance | Minimal | Higher |
+| Feature             | SSH Signing  | GPG Signing    |
+| ------------------- | ------------ | -------------- |
+| Setup complexity    | Simple       | Complex        |
+| Key generation      | One command  | Multiple steps |
+| Passphrase handling | Not required | Required       |
+| Wrapper scripts     | Not needed   | Required       |
+| GitHub verification | ✓ Supported  | ✓ Supported    |
+| Maintenance         | Minimal      | Higher         |
 
 ## 9. Security Best Practices
 
@@ -185,19 +186,22 @@ mv ~/.ssh/photostructure-bot-signing* ~/secure-backup/
 ## 11. Troubleshooting
 
 ### Commits show as "Unverified"
+
 - Ensure the SSH key is added as a **Signing Key** (not Authentication Key)
 - Verify the email in Git config matches the GitHub account email
 - Check that the bot account owns the key
 
 ### "error: Load key failed"
+
 - Verify SSH_SIGNING_KEY secret contains the complete private key
 - Check for extra newlines or spaces in the secret
 
 ### Permission denied on push
+
 - Ensure bot account has write access to the repository
 
 ## References
 
 - [GitHub SSH Commit Verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#ssh-commit-signature-verification)
 - [Git SSH Signing Documentation](https://git-scm.com/docs/git-config#Documentation/git-config.txt-gpgformat)
-- [GitHub Actions Encrypted Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
+- [GitHub Actions Encrypted Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets)

package/doc/WINDOWS_API_REFERENCE.md

@@ -0,0 +1,422 @@
+# Windows API Reference Guide
+
+## Overview
+
+This document serves as a comprehensive reference for all Windows APIs used in the fs-metadata project, with links to official Microsoft documentation and best practices.
+
+## File System APIs
+
+### GetLogicalDriveStringsW
+
+- **Docs**: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getlogicaldrivestringsw
+- **Purpose**: Fills a buffer with strings that specify valid drives in the system
+- **Security**: Buffer overflow risk if size not checked
+- **Best Practice**: Always call with NULL buffer first to get required size
+
+```cpp
+DWORD size = GetLogicalDriveStringsW(0, nullptr);
+if (size > 0) {
+    std::unique_ptr<WCHAR[]> buffer(new WCHAR[size]);
+    if (GetLogicalDriveStringsW(size, buffer.get())) {
+        // Process drives
+    }
+}
+```
+
+### GetDriveTypeW / GetDriveTypeA
+
+- **Docs**: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getdrivetypew
+- **Purpose**: Determines whether a disk drive is removable, fixed, CD-ROM, RAM disk, or network drive
+- **Return Values**:
+  - `DRIVE_UNKNOWN` (0)
+  - `DRIVE_NO_ROOT_DIR` (1)
+  - `DRIVE_REMOVABLE` (2)
+  - `DRIVE_FIXED` (3)
+  - `DRIVE_REMOTE` (4)
+  - `DRIVE_CDROM` (5)
+  - `DRIVE_RAMDISK` (6)
+
+### GetVolumeInformationW / GetVolumeInformationA
+
+- **Docs**: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getvolumeinformationw
+- **Purpose**: Retrieves information about the file system and volume
+- **Parameters**:
+  ```cpp
+  BOOL GetVolumeInformationW(
+    LPCWSTR lpRootPathName,           // Root directory
+    LPWSTR  lpVolumeNameBuffer,       // Volume name buffer
+    DWORD   nVolumeNameSize,          // Length of name buffer
+    LPDWORD lpVolumeSerialNumber,     // Volume serial number
+    LPDWORD lpMaximumComponentLength, // Max file name length
+    LPDWORD lpFileSystemFlags,        // File system options
+    LPWSTR  lpFileSystemNameBuffer,   // File system name buffer
+    DWORD   nFileSystemNameSize       // Length of file system name buffer
+  );
+  ```
+- **Common Errors**:
+  - `ERROR_NOT_READY`: Drive not ready (CD/DVD)
+  - `ERROR_PATH_NOT_FOUND`: Invalid path
+
+### GetDiskFreeSpaceExA
+
+- **Docs**: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getdiskfreespaceexa
+- **Purpose**: Retrieves disk space information
+- **Thread Safety**: Can block on network drives
+- **Parameters**:
+  ```cpp
+  BOOL GetDiskFreeSpaceExA(
+    LPCSTR          lpDirectoryName,    // Directory name
+    PULARGE_INTEGER lpFreeBytesAvailableToCaller, // Bytes available
+    PULARGE_INTEGER lpTotalNumberOfBytes,          // Total bytes
+    PULARGE_INTEGER lpTotalNumberOfFreeBytes       // Free bytes
+  );
+  ```
+
+### GetVolumeNameForVolumeMountPointW
+
+- **Docs**: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getvolumenameforvolumemountpointw
+- **Purpose**: Retrieves a volume GUID path for a volume mount point
+- **Requirements**: Input path must end with backslash
+- **Buffer Size**: 50 characters is sufficient for GUID path
+
+```cpp
+WCHAR volumeGUID[50];
+if (GetVolumeNameForVolumeMountPointW(L"C:\\", volumeGUID, 50)) {
+    // volumeGUID contains \\?\Volume{GUID}\
+}
+```
+
+### FindFirstFileExA
+
+- **Docs**: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-findfirstfileexa
+- **Purpose**: Searches a directory for files/subdirectories
+- **Flags**:
+  - `FIND_FIRST_EX_LARGE_FETCH`: Optimize for large directories
+  - `FIND_FIRST_EX_ON_DISK_ENTRIES_ONLY`: Skip reparse points
+- **Security**: Can follow symbolic links if not careful
+
+### GetFileAttributesW / SetFileAttributesW
+
+- **Docs**:
+  - https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfileattributesw
+  - https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-setfileattributesw
+- **Purpose**: Get/set file attributes including hidden flag
+- **Common Attributes**:
+  - `FILE_ATTRIBUTE_HIDDEN` (0x2)
+  - `FILE_ATTRIBUTE_SYSTEM` (0x4)
+  - `FILE_ATTRIBUTE_DIRECTORY` (0x10)
+  - `FILE_ATTRIBUTE_NORMAL` (0x80)
+- **Error Handling**: Returns `INVALID_FILE_ATTRIBUTES` on error
+
+## Network APIs
+
+### WNetGetConnectionA
+
+- **Docs**: https://docs.microsoft.com/en-us/windows/win32/api/winnetwk/nf-winnetwk-wnetgetconnectiona
+- **Purpose**: Retrieves network connection for a local device
+- **Header**: `#include <winnetwk.h>`
+- **Library**: `-lMpr.lib`
+- **Buffer Management**:
+  ```cpp
+  DWORD bufferSize = MAX_PATH;
+  std::unique_ptr<char[]> buffer(new char[bufferSize]);
+  DWORD result = WNetGetConnectionA("Z:", buffer.get(), &bufferSize);
+  if (result == ERROR_MORE_DATA) {
+      buffer.reset(new char[bufferSize]);
+      result = WNetGetConnectionA("Z:", buffer.get(), &bufferSize);
+  }
+  ```
+
+## String Conversion APIs
+
+### MultiByteToWideChar
+
+- **Docs**: https://docs.microsoft.com/en-us/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar
+- **Purpose**: Maps a character string to a UTF-16 wide character string
+- **Security**: Use `MB_ERR_INVALID_CHARS` to detect invalid sequences
+- **Integer Overflow Protection**: Always validate returned size before allocation
+- **Pattern**:
+
+  ```cpp
+  int len = MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS,
+                                source, -1, nullptr, 0);
+  if (len <= 0) {
+      // Handle error
+      return L"";
+  }
+
+  // Validate size to prevent overflow
+  if (len > PATHCCH_MAX_CCH) {
+      throw std::runtime_error("String too long for conversion");
+  }
+
+  std::wstring result(static_cast<size_t>(len - 1), L'\0');
+  int written = MultiByteToWideChar(CP_UTF8, MB_ERR_INVALID_CHARS,
+                                    source, -1, &result[0], len);
+  if (written <= 0) {
+      throw std::runtime_error("Conversion failed");
+  }
+  ```
+
+### WideCharToMultiByte
+
+- **Docs**: https://docs.microsoft.com/en-us/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte
+- **Purpose**: Maps a UTF-16 wide character string to a character string
+- **Flags**: Use `WC_ERR_INVALID_CHARS` for Vista+ to detect errors
+- **Integer Overflow Protection**: Validate size before `size - 1` subtraction
+- **Pattern**:
+
+  ```cpp
+  int size = WideCharToMultiByte(CP_UTF8, 0, wide, -1, nullptr, 0, nullptr, nullptr);
+
+  if (size <= 0) {
+      return "";  // Conversion failed
+  }
+
+  // Check for overflow and excessive size (1MB limit recommended)
+  if (size > INT_MAX - 1 || size > 1024 * 1024) {
+      throw std::runtime_error("String conversion size exceeds reasonable limits");
+  }
+
+  std::string result(static_cast<size_t>(size - 1), 0);
+  int written = WideCharToMultiByte(CP_UTF8, 0, wide, -1, &result[0], size, nullptr, nullptr);
+  if (written <= 0) {
+      throw std::runtime_error("String conversion failed");
+  }
+  return result;
+  ```
+
+## Shell APIs
+
+### SHGetFolderPathW
+
+- **Docs**: https://docs.microsoft.com/en-us/windows/win32/api/shlobj_core/nf-shlobj_core-shgetfolderpathw
+- **Purpose**: Gets path to special folders
+- **Common CSIDLs**:
+  - `CSIDL_WINDOWS`: Windows directory
+  - `CSIDL_SYSTEM`: System directory
+  - `CSIDL_PROGRAM_FILES`: Program Files
+- **Buffer Size**: MAX_PATH is always sufficient
+
+### PathCchCanonicalizeEx
+
+- **Docs**: https://docs.microsoft.com/en-us/windows/win32/api/pathcch/nf-pathcch-pathcchcanonicalize
+- **Purpose**: Simplifies a path by removing navigation elements with extended options
+- **Header**: `#include <pathcch.h>`
+- **Library**: `-lPathcch.lib`
+- **Security**: Prevents directory traversal attacks
+- **Long Path Support**: Use `PATHCCH_ALLOW_LONG_PATHS` flag for paths > MAX_PATH (260 chars)
+- **Buffer Size**: `PATHCCH_MAX_CCH` (32,768 characters) supports Windows 10+ long paths
+- **Usage**:
+  ```cpp
+  wchar_t canonicalPath[PATHCCH_MAX_CCH];
+  HRESULT hr = PathCchCanonicalizeEx(
+      canonicalPath,
+      PATHCCH_MAX_CCH,
+      inputPath,
+      PATHCCH_ALLOW_LONG_PATHS  // Enable long path support
+  );
+  ```
+- **Note**: Supersedes `PathCchCanonicalize` which is limited to MAX_PATH (260 chars)
+
+## Threading APIs
+
+### CreateThread
+
+- **Docs**: https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createthread
+- **Best Practice**: Always store handle for cleanup
+- **Never**: Never use `TerminateThread` - it can corrupt process state
+
+### WaitForSingleObject / WaitForMultipleObjects
+
+- **Docs**: https://docs.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitforsingleobject
+- **Timeout**: Use INFINITE carefully - prefer specific timeouts
+- **Return Values**:
+  - `WAIT_OBJECT_0`: Success
+  - `WAIT_TIMEOUT`: Timeout elapsed
+  - `WAIT_FAILED`: Error occurred
+
+### Critical Sections
+
+- **Initialize**: `InitializeCriticalSection`
+- **Enter**: `EnterCriticalSection` (blocking)
+- **Try Enter**: `TryEnterCriticalSection` (non-blocking)
+- **Leave**: `LeaveCriticalSection`
+- **Delete**: `DeleteCriticalSection`
+- **Best Practice**: Use RAII wrapper to ensure cleanup
+
+## Memory Management
+
+### Heap Functions
+
+- **HeapAlloc**: Allocate memory from heap
+- **HeapFree**: Free heap memory
+- **HeapValidate**: Validate heap integrity
+- **GetProcessHeap**: Get default process heap
+
+### Debug CRT Functions (Debug builds only)
+
+```cpp
+#ifdef _DEBUG
+#define _CRTDBG_MAP_ALLOC
+#include <crtdbg.h>
+
+// Enable leak detection
+_CrtSetDbgFlag(_CRTDBG_ALLOC_MEM_DF | _CRTDBG_LEAK_CHECK_DF);
+
+// Set allocation breakpoint
+_CrtSetBreakAlloc(1234); // Break on allocation #1234
+
+// Check memory state
+_CrtCheckMemory();
+
+// Dump leaks on exit
+_CrtDumpMemoryLeaks();
+#endif
+```
+
+## Security Considerations
+
+### Path Validation
+
+1. Check for null bytes
+2. Check for directory traversal (..)
+3. Check for device names (CON, PRN, AUX, etc.)
+4. Check for alternate data streams
+5. Validate UTF-8 sequences
+6. Use `PathCchCanonicalizeEx` with `PATHCCH_ALLOW_LONG_PATHS` for normalization
+7. Validate path length:
+   - Legacy limit: MAX_PATH (260 characters)
+   - Windows 10+ limit: PATHCCH_MAX_CCH (32,768 wide characters)
+   - UTF-8 validation: Account for multi-byte sequences (up to 3 bytes per wide char)
+
+### Buffer Overflow Prevention
+
+1. Always check buffer sizes
+2. Use safe string functions (StringCch\*)
+3. Validate all input lengths
+4. Use dynamic allocation when size unknown
+5. **Integer overflow checks** for string conversions:
+   - Validate `MultiByteToWideChar`/`WideCharToMultiByte` return values
+   - Check `size > INT_MAX - 1` before subtraction
+   - Enforce reasonable size limits (e.g., 1MB for general strings)
+   - Use `static_cast<size_t>()` for allocations to prevent sign issues
+
+### Handle Management
+
+1. Always close handles
+2. Use RAII wrappers
+3. Check for INVALID_HANDLE_VALUE
+4. Never use handles after closing
+
+### Memory Management with Windows APIs
+
+1. **FormatMessage with FORMAT_MESSAGE_ALLOCATE_BUFFER**:
+   - Always use RAII wrapper (LocalFreeGuard) to prevent leaks
+   - If `std::string` constructor throws, buffer must still be freed
+   - Never rely on manual `LocalFree` after potential throwing operations
+2. **HeapAlloc/LocalAlloc**:
+   - Prefer RAII wrappers over manual free calls
+   - Use smart pointers or custom deleters for C++ integration
+3. **Exception Safety**:
+   - Any API that allocates memory must have cleanup in destructor
+   - Never assume operations won't throw in low-memory conditions
+
+### Thread Safety
+
+1. Protect shared data with synchronization
+2. Use atomic operations where appropriate
+3. Avoid blocking operations in critical sections
+4. Always clean up threads gracefully
+
+## Error Handling
+
+### Common Error Codes
+
+- `ERROR_SUCCESS` (0): Operation successful
+- `ERROR_FILE_NOT_FOUND` (2): File not found
+- `ERROR_PATH_NOT_FOUND` (3): Path not found
+- `ERROR_ACCESS_DENIED` (5): Access denied
+- `ERROR_INVALID_HANDLE` (6): Invalid handle
+- `ERROR_NOT_READY` (21): Device not ready
+- `ERROR_SHARING_VIOLATION` (32): File in use
+- `ERROR_NETWORK_ACCESS_DENIED` (65): Network access denied
+- `ERROR_BAD_NETPATH` (53): Network path not found
+- `ERROR_MORE_DATA` (234): More data available
+- `ERROR_NO_MORE_FILES` (18): No more files
+
+### FormatMessage
+
+- **Docs**: https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-formatmessagea
+- **Memory Management**: With `FORMAT_MESSAGE_ALLOCATE_BUFFER`, must call `LocalFree`
+- **Exception Safety**: Use RAII wrapper to prevent leaks if exceptions thrown
+- **Pattern**:
+
+```cpp
+// UNSAFE - memory leak if exception thrown:
+LPVOID msgBuffer;
+FormatMessageA(FORMAT_MESSAGE_ALLOCATE_BUFFER | ..., &msgBuffer, ...);
+std::string msg((LPSTR)msgBuffer);  // If this throws, LocalFree never called!
+LocalFree(msgBuffer);
+
+// SAFE - RAII wrapper ensures cleanup:
+struct LocalFreeGuard {
+  LPVOID ptr;
+  explicit LocalFreeGuard(LPVOID p) : ptr(p) {}
+  ~LocalFreeGuard() { if (ptr) LocalFree(ptr); }
+  LocalFreeGuard(const LocalFreeGuard&) = delete;
+  LocalFreeGuard& operator=(const LocalFreeGuard&) = delete;
+};
+
+LPVOID msgBuffer = nullptr;
+FormatMessageA(
+    FORMAT_MESSAGE_ALLOCATE_BUFFER |
+    FORMAT_MESSAGE_FROM_SYSTEM |
+    FORMAT_MESSAGE_IGNORE_INSERTS,
+    NULL,
+    GetLastError(),
+    MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),
+    (LPSTR)&msgBuffer,
+    0,
+    NULL
+);
+
+LocalFreeGuard guard(msgBuffer);  // RAII ensures LocalFree called
+if (msgBuffer) {
+    std::string msg((LPSTR)msgBuffer);  // Now safe - guard cleans up
+    // ... use msg
+}
+// guard destructor calls LocalFree automatically
+```
+
+## Testing Recommendations
+
+### Memory Leak Detection
+
+```bash
+# Build debug version
+node-gyp rebuild --debug
+
+# Set CRT debug flags
+set _CRTDBG_MAP_ALLOC=1
+
+# Run with leak detection
+node --expose-gc test.js
+```
+
+### Address Sanitizer
+
+```bash
+# Set ASan options
+set ASAN_OPTIONS=halt_on_error=0:print_stats=1:check_initialization_order=1
+
+# Run tests
+npm test
+```
+
+### Performance Profiling
+
+1. Use Visual Studio Performance Profiler
+2. Enable heap profiling
+3. Monitor handle counts in Task Manager
+4. Use Performance Monitor for system metrics