@photostructure/fs-metadata 0.8.1 → 1.0.0

package/CHANGELOG.md

@@ -14,6 +14,28 @@ Fixed for any bug fixes.
 Security in case of vulnerabilities.
 -->
 
+## 1.0.0 - 2026-02-23
+
+### Security
+
+- Windows: add `/NXCOMPAT` (DEP) and `/HIGHENTROPYVA` (x64 high-entropy ASLR) linker flags
+- Windows: add `WarningLevel: 4` as structured MSBuild property on x64 and ARM64 targets (avoids `/W` flag ordering conflicts with node-gyp defaults)
+- Linux/macOS: add `-D_FORTIFY_SOURCE=2` and `-Wformat-security` compiler flags
+- Linux x64: add `-fcf-protection=full` (Intel CET); Linux ARM64: add `-mbranch-protection=standard` (PAC+BTI)
+
+## 0.9.0 - 2025-12-28
+
+### Added
+
+- New `networkFsTypes` option for configuring network filesystem detection
+- `NetworkFsTypesDefault` and `SkipNetworkVolumesDefault` exports
+
+### Changed
+
+- Expanded `SystemFsTypesDefault` with `bpf`, `tracefs`, `nsfs`, `ramfs`, `rpc_pipefs`, `fuse.lxcfs`, `fuse.portal`
+- Expanded `SystemPathPatternsDefault` with macOS metadata paths, kubelet, LXC/LXD, Flatpak paths
+- `isRemoteFsType()` and `extractRemoteInfo()` accept optional `networkFsTypes` parameter
+
 ## 0.8.1 - 2025-12-28
 
 ### Changed
