@openclaw/fs-safe 0.18.2 → 0.20.0

package/dist/native-binding.d.ts

@@ -1,6 +1,7 @@
 import type { TarMeterLimits } from "./archive-limits.js";
 import type { ArchiveMemberKind } from "./archive-plan.js";
 import type { CopyCloneMode } from "./copy-policy.js";
+import type { WindowsAceFlags } from "./owner-dacl.js";
 export interface NativeFileHash {
     bytes: number;
     digest: string;
@@ -58,16 +59,7 @@ export interface NativeWindowsAccessControlEntry {
     sid: string;
     mask: number;
     aceType: string;
-    flags: {
-        raw: number;
-        objectInherit: boolean;
-        containerInherit: boolean;
-        noPropagateInherit: boolean;
-        inheritOnly: boolean;
-        inherited: boolean;
-        successfulAccess: boolean;
-        failedAccess: boolean;
-    };
+    flags: WindowsAceFlags;
 }
 export interface NativeWindowsSecurityFacts {
     ownerSid: string;
@@ -96,6 +88,12 @@ export interface NativeWindowsDirectoryReceipt {
 export interface NativeDarwinAclFacts {
     state: "absent" | "empty" | "present";
 }
+type NativeTwoPathArgs = [
+    sourceRootFd: number,
+    sourceRelPath: string,
+    targetRootFd: number,
+    targetRelPath: string
+];
 export interface NativeBinding {
     /** Internal: consumes only a descriptor returned by this binding. */
     closeOwnedFd(fd: number): void;
@@ -125,6 +123,11 @@ export interface NativeBinding {
     readCloneFileMetadata(paths: string[]): Promise<(Buffer | null)[]>;
     probeTreeClone(parentFd: number): "apfs" | "btrfs" | "refs" | "xfs" | "zfs" | null;
     cloneTree(sourceFd: number | null, parentFd: number, basename: string, concurrency: number, signal?: AbortSignal): Promise<void>;
+    openStagedSymlink?(parentFd: number, basename: string): number;
+    stagedSymlinkTarget?(parentFd: number, basename: string, linkFd: number): string;
+    stagedSymlinkMatches?(parentFd: number, basename: string, linkFd: number): boolean;
+    publishStagedSymlink?(parentFd: number, basename: string, linkFd: number, destination: string): void;
+    removeStagedSymlink?(parentFd: number, basename: string, linkFd: number): "removed" | "name-absent" | "preserved";
     createStagedFile?(parentFd: number, basename: string): number;
     stagedFileMatches?(parentFd: number, basename: string, fileFd: number): boolean;
     removeStagedFile?(parentFd: number, basename: string, fileFd: number): "removed" | "name-absent" | "preserved";
@@ -141,7 +144,7 @@ export interface NativeBinding {
     extractArchiveNative(path: string, kind: string, rootFd: number, plan: NativeArchivePlanEntry[], limits: TarMeterLimits, signal: AbortSignal): Promise<void>;
     fstatIdentity(fd: number): NativeFileIdentity;
     inspectArchiveNative(path: string, kind: string, limits: TarMeterLimits, signal: AbortSignal): Promise<NativeArchiveEntry[]>;
-    linkBeneath(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
+    linkBeneath(...args: NativeTwoPathArgs): void;
     /** Direct-child mkdir; true is receipt provenance only, never cleanup ownership. */
     mkdirChildBeneath?(parentFd: number, basename: string, mode: number): boolean;
     mkdirBeneath(rootFd: number, relPath: string, mode: number): void;
@@ -153,10 +156,11 @@ export interface NativeBinding {
     ownedTreeRemovalAvailable?(parentFd: number): boolean;
     removeOwnedTree?(parentFd: number, basename: string, directoryFd: number): Promise<NativeOwnedTreeRemovalResult>;
     removeOwnedTreeSync?(parentFd: number, basename: string, directoryFd: number): NativeOwnedTreeRemovalResult;
-    renameNoReplace(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
+    renameNoReplace(...args: NativeTwoPathArgs): void;
     /** Identity-fenced retained-directory rename capability. */
-    renameNoReplaceWithIdentity?(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string, expectedSourceDev: bigint, expectedSourceIno: bigint): void;
-    renameReplace(sourceRootFd: number, sourceRelPath: string, targetRootFd: number, targetRelPath: string): void;
+    renameNoReplaceWithIdentity?(...args: [...paths: NativeTwoPathArgs, expectedSourceDev: bigint, expectedSourceIno: bigint]): void;
+    renameReplace(...args: NativeTwoPathArgs): void;
     sha256File(fd: number, maxBytes?: number, signal?: AbortSignal): Promise<NativeFileHash>;
 }
 export declare function captureNativeFdClose(binding: NativeBinding): (fd: number) => void;
+export {};

package/dist/native-staged-symlink.d.ts

@@ -0,0 +1,13 @@
+import { type BigIntStats, type Stats } from "node:fs";
+import type { DirectoryReceipt } from "./directory-durability.js";
+import type { StagedSymlink, StagedSymlinkExpected } from "./staged-symlink-types.js";
+/**
+ * Admit an existing staged symlink against caller-captured identity and retain
+ * its no-follow descriptor. Admission never creates, adopts by target, or unlinks.
+ */
+export declare function retainSymlinkInDirectory(options: {
+    directory: string | DirectoryReceipt<Stats | BigIntStats>;
+    basename: string;
+    expected: StagedSymlinkExpected;
+    assertBeforeMutation: () => void;
+}): Promise<StagedSymlink>;

package/dist/native-staged-symlink.js

@@ -0,0 +1,303 @@
+import fs, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { captureNativeFdClose } from "./native-binding.js";
+import { requireNativeBinding } from "./native.js";
+import { classifyNativeRenameFailure } from "./native-rename-outcome.js";
+import { assertStagedDirectoryCurrent, openStagedDirectory } from "./staged-directory.js";
+import { createStagedFileReceipt } from "./staged-file-settlement.js";
+const NOT_PUBLISHED = Object.freeze({ status: "not-published" });
+function basename(name) {
+    if (typeof name !== "string" || !name || name === "." || name === ".." ||
+        /[/\\:\u0000-\u001f\u007f-\u009f\u2028\u2029]/u.test(name)) {
+        throw new FsSafeError("invalid-path", "staged symlinks require a direct-child basename");
+    }
+}
+function failure(error, details) {
+    let code = "helper-failed";
+    try {
+        code = error instanceof FsSafeError ? error.code
+            : error?.code === "EEXIST" ? "already-exists" : "helper-failed";
+    }
+    catch {
+        // Uninspectable error metadata must not interrupt terminal settlement.
+    }
+    return new FsSafeError(code, `staged symlink ${details.phase} failed`, { cause: error, details });
+}
+function assertAuthority(assertion) {
+    assertSynchronousCallbackResult(assertion(), "assertBeforeMutation");
+}
+function expectedIdentity(stat, expected) {
+    return stat.isSymbolicLink() && stat.nlink === 1n &&
+        stat.dev === expected.dev && stat.ino === expected.ino &&
+        stat.uid === BigInt(expected.uid) && stat.gid === BigInt(expected.gid) &&
+        stat.ctimeNs === expected.ctimeNs;
+}
+class NativeStagedSymlink {
+    #publication = NOT_PUBLISHED;
+    #closed;
+    #removal;
+    #busy = false;
+    #receipt;
+    #binding;
+    #parentFd;
+    #linkFd;
+    #closeLink;
+    #assertion;
+    constructor(receipt, binding, parentFd, linkFd, closeLink, assertion) {
+        this.#receipt = receipt;
+        this.#binding = binding;
+        this.#parentFd = parentFd;
+        this.#linkFd = linkFd;
+        this.#closeLink = closeLink;
+        this.#assertion = assertion;
+    }
+    get receipt() { return this.#receipt; }
+    #idle() {
+        if (this.#busy)
+            throw new FsSafeError("helper-failed", "reentrant symlink operation");
+    }
+    #open() {
+        if (this.#closed)
+            throw new FsSafeError("helper-failed", "staged symlink is closed");
+    }
+    #matches(name) {
+        if (!this.#binding.stagedSymlinkMatches(this.#parentFd, name, this.#linkFd))
+            return false;
+        const stat = fs.fstatSync(this.#linkFd, { bigint: true });
+        const identity = this.#receipt.identity;
+        // ctime changes on rename; identity, ownership, mode and target do not.
+        return stat.dev === identity.dev && stat.ino === identity.ino &&
+            stat.uid === BigInt(identity.uid) && stat.gid === BigInt(identity.gid) &&
+            Number(stat.mode & 4095n) === identity.mode && stat.nlink === 1n &&
+            this.#binding.stagedSymlinkTarget(this.#parentFd, name, this.#linkFd) === this.#receipt.target;
+    }
+    #assertNamed(name) {
+        if (!this.#matches(name))
+            throw new FsSafeError("path-mismatch", "symlink no longer names the retained object");
+    }
+    #assertCurrent() {
+        this.#open();
+        if (this.#publication.status !== "not-published") {
+            throw new FsSafeError("helper-failed", "symlink publication has already been attempted");
+        }
+        assertStagedDirectoryCurrent(this.#receipt.directory);
+        this.#assertNamed(this.#receipt.temporaryBasename);
+    }
+    async assertCurrent() { this.#idle(); this.#assertCurrent(); }
+    async publish(name) {
+        this.#idle();
+        this.#busy = true;
+        try {
+            basename(name);
+            if (name === this.#receipt.temporaryBasename) {
+                throw new FsSafeError("invalid-path", "publication requires a distinct basename");
+            }
+            this.#assertCurrent();
+            assertAuthority(this.#assertion);
+            // A synchronous caller assertion can itself change either pathname.
+            this.#assertCurrent();
+            try {
+                this.#binding.publishStagedSymlink(this.#parentFd, this.#receipt.temporaryBasename, this.#linkFd, name);
+            }
+            catch (error) {
+                let outcome = "indeterminate";
+                try {
+                    outcome = classifyNativeRenameFailure(error);
+                }
+                catch {
+                    // Unreadable diagnostics cannot prove that the rename was uncommitted.
+                }
+                if (outcome === "indeterminate") {
+                    this.#publication = Object.freeze({ status: "indeterminate", basename: name, overwrite: false });
+                }
+                throw error;
+            }
+            const published = Object.freeze({
+                status: "published", staged: this.#receipt, basename: name, overwrite: false,
+            });
+            // Record dispatch success before any fallible post-observation.
+            this.#publication = published;
+            this.#assertNamed(name);
+            assertStagedDirectoryCurrent(this.#receipt.directory);
+            return published;
+        }
+        catch (error) {
+            throw failure(error, { phase: "publish", publication: this.#publication });
+        }
+        finally {
+            this.#busy = false;
+        }
+    }
+    #publishedName() {
+        this.#open();
+        if (this.#publication.status !== "published" || this.#removal) {
+            throw new FsSafeError("helper-failed", "no unsettled published symlink");
+        }
+        return this.#publication.basename;
+    }
+    async assertPublished() {
+        this.#idle();
+        const name = this.#publishedName();
+        assertStagedDirectoryCurrent(this.#receipt.directory);
+        this.#assertNamed(name);
+    }
+    #remove(name) {
+        try {
+            if (!this.#matches(name))
+                return "preserved";
+        }
+        catch (error) {
+            let missing = false;
+            try {
+                missing = error?.code === "ENOENT";
+            }
+            catch {
+                // Even a failed errno inspection must retain the original cause.
+            }
+            if (missing)
+                return "name-absent";
+            throw error;
+        }
+        assertAuthority(this.#assertion);
+        // Recheck after application code and immediately before guarded native unlink.
+        if (!this.#matches(name))
+            return "preserved";
+        return this.#binding.removeStagedSymlink(this.#parentFd, name, this.#linkFd);
+    }
+    async removePublished() {
+        this.#idle();
+        this.#open();
+        if (this.#removal) {
+            if (this.#removal.error)
+                throw this.#removal.error;
+            return this.#removal.receipt;
+        }
+        const name = this.#publishedName();
+        this.#busy = true;
+        try {
+            const receipt = this.#remove(name);
+            this.#removal = { receipt };
+            return receipt;
+        }
+        catch (error) {
+            const wrapped = failure(error, { phase: "remove-published", publication: this.#publication });
+            // A failed unlink is not safe to retry automatically.
+            this.#removal = { error: wrapped };
+            throw wrapped;
+        }
+        finally {
+            this.#busy = false;
+        }
+    }
+    async cleanup() {
+        this.#idle();
+        if (this.#closed) {
+            if (this.#closed.error)
+                throw this.#closed.error;
+            return this.#closed.receipt;
+        }
+        this.#busy = true;
+        let status = "not-needed";
+        const errors = [];
+        if (this.#publication.status === "indeterminate")
+            status = "preserved";
+        else if (this.#publication.status === "not-published") {
+            try {
+                status = this.#remove(this.#receipt.temporaryBasename);
+            }
+            catch (error) {
+                status = "failed";
+                errors.push(error);
+            }
+        }
+        let resources = "closed";
+        for (const close of [() => this.#closeLink(this.#linkFd), () => fs.closeSync(this.#parentFd)]) {
+            try {
+                close();
+            }
+            catch (error) {
+                resources = "close-failed";
+                errors.push(error);
+            }
+        }
+        const receipt = Object.freeze({
+            temporaryBasename: this.#receipt.temporaryBasename,
+            publication: this.#publication, status, resources,
+        });
+        const error = errors.length ? failure(errors.length === 1 ? errors[0] : new AggregateError(errors, "symlink settlement failed"), { phase: "cleanup", publication: this.#publication, cleanup: receipt }) : undefined;
+        this.#closed = { receipt, error };
+        this.#busy = false;
+        if (error)
+            throw error;
+        return receipt;
+    }
+    async [Symbol.asyncDispose]() {
+        const cleanup = await this.cleanup();
+        if (cleanup.status === "preserved") {
+            throw new FsSafeError("not-removable", "symlink settlement preserved an unverified entry", {
+                details: { phase: "cleanup", publication: this.#publication, cleanup },
+            });
+        }
+    }
+}
+/**
+ * Admit an existing staged symlink against caller-captured identity and retain
+ * its no-follow descriptor. Admission never creates, adopts by target, or unlinks.
+ */
+export async function retainSymlinkInDirectory(options) {
+    if (process.platform !== "linux" && process.platform !== "darwin") {
+        throw new FsSafeError("unsupported-platform", "retained symlinks require Linux or macOS");
+    }
+    const native = requireNativeBinding();
+    if ([
+        native.closeOwnedFd, native.openStagedSymlink, native.stagedSymlinkTarget,
+        native.stagedSymlinkMatches, native.publishStagedSymlink, native.removeStagedSymlink,
+    ].some((fn) => typeof fn !== "function")) {
+        throw new FsSafeError("helper-unavailable", "native retained symlink support is unavailable");
+    }
+    const binding = native;
+    const name = options.basename;
+    basename(name);
+    const expected = Object.freeze({ ...options.expected });
+    const assertion = options.assertBeforeMutation;
+    if (typeof assertion !== "function" || typeof expected.dev !== "bigint" ||
+        typeof expected.ino !== "bigint" || typeof expected.ctimeNs !== "bigint" ||
+        !Number.isSafeInteger(expected.uid) || expected.uid < 0 ||
+        !Number.isSafeInteger(expected.gid) || expected.gid < 0 ||
+        typeof expected.target !== "string" || !expected.target || expected.target.includes("\0")) {
+        throw new FsSafeError("invalid-path", "exact symlink identity, target and synchronous authority are required");
+    }
+    const closeLink = captureNativeFdClose(binding);
+    const parent = openStagedDirectory(options.directory);
+    let fd;
+    try {
+        fd = binding.openStagedSymlink(parent.fd, name);
+        const stat = fs.fstatSync(fd, { bigint: true });
+        if (!expectedIdentity(stat, expected) ||
+            binding.stagedSymlinkTarget(parent.fd, name, fd) !== expected.target) {
+            throw new FsSafeError("path-mismatch", "staged symlink does not match the supplied identity");
+        }
+        const receipt = Object.freeze({
+            ...createStagedFileReceipt(parent.receipt, name, stat), target: expected.target,
+        });
+        assertAuthority(assertion);
+        const owner = new NativeStagedSymlink(receipt, binding, parent.fd, fd, closeLink, assertion);
+        await owner.assertCurrent();
+        return owner;
+    }
+    catch (error) {
+        const errors = [error];
+        for (const close of [() => { if (fd !== undefined)
+                closeLink(fd); }, () => fs.closeSync(parent.fd)]) {
+            try {
+                close();
+            }
+            catch (closeError) {
+                errors.push(closeError);
+            }
+        }
+        // Until admission succeeds, the caller retains every namespace cleanup duty.
+        throw failure(errors.length === 1 ? error : new AggregateError(errors, "symlink admission and close failed"), { phase: "prepare", publication: NOT_PUBLISHED });
+    }
+}

package/dist/owner-dacl-batch-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/owner-dacl-batch-worker.js

@@ -0,0 +1,54 @@
+// One isolated process owns every native query in a batch, including stuck OS calls.
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { configureFsSafeNative } from "./native-config.js";
+import { formatCaughtPermissionFailure } from "./permission-exec.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+const MAX_INPUT_BYTES = 16 * 1024 * 1024;
+async function inspectBatch() {
+    const mode = process.env.FS_SAFE_OWNER_DACL_BATCH_MODE;
+    if (mode !== "auto" && mode !== "require") {
+        throw new FsSafeError("helper-unavailable", "isolated Windows native inspection was not enabled");
+    }
+    configureFsSafeNative({ mode });
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.byteLength;
+        if (bytes > MAX_INPUT_BYTES)
+            throw new Error("Windows security batch exceeded its input budget");
+        chunks.push(buffer);
+    }
+    const paths = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)));
+    if (!Array.isArray(paths) || !paths.every(value => typeof value === "string" && value && !value.includes("\0"))) {
+        throw new Error("Windows security batch contains invalid paths");
+    }
+    for (const pathname of paths)
+        assertNoWindowsPathAlias(pathname);
+    const binding = getNativeBinding();
+    const inspect = binding?.readOwnerAndDacl;
+    if (!binding || typeof inspect !== "function") {
+        throw new FsSafeError("helper-unavailable", "isolated Windows native inspection is unavailable");
+    }
+    const result = [];
+    let outputBytes = Buffer.byteLength(JSON.stringify({ ok: true, result: [] }));
+    for (const pathname of paths) {
+        const row = { path: pathname, security: inspect.call(binding, pathname) };
+        outputBytes += Buffer.byteLength(JSON.stringify(row)) + (result.length ? 1 : 0);
+        if (outputBytes > MAX_INPUT_BYTES) {
+            throw new FsSafeError("too-large", "Windows security batch exceeded its output budget");
+        }
+        result.push(row);
+    }
+    return result;
+}
+try {
+    const result = await inspectBatch();
+    process.stdout.write(JSON.stringify({ ok: true, result }));
+}
+catch (error) {
+    const code = error && typeof error === "object" && "code" in error && typeof error.code === "string"
+        ? error.code : "EIO";
+    process.stdout.write(JSON.stringify({ ok: false, code, message: formatCaughtPermissionFailure(error) }));
+}

package/dist/owner-dacl-batch.d.ts

@@ -0,0 +1,5 @@
+import { type OwnerAndDaclResult } from "./owner-dacl.js";
+/** Inspect an ordered batch outside the caller's event loop, without applying trust policy. */
+export declare function readOwnerAndDaclBatch(paths: readonly string[], options?: {
+    timeoutMs?: number;
+}): Promise<OwnerAndDaclResult[]>;

package/dist/owner-dacl-batch.js

@@ -0,0 +1,64 @@
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { warnNativeFallback } from "./native-fallback-warning.js";
+import { projectOwnerAndDacl } from "./owner-dacl.js";
+import { anchorWindowsDriveRelativePath, assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { readWindowsSecurityFactsBatch, WINDOWS_SECURITY_BATCH_MAX_BYTES } from "./windows-security-command.js";
+const DEFAULT_BATCH_TIMEOUT_MS = 60_000;
+function snapshotPaths(paths) {
+    if (!Array.isArray(paths))
+        throw new TypeError("paths must be an array of path strings");
+    const length = paths.length;
+    const selected = [];
+    let bytes = 2;
+    for (let index = 0; index < length; index += 1) {
+        const value = paths[index];
+        if (!Object.hasOwn(paths, index) || typeof value !== "string" || !value || value.includes("\0")) {
+            throw new TypeError("paths must contain nonempty path strings without null bytes");
+        }
+        let captured = value;
+        if (process.platform === "win32") {
+            captured = anchorWindowsDriveRelativePath(value);
+            assertNoWindowsPathAlias(captured, "filesystem", "owner and DACL path uses a Windows filesystem namespace alias");
+            const root = path.win32.parse(captured).root;
+            // Anchor cwd-dependent paths without normalizing their physical . or .. suffix.
+            if (root.length <= 1 || !path.win32.isAbsolute(captured)) {
+                const base = path.win32.resolve(root || ".");
+                captured = `${base}${base.endsWith("\\") ? "" : "\\"}${captured.slice(root.length)}`;
+            }
+            assertNoWindowsPathAlias(captured, "filesystem", "owner and DACL path uses a Windows filesystem namespace alias");
+        }
+        bytes += Buffer.byteLength(JSON.stringify(captured), "utf8") + (index ? 1 : 0);
+        if (bytes > WINDOWS_SECURITY_BATCH_MAX_BYTES) {
+            throw new FsSafeError("too-large", "owner and DACL batch exceeds its input budget");
+        }
+        selected.push(captured);
+    }
+    return selected;
+}
+/** Inspect an ordered batch outside the caller's event loop, without applying trust policy. */
+export async function readOwnerAndDaclBatch(paths, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_BATCH_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+        throw new RangeError("timeoutMs must be a positive integer no greater than 2147483647");
+    }
+    const selected = snapshotPaths(paths);
+    if (process.platform !== "win32") {
+        return selected.map(() => ({ status: "unsupported-platform", platform: process.platform }));
+    }
+    if (selected.length === 0)
+        return [];
+    const config = getFsSafeNativeConfig();
+    const native = getNativeBinding();
+    const useNative = typeof native?.readOwnerAndDacl === "function";
+    if (!useNative) {
+        if (config.mode === "require") {
+            throw new FsSafeError("helper-unavailable", "Windows owner and DACL facts require an up-to-date native helper");
+        }
+        warnNativeFallback("windows-owner-dacl", "Windows owner and DACL inspection uses a slower built-in system command.");
+    }
+    const facts = await readWindowsSecurityFactsBatch(selected, { timeoutMs, native: useNative, mode: config.mode });
+    return facts.map(projectOwnerAndDacl);
+}

package/dist/owner-dacl.d.ts

@@ -1,3 +1,4 @@
+import type { DescriptorFacts } from "./windows-security-facts.js";
 export type WindowsAceFlags = {
     raw: number;
     objectInherit: boolean;
@@ -28,3 +29,4 @@ export type OwnerAndDaclResult = {
     platform: NodeJS.Platform;
 };
 export declare function readOwnerAndDacl(targetPath: string): OwnerAndDaclResult;
+export declare function projectOwnerAndDacl(facts: DescriptorFacts): OwnerAndDaclResult;

package/dist/owner-dacl.js

@@ -18,6 +18,9 @@ export function readOwnerAndDacl(targetPath) {
         warnNativeFallback("windows-owner-dacl", "Windows owner and DACL inspection uses a slower built-in system command.");
     }
     const facts = typeof inspect === "function" ? inspect.call(native, targetPath) : readWindowsSecurityFactsCommand(targetPath);
+    return projectOwnerAndDacl(facts);
+}
+export function projectOwnerAndDacl(facts) {
     return {
         status: "supported",
         ownerSid: facts.ownerSid,

package/dist/path.js

@@ -81,7 +81,23 @@ export function isPathInside(root, target) {
     return relative === "" || (firstSegment !== ".." && !path.isAbsolute(relative));
 }
 export function isPathRelativeEscape(relativePath) {
-    return relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
+    if (path.isAbsolute(relativePath)) {
+        return true;
+    }
+    let depth = 0;
+    // Windows accepts both separators; POSIX backslashes are filename bytes.
+    const segments = relativePath.split(process.platform === "win32" ? /[/\\]/ : /\//);
+    for (const segment of segments) {
+        if (segment === "..") {
+            if (depth === 0)
+                return true;
+            depth -= 1;
+        }
+        else if (segment !== "" && segment !== ".") {
+            depth += 1;
+        }
+    }
+    return false;
 }
 export function resolveSafeBaseDir(rootDir) {
     const resolved = path.resolve(rootDir);

package/dist/permission-exec.js

@@ -58,14 +58,11 @@ function dataProperty(value, name) {
     }
     return undefined;
 }
-function caughtPrimitiveDisplay(value) {
-    if (value !== null && (typeof value === "object" || typeof value === "function"))
-        return undefined;
-    return primitiveString(value);
-}
 /** Formats only caught permission-query failures without invoking user code. */
 export function formatCaughtPermissionFailure(error) {
-    const primitive = caughtPrimitiveDisplay(error);
+    const primitive = error !== null && (typeof error === "object" || typeof error === "function")
+        ? undefined
+        : primitiveString(error);
     if (primitive !== undefined)
         return formatBoundedCaughtDetail(primitive);
     if (!isInspectableCaughtObject(error)) {

package/dist/permissions-public.d.ts

@@ -2,3 +2,4 @@ export { formatOctal, formatPermissionDetail, formatPermissionRemediation, inspe
 export type { PermissionCommandFailure } from "./permission-exec.js";
 export { createPrivateDirectory, type CreatePrivateDirectoryOptions, } from "./private-directory.js";
 export { readOwnerAndDacl, type OwnerAndDaclResult, type WindowsAccessControlEntry, type WindowsAceFlags, } from "./owner-dacl.js";
+export { readOwnerAndDaclBatch } from "./owner-dacl-batch.js";

package/dist/permissions-public.js

@@ -1,3 +1,4 @@
 export { formatOctal, formatPermissionDetail, formatPermissionRemediation, inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, safeStat, } from "./permissions.js";
 export { createPrivateDirectory, } from "./private-directory.js";
 export { readOwnerAndDacl, } from "./owner-dacl.js";
+export { readOwnerAndDaclBatch } from "./owner-dacl-batch.js";

package/dist/pinned-mutation-admission.d.ts

@@ -9,7 +9,6 @@ export type PinnedMutationPolicySnapshot = Readonly<{
 export declare function snapshotPinnedMutationPolicy(denyMutations: DenyMutationPolicy | undefined, mutationSymlinks: MutationSymlinkPolicy | undefined): PinnedMutationPolicySnapshot | undefined;
 export declare function preparePinnedWriteMutationAdmission(params: {
     rootReal: string;
-    rootWithSep: string;
     rootIdentity?: RootBoundaryIdentity;
     resolvedTargetPath: string;
     defaultRelativeParentPath: string;

package/dist/pinned-mutation-shared-route.d.ts

@@ -1,14 +1,9 @@
-import type { DenyMutationPolicy } from "./deny-mutations.js";
+import type { PinnedMutationPolicySnapshot } from "./pinned-mutation-admission.js";
 import type { RootBoundaryIdentity } from "./root-boundary.js";
-import type { MutationSymlinkPolicy } from "./root-symlink-policy.js";
 export type ExactRootIdentity = Readonly<{
     dev: bigint;
     ino: bigint;
 }>;
-type SharedMutationPolicy = Readonly<{
-    denyMutations?: DenyMutationPolicy;
-    mutationSymlinks?: MutationSymlinkPolicy;
-}>;
 export declare function ordinaryWindowsSegments(relativePath: string): boolean;
 export declare function ordinarySharedAbsoluteInsideRoot(rootReal: string, candidatePath: string, rootIdentity: ExactRootIdentity): boolean;
 export declare function simpleSharedRoute(params: {
@@ -16,9 +11,8 @@ export declare function simpleSharedRoute(params: {
     rootIdentity?: RootBoundaryIdentity;
     originalPath?: string;
     selectedTarget: string;
-    policy: SharedMutationPolicy;
+    policy: PinnedMutationPolicySnapshot;
 }): {
     route: string;
     rootIdentity: ExactRootIdentity;
 } | undefined;
-export {};

package/dist/pinned-open.d.ts

@@ -14,7 +14,6 @@ export type PinnedOpenSyncResult = {
 export type PinnedOpenSyncAllowedType = "file" | "directory";
 export type PinnedOpenSyncFinalAdmission = (params: {
     path: string;
-    preRealpathIdentity: fs.BigIntStats;
     descriptorIdentity: fs.BigIntStats;
 }) => string;
 export type PinnedOpenSyncFs = Pick<typeof fs, "constants" | "lstatSync" | "realpathSync" | "openSync" | "fstatSync" | "closeSync">;

package/dist/pinned-open.js

@@ -53,14 +53,13 @@ export function openPinnedFileSync(params) {
             assertAllowedStat(stat, allowedType, statPolicy);
             return stat;
         }, preOpenStat);
-        const pathIdentity = inspectFileIdentitySync(() => {
+        inspectFileIdentitySync(() => {
             const stat = ioFs.lstatSync(realPath, { bigint: true });
             assertAllowedStat(stat, allowedType, statPolicy);
             return stat;
         }, identity);
         const admittedPath = params.finalAdmission?.({
             path: realPath,
-            preRealpathIdentity: pathIdentity,
             descriptorIdentity: identity,
         }) ?? realPath;
         const opened = { ok: true, path: admittedPath, fd, stat: openedStat, identity };