@zenfs/core 2.7.0 → 2.7.2

package/README.md

@@ -43,6 +43,9 @@ Your financial support would go a long way toward improving ZenFS and its commun
 
 ## Usage
 
+> [!IMPORTANT]
+> **[Check out the ZenFS docs!](https://zenfs.dev/start/usage/)**
+
 ```js
 import { fs } from '@zenfs/core'; // You can also use the default export
 
@@ -52,15 +55,9 @@ const contents = fs.readFileSync('/test.txt', 'utf-8');
 console.log(contents);
 ```
 
-#### Using different and/or multiple backends
-
-A single `InMemory` backend is created by default, mounted on `/`.
-
-You can configure ZenFS to use a different backend and mount multiple backends. It is strongly recommended to do so using the `configure` function.
-
-You can use multiple backends by passing an object to `configure` which maps paths to file systems.
-
-The following example mounts a zip file to `/zip`, in-memory storage to `/tmp`, and IndexedDB to `/home`. Note that `/` has the default in-memory backend.
+A single `InMemory` backend is created by default, mounted on `/`. To use different backends, and to
+mount more than one, configure ZenFS with `configure`. This mounts a zip file to `/mnt/zip`,
+in-memory storage to `/tmp`, and IndexedDB to `/home`:
 
 ```js
 import { configure, InMemory } from '@zenfs/core';
@@ -78,110 +75,16 @@ await configure({
 });
 ```
 
-Note that while you aren't required to use absolute paths for the keys of `mounts`, it is a good practice to do so.
-
-> [!TIP]
-> When configuring a mount point, you can pass in
->
-> 1. A `Backend` object, if the backend has no required options
-> 2. An object that has the options accepted by the backend and a `backend` property which is a `Backend` object
-> 3. A `FileSystem` instance
-
-Here is an example that mounts the `WebStorage` backend from `@zenfs/dom` on `/`:
-
-```js
-import { configureSingle, fs } from '@zenfs/core';
-import { WebStorage } from '@zenfs/dom';
-
-await configureSingle({ backend: WebStorage });
-
-if (!fs.existsSync('/test.txt')) {
-	fs.writeFileSync('/test.txt', 'This will persist across reloads!');
-}
-
-const contents = fs.readFileSync('/test.txt', 'utf-8');
-console.log(contents);
-```
-
-#### FS Promises
-
-The FS promises API is exposed as `promises`.
-
-```js
-import { configureSingle } from '@zenfs/core';
-import { exists, writeFile } from '@zenfs/core/promises';
-import { IndexedDB } from '@zenfs/dom';
-
-await configureSingle({ backend: IndexedDB });
-
-const exists = await exists('/myfile.txt');
-if (!exists) {
-	await writeFile('/myfile.txt', 'Lots of persistent data');
-}
-```
-
-> [!NOTE]
-> You can import the promises API using:
->
-> 1. Exports from `@zenfs/core/promises`
-> 2. The `promises` export from `@zenfs/core`
-> 3. `fs.promises` on the exported `fs` from `@zenfs/core`.
+The `fs/promises` API is available from `@zenfs/core/promises`, as the `promises` export, or as
+`fs.promises`.
 
-#### Mounting and unmounting, creating backends
-
-If you would like to create backends without configure (e.g. to do something dynamic at runtime), you may do so by importing the backend and calling `resolveMountConfig` with it.
-
-You can then mount and unmount the backend instance by using `mount` and `umount`.
-
-```js
-import { configure, resolveMountConfig, InMemory } from '@zenfs/core';
-import { IndexedDB } from '@zenfs/dom';
-import { Zip } from '@zenfs/archives';
-
-await configure({
-	mounts: {
-		'/tmp': InMemory,
-		'/home': IndexedDB,
-	},
-});
-
-fs.mkdirSync('/mnt/zip', { recursive: true });
-
-const res = await fetch('mydata.zip');
-const zipfs = await resolveMountConfig({ backend: Zip, data: await res.arrayBuffer() });
-fs.mount('/mnt/zip', zipfs);
-
-// do stuff with the mounted zip
-
-fs.umount('/mnt/zip'); // finished using the zip
-```
-
-> [!CAUTION]
-> Instances of backends follow the _internal_ API. You should never use a backend's methods unless you are extending a backend.
-
-### Devices and device files
-
-ZenFS includes support for device files. These are designed to follow Linux's device file behavior, for consistency and ease of use. Check out the [Devices and Device Drivers](https://zenfs.dev/core/documents/Devices_and_Device_Drivers) documentation for more information.
-
-## `node:*` emulation
-
-ZenFS also includes emulation of some other `node:` modules for various reasons, importable from `@zenfs/core/<name>`:
-
-- `node:path`
-- `node:readline`
-
-For example:
-
-```ts
-import * as path from '@zenfs/core/path';
-```
+For the full usage guide, see **[the documentation](https://zenfs.dev/start/usage/)**.
+This includes mounting at runtime, contexts and permissions, devices, and the `node:*`module emulation.
 
 ## Bundling
 
 ZenFS exports a drop-in for Node's `fs` module, so you can use it for your bundler of preference using the default export.
-
-> [!IMPORTANT]
-> See [COPYING.md](./COPYING.md)
+See [COPYING.md](./COPYING.md) for more info.
 
 ## Sponsors
 

package/dist/config.d.ts

@@ -56,6 +56,8 @@ export interface Configuration<T extends ConfigMounts> extends SharedConfig {
     /**
      * Whether to automatically add normal Linux devices
      * @default false
+     * @deprecated Use `@zenfs/linux`!
+     * @todo [breaking] remove
      */
     addDevices: boolean;
     /**
@@ -97,6 +99,8 @@ export declare function configureSingle<T extends Backend>(configuration: MountC
 export declare function configureSingleSync<T extends Backend>(configuration: MountConfiguration<T>): void;
 /**
  * @category Backends and Configuration
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare function addDevice(driver: DeviceDriver, options?: object): Device;
 /**

package/dist/config.js

@@ -189,6 +189,8 @@ function mountWithMkdirSync(path, fs) {
 }
 /**
  * @category Backends and Configuration
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export function addDevice(driver, options) {
     const devfs = defaultContext.mounts.get('/dev');

package/dist/context.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 import { UV } from 'kerium';
 import { bindFunctions } from 'utilium';
-import { contextOf, createChildContext } from './internal/contexts.js';
+import { contextOf, createChildContext, defaultContext } from './internal/contexts.js';
 import * as fs from './node/index.js';
 import * as path from './path.js';
 import * as xattr from './vfs/xattr.js';
@@ -17,9 +17,9 @@ export const boundContexts = new Map();
  * @category Contexts
  */
 export function bindContext(init = {}) {
-    const $ = contextOf(this);
-    if (!fs.statSync.call(this, $.root).isDirectory())
-        throw UV('ENOTDIR', { syscall: 'chroot', path: $.root });
+    const $ = contextOf(this), parent = $.parent || defaultContext;
+    if (!fs.statSync.call(parent, parent.root).isDirectory())
+        throw UV('ENOTDIR', { syscall: 'chroot', path: parent.root });
     const ctx = createChildContext($, init);
     const bound = Object.assign(ctx, {
         fs: {

package/dist/internal/contexts.js

@@ -46,7 +46,7 @@ let _nextId = 2;
  */
 export function createChildContext(parent, init = {}) {
     assertContext(parent);
-    const { root = parent.root, pwd = parent.pwd, credentials = structuredClone(parent.credentials), mounts = Object.fromEntries(parent.mounts), } = init;
+    const { root = parent.root, pwd = parent.pwd, credentials = structuredClone(parent.credentials), mounts } = init;
     const ctx = {
         [kIsContext]: true,
         id: _nextId++,
@@ -56,7 +56,7 @@ export function createChildContext(parent, init = {}) {
         descriptors: new Map(),
         parent: parent,
         children: [],
-        mounts: new Map(Object.entries(mounts)),
+        mounts: mounts ? new Map(Object.entries(mounts)) : parent.mounts,
     };
     Object.defineProperties(ctx, {
         id: { configurable: false, writable: false },

package/dist/internal/devices.d.ts

@@ -4,10 +4,11 @@ import type { CreationOptions } from './filesystem.js';
 import { Inode, type InodeLike } from './inode.js';
 /**
  * A device
- * @todo Maybe add some other device information, like a UUID?
  * @category Internals
  * @privateRemarks
  * UUIDs were considered, however they don't make sense without an easy mechanism for persistence
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export interface Device<TData = any> {
     /**
@@ -34,6 +35,8 @@ export interface Device<TData = any> {
 }
 /**
  * @category Internals
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export interface DeviceInit<TData = any> {
     data?: TData;
@@ -45,6 +48,8 @@ export interface DeviceInit<TData = any> {
 /**
  * A device driver
  * @category Internals
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export interface DeviceDriver<TData = any> {
     /**
@@ -88,6 +93,8 @@ export interface DeviceDriver<TData = any> {
 /**
  * A temporary file system that manages and interfaces with devices
  * @category Internals
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare class DeviceFS extends StoreFS<InMemoryStore> {
     protected readonly devices: Map<string, Device<any>>;
@@ -132,6 +139,8 @@ export declare class DeviceFS extends StoreFS<InMemoryStore> {
  * - Writes discard data, advancing the file position.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const nullDevice: DeviceDriver;
 /**
@@ -144,6 +153,8 @@ export declare const nullDevice: DeviceDriver;
  * - Provides basic file metadata, treating it as a character device.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const zeroDevice: DeviceDriver;
 /**
@@ -152,6 +163,8 @@ export declare const zeroDevice: DeviceDriver;
  * - Writes always fail with ENOSPC (no space left on device).
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const fullDevice: DeviceDriver;
 /**
@@ -160,12 +173,16 @@ export declare const fullDevice: DeviceDriver;
  * - Writes discard data, advancing the file position.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const randomDevice: DeviceDriver;
 /**
  * Shortcuts for importing.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const devices: {
     null: DeviceDriver<any>;

package/dist/internal/devices.js

@@ -13,6 +13,8 @@ import { Inode } from './inode.js';
 /**
  * A temporary file system that manages and interfaces with devices
  * @category Internals
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export class DeviceFS extends StoreFS {
     devices = new Map();
@@ -231,6 +233,8 @@ const emptyBuffer = new Uint8Array();
  * - Writes discard data, advancing the file position.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const nullDevice = {
     name: 'null',
@@ -255,6 +259,8 @@ export const nullDevice = {
  * - Provides basic file metadata, treating it as a character device.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const zeroDevice = {
     name: 'zero',
@@ -275,6 +281,8 @@ export const zeroDevice = {
  * - Writes always fail with ENOSPC (no space left on device).
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const fullDevice = {
     name: 'full',
@@ -295,6 +303,8 @@ export const fullDevice = {
  * - Writes discard data, advancing the file position.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const randomDevice = {
     name: 'random',
@@ -315,6 +325,8 @@ export const randomDevice = {
  * Simulates the `/dev/console` device.
  * @category Internals
  * @experimental @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 const consoleDevice = {
     name: 'console',
@@ -334,6 +346,8 @@ const consoleDevice = {
  * Shortcuts for importing.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const devices = {
     null: nullDevice,

package/dist/internal/inode.js

@@ -642,8 +642,10 @@ export function isFIFO(metadata) {
  */
 export function hasAccess($, inode, access) {
     const { credentials } = contextOf($);
-    if (isSymbolicLink(inode) || credentials.euid === 0 || credentials.egid === 0)
+    if (isSymbolicLink(inode))
         return true;
+    if (credentials.euid === 0 || credentials.egid === 0)
+        return !(access & c.X_OK) || isDirectory(inode) || !!(inode.mode & (c.S_IXUSR | c.S_IXGRP | c.S_IXOTH));
     let perm = 0;
     if (credentials.uid === inode.uid) {
         if (inode.mode & c.S_IRUSR)

package/dist/node/async.js

@@ -328,7 +328,7 @@ export function access(path, cbMode, cb = nop) {
 access;
 const statWatchers = new Map();
 export function watchFile(path, options, listener) {
-    const normalizedPath = normalizePath(path);
+    const normalizedPath = normalizePath.call(this, path);
     const opts = typeof options != 'function' ? options : {};
     if (typeof options == 'function') {
         listener = options;
@@ -365,7 +365,7 @@ watchFile;
  * @param listener Optional listener to remove.
  */
 export function unwatchFile(path, listener = nop) {
-    const normalizedPath = normalizePath(path);
+    const normalizedPath = normalizePath.call(this, path);
     const entry = statWatchers.get(normalizedPath);
     if (entry) {
         if (listener && listener !== nop) {
@@ -384,7 +384,7 @@ export function unwatchFile(path, listener = nop) {
 }
 unwatchFile;
 export function watch(path, options, listener) {
-    const watcher = new FSWatcher(this, normalizePath(path), typeof options == 'object' ? options : {});
+    const watcher = new FSWatcher(this, normalizePath.call(this, path), typeof options == 'object' ? options : {});
     listener = typeof options == 'function' ? options : listener;
     watcher.on('change', listener || nop);
     return watcher;

package/dist/node/promises.js

@@ -529,7 +529,7 @@ rename;
  * Test whether or not `path` exists by checking with the file system.
  */
 export async function exists(path) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     try {
         const { fs, path: resolved } = await _async.resolve(this, path);
         return await fs.exists(resolved);
@@ -579,7 +579,7 @@ truncate;
 export async function unlink(path) {
     const env_2 = { stack: [], error: void 0, hasError: false };
     try {
-        path = normalizePath(path);
+        path = normalizePath.call(this, path);
         const { fs, path: resolved } = resolveMount(path, this);
         const $ex = { syscall: 'unlink', path };
         const stats = await fs.stat(resolved).catch(rethrow($ex));
@@ -691,7 +691,7 @@ appendFile;
 export async function rmdir(path) {
     const env_6 = { stack: [], error: void 0, hasError: false };
     try {
-        path = normalizePath(path);
+        path = normalizePath.call(this, path);
         const { fs, path: resolved } = await _async.resolve(this, path);
         const $ex = { syscall: 'rmdir', path };
         const stats = await fs.stat(resolved).catch(rethrow($ex));
@@ -722,7 +722,7 @@ export async function mkdir(path, options) {
 }
 mkdir;
 export async function readdir(path, options) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const opt = typeof options === 'object' && options != null ? options : { encoding: options, withFileTypes: false, recursive: false };
     const rawEntries = await _async.readdir.call(this, path, opt);
     const values = [];
@@ -755,11 +755,11 @@ export async function symlink(dest, path, type = 'file') {
     try {
         if (!['file', 'dir', 'junction'].includes(type))
             throw new TypeError('Invalid symlink type: ' + type);
-        path = normalizePath(path);
+        path = normalizePath.call(this, path);
         if (await exists.call(this, path))
             throw UV('EEXIST', 'symlink', path);
         const handle = __addDisposableResource(env_7, await _async.open(this, path, { flag: 'w+', mode: 0o644, preserveSymlinks: true }), true);
-        const encoded = encodeUTF8(normalizePath(dest, true));
+        const encoded = encodeUTF8(normalizePath.call(this, dest, true));
         await handle.write(encoded, 0, encoded.length, 0);
         await handle.chmod(constants.S_IFLNK);
     }
@@ -775,7 +775,7 @@ export async function symlink(dest, path, type = 'file') {
 }
 symlink;
 export async function readlink(path, options) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const buf = Buffer.from(await _async.readlink.call(this, path), 'utf-8');
     const encoding = typeof options == 'object' ? options?.encoding : options;
     // always defaults to utf-8 to avoid wrangler (cloudflare) worker "unknown encoding" exception
@@ -824,7 +824,7 @@ lchown;
 export async function chmod(path, mode) {
     const env_10 = { stack: [], error: void 0, hasError: false };
     try {
-        const handle = __addDisposableResource(env_10, await open.call(this, path, 'r+').catch(rethrow({ syscall: 'chmod', path: normalizePath(path) })), true);
+        const handle = __addDisposableResource(env_10, await open.call(this, path, 'r+').catch(rethrow({ syscall: 'chmod', path: normalizePath.call(this, path) })), true);
         await handle.chmod(mode);
     }
     catch (e_10) {
@@ -911,7 +911,7 @@ export async function lutimes(path, atime, mtime) {
 lutimes;
 export async function realpath(path, options) {
     const encoding = typeof options == 'string' ? options : (options?.encoding ?? 'utf8');
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const { fullPath } = await _async.resolve(this, path);
     if (encoding == 'utf8' || encoding == 'utf-8')
         return fullPath;
@@ -976,7 +976,7 @@ access;
  * @param path The path to the file or directory to remove.
  */
 export async function rm(path, options) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const stats = await lstat.call(this, path).catch((error) => {
         if (error.code == 'ENOENT' && options?.force)
             return undefined;
@@ -1034,8 +1034,8 @@ export async function mkdtempDisposable(prefix, options) {
  *    * `fs.constants.COPYFILE_EXCL`: If the destination file already exists, the operation fails.
  */
 export async function copyFile(src, dest, mode) {
-    src = normalizePath(src);
-    dest = normalizePath(dest);
+    src = normalizePath.call(this, src);
+    dest = normalizePath.call(this, dest);
     if (mode && mode & constants.COPYFILE_EXCL && (await exists.call(this, dest)))
         throw UV('EEXIST', 'copyFile', dest);
     await writeFile.call(this, dest, await readFile.call(this, src));
@@ -1050,7 +1050,7 @@ copyFile;
  * @todo Use options
  */
 export function opendir(path, options) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     return Promise.resolve(new Dir(path, this));
 }
 opendir;
@@ -1067,8 +1067,8 @@ opendir;
  *   * `recursive`: If `true`, copies directories recursively.
  */
 export async function cp(source, destination, opts) {
-    source = normalizePath(source);
-    destination = normalizePath(destination);
+    source = normalizePath.call(this, source);
+    destination = normalizePath.call(this, destination);
     const srcStats = await lstat.call(this, source); // Use lstat to follow symlinks if not dereferencing
     if (opts?.errorOnExist && (await exists.call(this, destination)))
         throw UV('EEXIST', 'cp', destination);
@@ -1116,7 +1116,7 @@ export async function cp(source, destination, opts) {
 }
 cp;
 export async function statfs(path, opts) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const { fs } = resolveMount(path, this);
     return Promise.resolve(_statfs(fs, opts?.bigint));
 }

package/dist/node/sync.js

@@ -76,7 +76,7 @@ renameSync;
  * Test whether or not `path` exists by checking with the file system.
  */
 export function existsSync(path) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     try {
         const { fs, path: resolvedPath } = _sync.resolve(this, path);
         return fs.existsSync(resolvedPath);
@@ -133,7 +133,7 @@ export function truncateSync(path, len = 0) {
 }
 truncateSync;
 export function unlinkSync(path) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const { fs, path: resolved } = resolveMount(path, this);
     try {
         const env_2 = { stack: [], error: void 0, hasError: false };
@@ -250,7 +250,7 @@ export function appendFileSync(filename, data, _options = {}) {
     const encodedData = typeof data == 'string' ? Buffer.from(data, options.encoding) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
     const file = typeof filename == 'number'
         ? fromFD(this, filename)
-        : _sync.open(this, normalizePath(filename), {
+        : _sync.open(this, normalizePath.call(this, filename), {
             flag,
             mode: options.mode,
         });
@@ -354,7 +354,7 @@ futimesSync;
 export function rmdirSync(path) {
     const env_5 = { stack: [], error: void 0, hasError: false };
     try {
-        path = normalizePath(path);
+        path = normalizePath.call(this, path);
         const { fs, path: resolved } = _sync.resolve(this, path);
         const stats = wrap(fs, 'statSync', { path, syscall: 'rmdir' })(resolved);
         if (!isDirectory(stats))
@@ -383,7 +383,7 @@ export function mkdirSync(path, options) {
 mkdirSync;
 export function readdirSync(path, options) {
     options = typeof options === 'object' ? options : { encoding: options };
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const entries = [];
     const rawEntries = _sync.readdir.call(this, path, options ?? undefined);
     for (const raw of rawEntries) {
@@ -415,9 +415,9 @@ export function symlinkSync(target, path, type = 'file') {
     try {
         if (!['file', 'dir', 'junction'].includes(type))
             throw new TypeError('Invalid symlink type: ' + type);
-        path = normalizePath(path);
+        path = normalizePath.call(this, path);
         const file = __addDisposableResource(env_6, _sync.open(this, path, { flag: 'wx', mode: 0o644 }), false);
-        file.writeSync(encodeUTF8(normalizePath(target, true)));
+        file.writeSync(encodeUTF8(normalizePath.call(this, target, true)));
         file.chmodSync(constants.S_IFLNK);
     }
     catch (e_6) {
@@ -466,7 +466,7 @@ export function chmodSync(path, mode) {
         fd = openSync.call(this, path, 'r+');
     }
     catch (e) {
-        throw setUVMessage(Object.assign(e, { syscall: 'chmod', path: normalizePath(path) }));
+        throw setUVMessage(Object.assign(e, { syscall: 'chmod', path: normalizePath.call(this, path) }));
     }
     fchmodSync.call(this, fd, mode);
     closeSync.call(this, fd);
@@ -498,7 +498,7 @@ export function lutimesSync(path, atime, mtime) {
 lutimesSync;
 export function realpathSync(path, options) {
     const encoding = typeof options == 'string' ? options : (options?.encoding ?? 'utf8');
-    path = normalizePath(path, true);
+    path = normalizePath.call(this, path, true);
     const { fullPath } = _sync.resolve(this, path);
     if (encoding == 'utf8' || encoding == 'utf-8')
         return fullPath;
@@ -521,7 +521,7 @@ accessSync;
  * @param path The path to the file or directory to remove.
  */
 export function rmSync(path, options) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     let stats;
     try {
         stats = lstatSync.bind(this)(path);
@@ -580,8 +580,8 @@ export function mkdtempDisposableSync(prefix, options) {
  * - `fs.constants.COPYFILE_EXCL`: If the destination file already exists, the operation fails.
  */
 export function copyFileSync(source, destination, flags) {
-    source = normalizePath(source);
-    destination = normalizePath(destination);
+    source = normalizePath.call(this, source);
+    destination = normalizePath.call(this, destination);
     if (flags && flags & constants.COPYFILE_EXCL && existsSync.call(this, destination))
         throw UV('EEXIST', 'copyFile', destination);
     writeFileSync.call(this, destination, readFileSync.call(this, source));
@@ -628,7 +628,7 @@ writevSync;
  * @todo Handle options
  */
 export function opendirSync(path, options) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     return new Dir(path, this);
 }
 opendirSync;
@@ -645,8 +645,8 @@ opendirSync;
  * - `recursive`: If `true`, copies directories recursively.
  */
 export function cpSync(source, destination, opts) {
-    source = normalizePath(source);
-    destination = normalizePath(destination);
+    source = normalizePath.call(this, source);
+    destination = normalizePath.call(this, destination);
     const srcStats = lstatSync.call(this, source); // Use lstat to follow symlinks if not dereferencing
     if (opts?.errorOnExist && existsSync.call(this, destination))
         throw UV('EEXIST', 'cp', destination);
@@ -688,7 +688,7 @@ export function cpSync(source, destination, opts) {
 }
 cpSync;
 export function statfsSync(path, options) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const { fs } = resolveMount(path, this);
     return _statfs(fs, options?.bigint);
 }

package/dist/vfs/async.js

@@ -114,7 +114,7 @@ export async function resolve($, path, preserveSymlinks, extra) {
  * @internal
  */
 export async function open($, path, opt) {
-    path = normalizePath(path);
+    path = normalizePath.call($, path);
     const mode = normalizeMode(opt.mode, 0o644), flag = flags.parse(opt.flag);
     const $ex = { syscall: 'open', path };
     // eslint-disable-next-line prefer-const
@@ -169,7 +169,7 @@ export async function open($, path, opt) {
     return handle;
 }
 export async function readlink(path) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const $ex = { syscall: 'readlink', path };
     const { fs, stats, path: resolved } = await resolve(this, path, true, $ex);
     if (!stats)
@@ -184,7 +184,7 @@ export async function readlink(path) {
     return decodeUTF8(data);
 }
 export async function mkdir(path, options = {}) {
-    const original = normalizePath(path);
+    const original = normalizePath.call(this, path);
     const { euid: uid, egid: gid } = contextOf(this).credentials;
     const { mode = 0o777, recursive } = options;
     const $ex = { syscall: 'mkdir', path: original };
@@ -238,7 +238,7 @@ export async function mkdir(path, options = {}) {
     return firstCreated;
 }
 export async function readdir(path, options = {}) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     // Node reports `readdir` failures as `scandir`
     const $ex = { syscall: 'scandir', path };
     const { fs, path: resolved, stats } = await resolve(this, path, false, $ex);
@@ -290,8 +290,8 @@ export async function readdir(path, options = {}) {
 export async function rename(oldPath, newPath) {
     const env_4 = { stack: [], error: void 0, hasError: false };
     try {
-        oldPath = normalizePath(oldPath);
-        newPath = normalizePath(newPath);
+        oldPath = normalizePath.call(this, oldPath);
+        newPath = normalizePath.call(this, newPath);
         const $ex = { syscall: 'rename', path: oldPath, dest: newPath };
         const src = await resolve(this, oldPath, true, $ex);
         const dst = resolveMount(newPath, this, $ex);
@@ -344,8 +344,8 @@ export async function rename(oldPath, newPath) {
 export async function link(target, link) {
     const env_5 = { stack: [], error: void 0, hasError: false };
     try {
-        target = normalizePath(target);
-        link = normalizePath(link);
+        target = normalizePath.call(this, target);
+        link = normalizePath.call(this, link);
         const $ex = { syscall: 'link', path: target, dest: link };
         const { fs, path: resolved } = resolveMount(target, this, $ex);
         const dst = resolveMount(link, this, $ex);

package/dist/vfs/file.d.ts

@@ -45,6 +45,10 @@ export declare class Handle {
      * Whether the file is open or closed
      */
     protected closed: boolean;
+    /** How many descriptors refer to this open file */
+    protected refs: number;
+    /** Take another reference to the open file */
+    ref(): this;
     get isClosed(): boolean;
     /**
      * Creates a file handle for the vnode.
@@ -141,11 +145,17 @@ export declare class Handle {
     streamWrite(options: StreamOptions): WritableStream;
 }
 /**
+ * Give an open file a descriptor
  * @internal @hidden
  */
-export declare function toFD(file: Handle): number;
+export declare function toFD(file: Handle, $?: V_Context): number;
 /**
  * @internal @hidden
  */
 export declare function fromFD($: V_Context, fd: number): Handle;
 export declare function deleteFD($: V_Context, fd: number): boolean;
+/**
+ * Give an open file another descriptor
+ * @internal @hidden
+ */
+export declare function dupFD($: V_Context, fd: number): number;

package/dist/vfs/file.js

@@ -152,6 +152,15 @@ let Handle = (() => {
          * Whether the file is open or closed
          */
         closed = false;
+        /** How many descriptors refer to this open file */
+        refs = 1;
+        /** Take another reference to the open file */
+        ref() {
+            if (this.closed)
+                throw UV('EBADF', 'dup', this.path);
+            this.refs++;
+            return this;
+        }
         get isClosed() {
             return this.closed;
         }
@@ -199,6 +208,8 @@ let Handle = (() => {
             if (this.closed)
                 throw UV('EBADF', 'close', this.path);
             this.syncSync();
+            if (--this.refs > 0)
+                return;
             this.disposeSync(true);
         }
         /**
@@ -406,6 +417,8 @@ let Handle = (() => {
             if (this.closed)
                 throw UV('EBADF', 'close', this.path);
             await this.sync();
+            if (--this.refs > 0)
+                return;
             this.dispose(true);
         }
         /**
@@ -671,12 +684,14 @@ let Handle = (() => {
 export { Handle };
 // descriptors
 /**
+ * Give an open file a descriptor
  * @internal @hidden
  */
-export function toFD(file) {
-    const map = contextOf(file.context).descriptors;
-    // @todo use `Iterator` helper #296
-    const fd = Array.from(map.keys()).reduce((next, k) => Math.max(next, k + 1), 4);
+export function toFD(file, $ = file.context) {
+    const map = contextOf($).descriptors;
+    let fd = 0;
+    while (map.has(fd))
+        fd++;
     map.set(fd, file);
     return fd;
 }
@@ -694,3 +709,10 @@ export function fromFD($, fd) {
 export function deleteFD($, fd) {
     return contextOf($).descriptors.delete(fd);
 }
+/**
+ * Give an open file another descriptor
+ * @internal @hidden
+ */
+export function dupFD($, fd) {
+    return toFD(fromFD($, fd).ref(), $);
+}

package/dist/vfs/ioctl.js

@@ -26,7 +26,7 @@ export async function ioctl(path, command, ...args) {
         vnode.refs++;
     }
     else {
-        path = normalizePath(path);
+        path = normalizePath.call(this, path);
         const mnt = await resolveAsync(this, path, false, { syscall: 'ioctl', path });
         if (!mnt.stats)
             throw UV('ENOENT', { syscall: 'ioctl', path });
@@ -64,7 +64,7 @@ export function ioctlSync(path, command, ...args) {
         vnode.refs++;
     }
     else {
-        path = normalizePath(path);
+        path = normalizePath.call(this, path);
         const mnt = resolveSync(this, path, false, { syscall: 'ioctl', path });
         if (!mnt.stats)
             throw UV('ENOENT', { syscall: 'ioctl', path });

package/dist/vfs/shared.js

@@ -128,7 +128,7 @@ export function chroot(path) {
             throw UV('EBUSY', 'chroot', handle.path);
         handle.path = handle.path.slice($.root.length);
     }
-    if (newRoot.length > $.root.length)
+    if (newRoot.length < $.root.length)
         throw withErrno('EPERM', 'Can not chroot() outside of current root');
     $.root = newRoot;
 }

package/dist/vfs/sync.js

@@ -114,7 +114,7 @@ export function resolve($, path, preserveSymlinks, extra) {
  * @internal
  */
 export function open($, path, opt) {
-    path = normalizePath(path);
+    path = normalizePath.call($, path);
     const mode = normalizeMode(opt.mode, 0o644), flag = flags.parse(opt.flag);
     path = opt.preserveSymlinks ? path : resolve($, path).fullPath;
     const { fs, path: resolved } = resolveMount(path, $);
@@ -175,7 +175,7 @@ export function open($, path, opt) {
     return file;
 }
 export function readlink(path) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const { fs, stats, path: resolved } = resolve(this, path, true, { syscall: 'readlink' });
     if (!stats)
         throw UV('ENOENT', 'readlink', path);
@@ -189,7 +189,7 @@ export function readlink(path) {
     return decodeUTF8(data);
 }
 export function mkdir(path, options = {}) {
-    const original = normalizePath(path);
+    const original = normalizePath.call(this, path);
     const $ex = { syscall: 'mkdir', path: original };
     const { fullPath: realParent } = resolve(this, dirname(original), false, $ex);
     const { fs, path: target } = resolveMount(join(realParent, basename(original)), this, $ex);
@@ -246,7 +246,7 @@ export function mkdir(path, options = {}) {
     return firstCreated;
 }
 export function readdir(path, options = {}) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const { fs, path: resolved } = resolve(this, path);
     // Node reports `readdir` failures as `scandir`
     const stats = cacheOf(fs).get(resolved)?.inode ?? wrap(fs, 'statSync', { path, syscall: 'scandir' })(resolved);
@@ -300,8 +300,8 @@ export function readdir(path, options = {}) {
 export function rename(oldPath, newPath) {
     const env_4 = { stack: [], error: void 0, hasError: false };
     try {
-        oldPath = normalizePath(oldPath);
-        newPath = normalizePath(newPath);
+        oldPath = normalizePath.call(this, oldPath);
+        newPath = normalizePath.call(this, newPath);
         const $ex = { syscall: 'rename', path: oldPath, dest: newPath };
         const src = resolve(this, oldPath, true, $ex);
         const dst = resolveMount(newPath, this, $ex);
@@ -357,8 +357,8 @@ export function rename(oldPath, newPath) {
 export function link(target, link) {
     const env_5 = { stack: [], error: void 0, hasError: false };
     try {
-        target = normalizePath(target);
-        link = normalizePath(link);
+        target = normalizePath.call(this, target);
+        link = normalizePath.call(this, link);
         const $ex = { syscall: 'link', path: target, dest: link };
         const { fs, path: resolved } = resolveMount(target, this, $ex);
         const dst = resolveMount(link, this, $ex);

package/dist/vfs/watchers.js

@@ -151,7 +151,7 @@ export function emitChange(context, eventType, filename) {
     const $ = contextOf(context);
     if ($)
         filename = join($.root ?? '/', filename);
-    filename = normalizePath(filename);
+    filename = normalizePath.call(context, filename);
     // Notify watchers, including ones on parent directories if they are watching recursively.
     for (let path = filename;; path = dirname(path)) {
         const watchersForPath = watchers.get(path);

package/dist/vfs/xattr.js

@@ -17,7 +17,7 @@ function checkName($, name, path, syscall) {
         throw UV('ENOTSUP', syscall, path);
 }
 export async function get(path, name, opt = {}) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const { fs, path: resolved } = resolveMount(path, this);
     checkName(this, name, path, 'xattr.get');
     const inode = await fs.stat(resolved).catch(rethrow('xattr.get', path));
@@ -31,7 +31,7 @@ export async function get(path, name, opt = {}) {
     return opt.encoding == 'buffer' || !opt.encoding ? buffer : buffer.toString(opt.encoding);
 }
 export function getSync(path, name, opt = {}) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     checkName(this, name, path, 'xattr.get');
     const { fs, path: resolved } = resolveMount(path, this);
     let inode;
@@ -59,7 +59,7 @@ export function getSync(path, name, opt = {}) {
  * @param opt Options for the operation
  */
 export async function set(path, name, value, opt = {}) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const { fs, path: resolved } = resolveMount(path, this);
     checkName(this, name, path, 'xattr.set');
     const inode = await fs.stat(resolved).catch(rethrow('xattr.set', path));
@@ -83,7 +83,7 @@ export async function set(path, name, value, opt = {}) {
  * @param opt Options for the operation
  */
 export function setSync(path, name, value, opt = {}) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const { fs, path: resolved } = resolveMount(path, this);
     checkName(this, name, path, 'xattr.set');
     let inode;
@@ -116,7 +116,7 @@ export function setSync(path, name, value, opt = {}) {
  * @param name Name of the attribute to remove
  */
 export async function remove(path, name) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const { fs, path: resolved } = resolveMount(path, this);
     checkName(this, name, path, 'xattr.remove');
     const inode = await fs.stat(resolved).catch(rethrow('xattr.remove', path));
@@ -136,7 +136,7 @@ export async function remove(path, name) {
  * @param name Name of the attribute to remove
  */
 export function removeSync(path, name) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const { fs, path: resolved } = resolveMount(path, this);
     checkName(this, name, path, 'xattr.remove');
     let inode;
@@ -167,7 +167,7 @@ export function removeSync(path, name) {
  * @returns Array of attribute names
  */
 export async function list(path) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const { fs, path: resolved } = resolveMount(path, this);
     const inode = await fs.stat(resolved).catch(rethrow('xattr.list', path));
     if (!inode.attributes)
@@ -181,7 +181,7 @@ export async function list(path) {
  * @returns Array of attribute names
  */
 export function listSync(path) {
-    path = normalizePath(path);
+    path = normalizePath.call(this, path);
     const { fs, path: resolved } = resolveMount(path, this);
     let inode;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "2.7.0",
+	"version": "2.7.2",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",

package/tests/common/context.test.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
-import { bindContext, configure, fs, InMemory } from '@zenfs/core';
+import { bindContext, configure, fs, InMemory, type BoundContext } from '@zenfs/core';
 import assert from 'node:assert/strict';
 import { suite, test } from 'node:test';
 import { canary } from 'utilium';
@@ -124,4 +124,14 @@ suite('Context', () => {
 		assert.equal(ctx.readFileSync('/copy.txt', 'utf-8'), 'not in real root!');
 		assert(fs.readdirSync('/ctx').includes('copy.txt'));
 	});
+
+	test('bindContext should resolve root relative to the parent context', () => {
+		fs.mkdirSync('/secure');
+		const ctx = bindContext({ root: '/secure', credentials: { uid: 333, gid: 333 } });
+
+		const plain = bindContext({ credentials: { uid: 1, gid: 1 } });
+		console.log('child of / context: ok, root =', plain.root);
+
+		assert.doesNotThrow(() => ctx.bind({ credentials: { uid: 500, gid: 500 } }));
+	});
 });

package/tests/common/utf8stream.test.ts

@@ -26,7 +26,7 @@ suite('Utf8Stream', config('write'), () => {
 		assert.equal(stream.maxLength, 32);
 		assert.equal(stream.periodicFlush, 0);
 		assert.equal(stream.mkdir, false);
-		assert.ok(stream.fd > 0);
+		assert.ok(stream.fd >= 0);
 
 		stream.destroy();
 	});

package/tests/fs/permissions.test.ts

@@ -54,7 +54,7 @@ suite('Permissions', config('permissions'), () => {
 			assert.equal(error.code, 'EACCES');
 		});
 		if (!stats) return;
-		assert(hasAccess(defaultContext, stats, X_OK));
+		if (stats.isDirectory()) assert(hasAccess(defaultContext, stats, X_OK));
 
 		function checkError(access: number) {
 			return function (error: Exception) {