@photostructure/fs-metadata 0.6.1 → 0.7.1

package/doc/WINDOWS_ARM64_SECURITY.md

@@ -0,0 +1,161 @@
+# Windows ARM64 Security Configuration
+
+## Overview
+
+This document explains the security compilation flags used for ARM64 builds on Windows and why certain x64-specific flags are intentionally omitted.
+
+## ARM64 Security Flags in binding.gyp
+
+### Compiler Flags (`VCCLCompilerTool`)
+
+#### `/guard:cf` - Control Flow Guard ✅ ENABLED
+
+- **Supported**: Yes, ARM64 supports Control Flow Guard
+- **Purpose**: Prevents exploitation of memory corruption vulnerabilities
+- **Status**: Fully supported on ARM64 Windows since Windows 10
+
+#### `/ZH:SHA_256` - Hash Algorithm ✅ ENABLED
+
+- **Supported**: Yes, platform-independent
+- **Purpose**: Specifies SHA-256 hash algorithm for file checksums
+- **Status**: Standard security practice across all architectures
+
+#### `/sdl` - Security Development Lifecycle ✅ ENABLED
+
+- **Supported**: Yes, platform-independent
+- **Purpose**: Enables additional compile-time security checks
+- **Status**: Recommended for all builds
+
+### Linker Flags (`VCLinkerTool`)
+
+#### `/guard:cf` - Control Flow Guard at Link Time ✅ ENABLED
+
+- **Supported**: Yes, ARM64 supports CFG
+- **Purpose**: Enables CFG checks during linking
+- **Status**: Must match compiler flag
+
+#### `/DYNAMICBASE` - ASLR ✅ ENABLED
+
+- **Supported**: Yes, ARM64 supports ASLR
+- **Purpose**: Address Space Layout Randomization
+- **Status**: Critical security feature, enabled on all architectures
+
+## Flags Intentionally Omitted for ARM64
+
+### `/Qspectre` - Spectre Mitigation ❌ NOT AVAILABLE
+
+**Why omitted**: This flag is x64/x86-specific and not available for ARM64
+
+- **Spectre vulnerability**: CPU speculative execution side-channel attack
+- **x64 mitigation**: Compiler inserts speculation barriers
+- **ARM64 status**: ARM processors have different speculative execution behavior
+- **Alternative**: ARM64 has hardware-level mitigations built into the CPU architecture
+- **Reference**: [Microsoft ARM64 Security](https://learn.microsoft.com/en-us/windows-hardware/drivers/kernel/arm64-exception-handling)
+
+### `/CETCOMPAT` - Control-flow Enforcement Technology ❌ NOT AVAILABLE
+
+**Why omitted**: Intel CET is x64-specific and not available for ARM64
+
+- **Intel CET**: Hardware-based control-flow integrity (shadow stack)
+- **x64 status**: Available on recent Intel CPUs (11th gen+)
+- **ARM64 alternative**: ARM has different hardware security features:
+  - **PAC (Pointer Authentication Codes)**: Cryptographic signatures on pointers
+  - **BTI (Branch Target Identification)**: Forward-edge control flow integrity
+- **Future**: When compiler support for ARM64 shadow stack stabilizes, we may add it
+- **Reference**: [ARM Pointer Authentication](https://learn.microsoft.com/en-us/cpp/build/arm64-windows-abi-conventions?view=msvc-170#pointer-authentication-on-arm64)
+
+## ARM64-Specific Security Features
+
+While ARM64 doesn't support `/Qspectre` or `/CETCOMPAT`, it has equivalent or superior hardware-level security features:
+
+### 1. Pointer Authentication (PAC)
+
+- Cryptographically signs pointers to prevent corruption
+- Protects return addresses and function pointers
+- Hardware-accelerated, minimal performance overhead
+- **Status**: Supported in hardware, compiler support evolving
+
+### 2. Branch Target Identification (BTI)
+
+- Ensures indirect branches land on valid targets
+- Prevents code-reuse attacks (ROP/JOP)
+- Hardware-enforced control flow integrity
+- **Status**: Supported in hardware, compiler support evolving
+
+### 3. Memory Tagging Extension (MTE)
+
+- Hardware-based memory safety
+- Detects use-after-free and buffer overflows
+- Probabilistic detection with ~0-15% overhead
+- **Status**: ARMv8.5-A+, not yet in consumer Windows devices
+
+## Comparison: x64 vs ARM64 Security
+
+| Feature            | x64                             | ARM64                   | Notes                         |
+| ------------------ | ------------------------------- | ----------------------- | ----------------------------- |
+| Control Flow Guard | ✅ `/guard:cf`                  | ✅ `/guard:cf`          | Same implementation           |
+| ASLR               | ✅ `/DYNAMICBASE`               | ✅ `/DYNAMICBASE`       | Same implementation           |
+| Spectre Mitigation | ✅ `/Qspectre`                  | ⚠️ Hardware mitigations | Different approaches          |
+| Shadow Stack       | ✅ `/CETCOMPAT` (Intel CET)     | ⚠️ PAC (different tech) | Both protect return addresses |
+| Branch Protection  | ✅ CET Indirect Branch Tracking | ✅ BTI                  | Similar purpose               |
+| Memory Safety      | ⚠️ Software-based               | ✅ MTE (future)         | ARM has hardware advantage    |
+
+## Build Configuration
+
+### Current ARM64 Flags (binding.gyp)
+
+```json
+{
+  "target_arch=='arm64'": {
+    "defines": ["_M_ARM64", "_WIN64"],
+    "msvs_settings": {
+      "VCCLCompilerTool": {
+        "AdditionalOptions": ["/guard:cf", "/ZH:SHA_256", "/sdl"],
+        "ExceptionHandling": 1,
+        "RuntimeTypeInfo": "true"
+      },
+      "VCLinkerTool": {
+        "AdditionalOptions": ["/guard:cf", "/DYNAMICBASE"]
+      }
+    }
+  }
+}
+```
+
+### Security Posture
+
+✅ **Current**: ARM64 builds have equivalent or better security than x64
+
+- All applicable mitigations are enabled
+- ARM64 hardware features provide additional protection
+- No security regression compared to x64
+
+⏳ **Future Improvements**:
+
+- Monitor compiler support for ARM64 shadow stack
+- Evaluate PAC/BTI enablement when stable
+- Consider MTE when available in consumer devices
+
+## Testing
+
+ARM64 builds are tested on:
+
+- Windows 11 ARM64 (native)
+- Windows 10 ARM64 (emulation on x64)
+
+Security features are validated through:
+
+- Static analysis during compilation
+- Runtime testing on ARM64 devices
+- Memory safety tests (windows-memory-check.test.ts)
+
+## References
+
+- [Microsoft ARM64 ABI](https://learn.microsoft.com/en-us/cpp/build/arm64-windows-abi-conventions)
+- [ARM Security Features](https://developer.arm.com/documentation/102433/0100)
+- [Windows ARM64 Security](https://learn.microsoft.com/en-us/windows/arm/overview)
+- [Control Flow Guard on ARM64](https://learn.microsoft.com/en-us/windows/win32/secbp/control-flow-guard)
+
+## Last Updated
+
+2025-10-23 - Initial documentation of ARM64 security configuration

package/doc/WINDOWS_DEBUG_GUIDE.md

@@ -1,7 +1,9 @@
 # Windows and Alpine Linux Debugging Guide for debuglog.test.ts
 
 ## Issue Summary
+
 The debuglog.test.ts file was failing on:
+
 1. **Windows CI**: "Converting circular structure to JSON" error in Jest's message passing system when `execFileSync` threw errors with circular references
 2. **Alpine Linux**: `ETIMEDOUT` errors when spawning child processes with `npx`
 
@@ -28,11 +30,13 @@ The debuglog.test.ts file was failing on:
 To test these changes on your Windows test box:
 
 1. **Run the specific test file:**
+
    ```powershell
    npm test -- src/debuglog.test.ts
    ```
 
 2. **Run with verbose output to see debugging info:**
+
    ```powershell
    npm test -- src/debuglog.test.ts --verbose
    ```
@@ -43,11 +47,12 @@ To test these changes on your Windows test box:
    - Whether `npx tsx` is available and working correctly
 
 4. **To test individual child scripts directly:**
+
    ```powershell
    # Test debuglog-child.ts
    $env:NODE_DEBUG="fs-metadata"
    npx tsx src/test-utils/debuglog-child.ts
-   
+
    # Test debuglog-enabled-child.ts
    $env:NODE_DEBUG="fs-metadata"
    npx tsx src/test-utils/debuglog-enabled-child.ts
@@ -61,12 +66,14 @@ To test these changes on your Windows test box:
 ## Debugging Tips
 
 1. **Enable Node.js debugging:**
+
    ```powershell
    $env:NODE_OPTIONS="--trace-warnings"
    npm test -- src/debuglog.test.ts
    ```
 
 2. **Check npx/tsx availability:**
+
    ```powershell
    npx --version
    npx tsx --version
@@ -86,4 +93,4 @@ To test these changes on your Windows test box:
 
 ## Rollback Plan
 
-If these changes cause new issues, the previous approach using execFileSync can be restored by reverting this commit. The key difference is the switch from execFileSync to spawnSync and the enhanced error handling.
+If these changes cause new issues, the previous approach using execFileSync can be restored by reverting this commit. The key difference is the switch from execFileSync to spawnSync and the enhanced error handling.

package/doc/examples.md

@@ -0,0 +1,267 @@
+# Examples
+
+This guide provides practical examples for using `@photostructure/fs-metadata`.
+
+## Basic Usage
+
+### List All Mounted Volumes
+
+```typescript
+import { getVolumeMountPoints } from "@photostructure/fs-metadata";
+
+const mountPoints = await getVolumeMountPoints();
+
+// Example output on Windows:
+// [
+//   { mountPoint: 'C:\\', status: 'healthy' },
+//   { mountPoint: 'D:\\', status: 'healthy' },
+//   { mountPoint: 'E:\\', status: 'unavailable' }
+// ]
+
+// Example output on Linux:
+// [
+//   { mountPoint: '/', status: 'healthy' },
+//   { mountPoint: '/home', status: 'healthy' },
+//   { mountPoint: '/mnt/nas', status: 'timeout' }
+// ]
+```
+
+### Get Volume Metadata
+
+```typescript
+import { getVolumeMetadata } from "@photostructure/fs-metadata";
+
+const metadata = await getVolumeMetadata("/");
+
+// Example output:
+// {
+//   mountPoint: '/',
+//   mountFrom: '/dev/sda1',
+//   fstype: 'ext4',
+//   size: 500107862016,
+//   used: 234567890123,
+//   available: 239539971893,
+//   status: 'healthy'
+// }
+```
+
+### Get All Volume Metadata
+
+```typescript
+import { getAllVolumeMetadata } from "@photostructure/fs-metadata";
+
+// Get all volumes including system volumes
+const allVolumes = await getAllVolumeMetadata({ includeSystemVolumes: true });
+
+// Filter healthy volumes only
+const healthyVolumes = allVolumes.filter((v) => v.status === "healthy");
+
+// Calculate total storage
+const totalStorage = healthyVolumes.reduce((sum, v) => sum + v.size, 0);
+const totalUsed = healthyVolumes.reduce((sum, v) => sum + v.used, 0);
+```
+
+## Hidden Files
+
+### Check if File is Hidden
+
+```typescript
+import { isHidden } from "@photostructure/fs-metadata";
+
+// Simple check
+const hidden = await isHidden("/path/to/file.txt");
+
+// Check with timeout
+const hidden2 = await isHidden("/mnt/slow-network/file.txt", {
+  timeoutMs: 5000,
+});
+```
+
+### Set Hidden Attribute
+
+```typescript
+import { setHidden } from "@photostructure/fs-metadata";
+
+// Hide a file
+await setHidden("/path/to/file.txt", true);
+
+// Unhide a file
+await setHidden("/path/to/.hidden-file", false);
+
+// Note: On POSIX systems (Linux/macOS), this will rename the file
+// to add/remove a leading dot. On Windows, it sets the hidden attribute.
+```
+
+### Recursive Hidden Check
+
+```typescript
+import { isHiddenRecursive } from "@photostructure/fs-metadata";
+
+// Check if file or any parent directory is hidden
+const hidden = await isHiddenRecursive("/home/user/.config/app/settings.json");
+// Returns true because .config is hidden
+
+// Works with Windows hidden attributes too
+const hidden2 = await isHiddenRecursive("C:\\Users\\Public\\Desktop\\file.txt");
+```
+
+### Get Hidden Metadata
+
+```typescript
+import { getHiddenMetadata } from "@photostructure/fs-metadata";
+
+const metadata = await getHiddenMetadata("/path/to/file");
+
+// Example output:
+// {
+//   hidden: true,
+//   hiddenByAncestor: false,
+//   localSupport: 'native',  // or 'posix' or 'none'
+//   exists: true
+// }
+```
+
+## CommonJS Usage
+
+```javascript
+const {
+  getVolumeMountPoints,
+  getVolumeMetadata,
+  isHidden,
+  setHidden,
+} = require("@photostructure/fs-metadata");
+
+async function main() {
+  const mountPoints = await getVolumeMountPoints();
+  console.log("Mount points:", mountPoints);
+
+  const metadata = await getVolumeMetadata(mountPoints[0].mountPoint);
+  console.log("Volume metadata:", metadata);
+}
+
+main().catch(console.error);
+```
+
+## Error Handling
+
+```typescript
+import {
+  getVolumeMetadata,
+  VolumeMountPointNotAccessibleError,
+  TimeoutError,
+} from "@photostructure/fs-metadata";
+
+try {
+  const metadata = await getVolumeMetadata("/mnt/network-drive", {
+    timeoutMs: 10000, // 10 second timeout
+  });
+} catch (error) {
+  if (error instanceof TimeoutError) {
+    console.error("Operation timed out - network drive may be unreachable");
+  } else if (error instanceof VolumeMountPointNotAccessibleError) {
+    console.error("Volume is not accessible:", error.message);
+  } else {
+    console.error("Unexpected error:", error);
+  }
+}
+```
+
+## Working with Network Volumes
+
+```typescript
+import {
+  getVolumeMountPoints,
+  getVolumeMetadata,
+} from "@photostructure/fs-metadata";
+
+// Network volumes may timeout or be unavailable
+const mountPoints = await getVolumeMountPoints({ timeoutMs: 30000 });
+
+// Filter out unhealthy volumes
+const availableVolumes = mountPoints.filter((mp) => mp.status === "healthy");
+
+// Get metadata with extended timeout for network drives
+for (const mp of availableVolumes) {
+  try {
+    const metadata = await getVolumeMetadata(mp.mountPoint, {
+      timeoutMs: 20000, // 20 seconds for network volumes
+    });
+    console.log(
+      `${mp.mountPoint}: ${metadata.used} of ${metadata.size} bytes used`,
+    );
+  } catch (error) {
+    console.error(
+      `Failed to get metadata for ${mp.mountPoint}:`,
+      error.message,
+    );
+  }
+}
+```
+
+## Platform-Specific Examples
+
+### Windows: List Drive Letters
+
+```typescript
+import { getVolumeMountPoints } from "@photostructure/fs-metadata";
+
+const volumes = await getVolumeMountPoints();
+const driveLetters = volumes
+  .filter((v) => v.status === "healthy")
+  .map((v) => v.mountPoint)
+  .filter((mp) => /^[A-Z]:\\$/.test(mp))
+  .sort();
+
+console.log("Available drives:", driveLetters);
+// Output: ["C:\\", "D:\\", "E:\\"]
+```
+
+### Linux: Filter System Volumes
+
+```typescript
+import { getAllVolumeMetadata } from "@photostructure/fs-metadata";
+
+// Get only user-accessible volumes (excludes /proc, /sys, etc.)
+const userVolumes = await getAllVolumeMetadata({
+  includeSystemVolumes: false,
+});
+
+// Custom filtering for specific filesystem types
+const dataVolumes = userVolumes.filter((v) =>
+  ["ext4", "xfs", "btrfs", "zfs"].includes(v.fstype),
+);
+```
+
+### macOS: APFS Volumes
+
+```typescript
+import { getAllVolumeMetadata } from "@photostructure/fs-metadata";
+
+const volumes = await getAllVolumeMetadata();
+
+// Find APFS volumes
+const apfsVolumes = volumes.filter((v) => v.fstype === "apfs");
+
+// APFS containers share space, so available space might be the same
+const containers = new Map();
+for (const vol of apfsVolumes) {
+  const key = `${vol.size}-${vol.available}`;
+  if (!containers.has(key)) {
+    containers.set(key, []);
+  }
+  containers.get(key).push(vol.mountPoint);
+}
+```
+
+## Debug Logging
+
+```typescript
+// Enable debug logging before importing
+process.env.NODE_DEBUG = "fs-meta";
+
+import { getVolumeMetadata } from "@photostructure/fs-metadata";
+
+// Now operations will log debug information to stderr
+const metadata = await getVolumeMetadata("/");
+// Debug output includes native code operations and timing information
+```