@parcha/pi-durable-disk 0.1.0-beta.12 → 0.1.0-beta.14

package/dist/commands.js

@@ -0,0 +1,257 @@
+// The commands a run's environment starts, recorded where the next open of the same claim finds them. pi makes each
+// command the leader of a process group of its own, so killing an instance does not reach its commands: a host's unit
+// cgroup or a container ends them with it, and a run on a local directory has neither. While commands run, the instance
+// walks its own process tree (`/proc/<pid>/task/<tid>/children` on Linux, one ps listing on macOS: process-table.ts) and
+// records each of its commands' group leader and every descendant it has seen, each by pid, start and boot. Its commands
+// are the children that lead their own group and carry its mark (COMMANDS_MARK=<its token>) in their environment:
+// another environment's commands in the same process, or the app's own helpers, are not its to record. The next open,
+// which holds the owner lock, kills whatever a previous incarnation recorded that is still the same process (pid, start
+// and boot all match), waits until it is gone, and clears the records, before the Harness opens. Only the instance writes
+// records: a command never does. Nothing stops a command from writing one too, and none needs stopping: a run's commands
+// run as the instance's user (or, with `runAs`, as another one that cannot write the instance's 0700 directory), so a
+// record a command forged names only what that command could already kill itself. A record grants nothing.
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { HeldError } from "./errors.js";
+import { processTable, procTable } from "./process-table.js";
+/** The environment variable that marks a command as one environment's: its value is that recorder's token. */
+export const COMMANDS_MARK = "PI_DURABLE_DISK_COMMANDS";
+const tableOf = (options) => options.table ?? (options.proc === undefined ? processTable() : procTable(options.proc));
+/** Whether `mark` is still the process it was: same pid, same start, not a zombie. Never pid 1 or below. */
+function same(look, mark) {
+    return mark.pid > 1 && look.info(mark.pid)?.start === mark.start;
+}
+const RECORD = /^(\d+)-(\d+)\.json$/;
+/**
+ * Records this environment's command groups under this process while commands run. `started()` and `finished()` bracket
+ * each command, which carries `COMMANDS_MARK=<token>` in its environment; while any runs, the tree is walked soon after a
+ * start and then every `everyMs`. A record is written when its group gains a process and removed once nothing in it is
+ * alive. A walk that fails (a record cannot be written: a full disk) goes to `onError` the first time, never out of a
+ * timer, and the next walk tries again.
+ */
+export class CommandRecorder {
+    /** The value of `COMMANDS_MARK` in this environment's commands. */
+    token = randomUUID();
+    #dir;
+    #table;
+    #instance;
+    #everyMs;
+    #boot;
+    #onError;
+    #reported = false;
+    #records = new Map();
+    /** The records on disk, by key; a group's first walk writes its record even before it has members. */
+    #written = new Set();
+    #active = 0;
+    #timer;
+    constructor(dir, options = {}) {
+        this.#dir = dir;
+        this.#table = tableOf(options);
+        this.#instance = options.instance ?? process.pid;
+        this.#everyMs = options.everyMs ?? this.#table.walkMs;
+        this.#boot = this.#table.bootId();
+        this.#onError = options.onError;
+    }
+    /** A command is about to start. */
+    started() {
+        if (this.#boot === undefined)
+            return; // nothing could verify a record on the next open
+        if (this.#active++ === 0) {
+            this.#timer = setInterval(() => this.scan(), this.#everyMs);
+            this.#timer.unref();
+        }
+        setTimeout(() => this.scan(), 20).unref();
+    }
+    /** A command ended (its result is in). The last one stops the walks after a final one. */
+    finished() {
+        if (this.#boot === undefined || this.#active === 0)
+            return;
+        if (--this.#active === 0) {
+            clearInterval(this.#timer);
+            this.#timer = undefined;
+            this.scan();
+        }
+    }
+    /** Stops recording (the environment closed); the records stay for the next open. */
+    close() {
+        clearInterval(this.#timer);
+        this.#timer = undefined;
+        this.#active = 0;
+    }
+    /** One walk. It is called from timers, so it never throws: a failure goes to `onError` once, and the next walk retries. */
+    scan() {
+        try {
+            this.#scan();
+        }
+        catch (error) {
+            if (this.#reported)
+                return;
+            this.#reported = true;
+            this.#onError?.(error);
+        }
+    }
+    /** Record what is new under each of this environment's command groups, and drop the records of groups that are gone. */
+    #scan() {
+        const boot = this.#boot;
+        if (boot === undefined)
+            return;
+        const look = this.#table.snapshot();
+        const own = look.info(this.#instance);
+        if (own === undefined)
+            return;
+        // New commands: children of this process that lead their own group (pi spawns each one so) and carry this
+        // environment's mark. Once recorded, a leader stays its environment's whatever it execs next (same pid and start).
+        for (const pid of look.children(this.#instance)) {
+            const leader = look.info(pid);
+            if (leader === undefined || leader.pgrp !== pid || leader.pgrp === own.pgrp)
+                continue;
+            const key = `${pid}-${leader.start}`;
+            if (this.#records.has(key) || !look.marked(pid, COMMANDS_MARK, this.token))
+                continue;
+            this.#records.set(key, { leader: { pid, start: leader.start }, members: new Map() });
+        }
+        // Every record: walk from each of its processes still alive, the leader and every member, so a background worker whose
+        // leader (or parent) exited and was reparented away is still followed, and so are the children it starts later.
+        for (const [key, record] of this.#records) {
+            const live = [record.leader, ...record.members.values()].filter((mark) => same(look, mark));
+            if (live.length === 0) {
+                this.#records.delete(key);
+                this.#written.delete(key);
+                rmSync(join(this.#dir, `${key}.json`), { force: true });
+                continue;
+            }
+            let grew = !this.#written.has(key);
+            const walk = (parent) => {
+                for (const child of look.children(parent)) {
+                    const s = look.info(child);
+                    if (s === undefined || child === record.leader.pid)
+                        continue;
+                    const known = record.members.get(child)?.start === s.start;
+                    if (!known) {
+                        record.members.set(child, { pid: child, start: s.start });
+                        grew = true;
+                    }
+                    if (!known || !live.some((mark) => mark.pid === child))
+                        walk(child);
+                }
+            };
+            for (const mark of live)
+                walk(mark.pid);
+            if (grew)
+                this.#write(key, { boot, leader: record.leader, members: [...record.members.values()] });
+        }
+    }
+    #write(key, record) {
+        mkdirSync(this.#dir, { recursive: true, mode: 0o700 });
+        const file = join(this.#dir, `${key}.json`);
+        writeFileSync(`${file}.tmp`, JSON.stringify(record));
+        renameSync(`${file}.tmp`, file);
+        this.#written.add(key);
+    }
+}
+/**
+ * Ends what a previous incarnation's commands left running: for each record of this boot, the leader's whole group when
+ * the leader is still the recorded process, and each recorded descendant that still is. Waits up to `timeoutMs` until
+ * none of them is alive. A record whose processes are all gone is removed; one that still names a live process (it did
+ * not die at the deadline: a process in an uninterruptible wait) is rewritten with just those, so the next open tries
+ * again, and they are returned. Run only while holding the run (after its owner lock), before the Harness opens.
+ */
+export async function reapCommands(dir, options = {}) {
+    const table = tableOf(options);
+    const signal = options.kill ?? ((target, name) => process.kill(target, name));
+    let files;
+    try {
+        files = readdirSync(dir).filter((name) => RECORD.test(name));
+    }
+    catch {
+        return { signalled: 0, survivors: [] };
+    }
+    if (files.length === 0) {
+        rmSync(dir, { recursive: true, force: true });
+        return { signalled: 0, survivors: [] };
+    }
+    const boot = table.bootId();
+    const before = table.snapshot();
+    const own = before.info(process.pid);
+    let signalled = 0;
+    /**
+     * False for what is never a target: this process, its group, and a pid of 1 or below, since `kill(0)` is the caller's
+     * group and `kill(-1)` every process the user may signal.
+     */
+    const kill = (target, mark) => {
+        if (!(mark.pid > 1) || mark.pid === process.pid || (target < 0 && -target === own?.pgrp))
+            return false;
+        try {
+            signal(target, "SIGKILL");
+            signalled++;
+        }
+        catch {
+            // gone between the check and the kill, or not ours to signal: still a target, a survivor if it is alive
+        }
+        return true;
+    };
+    const pending = [];
+    for (const name of files) {
+        const file = join(dir, name);
+        let record;
+        try {
+            record = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            rmSync(file, { force: true }); // a torn write of a record names nothing
+            continue;
+        }
+        if (boot === undefined || record.boot !== boot) {
+            rmSync(file, { force: true }); // another boot's pids mean nothing on this one
+            continue;
+        }
+        const leader = record.leader !== null && same(before, record.leader) && kill(-record.leader.pid, record.leader) ? record.leader : null;
+        // A member that is the leader went with its group.
+        const members = (record.members ?? []).filter((member) => member.pid !== record.leader?.pid && same(before, member) && kill(member.pid, member));
+        pending.push({ file, boot, leader, members });
+    }
+    const alive = () => {
+        const marks = pending.flatMap((p) => [...(p.leader ? [p.leader] : []), ...p.members]);
+        if (marks.length === 0)
+            return marks;
+        const look = table.snapshot();
+        return marks.filter((mark) => same(look, mark));
+    };
+    const deadline = Date.now() + (options.timeoutMs ?? 5_000);
+    while (alive().length > 0 && Date.now() < deadline)
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    const survivors = [];
+    const after = pending.length === 0 ? before : table.snapshot();
+    for (const record of pending) {
+        const leader = record.leader !== null && same(after, record.leader) ? record.leader : null;
+        const members = record.members.filter((member) => same(after, member));
+        if (leader === null && members.length === 0) {
+            rmSync(record.file, { force: true });
+            continue;
+        }
+        survivors.push(...(leader ? [leader] : []), ...members);
+        writeFileSync(`${record.file}.tmp`, JSON.stringify({ boot: record.boot, leader, members }));
+        renameSync(`${record.file}.tmp`, record.file);
+    }
+    if (survivors.length === 0)
+        rmSync(dir, { recursive: true, force: true });
+    return { signalled, survivors };
+}
+/**
+ * `reapCommands` at an open: refuses the run (`HeldError("commands")`, exit 76) when a process a killed incarnation's
+ * commands left is still alive after it, since the run must not resume beside it. Its record stays, and the next open
+ * tries again.
+ */
+export async function reapOrRefuse(dir, options = {}) {
+    const reaped = await reapCommands(dir, options);
+    if (reaped.survivors.length > 0) {
+        const look = tableOf(options).snapshot();
+        const pids = reaped.survivors.map((s) => s.pid);
+        throw new HeldError("commands", `${pids.length} process(es) a killed incarnation's commands started are still alive after SIGKILL: ` +
+            `${reaped.survivors.map((s) => `pid ${s.pid} (${look.commandLine(s.pid)})`).join(", ")}. ` +
+            `The run does not resume beside them. End them (kill -9 ${pids.join(" ")}, as their owner, or wait for them) and open the run again; ` +
+            `they stay recorded in ${dir} until then.`);
+    }
+    return reaped;
+}

package/dist/confine.d.ts

@@ -14,6 +14,8 @@ export declare class PathOutsideWorkError extends FileError {
 /** Test seam: runs after a path was resolved and checked, before anything is opened. */
 export declare const confineHooks: {
     afterCheck?: (canonical: string) => Promise<void> | void;
+    /** After `createTempDir` made a directory and before it is granted (a command may act in between). */
+    afterTempDir?: (dir: string) => Promise<void> | void;
 };
 /** pi's mapping from a Node error to its `FileError` codes (pi does not export it). */
 export declare function fileError(error: unknown, path: string): FileError;
@@ -35,8 +37,9 @@ export interface PinSpec {
     readonly strict?: boolean;
 }
 /**
- * A resolved target held open. `dir` and `entry` are `/proc/self/fd/...` paths to hand to pi's own implementation; every
- * path and message it returns is mapped back to the real one with `restore`. Close it when the operation is done.
+ * A resolved target held open. `dir` and `entry` are `/proc/self/fd/...` paths (by path, the real ones) to hand to pi's
+ * own implementation; every path and message it returns is mapped back to the real one with `restore`. Close it when
+ * the operation is done.
  */
 export declare class Pin {
     #private;
@@ -47,24 +50,58 @@ export declare class Pin {
     readonly dir: string;
     /** The target below `dir`, for operations that do not follow a last symlink. */
     readonly entry: string;
-    constructor(handle: FileHandle, canonical: string, name: string, dirMode: boolean);
-    /** `text` with the held paths replaced by the real ones. */
+    /**
+     * `held` is the walk's: whether it went by path, and then the held directory's real path; and the names of the
+     * confinement's roots (`Confinement`'s `names`).
+     */
+    constructor(handle: FileHandle, canonical: string, name: string, dirMode: boolean, held?: {
+        byPath: boolean;
+        path: string;
+        names?: readonly RootName[];
+    });
+    /** `text` with the held paths replaced by the real ones, and a root named as the caller names it. */
     translate(text: string): string;
     /** An error pi or Node raised on a held path, as a FileError that names the real one. */
     error(error: unknown, path: string): FileError;
     restore<T>(result: Result<T, FileError>): Result<T, FileError>;
-    /** Opens the target's last component, which is never followed, and returns its handle; the caller closes it. */
+    /**
+     * Opens the target's last component, which is never followed, and returns its handle; the caller closes it. By path,
+     * the directory's path must still name the directory held once the file is open.
+     */
     openFile(flags: number, mode?: number): Promise<FileHandle>;
     binaryReader(reader: BinaryReader): BinaryReader;
     /** The reader keeps the pin open: pi's reader names each entry through `dir` as it pages. */
     dirReader(reader: DirReader): DirReader;
     close(): Promise<void>;
 }
+/** A root's canonical path, as a pattern that matches it whole in a path or a message, and the name the caller gave it. */
+interface RootName {
+    readonly canonical: RegExp;
+    readonly named: string;
+}
 export declare class Confinement {
+    #private;
     readonly work: string;
     readonly readOnly: readonly string[];
-    /** Canonical directories: `work` may be read and written, `readOnly` only read. */
-    constructor(work: string, readOnly: readonly string[]);
+    /** Whether the walk goes by path (macOS, which has no `/proc/self/fd`; see the top of this file). */
+    readonly byPath: boolean;
+    /**
+     * Canonical directories: `work` may be read and written, `readOnly` only read. `byPath` defaults to true on macOS only.
+     * `names` maps a canonical root to the path the caller names it by, where they differ (a root under a symlinked
+     * directory, as `/tmp` and `/var` are on macOS): results name paths under it as the caller does, as pi's own do.
+     */
+    constructor(work: string, readOnly: readonly string[], options?: {
+        readonly byPath?: boolean;
+        readonly names?: ReadonlyMap<string, string>;
+    });
+    /**
+     * Lets file operations write inside `dir` too: a directory this process just created (`createTempDir`) directly in a
+     * read-only root, for the tool it is handed to. `dir` is that root joined with the new name, never resolved: if the
+     * directory is later swapped for a link, a path through it resolves elsewhere and is refused.
+     */
+    allowWrites(dir: string): void;
+    /** `dir` was removed: writes inside it, or inside any handed directory below it, are no longer allowed. */
+    forgetWrites(dir: string): void;
     /** Resolves `abs` and refuses it unless it lies under an allowed root; returns the root that holds it. */
     locate(abs: string, original: string, access: "read" | "write", follow: boolean): Promise<{
         canonical: string;
@@ -78,3 +115,6 @@ export declare class Confinement {
         create?: boolean;
     }): Promise<Pin>;
 }
+/** Whether `path` still names the directory `held` holds (same device and inode); false when it cannot be read. */
+export declare function namesHeld(path: string, held: FileHandle): Promise<boolean>;
+export {};

package/dist/confine.js

@@ -10,8 +10,14 @@
 // openat2(RESOLVE_BENEATH | RESOLVE_NO_SYMLINKS) done in user space. Node has no openat, so a handle's directory is named
 // `/proc/self/fd/<fd>`: the kernel jumps straight to the held inode there and never re-walks the directory's own path. A
 // swapped component fails the open (ELOOP or ENOTDIR) and the call is refused as changed; nothing is retried.
+//
+// macOS has no /proc/self/fd, so there (`byPath`) each step is opened by its full path, still with O_NOFOLLOW, and the
+// walk ends by checking that the path still resolves to itself and names the directory held (same device and inode). A
+// component that is a symlink, or was swapped for one before that check, is refused as changed. The operation then
+// names the path again, so a command that swaps a directory above the target between the check and the operation can
+// win: by path, the confinement holds against an agent's paths and the links already in place, not a command racing it.
 import { constants, existsSync, realpathSync } from "node:fs";
-import { lstat, mkdir, open, readlink, realpath } from "node:fs/promises";
+import { lstat, mkdir, open, readlink, realpath, stat } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { err, FileError, ok } from "@earendil-works/pi-durable/env";
 /**
@@ -119,8 +125,9 @@ export const inside = (path, root) => path === root || path.startsWith(root.ends
 const FILE_INFO_KEYS = ["name", "path", "kind", "size", "mtimeMs"];
 const isFileInfo = (value) => typeof value === "object" && value !== null && FILE_INFO_KEYS.every((key) => key in value) && typeof value.path === "string";
 /**
- * A resolved target held open. `dir` and `entry` are `/proc/self/fd/...` paths to hand to pi's own implementation; every
- * path and message it returns is mapped back to the real one with `restore`. Close it when the operation is done.
+ * A resolved target held open. `dir` and `entry` are `/proc/self/fd/...` paths (by path, the real ones) to hand to pi's
+ * own implementation; every path and message it returns is mapped back to the real one with `restore`. Close it when
+ * the operation is done.
  */
 export class Pin {
     canonical;
@@ -134,17 +141,29 @@ export class Pin {
     /** What `dir` stands for: the directory itself, or the directory holding the entry. */
     #real;
     #closed = false;
-    constructor(handle, canonical, name, dirMode) {
+    #byPath;
+    #names;
+    /**
+     * `held` is the walk's: whether it went by path, and then the held directory's real path; and the names of the
+     * confinement's roots (`Confinement`'s `names`).
+     */
+    constructor(handle, canonical, name, dirMode, held = { byPath: false, path: "" }) {
         this.#handle = handle;
         this.canonical = canonical;
         this.name = name;
-        this.dir = `/proc/self/fd/${handle.fd}`;
+        this.#byPath = held.byPath;
+        this.#names = held.names ?? [];
+        this.dir = held.byPath ? held.path : `/proc/self/fd/${handle.fd}`;
         this.entry = dirMode ? this.dir : name === "" ? `${this.dir}/.` : `${this.dir}/${name}`;
         this.#real = dirMode || name === "" ? canonical : dirname(canonical);
     }
-    /** `text` with the held paths replaced by the real ones. */
+    /** `text` with the held paths replaced by the real ones, and a root named as the caller names it. */
     translate(text) {
-        return text.split(this.entry).join(this.canonical).split(this.dir).join(this.#real);
+        let real = text.split(this.entry).join(this.canonical).split(this.dir).join(this.#real);
+        // A function, so `$&` or `$$` in the name is kept as written rather than expanded.
+        for (const { canonical, named } of this.#names)
+            real = real.replace(canonical, () => named);
+        return real;
     }
     /** An error pi or Node raised on a held path, as a FileError that names the real one. */
     error(error, path) {
@@ -169,16 +188,25 @@ export class Pin {
         }
         return value;
     }
-    /** Opens the target's last component, which is never followed, and returns its handle; the caller closes it. */
+    /**
+     * Opens the target's last component, which is never followed, and returns its handle; the caller closes it. By path,
+     * the directory's path must still name the directory held once the file is open.
+     */
     async openFile(flags, mode) {
+        let file;
         try {
-            return await open(this.entry, flags | FILE, mode);
+            file = await open(this.entry, flags | FILE, mode);
         }
         catch (error) {
             if (errno(error) === "ELOOP")
                 throw changed(this.canonical);
             throw error;
         }
+        if (this.#byPath && !(await namesHeld(this.dir, this.#handle))) {
+            await file.close().catch(() => undefined);
+            throw changed(this.canonical);
+        }
+        return file;
     }
     binaryReader(reader) {
         return {
@@ -213,15 +241,44 @@ const changed = (path) => new PathOutsideWorkError(path, "changed", `${path}: a
 export class Confinement {
     work;
     readOnly;
-    /** Canonical directories: `work` may be read and written, `readOnly` only read. */
-    constructor(work, readOnly) {
+    /** Whether the walk goes by path (macOS, which has no `/proc/self/fd`; see the top of this file). */
+    byPath;
+    /** Directories handed out for writing after construction (the environment's temp dirs), canonical. */
+    #handed = new Set();
+    #names;
+    /**
+     * Canonical directories: `work` may be read and written, `readOnly` only read. `byPath` defaults to true on macOS only.
+     * `names` maps a canonical root to the path the caller names it by, where they differ (a root under a symlinked
+     * directory, as `/tmp` and `/var` are on macOS): results name paths under it as the caller does, as pi's own do.
+     */
+    constructor(work, readOnly, options = {}) {
         this.work = work;
         this.readOnly = readOnly;
+        this.byPath = options.byPath ?? process.platform === "darwin";
+        // Longest first, so a root inside another is named before the outer one could take its prefix.
+        this.#names = [...(options.names ?? [])]
+            .sort(([a], [b]) => b.length - a.length)
+            .map(([canonical, named]) => ({ canonical: new RegExp(`${canonical.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![^/'"\\s,;:)\\]])`, "g"), named }));
+    }
+    /**
+     * Lets file operations write inside `dir` too: a directory this process just created (`createTempDir`) directly in a
+     * read-only root, for the tool it is handed to. `dir` is that root joined with the new name, never resolved: if the
+     * directory is later swapped for a link, a path through it resolves elsewhere and is refused.
+     */
+    allowWrites(dir) {
+        if (this.readOnly.some((root) => dirname(dir) === root))
+            this.#handed.add(dir);
+    }
+    /** `dir` was removed: writes inside it, or inside any handed directory below it, are no longer allowed. */
+    forgetWrites(dir) {
+        for (const handed of this.#handed)
+            if (inside(handed, dir))
+                this.#handed.delete(handed);
     }
     /** Resolves `abs` and refuses it unless it lies under an allowed root; returns the root that holds it. */
     async locate(abs, original, access, follow) {
         const canonical = follow ? await canonicalize(abs) : join(await canonicalize(dirname(abs)), basename(abs));
-        const roots = access === "write" ? [this.work] : [this.work, ...this.readOnly];
+        const roots = access === "write" ? [this.work, ...this.#handed] : [this.work, ...this.#handed, ...this.readOnly];
         const root = roots.find((candidate) => inside(canonical, candidate));
         if (root === undefined) {
             const where = canonical === abs ? "" : ` (it resolves to ${canonical})`;
@@ -235,18 +292,23 @@ export class Confinement {
         await confineHooks.afterCheck?.(canonical);
         const names = relative(root, canonical);
         if (names.length === 0 && spec.strict === true) {
-            throw new PathOutsideWorkError(original, "outside_work", `${original}: the workspace root itself cannot be removed or renamed`);
+            // a handed directory itself (a tool removing the temp dir it was given): pinned as an entry of the read-only root that
+            // holds it, so it can go; the workspace root never can
+            const holder = this.#handed.has(root) ? this.readOnly.find((candidate) => dirname(root) === candidate) : undefined;
+            if (holder === undefined)
+                throw new PathOutsideWorkError(original, "outside_work", `${original}: the workspace root itself cannot be removed or renamed`);
+            return new Pin(await walk(holder, [], "none", canonical, this.byPath), canonical, basename(root), false, { byPath: this.byPath, path: holder, names: this.#names });
         }
         const name = names.pop() ?? "";
-        const handle = await walk(root, names, spec.parents === true ? "all" : "none", canonical);
-        return new Pin(handle, canonical, name, false);
+        const handle = await walk(root, names, spec.parents === true ? "all" : "none", canonical, this.byPath);
+        return new Pin(handle, canonical, name, false, { byPath: this.byPath, path: join(root, ...names), names: this.#names });
     }
     /** Pins the target directory itself; `create` makes it and the directories above it when they are missing. */
     async pinDir(abs, original, spec) {
         const { canonical, root } = await this.locate(abs, original, spec.access, true);
         await confineHooks.afterCheck?.(canonical);
-        const handle = await walk(root, relative(root, canonical), spec.create === true ? "all" : "none", canonical);
-        return new Pin(handle, canonical, basename(canonical), true);
+        const handle = await walk(root, relative(root, canonical), spec.create === true ? "all" : "none", canonical, this.byPath);
+        return new Pin(handle, canonical, basename(canonical), true, { byPath: this.byPath, path: canonical, names: this.#names });
     }
 }
 const relative = (root, path) => (path === root ? [] : path.slice(root.length + (root.endsWith("/") ? 0 : 1)).split("/"));
@@ -264,8 +326,23 @@ async function swapped(error, path) {
         return false;
     return (await lstat(path).catch(() => undefined))?.isSymbolicLink() === true;
 }
-/** Opens `root`, then each name below it, every step relative to the handle before it and without following links. */
-async function walk(root, names, create, canonical) {
+/** Whether `path` still names the directory `held` holds (same device and inode); false when it cannot be read. */
+export async function namesHeld(path, held) {
+    try {
+        const [named, opened] = await Promise.all([stat(path, { bigint: true }), held.stat({ bigint: true })]);
+        return named.dev === opened.dev && named.ino === opened.ino;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Opens `root`, then each name below it, every step relative to the handle before it and without following links. By
+ * path, every step is opened by its full path instead, and the last must then resolve to itself and be the one held.
+ */
+async function walk(root, names, create, canonical, byPath = false) {
+    if (byPath)
+        return walkByPath(root, names, create, canonical);
     let dir;
     try {
         dir = await open(root, DIRECTORY);
@@ -317,3 +394,55 @@ async function walk(root, names, create, canonical) {
         throw error;
     }
 }
+async function walkByPath(root, names, create, canonical) {
+    let real = root;
+    let dir;
+    try {
+        dir = await open(root, DIRECTORY);
+    }
+    catch (error) {
+        if (await swapped(error, root))
+            throw changed(canonical);
+        throw error;
+    }
+    try {
+        for (const name of names) {
+            if (name === "" || name === "." || name === ".." || name.includes("\0"))
+                throw changed(canonical);
+            real = join(real, name);
+            let next;
+            try {
+                next = await open(real, DIRECTORY);
+            }
+            catch (error) {
+                if (create === "all" && errno(error) === "ENOENT") {
+                    await mkdir(real).catch((made) => {
+                        if (errno(made) !== "EEXIST")
+                            throw made;
+                    });
+                    next = await open(real, DIRECTORY).catch(async (opened) => {
+                        throw (await swapped(opened, real)) ? changed(canonical) : opened;
+                    });
+                }
+                else if (await swapped(error, real)) {
+                    throw changed(canonical);
+                }
+                else {
+                    throw error;
+                }
+            }
+            await dir.close();
+            dir = next;
+        }
+        // Each step was opened by its full path, and only the last component of each open is never followed: the path must
+        // still resolve to itself (no component above is a link) and name the directory held (none was swapped and back).
+        const resolved = await realpath(real).catch(() => undefined);
+        if (resolved !== real || !(await namesHeld(real, dir)))
+            throw changed(canonical);
+        return dir;
+    }
+    catch (error) {
+        await dir.close().catch(() => undefined);
+        throw error;
+    }
+}