@photostructure/fs-metadata 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -14,6 +14,25 @@ Fixed for any bug fixes.
 Security in case of vulnerabilities.
 -->
 
+## 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
+
+- Added container runtime paths to the default set of system paths. See SystemPathPatternsDefault
+
 ## 0.8.0 - 2025-12-01
 
 ### Added
@@ -98,9 +117,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,6 +1,6 @@
 ![PhotoStructure fs-metadata logo](https://raw.githubusercontent.com/photostructure/fs-metadata/main/doc/logo.svg)
 
-Cross-platform native Node.js module for filesystem metadata, mount points, and volume information.
+Cross-platform native Node.js module for filesystem metadata, mount points, and volume information. Built for and supported by [PhotoStructure](https://photostructure.com).
 
 [![npm version](https://img.shields.io/npm/v/@photostructure/fs-metadata.svg)](https://www.npmjs.com/package/@photostructure/fs-metadata)
 [![Build](https://github.com/photostructure/fs-metadata/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/photostructure/fs-metadata/actions/workflows/build.yml)
@@ -48,10 +48,11 @@ console.log(metadata);
 
 ## Documentation
 
-- 📖 [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
-- 🔧 [Contributing](./CONTRIBUTING.md) - Build instructions and development guide
+- [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
+- [Contributing](./CONTRIBUTING.md) - Build instructions and development guide
 
 ### Options
 
@@ -60,10 +61,6 @@ console.log(metadata);
   - 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)
 
-## Support
+## Development
 
-Built and supported by [PhotoStructure](https://photostructure.com)
-
-- [GitHub Issues](https://github.com/photostructure/fs-metadata/issues)
-- [Security Policy](./SECURITY.md)
-- [MIT License](./LICENSE.txt)
+Development of this library was assisted by AI coding tools. All changes are human-reviewed and tested.

package/binding.gyp

@@ -31,11 +31,13 @@
               "-lblkid"
             ],
             "cflags": [
-              "-fPIC"
+              "-fPIC",
+              "-fstack-protector-strong"
             ],
             "cflags_cc": [
               "-fexceptions",
-              "-fPIC"
+              "-fPIC",
+              "-fstack-protector-strong"
             ],
             "conditions": [
               [
@@ -179,14 +181,19 @@
               "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"
+              ]
             },
             "cflags": [
               "-fexceptions",
-              "-fPIC"
+              "-fPIC",
+              "-fstack-protector-strong"
             ],
             "cflags_cc": [
-              "-fexceptions"
+              "-fexceptions",
+              "-fstack-protector-strong"
             ],
             "link_settings": {
               "libraries": [

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",
@@ -639,12 +642,39 @@ var SystemPathPatternsDefault = [
   // we aren't including /tmp/**, as some people temporarily mount volumes there, like /tmp/project.
   "**/#snapshot",
   // Synology and Kubernetes volume snapshots
-  // windows for linux:
+  // 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/**",
+  //
+  // 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",
@@ -654,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",
@@ -667,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 = {
@@ -693,6 +806,7 @@ var OptionsDefault = {
   systemPathPatterns: [...SystemPathPatternsDefault],
   systemFsTypes: [...SystemFsTypesDefault],
   linuxMountTablePaths: [...LinuxMountTablePathsDefault],
+  networkFsTypes: [...NetworkFsTypesDefault],
   includeSystemVolumes: IncludeSystemVolumesDefault,
   skipNetworkVolumes: SkipNetworkVolumesDefault
 };
@@ -817,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"],
@@ -859,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 {
@@ -869,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, "/");
@@ -918,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
@@ -1071,6 +1166,7 @@ function mountEntryToMountPoint(entry) {
   };
 }
 function mountEntryToPartialVolumeMetadata(entry, options = {}) {
+  const networkFsTypes = options.networkFsTypes ?? NetworkFsTypesDefault;
   return {
     mountPoint: entry.fs_file,
     fstype: entry.fs_vfstype,
@@ -1078,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) {
@@ -1330,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,
@@ -1460,7 +1556,9 @@ function setHidden(pathname, hidden, method = "auto") {
 0 && (module.exports = {
   IncludeSystemVolumesDefault,
   LinuxMountTablePathsDefault,
+  NetworkFsTypesDefault,
   OptionsDefault,
+  SkipNetworkVolumesDefault,
   SystemFsTypesDefault,
   SystemPathPatternsDefault,
   VolumeHealthStatuses,