@openclaw/fs-safe 0.20.0 → 0.21.0

package/dist/temp-workspace-child-admission.js

@@ -3,6 +3,7 @@ import { inspectDirectoryIdentitySync, observeDirectoryIdentitySync } from "./di
 import { pinNodeDirectoryForMode, pinNodeDirectoryForModeSync } from "./directory-mode-node.js";
 import { FsSafeError } from "./errors.js";
 import { fileIdentityMismatchError, inspectFileIdentitySync } from "./strict-file-identity.js";
+import { classifyTempWorkspaceOwner, warnUnmappedTempWorkspaceAncestor } from "./temp-workspace-ownership.js";
 export const TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY = process.platform === "linux" || process.platform === "darwin";
 export function projectTempWorkspaceNumericIdentity(identity) {
     const dev = Number(identity.dev);
@@ -42,16 +43,16 @@ export function validateTempWorkspaceDirMode(mode) {
         throw new FsSafeError("insecure-permissions", "temp workspace must not be group/world writable");
     }
 }
-export function assertTrustedTempWorkspaceDirectory(stat, uid, child = false) {
+export function assertTrustedTempWorkspaceDirectory(stat, uid, privateDirectory = false) {
     if (uid === undefined)
         return;
-    const ownedByUser = typeof stat.uid === "bigint" ? stat.uid === BigInt(uid) : stat.uid === uid;
-    const ownedByRoot = typeof stat.uid === "bigint" ? stat.uid === 0n : stat.uid === 0;
-    if (!ownedByUser && (child || !ownedByRoot)) {
-        throw new FsSafeError("not-owned", "temp workspace directory has an untrusted owner");
+    const ownership = classifyTempWorkspaceOwner(stat, uid);
+    if (ownership === "foreign" || (privateDirectory && ownership !== "user")) {
+        throw new FsSafeError("not-owned", "temp workspace directory has an untrusted owner; use a private temp root owned by the effective user under a trusted directory hierarchy");
     }
-    // A root/current-user-owned sticky directory protects children owned by us,
-    // including the usual shared system temp directory. Never chmod that parent.
+    // Unmapped host owners are unverifiable; trust the host directory hierarchy.
+    // Admit sticky ancestors so PrivateUsers keeps host /tmp and PrivateTmp usable.
+    // Leaf roots stay euid-owned/private; non-sticky writable ancestors are rejected.
     const writable = typeof stat.mode === "bigint"
         ? (stat.mode & 18n) !== 0n
         : Number.isSafeInteger(stat.mode) && stat.mode >= 0 && (stat.mode & 0o022) !== 0;
@@ -61,9 +62,13 @@ export function assertTrustedTempWorkspaceDirectory(stat, uid, child = false) {
     if (typeof stat.mode !== "bigint" && (!Number.isSafeInteger(stat.mode) || stat.mode < 0)) {
         throw new FsSafeError("insecure-permissions", "temp workspace directory permissions are invalid");
     }
-    if (writable && (child || !sticky)) {
-        throw new FsSafeError("insecure-permissions", "temp workspace directory is group/world writable without sticky protection");
+    if (writable && (privateDirectory || !sticky)) {
+        throw new FsSafeError("insecure-permissions", privateDirectory
+            ? "temp workspace root and child must not be group/world writable; use a private temp directory"
+            : "temp workspace ancestor is group/world writable without sticky protection");
     }
+    if (ownership === "unmapped")
+        warnUnmappedTempWorkspaceAncestor();
 }
 const WINDOWS = process.platform === "win32";
 export function assertTempWorkspaceChildState(stat, ownerUid) {

package/dist/temp-workspace-ownership.d.ts

@@ -0,0 +1,8 @@
+type DirectoryOwner = {
+    uid: number | bigint;
+    gid: number | bigint;
+};
+export type TempWorkspaceOwnership = "user" | "root" | "unmapped" | "foreign";
+export declare function classifyTempWorkspaceOwner(stat: DirectoryOwner, uid: number): TempWorkspaceOwnership;
+export declare function warnUnmappedTempWorkspaceAncestor(): void;
+export {};

package/dist/temp-workspace-ownership.js

@@ -0,0 +1,52 @@
+import fs from "node:fs";
+let warned = false;
+function overflowId(kind) {
+    try {
+        const value = Number(fs.readFileSync(`/proc/sys/kernel/overflow${kind}`, "utf8").trim());
+        if (Number.isSafeInteger(value) && value >= 0 && value < 0xffffffff)
+            return value;
+    }
+    catch {
+        // Linux defaults when the sysctl files are unavailable in the service mount.
+    }
+    return 65534;
+}
+function unmappedId(kind) {
+    const mappings = fs.readFileSync(`/proc/self/${kind}_map`, "utf8").trim()
+        .split("\n").map((line) => line.trim().split(/\s+/).map(Number));
+    if (!mappings.every((row) => row.length === 3 && row.every((id) => Number.isSafeInteger(id) && id >= 0 && id <= 0xffffffff) && row[2] > 0))
+        return null;
+    if (mappings.length === 1 && mappings[0][0] === 0 &&
+        mappings[0][1] === 0 && mappings[0][2] === 0xffffffff)
+        return null;
+    const id = overflowId(kind);
+    // Recheck every admission: an explicitly mapped overflow-number ID is real ownership.
+    return mappings.some(([start, , count]) => id >= start && id < start + count) ? null : id;
+}
+export function classifyTempWorkspaceOwner(stat, uid) {
+    if (stat.uid === uid || stat.uid === BigInt(uid))
+        return "user";
+    if (stat.uid === 0 || stat.uid === 0n)
+        return "root";
+    if (process.platform !== "linux")
+        return "foreign";
+    try {
+        const overflowUid = unmappedId("uid");
+        const overflowGid = unmappedId("gid");
+        return overflowUid !== null && overflowGid !== null &&
+            (stat.uid === overflowUid || stat.uid === BigInt(overflowUid)) &&
+            (stat.gid === overflowGid || stat.gid === BigInt(overflowGid))
+            ? "unmapped"
+            : "foreign";
+    }
+    catch {
+        // Unavailable mapping evidence cannot authorize the namespace exception.
+        return "foreign";
+    }
+}
+export function warnUnmappedTempWorkspaceAncestor() {
+    if (warned)
+        return;
+    warned = true;
+    process.emitWarning("Temp workspace ancestor ownership is unverifiable in this user namespace; trusting the host directory hierarchy while enforcing ancestor modes and a process-owned private root.", { code: "FS_SAFE_UNMAPPED_TEMP_ANCESTOR", type: "FsSafeWarning" });
+}

package/dist/test-hooks.d.ts

@@ -1,6 +1,9 @@
 import type { FileHandle } from "node:fs/promises";
 import type { FileIdentityStat } from "./file-identity.js";
 export type FsSafeTestHooks = {
+    beforeWatchRegistration?: (path: string) => void | Promise<void>;
+    afterWatchRegistration?: (path: string) => void | Promise<void>;
+    afterWatchBackendCreated?: (root: string, emit: (batch: import("./watch-native.js").NativeWatchBatch) => void, nativeEvent?: (path: string, flags: number) => void) => void;
     afterPreOpenLstat?: (filePath: string) => Promise<void> | void;
     beforeOpen?: (filePath: string, flags: number) => Promise<void> | void;
     afterOpen?: (filePath: string, handle: FileHandle) => Promise<void> | void;

package/dist/watch-alias.d.ts

@@ -0,0 +1,6 @@
+import { type RootContext } from "./root-context.js";
+import type { NativeWatchBatch } from "./watch-native.js";
+import type { WatchSnapshot } from "./watch-scan.js";
+import type { WatchChange, WatchScope } from "./watch-types.js";
+/** Resolve native spelling aliases without treating case folding as identity. */
+export declare function admittedNativeChanges(root: RootContext, scopes: readonly WatchScope[], before: WatchSnapshot | undefined, after: WatchSnapshot, batch: NativeWatchBatch, signal: AbortSignal, limit: number): Promise<WatchChange[] | undefined>;

package/dist/watch-alias.js

@@ -0,0 +1,80 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError } from "./path.js";
+import { assertRootIdentityCurrent, resolvePathInRoot } from "./root-context.js";
+import { createRootDirectoryObservationGuard, assertRootDirectoryObservationGuard } from "./root-directory-list.js";
+import { lookupRootDirectoryEntry } from "./root-directory-entry.js";
+import { nativeChanges, scopedChanges } from "./watch-hints.js";
+/** Resolve native spelling aliases without treating case folding as identity. */
+export async function admittedNativeChanges(root, scopes, before, after, batch, signal, limit) {
+    if (!nativeChanges(scopes, before, batch, limit))
+        return undefined;
+    const result = new Map();
+    const candidates = new Map([...before?.targets ?? [], ...after.targets, ...after.directories]);
+    const add = (change) => {
+        if (!result.has(change.path) && result.size >= limit)
+            return false;
+        const prior = result.get(change.path);
+        result.set(change.path, prior?.type === "structural" ? prior : change);
+        return true;
+    };
+    for (const hint of batch.hints) {
+        signal.throwIfAborted();
+        const name = hint.name; // nativeChanges rejected unknown or non-literal names.
+        let parent = hint.directory;
+        let guard;
+        let expected = after.directories.get(parent);
+        if (!expected) {
+            // Native recursion observes one Root handle and may report descendants of
+            // unselected/entry-only directories. Admit a parent alias by exact identity,
+            // not by lowercasing, and do not turn unselected descendants into events.
+            try {
+                const resolved = await resolvePathInRoot(root, parent ? "./" + parent : ".", { rejectSymlinks: true });
+                guard = await createRootDirectoryObservationGuard(root, resolved.resolved);
+            }
+            catch (error) {
+                await assertRootIdentityCurrent(root);
+                if (isNotFoundPathError(error) || (error instanceof FsSafeError && ["not-found", "path-alias", "outside-workspace", "symlink", "not-file"].includes(error.code)))
+                    continue;
+                throw error;
+            }
+            const admitted = [...after.directories].find(([, identity]) => identity.dev === guard.stat.dev && identity.ino === guard.stat.ino);
+            if (!admitted)
+                continue;
+            [parent, expected] = admitted;
+        }
+        const candidate = parent ? path.join(parent, name) : name;
+        const selected = scopedChanges(scopes, { path: candidate,
+            type: hint.event === "change" && before?.entries.get(candidate)?.startsWith("file:") ? "content" : "structural" });
+        if (selected.length) {
+            for (const change of selected)
+                if (!add(change))
+                    return undefined;
+            continue;
+        }
+        if (!guard) {
+            const resolved = await resolvePathInRoot(root, parent ? "./" + parent : ".", { rejectSymlinks: true });
+            guard = await createRootDirectoryObservationGuard(root, resolved.resolved);
+        }
+        if (guard.stat.dev !== expected.dev || guard.stat.ino !== expected.ino) {
+            throw new FsSafeError("path-mismatch", "watch hint parent changed during reconciliation");
+        }
+        const found = await lookupRootDirectoryEntry(root, guard, name);
+        signal.throwIfAborted();
+        if (!found)
+            return undefined; // Could be a deleted short-name/case alias.
+        for (const [relative, identity] of candidates) {
+            if (!relative || (path.dirname(relative) === "." ? "" : path.dirname(relative)) !== parent)
+                continue;
+            if (identity.dev !== found.identity.dev || identity.ino !== found.identity.ino)
+                continue;
+            for (const change of scopedChanges(scopes, { path: relative, type: "structural" }))
+                if (!add(change))
+                    return undefined;
+        }
+        await assertRootDirectoryObservationGuard(root, guard);
+    }
+    await assertRootIdentityCurrent(root);
+    signal.throwIfAborted();
+    return [...result.values()];
+}

package/dist/watch-hints.d.ts

@@ -0,0 +1,8 @@
+import type { NativeWatchBatch } from "./watch-native.js";
+import type { WatchSnapshot } from "./watch-scan.js";
+import type { WatchChange, WatchScope } from "./watch-types.js";
+export declare function scopedChanges(scopes: readonly WatchScope[], change: WatchChange): WatchChange[];
+export declare function nativeChanges(scopes: readonly WatchScope[], snapshot: WatchSnapshot | undefined, batch: NativeWatchBatch, limit?: number): WatchChange[] | undefined;
+export declare function changedEntries(before: WatchSnapshot | undefined, after: WatchSnapshot, limit: number): WatchChange[] | undefined;
+/** Backend names never establish authority to publish a pathname. */
+export declare function guardedHintChanges(scopes: readonly WatchScope[], before: WatchSnapshot | undefined, after: WatchSnapshot, hints: readonly WatchChange[] | undefined, observed: readonly WatchChange[] | undefined, limit: number): WatchChange[] | undefined;

package/dist/watch-hints.js

@@ -0,0 +1,77 @@
+import path from "node:path";
+function below(parent, child) {
+    return parent === "" ? child !== "" : child.startsWith(parent + path.sep);
+}
+function distance(parent, child) {
+    return (parent === "" ? child : child.slice(parent.length + 1)).split(path.sep).length;
+}
+export function scopedChanges(scopes, change) {
+    const result = new Map();
+    for (const scope of scopes) {
+        if (scope.path === change.path || (scope.kind === "tree" && below(scope.path, change.path) && distance(scope.path, change.path) <= scope.depth)) {
+            result.set(change.path, change);
+        }
+        else if (below(change.path, scope.path)) {
+            // A changed ancestor invalidates the requested target, not authority outside it.
+            result.set(scope.path, { path: scope.path, type: "structural" });
+        }
+    }
+    return [...result.values()];
+}
+export function nativeChanges(scopes, snapshot, batch, limit = 256) {
+    if (batch.overflow)
+        return undefined;
+    const result = new Map();
+    for (const hint of batch.hints) {
+        const name = hint.name;
+        // Backend filenames are untrusted hints. Never resolve or perform I/O on them.
+        if (typeof name !== "string" || !name || name === "." || name === ".." || name.includes("\0") || name.includes("/") || (process.platform === "win32" && /[\\:]/.test(name)))
+            return undefined;
+        const relative = hint.directory ? path.join(hint.directory, name) : name;
+        for (const change of scopedChanges(scopes, {
+            path: relative,
+            type: hint.event === "change" && snapshot?.entries.get(relative)?.startsWith("file:") ? "content" : "structural",
+        })) {
+            if (!result.has(change.path) && result.size >= limit)
+                return undefined;
+            const prior = result.get(change.path);
+            result.set(change.path, prior?.type === "structural" ? prior : change);
+        }
+    }
+    return [...result.values()];
+}
+export function changedEntries(before, after, limit) {
+    if (!before)
+        return undefined;
+    const changes = [];
+    for (const name of new Set([...before.entries.keys(), ...after.entries.keys()])) {
+        const left = before.entries.get(name);
+        const right = after.entries.get(name);
+        if (left === right)
+            continue;
+        if (changes.length >= limit)
+            return undefined;
+        const sameFile = left?.startsWith("file:") && right?.startsWith("file:") &&
+            left.split(":").slice(0, 3).join(":") === right.split(":").slice(0, 3).join(":");
+        changes.push(Object.freeze({ path: name, type: sameFile ? "content" : "structural" }));
+    }
+    return changes;
+}
+/** Backend names never establish authority to publish a pathname. */
+export function guardedHintChanges(scopes, before, after, hints, observed, limit) {
+    if (!hints || !observed)
+        return undefined;
+    const result = new Map(observed.map(change => [change.path, change]));
+    for (const hint of hints) {
+        // Only publish an independently observed name (including a deletion from
+        // the previous guarded snapshot), or a target explicitly supplied by caller.
+        // A stale/misdirected inode watch may report outside names: erase its detail.
+        if (!before?.entries.has(hint.path) && !after.entries.has(hint.path) && !scopes.some(scope => scope.path === hint.path))
+            return undefined;
+        if (!result.has(hint.path) && result.size >= limit)
+            return undefined;
+        const prior = result.get(hint.path);
+        result.set(hint.path, Object.freeze(prior?.type === "structural" ? prior : hint));
+    }
+    return [...result.values()];
+}

package/dist/watch-native.d.ts

@@ -0,0 +1,32 @@
+import { type NativeBinding } from "./native.js";
+import type { RootContext } from "./root-context.js";
+import type { DirectoryIdentity } from "./watch-scan.js";
+export type NativeWatchHint = {
+    directory: string;
+    name: string;
+    event: "rename" | "change";
+};
+export type NativeWatchBatch = {
+    hints: NativeWatchHint[];
+    overflow: boolean;
+    error?: string;
+};
+export type NativeWatchWireBatch = {
+    hints: {
+        directory: string;
+        name: string;
+        structural: boolean;
+    }[];
+    overflow: boolean;
+    error?: string;
+};
+export declare function watchBinding(mode: "auto" | "events" | "poll"): NativeBinding | undefined;
+export declare class NativeWatchBackend {
+    private binding;
+    private root;
+    private id;
+    constructor(binding: NativeBinding, root: RootContext, callback: (batch: NativeWatchBatch) => void, limit: number, persistent: boolean);
+    add(name: string, identity: DirectoryIdentity): void;
+    testEvent(path: string, flags: number): void;
+    close(): void;
+}

package/dist/watch-native.js

@@ -0,0 +1,56 @@
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+export function watchBinding(mode) {
+    if (mode === "poll")
+        return;
+    const binding = getNativeBinding(); // Preserves require + missing-addon failure.
+    // Bun TSFN teardown remains unqualified; guarded native scans remain usable.
+    if (binding?.watchRegister && !process.versions.bun && !process.versions.deno && ["linux", "darwin", "win32"].includes(process.platform))
+        return binding;
+    if (mode === "events" || getFsSafeNativeConfig().mode === "require") {
+        throw new FsSafeError("helper-unavailable", "native watch events are unavailable", { details: { operation: "watch" } });
+    }
+}
+export class NativeWatchBackend {
+    binding;
+    root;
+    id;
+    constructor(binding, root, callback, limit, persistent) {
+        this.binding = binding;
+        this.root = root;
+        try {
+            this.id = binding.watchRegister(root.rootReal, limit, batch => {
+                if (this.id !== undefined)
+                    callback({ overflow: batch.overflow, error: batch.error, hints: batch.hints.map(hint => ({
+                            directory: hint.directory, name: hint.name, event: hint.structural ? "rename" : "change",
+                        })) });
+            }, persistent);
+        }
+        catch (cause) {
+            throw watchError(cause);
+        }
+    }
+    add(name, identity) {
+        try {
+            this.binding.watchAdd(this.id, { root: this.root.rootReal, relative: name,
+                rootDev: BigInt(this.root.rootIdentity.dev), rootIno: BigInt(this.root.rootIdentity.ino), ...identity });
+        }
+        catch (cause) {
+            throw watchError(cause);
+        }
+    }
+    testEvent(path, flags) { this.binding.watchTestEvent(this.id, path, flags); }
+    close() {
+        const id = this.id;
+        this.id = undefined; // Fence queued TSFN callbacks before synchronous native join.
+        if (id !== undefined)
+            this.binding.watchUnregister(id);
+    }
+}
+function watchError(cause) {
+    const code = cause?.code;
+    return new FsSafeError(code === "ENOTSUP" ? "helper-unavailable" : ["ESTALE", "ENOTDIR", "ELOOP"].includes(code ?? "") ? "path-mismatch" : code === "ENOENT" ? "not-found" : "helper-failed", "native watch registration failed", {
+        cause, details: { operation: "watch", code },
+    });
+}

package/dist/watch-scan.d.ts

@@ -0,0 +1,24 @@
+import { type RootContext } from "./root-context.js";
+import { type RootDirectoryObservationGuard } from "./root-directory-list.js";
+import type { WatchOptions, WatchScope } from "./watch-types.js";
+export type DirectoryIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+export type WatchSnapshot = {
+    entries: Map<string, string>;
+    directories: Map<string, DirectoryIdentity>;
+    targets: Map<string, DirectoryIdentity>;
+    scanned: number;
+    structural?: Set<string>;
+    overflow?: boolean;
+};
+export declare function watchScopes(input: readonly WatchScope[]): readonly WatchScope[];
+/** A descendant's unavailable metadata never grants it authority or retires the Root. */
+export declare function isWatchPathError(error: unknown): boolean;
+export declare function scanWatch(root: RootContext, scopes: readonly WatchScope[], options: Pick<WatchOptions, "exclude"> & {
+    maxEntries: number;
+    maxDirectories: number;
+    maxPendingPaths: number;
+    admitting: boolean;
+}, signal: AbortSignal, register: (name: string, identity: DirectoryIdentity, guard: RootDirectoryObservationGuard) => Promise<void>, onCleanupFailure?: (error: unknown) => void): Promise<WatchSnapshot>;