@@ -104,9 +126,9 @@ Security in case of vulnerabilities.
 
 - `Packaging`: Improved ESM/CJS support with common `__dirname` implementation thanks to `tsup` [shims](https://tsup.egoist.dev/#inject-cjs-and-esm-shims).
 
-  This change simplifies the implementation and improves inline jsdocs as the exported code and docs have been inlined.
+  This change simplifies the implementation and improves inline js docs as the exported code and docs have been inlined.
 
-- `Packaging`: Re-enabled test coverage assertions (after finding the magicks to get istanbul to see what the tests were exercising)
+- `Packaging`: Re-enabled test coverage assertions (after finding the magics to get istanbul to see what the tests were exercising)
 
 - `Packaging`: Added debuglog tests
 

package/README.md

@@ -1,4 +1,4 @@
-![PhotoStructure fs-metadata logo](https://raw.githubusercontent.com/photostructure/fs-metadata/main/doc/logo.svg)
+<img src="https://raw.githubusercontent.com/photostructure/fs-metadata/main/doc/logo.svg" alt="PhotoStructure fs-metadata logo" width="200">
 
 Cross-platform native Node.js module for filesystem metadata, mount points, and volume information. Built for and supported by [PhotoStructure](https://photostructure.com).
 
@@ -7,7 +7,7 @@ Cross-platform native Node.js module for filesystem metadata, mount points, and
 [![Node-API v9 Badge](https://raw.githubusercontent.com/nodejs/abi-stable-node/refs/heads/doc/assets/Node-API%20v9%20Badge.svg)](https://nodejs.org/dist/latest/docs/api/n-api.html#node-api-version-matrix)
 [![View on GitHub](https://img.shields.io/badge/View%20on-GitHub-blue)](https://github.com/photostructure/fs-metadata)
 
-## Quick Start
+## Quick start
 
 ```bash
 npm install @photostructure/fs-metadata
@@ -28,14 +28,14 @@ const metadata = await getVolumeMetadata("/");
 console.log(metadata);
 ```
 
-## Key Features
+## Features
 
-- **Volume Management**: List mount points, get volume metadata, space usage
-- **Hidden Files**: Get/set hidden attributes, recursive checks, cross-platform support
+- **Volume management**: List mount points, get volume metadata, space usage
+- **Hidden files**: Get/set hidden attributes, recursive checks, cross-platform support
 - **Performance**: Non-blocking async operations with timeout protection
-- **TypeScript**: Full type definitions with ESM and CommonJS support
+- **TypeScript**: Type definitions with ESM and CommonJS support
 
-## Supported Platforms
+## Supported platforms
 
 | Platform      | Architecture | Node.js | OS Version                |
 | ------------- | ------------ | ------- | ------------------------- |
@@ -48,6 +48,7 @@ console.log(metadata);
 
 ## Documentation
 
+- [Security reporting](./SECURITY.md) - How to report security issues
 - [API Reference](https://photostructure.github.io/fs-metadata/modules.html)
 - [Examples](./doc/examples.md) - Common usage patterns and recipes
 - [Gotchas](./doc/gotchas.md) - Platform quirks, timeouts, and troubleshooting
@@ -59,3 +60,7 @@ console.log(metadata);
 - **Timeouts**: Configure [timeout duration](https://photostructure.github.io/fs-metadata/functions/getTimeoutMsDefault.html) for slow devices
   - Set `FS_METADATA_TIMEOUT_MS` environment variable to override the default (5000ms)
 - **System Volumes**: Control [system volume filtering](https://photostructure.github.io/fs-metadata/interfaces/Options.html)
+
+## Development
+
+Development of this library was assisted by AI coding tools. All changes are human-reviewed and tested.

package/binding.gyp

@@ -31,13 +31,33 @@
               "-lblkid"
             ],
             "cflags": [
-              "-fPIC"
+              "-fPIC",
+              "-fstack-protector-strong",
+              "-D_FORTIFY_SOURCE=2",
+              "-Wformat-security"
             ],
             "cflags_cc": [
               "-fexceptions",
-              "-fPIC"
+              "-fPIC",
+              "-fstack-protector-strong",
+              "-D_FORTIFY_SOURCE=2",
+              "-Wformat-security"
             ],
             "conditions": [
+              [
+                "target_arch=='x64'",
+                {
+                  "cflags": ["-fcf-protection=full"],
+                  "cflags_cc": ["-fcf-protection=full"]
+                }
+              ],
+              [
+                "target_arch=='arm64'",
+                {
+                  "cflags": ["-mbranch-protection=standard"],
+                  "cflags_cc": ["-mbranch-protection=standard"]
+                }
+              ],
               [
                 "enable_gio=='true'",
                 {
@@ -86,6 +106,7 @@
                   ],
                   "msvs_settings": {
                     "VCCLCompilerTool": {
+                      "WarningLevel": 4,
                       "AdditionalOptions": [
                         "/Qspectre",
                         "/guard:cf",
@@ -99,6 +120,8 @@
                       "AdditionalOptions": [
                         "/guard:cf",
                         "/DYNAMICBASE",
+                        "/HIGHENTROPYVA",
+                        "/NXCOMPAT",
                         "/CETCOMPAT"
                       ]
                     }
@@ -116,6 +139,7 @@
                   ],
                   "msvs_settings": {
                     "VCCLCompilerTool": {
+                      "WarningLevel": 4,
                       "AdditionalOptions": [
                         "/guard:cf",     # Control Flow Guard (supported on ARM64)
                         "/ZH:SHA_256",   # SHA-256 hash algorithm for checksums
@@ -131,38 +155,14 @@
                     "VCLinkerTool": {
                       "AdditionalOptions": [
                         "/guard:cf",      # Control Flow Guard at link time
-                        "/DYNAMICBASE"    # ASLR (Address Space Layout Randomization)
-                        # NOTE: /CETCOMPAT omitted - Intel CET is x64-specific
+                        "/DYNAMICBASE",   # ASLR (Address Space Layout Randomization)
+                        "/NXCOMPAT"       # DEP (Data Execution Prevention)
+                        # NOTE: /HIGHENTROPYVA and /CETCOMPAT are x64-specific
                         #       ARM64 has equivalent hardware security features
                       ]
                     }
                   }
                 }
-              ],
-              [
-                "target_arch=='ia32'",
-                {
-                  "defines": [
-                    "_M_IX86"
-                  ],
-                  "msvs_settings": {
-                    "VCCLCompilerTool": {
-                      "AdditionalOptions": [
-                        "/guard:cf",
-                        "/ZH:SHA_256",
-                        "/sdl"
-                      ],
-                      "ExceptionHandling": 1,
-                      "RuntimeTypeInfo": "true"
-                    },
-                    "VCLinkerTool": {
-                      "AdditionalOptions": [
-                        "/guard:cf",
-                        "/DYNAMICBASE"
-                      ]
-                    }
-                  }
-                }
               ]
             ]
           }
@@ -179,14 +179,25 @@
               "CLANG_CXX_LANGUAGE_STANDARD": "c++17",
               "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
               "CLANG_CXX_LIBRARY": "libc++",
-              "MACOSX_DEPLOYMENT_TARGET": "10.15"
+              "MACOSX_DEPLOYMENT_TARGET": "10.15",
+              "OTHER_CFLAGS": [
+                "-fstack-protector-strong",
+                "-D_FORTIFY_SOURCE=2",
+                "-Wformat-security"
+              ]
             },
             "cflags": [
               "-fexceptions",
-              "-fPIC"
+              "-fPIC",
+              "-fstack-protector-strong",
+              "-D_FORTIFY_SOURCE=2",
+              "-Wformat-security"
             ],
             "cflags_cc": [
-              "-fexceptions"
+              "-fexceptions",
+              "-fstack-protector-strong",
+              "-D_FORTIFY_SOURCE=2",
+              "-Wformat-security"
             ],
             "link_settings": {
               "libraries": [

package/claude.sh

@@ -12,7 +12,10 @@ claude --append-system-prompt "$(
 # MANDATORY GUIDELINES
 - **Study your CLAUDE.md** - Every conversation begins by studying CLAUDE.md
 - **Always Start By Reading** - You must study the referenced codebase and related documentation before making any change. NEVER assume APIs or implementation details.
-- **Assume Concurrent Edits** - STOP if build errors aren't from your changes
+- **Assume Concurrent Edits** - if you encounter a compilation error that you don't think you caused, **STOP immediately**, do not try to fix it blindly, **describe the error** to the user clearly, and **use AskUserQuestion** with these options:
+   - "Build is now fixed, continue"
+   - "Please fix the build and then continue"
+
 - **Validate your work** - Does your code compile? Can we clean up compilation warnings? Do the related tests pass?
 - **Don't use git checkout to undo changes** - Instead, re-apply your diff in reverse. You have to assume that the git tree was not clean when you made edits.
 - **Ask questions** - If anything is nebulous or unclear, it is IMPERATIVE that you ask clarifying questions to maximize velocity and avoid spurious work.

package/dist/index.cjs

@@ -32,7 +32,9 @@ var index_exports = {};
 __export(index_exports, {
   IncludeSystemVolumesDefault: () => IncludeSystemVolumesDefault,
   LinuxMountTablePathsDefault: () => LinuxMountTablePathsDefault,
+  NetworkFsTypesDefault: () => NetworkFsTypesDefault,
   OptionsDefault: () => OptionsDefault,
+  SkipNetworkVolumesDefault: () => SkipNetworkVolumesDefault,
   SystemFsTypesDefault: () => SystemFsTypesDefault,
   SystemPathPatternsDefault: () => SystemPathPatternsDefault,
   VolumeHealthStatuses: () => VolumeHealthStatuses,
@@ -628,6 +630,7 @@ var SystemPathPatternsDefault = [
   "/proc/**",
   "/run",
   "/run/credentials/**",
+  "/run/flatpak/**",
   "/run/lock",
   "/run/snapd/**",
   "/run/user/*/doc",
@@ -657,12 +660,21 @@ var SystemPathPatternsDefault = [
   // - Rootless and rootful container storage
   "/run/containers/**",
   "/var/lib/containers/**",
-  // windows for linux:
+  //
+  // Kubernetes: https://kubernetes.io/docs/reference/node/kubelet-files/
+  // - kubelet stores pod data, device plugins, and seccomp profiles
+  "/var/lib/kubelet/**",
+  //
+  // LXC/LXD: https://linuxcontainers.org/
+  // - Linux container storage and configuration
+  "/var/lib/lxc/**",
+  "/var/lib/lxd/**",
+  // WSL (Windows Subsystem for Linux):
   "/mnt/wslg/distro",
   "/mnt/wslg/doc",
   "/mnt/wslg/versions.txt",
   "/usr/lib/wsl/drivers",
-  // MacOS stuff:
+  // macOS system paths:
   "/private/var/vm",
   // macOS swap
   "/System/Volumes/Hardware",
@@ -672,11 +684,20 @@ var SystemPathPatternsDefault = [
   "/System/Volumes/Reserved",
   "/System/Volumes/Update",
   "/System/Volumes/VM",
-  "/System/Volumes/xarts"
+  "/System/Volumes/xarts",
+  // macOS per-volume metadata (Spotlight, FSEvents, versioning, Trash):
+  // https://eclecticlight.co/2021/01/28/spotlight-on-search-how-spotlight-works/
+  "**/.DocumentRevisions-V100",
+  "**/.fseventsd",
+  "**/.Spotlight-V100",
+  "**/.Trashes"
 ];
 var SystemFsTypesDefault = [
   "autofs",
   "binfmt_misc",
+  // BPF filesystem for persistent BPF objects
+  // https://docs.kernel.org/bpf/
+  "bpf",
   "cgroup",
   "cgroup2",
   "configfs",
@@ -685,24 +706,98 @@ var SystemFsTypesDefault = [
   "devtmpfs",
   "efivarfs",
   "fusectl",
+  // LXC container filesystem virtualization
+  // https://linuxcontainers.org/lxcfs/
+  "fuse.lxcfs",
+  // XDG Desktop Portal for Flatpak sandboxed app file access
+  // https://flatpak.github.io/xdg-desktop-portal/
+  "fuse.portal",
   "fuse.snapfuse",
   "hugetlbfs",
   "mqueue",
   "none",
+  // Linux namespace filesystem (internal kernel use)
+  // https://man7.org/linux/man-pages/man7/namespaces.7.html
+  "nsfs",
   "proc",
   "pstore",
+  // RAM-based filesystem (predecessor to tmpfs)
+  // https://www.kernel.org/doc/html/latest/filesystems/ramfs-rootfs-initramfs.html
+  "ramfs",
   "rootfs",
+  // NFS RPC communication pipe filesystem
+  // https://man7.org/linux/man-pages/man8/rpc.gssd.8.html
+  "rpc_pipefs",
   "securityfs",
   "snap*",
   "squashfs",
   "sysfs",
-  "tmpfs"
+  "tmpfs",
+  // Kernel function tracing filesystem
+  // https://www.kernel.org/doc/html/latest/trace/ftrace.html
+  "tracefs"
 ];
 var LinuxMountTablePathsDefault = [
   "/proc/self/mounts",
   "/proc/mounts",
   "/etc/mtab"
 ];
+var NetworkFsTypesDefault = [
+  // Plan 9 filesystem (VM host-guest, also network)
+  // https://www.kernel.org/doc/html/latest/filesystems/9p.html
+  "9p",
+  // Apple Filing Protocol (legacy macOS/netatalk)
+  "afp",
+  // Andrew File System (distributed) - not to be confused with Apple's APFS
+  // https://www.openafs.org/
+  "afs",
+  // BeeGFS parallel filesystem (HPC)
+  // https://www.beegfs.io/
+  "beegfs",
+  // Ceph distributed filesystem
+  // https://docs.ceph.com/
+  "ceph",
+  // Windows/Samba shares (SMB/CIFS)
+  // https://www.samba.org/
+  "cifs",
+  // FTP filesystem mount
+  "ftp",
+  // Generic FUSE (often remote, treated conservatively)
+  "fuse",
+  // rclone cloud storage mount (Google Drive, S3, etc.)
+  // https://rclone.org/commands/rclone_mount/
+  "fuse.rclone",
+  // Amazon S3 FUSE mount
+  // https://github.com/s3fs-fuse/s3fs-fuse
+  "fuse.s3fs",
+  // SSH filesystem
+  // https://github.com/libfuse/sshfs
+  "fuse.sshfs",
+  // Red Hat Global File System (cluster)
+  "gfs",
+  "gfs2",
+  // GlusterFS distributed filesystem
+  // https://www.gluster.org/
+  "glusterfs",
+  // Lustre parallel filesystem (HPC)
+  // https://www.lustre.org/
+  "lustre",
+  // Novell NetWare (legacy)
+  "ncpfs",
+  "ncp",
+  // Network File System
+  // https://man7.org/linux/man-pages/man5/nfs.5.html
+  "nfs",
+  "nfs4",
+  // SMB filesystem
+  "smb",
+  "smbfs",
+  // SSH filesystem (non-FUSE variant)
+  "sshfs",
+  // WebDAV filesystem
+  // https://savannah.nongnu.org/projects/davfs2
+  "webdav"
+];
 var IncludeSystemVolumesDefault = isWindows;
 var SkipNetworkVolumesDefault = false;
 var OptionsDefault = {
@@ -711,6 +806,7 @@ var OptionsDefault = {
   systemPathPatterns: [...SystemPathPatternsDefault],
   systemFsTypes: [...SystemFsTypesDefault],
   linuxMountTablePaths: [...LinuxMountTablePathsDefault],
+  networkFsTypes: [...NetworkFsTypesDefault],
   includeSystemVolumes: IncludeSystemVolumesDefault,
   skipNetworkVolumes: SkipNetworkVolumesDefault
 };
@@ -835,38 +931,15 @@ function isRemoteInfo(obj) {
   const { remoteHost, remoteShare } = obj;
   return isNotBlank(remoteHost) && isNotBlank(remoteShare);
 }
-var NETWORK_FS_TYPE_ARRAY = [
-  "9p",
-  "afp",
-  "afs",
-  "beegfs",
-  "ceph",
-  "cifs",
-  "ftp",
-  "fuse",
-  "gfs2",
-  "glusterfs",
-  "lustre",
-  "ncpfs",
-  "nfs",
-  "nfs4",
-  "smb",
-  "smbfs",
-  "sshfs",
-  "webdav"
-];
-var NETWORK_FS_TYPES = new Set(NETWORK_FS_TYPE_ARRAY);
 var FS_TYPE_ALIASES = /* @__PURE__ */ new Map([
   ["nfs1", "nfs"],
   ["nfs2", "nfs"],
   ["nfs3", "nfs"],
-  ["nfs4", "nfs4"],
   ["fuse.sshfs", "sshfs"],
   ["sshfs.fuse", "sshfs"],
   ["davfs2", "webdav"],
   ["davfs", "webdav"],
   ["cifs.smb", "cifs"],
-  ["smbfs", "cifs"],
   ["cephfs", "ceph"],
   ["fuse.ceph", "ceph"],
   ["fuse.cephfs", "ceph"],
@@ -877,8 +950,12 @@ function normalizeFsType(fstype) {
   const norm = toS(fstype).toLowerCase().replace(/:$/, "");
   return FS_TYPE_ALIASES.get(norm) ?? norm;
 }
-function isRemoteFsType(fstype) {
-  return isNotBlank(fstype) && NETWORK_FS_TYPES.has(normalizeFsType(fstype));
+function isRemoteFsType(fstype, networkFsTypes = NetworkFsTypesDefault) {
+  if (!isNotBlank(fstype)) return false;
+  const normalized = normalizeFsType(fstype);
+  return networkFsTypes.some(
+    (nft) => nft === normalized || normalized.startsWith(nft + ".")
+  );
 }
 function parseURL(s) {
   try {
@@ -887,7 +964,7 @@ function parseURL(s) {
     return;
   }
 }
-function extractRemoteInfo(fsSpec) {
+function extractRemoteInfo(fsSpec, networkFsTypes = NetworkFsTypesDefault) {
   if (fsSpec == null || isBlank(fsSpec)) return;
   if (isWindows) {
     fsSpec = fsSpec.replace(/\\/g, "/");
@@ -936,7 +1013,7 @@ function extractRemoteInfo(fsSpec) {
     if (parsed != null) {
       debug("[extractRemoteInfo] parsed URL: %o", parsed);
       const fstype = normalizeFsType(parsed.protocol);
-      if (!isRemoteFsType(fstype)) {
+      if (!isRemoteFsType(fstype, networkFsTypes)) {
         return {
           uri: fsSpec,
           remote: false
@@ -1089,6 +1166,7 @@ function mountEntryToMountPoint(entry) {
   };
 }
 function mountEntryToPartialVolumeMetadata(entry, options = {}) {
+  const networkFsTypes = options.networkFsTypes ?? NetworkFsTypesDefault;
   return {
     mountPoint: entry.fs_file,
     fstype: entry.fs_vfstype,
@@ -1096,7 +1174,7 @@ function mountEntryToPartialVolumeMetadata(entry, options = {}) {
     isSystemVolume: isSystemVolume(entry.fs_file, entry.fs_vfstype, options),
     remote: false,
     // < default to false, but it may be overridden by extractRemoteInfo
-    ...extractRemoteInfo(entry.fs_spec)
+    ...extractRemoteInfo(entry.fs_spec, networkFsTypes)
   };
 }
 function parseMtab(content) {
@@ -1348,9 +1426,9 @@ async function _getVolumeMetadata(o, nativeFn2) {
   debug("[getVolumeMetadata] requesting native metadata");
   const metadata = await (await nativeFn2()).getVolumeMetadata(o);
   debug("[getVolumeMetadata] native metadata: %o", metadata);
-  const remoteInfo = mtabInfo ?? extractRemoteInfo(metadata.uri) ?? extractRemoteInfo(metadata.mountFrom) ?? (isWindows ? parseUNCPath(o.mountPoint) : void 0);
+  const remoteInfo = mtabInfo ?? extractRemoteInfo(metadata.uri, o.networkFsTypes) ?? extractRemoteInfo(metadata.mountFrom, o.networkFsTypes) ?? (isWindows ? parseUNCPath(o.mountPoint) : void 0);
   debug("[getVolumeMetadata] extracted remote info: %o", remoteInfo);
-  remote ||= isRemoteFsType(metadata.fstype) || (remoteInfo?.remote ?? metadata.remote ?? false);
+  remote ||= isRemoteFsType(metadata.fstype, o.networkFsTypes) || (remoteInfo?.remote ?? metadata.remote ?? false);
   debug("[getVolumeMetadata] assembling: %o", {
     status,
     mtabInfo,
@@ -1478,7 +1556,9 @@ function setHidden(pathname, hidden, method = "auto") {
 0 && (module.exports = {
   IncludeSystemVolumesDefault,
   LinuxMountTablePathsDefault,
+  NetworkFsTypesDefault,
   OptionsDefault,
+  SkipNetworkVolumesDefault,
   SystemFsTypesDefault,
   SystemPathPatternsDefault,
   VolumeHealthStatuses,