@openclaw/fs-safe 0.14.0 → 0.16.0

package/dist/temp-workspace-descriptor.js

@@ -185,18 +185,15 @@ export class TempWorkspaceRetainedChild {
         return descriptor;
     }
     async #assertProcAuthority(fd, ownerUid) {
-        if ((await fs.statfs("/proc/self/fd", { bigint: true })).type !== 0x9fa0n) {
-            throw new FsSafeError("path-mismatch", "directory mode requires a trusted procfs fd namespace");
-        }
-        const procPath = `/proc/self/fd/${fd}`;
-        const opened = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), this.#identity);
-        const followed = inspectFileIdentitySync(() => fsSync.statSync(procPath, { bigint: true }), this.#identity);
-        assertOwnedDirectory(opened, followed);
-        assertTempWorkspaceChildState(opened, ownerUid);
-        assertTempWorkspaceChildState(followed, ownerUid);
+        const filesystem = await fs.statfs("/proc/self/fd", { bigint: true });
+        this.#assertProcDescriptorAuthority(fd, ownerUid, filesystem.type);
     }
     #assertProcAuthoritySync(fd, ownerUid) {
-        if (fsSync.statfsSync("/proc/self/fd", { bigint: true }).type !== 0x9fa0n) {
+        const filesystem = fsSync.statfsSync("/proc/self/fd", { bigint: true });
+        this.#assertProcDescriptorAuthority(fd, ownerUid, filesystem.type);
+    }
+    #assertProcDescriptorAuthority(fd, ownerUid, filesystemType) {
+        if (filesystemType !== 0x9fa0n) {
             throw new FsSafeError("path-mismatch", "directory mode requires a trusted procfs fd namespace");
         }
         const procPath = `/proc/self/fd/${fd}`;
@@ -309,13 +306,7 @@ export class TempWorkspaceRetainedChild {
         catch (error) {
             // The readable replacement has not been installed. Give it exactly one
             // close attempt and leave neither indeterminate descriptor owned here.
-            try {
-                fsSync.closeSync(fd);
-            }
-            catch (closeError) {
-                throw new AggregateError([error, closeError], "temp workspace child descriptor replacement close failed");
-            }
-            throw error;
+            closeAfterAdmissionFailure(fd, error, "temp workspace child descriptor replacement close failed");
         }
         this.#fd = fd;
         this.#access = "read";
@@ -334,16 +325,7 @@ export class TempWorkspaceRetainedChild {
         const fd = this.#fd;
         this.#fd = undefined;
         if (retainDescriptor && !this.canEnumerate) {
-            try {
-                fsSync.closeSync(fd);
-            }
-            catch (closeError) {
-                throw new AggregateError([
-                    new FsSafeError("helper-unavailable", "temp workspace cleanup requires a readable child descriptor"),
-                    closeError,
-                ], "temp workspace child descriptor rejection and close failed");
-            }
-            throw new FsSafeError("helper-unavailable", "temp workspace cleanup requires a readable child descriptor");
+            closeAfterAdmissionFailure(fd, new FsSafeError("helper-unavailable", "temp workspace cleanup requires a readable child descriptor"), "temp workspace child descriptor rejection and close failed");
         }
         if (!retainDescriptor) {
             fsSync.closeSync(fd);

package/dist/temp-workspace-owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-workspace-owner.d.ts","sourceRoot":"","sources":["../src/temp-workspace-owner.ts"],"names":[],"mappings":"AAOA,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAEL,0BAA0B,EAE1B,KAAK,iBAAiB,EACvB,MAAM,gCAAgC,CAAC;AAGxC,MAAM,MAAM,0BAA0B,GAAG,SAAS,GAAG,SAAS,GAAG,mBAAmB,GAAG,eAAe,CAAC;AACvG,MAAM,MAAM,0BAA0B,GAAG,YAAY,GAAG,iBAAiB,CAAC;AAsB1E,qBAAa,8BAA8B;;IACzC,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAM/C,YACE,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,0BAA0B,EAClC,SAAS,EAAE,0BAA0B,EACrC,OAAO,EAAE,MAAM,EAuEhB;IAED,IAAI,kBAAkB,IAAI,OAAO,CAGhC;IAED,oBAAoB,IAAI,IAAI,CAiB3B;IAUD,oBAAoB,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAenD;IAED,aAAa,IAAI,IAAI,CAEpB;IAED,qBAAqB,IAAI,IAAI,CAE5B;IAED,KAAK,IAAI,IAAI,CAIZ;CACF;AAED,qBAAa,yBAAyB;;IAWpC,YACE,QAAQ,EAAE,0BAA0B,EACpC,UAAU,EAAE,8BAA8B,EAC1C,gBAAgB,EAAE,OAAO,EAO1B;IAkLD,OAAO,IAAI,OAAO,CAAC,0BAA0B,CAAC,CAM7C;IAED,WAAW,IAAI,0BAA0B,CAexC;CACF"}
+{"version":3,"file":"temp-workspace-owner.d.ts","sourceRoot":"","sources":["../src/temp-workspace-owner.ts"],"names":[],"mappings":"AAOA,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAChF,OAAO,EAEL,0BAA0B,EAE1B,KAAK,iBAAiB,EACvB,MAAM,gCAAgC,CAAC;AAGxC,MAAM,MAAM,0BAA0B,GAAG,SAAS,GAAG,SAAS,GAAG,mBAAmB,GAAG,eAAe,CAAC;AACvG,MAAM,MAAM,0BAA0B,GAAG,YAAY,GAAG,iBAAiB,CAAC;AAuB1E,qBAAa,8BAA8B;;IACzC,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAM/C,YACE,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,0BAA0B,EAClC,SAAS,EAAE,0BAA0B,EACrC,OAAO,EAAE,MAAM,EAuEhB;IAED,IAAI,kBAAkB,IAAI,OAAO,CAGhC;IAED,oBAAoB,IAAI,IAAI,CAiB3B;IAUD,oBAAoB,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAenD;IAED,aAAa,IAAI,IAAI,CAEpB;IAED,qBAAqB,IAAI,IAAI,CAE5B;IAED,KAAK,IAAI,IAAI,CAIZ;CACF;AAED,qBAAa,yBAAyB;;IAWpC,YACE,QAAQ,EAAE,0BAA0B,EACpC,UAAU,EAAE,8BAA8B,EAC1C,gBAAgB,EAAE,OAAO,EAO1B;IAkLD,OAAO,IAAI,OAAO,CAAC,0BAA0B,CAAC,CAM7C;IAED,WAAW,IAAI,0BAA0B,CAexC;CACF"}

package/dist/temp-workspace-owner.js

@@ -294,22 +294,22 @@ export class TempWorkspaceCleanupOwner {
                 await beforeNativeRemoval(quarantine.path);
             return this.#mapRemoval(await this.#capability.binding.removeOwnedTree(this.#capability.parent.fd, quarantine.name, this.#directory.fd));
         }
-        let removalError;
+        let removalFailure;
         try {
             this.#assertQuarantine(quarantine);
             try {
                 await fs.rm(quarantine.path, { recursive: true, force: true });
             }
             catch (error) {
-                removalError = error;
+                removalFailure = { error };
                 throw error;
             }
             this.#capability.assertCurrent();
             return "removed";
         }
         catch (error) {
-            if (error === removalError)
-                throw error;
+            if (removalFailure !== undefined)
+                throw removalFailure.error;
             return "indeterminate";
         }
     }
@@ -318,22 +318,22 @@ export class TempWorkspaceCleanupOwner {
             getFsSafeTestHooks()?.beforeTempWorkspaceNativeRemovalSync?.(quarantine.path);
             return this.#mapRemoval(this.#capability.binding.removeOwnedTreeSync(this.#capability.parent.fd, quarantine.name, this.#directory.fd));
         }
-        let removalError;
+        let removalFailure;
         try {
             this.#assertQuarantine(quarantine);
             try {
                 fsSync.rmSync(quarantine.path, { recursive: true, force: true });
             }
             catch (error) {
-                removalError = error;
+                removalFailure = { error };
                 throw error;
             }
             this.#capability.assertCurrent();
             return "removed";
         }
         catch (error) {
-            if (error === removalError)
-                throw error;
+            if (removalFailure !== undefined)
+                throw removalFailure.error;
             return "indeterminate";
         }
     }

package/dist/walk.d.ts

@@ -16,6 +16,10 @@ export type WalkDirectoryOptions = {
     include?: (entry: WalkDirectoryEntry) => boolean;
     descend?: (entry: WalkDirectoryEntry) => boolean;
 };
+export type AsyncWalkDirectoryOptions = Omit<WalkDirectoryOptions, "include" | "descend"> & {
+    include?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
+    descend?: (entry: WalkDirectoryEntry) => boolean | Promise<boolean>;
+};
 export type WalkDirectoryFailure = {
     path: string;
     relativePath: string;
@@ -32,6 +36,6 @@ type WalkDirectoryResultWithFailures = WalkDirectoryResult & {
     failedDirs: WalkDirectoryFailure[];
 };
 export declare function walkDirectorySync(rootDir: string, options?: WalkDirectoryOptions): WalkDirectoryResultWithFailures;
-export declare function walkDirectory(rootDir: string, options?: WalkDirectoryOptions): Promise<WalkDirectoryResultWithFailures>;
+export declare function walkDirectory(rootDir: string, options?: AsyncWalkDirectoryOptions): Promise<WalkDirectoryResultWithFailures>;
 export {};
 //# sourceMappingURL=walk.d.ts.map

package/dist/walk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAS7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IAGnB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAAC;AAEF,KAAK,+BAA+B,GAAG,mBAAmB,GAAG;IAC3D,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AA+EF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,+BAA+B,CA2DjC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,+BAA+B,CAAC,CA2D1C"}
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAS7B,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACjD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC;CAClD,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,oBAAoB,EAAE,SAAS,GAAG,SAAS,CAAC,GAAG;IAC1F,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrE,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IAGnB,UAAU,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACrC,CAAC;AAEF,KAAK,+BAA+B,GAAG,mBAAmB,GAAG;IAC3D,UAAU,EAAE,oBAAoB,EAAE,CAAC;CACpC,CAAC;AAoFF,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,+BAA+B,CA4DjC;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,+BAA+B,CAAC,CAiE1C"}

package/dist/walk.js

@@ -16,6 +16,10 @@ function validateWalkOptions(options) {
         throw new TypeError(`invalid walk symlink policy: ${String(options.symlinks)}`);
     }
 }
+function isObjectResult(result) {
+    return result !== null &&
+        (typeof result === "object" || typeof result === "function");
+}
 function kindForDirent(dirent) {
     if (dirent.isDirectory())
         return "directory";
@@ -85,6 +89,8 @@ export function walkDirectorySync(rootDir, options = {}) {
         let realDir;
         const operationPath = pathForWindowsFilesystem(dir);
         try {
+            if (depth > 1 && symlinks !== "follow" && fsSync.lstatSync(operationPath).isSymbolicLink())
+                return;
             realDir = realpathSync(operationPath);
         }
         catch (error) {
@@ -146,6 +152,8 @@ export async function walkDirectory(rootDir, options = {}) {
         let realDir;
         const operationPath = pathForWindowsFilesystem(dir);
         try {
+            if (depth > 1 && symlinks !== "follow" && fsSync.lstatSync(operationPath).isSymbolicLink())
+                return;
             realDir = realpathSync.native(operationPath);
         }
         catch (error) {
@@ -175,15 +183,20 @@ export async function walkDirectory(rootDir, options = {}) {
                 continue;
             const relativePath = relativeDir ? `${relativeDir}${path.sep}${dirent.name}` : dirent.name;
             const entry = buildEntry({ relativePath, fullPath, dirent, depth, kind });
-            if (options.include?.(entry) ?? true) {
+            const include = options.include;
+            const included = include == null ? true : Reflect.apply(include, options, [entry]);
+            if ((isObjectResult(included) ? await included : included) ?? true) {
                 result.entries.push(entry);
             }
             if (kind === "directory" &&
-                (options.maxDepth === undefined || depth < options.maxDepth) &&
-                (options.descend?.(entry) ?? true)) {
-                await visit(fullPath, relativePath, depth + 1);
-                if (result.truncated)
-                    return;
+                (options.maxDepth === undefined || depth < options.maxDepth)) {
+                const descend = options.descend;
+                const descended = descend == null ? true : Reflect.apply(descend, options, [entry]);
+                if ((isObjectResult(descended) ? await descended : descended) ?? true) {
+                    await visit(fullPath, relativePath, depth + 1);
+                    if (result.truncated)
+                        return;
+                }
             }
         }
     }

package/dist/windows-owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"windows-owner.d.ts","sourceRoot":"","sources":["../src/windows-owner.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAI9B,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,IAAI,CAAC,EAAE,eAAe,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAqDF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmD/B"}
+{"version":3,"file":"windows-owner.d.ts","sourceRoot":"","sources":["../src/windows-owner.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAI9B,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,IAAI,CAAC,EAAE,eAAe,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC;AAsDF,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmD/B"}

package/dist/windows-owner.js

@@ -1,4 +1,4 @@
-import { formatPermissionErrorDetail, getPermissionCommandFailure, } from "./permission-exec.js";
+import { formatCaughtPermissionFailure, formatPermissionErrorDetail, getPermissionCommandFailure, } from "./permission-exec.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
 import { hasWindowsPathAlias } from "./windows-path-alias.js";
 const SID_RE = /^\*?s-\d+-\d+(-\d+)+$/i;
@@ -14,6 +14,7 @@ function windowsOwnerQueryCommand(targetPath) {
     const encodedPath = Buffer.from(targetPath, "utf8").toString("base64");
     return [
         "$ErrorActionPreference='Stop'",
+        "$env:PSModulePath=[IO.Path]::Combine($PSHOME,'Modules')",
         `$p=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPath}'))`,
         "$sections=[System.Security.AccessControl.AccessControlSections]::Access -bor [System.Security.AccessControl.AccessControlSections]::Owner",
         "$acl=if([IO.Directory]::Exists($p)){[IO.Directory]::GetAccessControl($p,$sections)}else{[IO.File]::GetAccessControl($p,$sections)}",
@@ -29,7 +30,7 @@ function windowsOwnerQueryCommand(targetPath) {
         "$raw=[System.Security.AccessControl.RawSecurityDescriptor]::new($acl.GetSecurityDescriptorBinaryForm(),0)",
         "$dacl=$raw.DiscretionaryAcl;$complete=$true",
         "$aces=@(foreach($ace in $dacl){if($ace -isnot [System.Security.AccessControl.CommonAce] -or $ace.IsCallback -or [int]$ace.AceType -notin @(0,1)){$complete=$false;continue};@{sid=$ace.SecurityIdentifier.Value;mask=([long]$ace.AccessMask -band 4294967295);deny=([int]$ace.AceType -eq 1);inheritOnly=([int]$ace.AceFlags -band 8) -ne 0}})",
-        "@{ownerSid=$ownerSid;currentUserSid=$currentSid;daclPresent=($null -ne $dacl);aces=$aces;complete=$complete;remote=$remote}|ConvertTo-Json -Depth 4 -Compress",
+        "@{ownerSid=$ownerSid;currentUserSid=$currentSid;daclPresent=($null -ne $dacl);aces=$aces;complete=$complete;remote=$remote}|Microsoft.PowerShell.Utility\\ConvertTo-Json -Depth 4 -Compress",
     ].join(";");
 }
 function parseWindowsAclFacts(parsed) {
@@ -89,7 +90,7 @@ export async function inspectWindowsOwner(params) {
     }
     catch (err) {
         return {
-            error: formatPermissionErrorDetail(String(err)),
+            error: formatCaughtPermissionFailure(err),
             errorDetail: getPermissionCommandFailure(err, command, performance.now() - startedAt),
             errorCause: err,
         };

package/dist/windows-security-bridge.cs

@@ -0,0 +1,336 @@
+// Executed only by the built-in Windows PowerShell/.NET host. The raw security
+// descriptor never passes through CommonSecurityDescriptor's ACE normalization.
+using System;
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Security.AccessControl;
+using System.Security.Principal;
+using System.Text;
+using Microsoft.Win32.SafeHandles;
+
+public static partial class FsSafeWindowsBridge {
+  [StructLayout(LayoutKind.Sequential)] struct IoStatus { public IntPtr Status; public UIntPtr Information; }
+  [StructLayout(LayoutKind.Sequential)] struct UnicodeString { public ushort Length, MaximumLength; public IntPtr Buffer; }
+  [StructLayout(LayoutKind.Sequential)] struct ObjectAttributes {
+    public uint Length; public IntPtr RootDirectory, ObjectName; public uint Attributes;
+    public IntPtr SecurityDescriptor, SecurityQualityOfService;
+  }
+  [StructLayout(LayoutKind.Sequential)] struct FileInfo {
+    public uint Attributes, CreationLow, CreationHigh, AccessLow, AccessHigh, WriteLow, WriteHigh;
+    public uint Volume, SizeHigh, SizeLow, Links, IndexHigh, IndexLow;
+  }
+  [StructLayout(LayoutKind.Sequential)] struct FileId {
+    public ulong Volume; [MarshalAs(UnmanagedType.ByValArray, SizeConst=16)] public byte[] Id;
+  }
+  [DllImport("kernel32.dll", SetLastError=true, CharSet=CharSet.Unicode, ExactSpelling=true)] static extern SafeFileHandle CreateFileW(string path, uint access, uint share, IntPtr security, uint disposition, uint flags, IntPtr template);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern IntPtr GetStdHandle(int standard);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern uint GetFileType(SafeFileHandle handle);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern bool GetFileInformationByHandle(SafeFileHandle handle, out FileInfo information);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern bool GetFileInformationByHandleEx(SafeFileHandle handle, int kind, out FileId information, uint size);
+  [DllImport("kernel32.dll", SetLastError=true)] static extern bool SetFileInformationByHandle(SafeFileHandle handle, int kind, ref uint information, uint size);
+  [DllImport("kernel32.dll", SetLastError=true, CharSet=CharSet.Unicode, ExactSpelling=true)] static extern uint GetFinalPathNameByHandleW(SafeFileHandle handle, StringBuilder path, uint capacity, uint flags);
+  [DllImport("kernel32.dll")] static extern IntPtr LocalFree(IntPtr memory);
+  [DllImport("advapi32.dll")] static extern uint GetSecurityInfo(SafeFileHandle handle, int kind, uint sections, out IntPtr owner, out IntPtr group, out IntPtr dacl, out IntPtr sacl, out IntPtr descriptor);
+  [DllImport("advapi32.dll")] static extern uint GetSecurityDescriptorLength(IntPtr descriptor);
+  [DllImport("advapi32.dll", SetLastError=true)] static extern bool GetSecurityDescriptorDacl(IntPtr descriptor, out bool present, out IntPtr dacl, out bool defaulted);
+  [DllImport("advapi32.dll", SetLastError=true)] static extern bool GetSecurityDescriptorOwner(IntPtr descriptor, out IntPtr owner, out bool defaulted);
+  [DllImport("advapi32.dll")] static extern uint SetSecurityInfo(SafeFileHandle handle, int kind, uint sections, IntPtr owner, IntPtr group, IntPtr dacl, IntPtr sacl);
+  [DllImport("ntdll.dll")] static extern int NtQueryInformationFile(SafeFileHandle handle, out IoStatus io, [Out] byte[] information, uint length, int kind);
+  [DllImport("ntdll.dll")] static extern int NtCreateFile(out SafeFileHandle handle, uint access, ref ObjectAttributes attributes, out IoStatus io, IntPtr allocation, uint flags, uint share, uint disposition, uint options, IntPtr ea, uint eaLength);
+  [DllImport("ntdll.dll")] static extern uint RtlNtStatusToDosError(int status);
+
+  sealed class Failure : Exception {
+    public readonly string Code;
+    public Failure(string code, string message) : base(message) { Code=code; }
+  }
+  static Failure OsFailure(uint error, string operation, bool identity=false, bool fullIdentity=false) {
+    // Native security calls retain EACCES; shared handle identity calls use EPERM.
+    string code=error==5 ? (identity ? "EPERM" : "EACCES") : error==80 || error==183 ? "EEXIST" : error==2 || error==3 ? "ENOENT" :
+      identity && (error==112 || error==39) ? "ENOSPC" : identity && (error==32 || error==33) ? "EBUSY" :
+      fullIdentity && (error==1 || error==50 || error==87) ? "ENOTSUP" : "EIO";
+    return new Failure(code, operation+" failed with Windows error "+error);
+  }
+  static Failure CreateFailure(uint error) {
+    var failure=OsFailure(error,"create private directory",true);
+    return failure.Code=="EPERM" ? new Failure("EACCES",failure.Message) : failure;
+  }
+  static void Require(bool condition, string code, string message) {
+    if (!condition) throw new Failure(code,message);
+  }
+  static Dictionary<string,object> Row(params object[] fields) {
+    var result=new Dictionary<string,object>();
+    for(int i=0;i<fields.Length;i+=2) result.Add((string)fields[i],fields[i+1]);
+    return result;
+  }
+  static SafeFileHandle Open(string path, uint access, bool noFollow) {
+    var handle=CreateFileW(path,access,7,IntPtr.Zero,3,0x02000000u | (noFollow ? 0x00200000u : 0),IntPtr.Zero);
+    if(handle.IsInvalid) { uint error=(uint)Marshal.GetLastWin32Error(); handle.Dispose(); throw OsFailure(error,"open security handle"); }
+    return handle;
+  }
+  static FileInfo Information(SafeFileHandle handle) {
+    FileInfo info;
+    if(!GetFileInformationByHandle(handle,out info)) throw OsFailure((uint)Marshal.GetLastWin32Error(),"inspect handle identity",true);
+    return info;
+  }
+  static string Identity(SafeFileHandle handle) {
+    var info=Information(handle);
+    return info.Volume.ToString("x8")+":"+(((ulong)info.IndexHigh<<32)|info.IndexLow).ToString("x16");
+  }
+  static string DirectoryIdentity(SafeFileHandle handle, bool requireLocal=false) {
+    var info=Information(handle);
+    Require((info.Attributes&0x400)==0,"ELOOP","private directory must not be a reparse point");
+    Require((info.Attributes&0x10)!=0,"ENOTDIR","private directory handle must name a directory");
+    if(requireLocal) Require(IsLocal(handle),"ENOTSUP","private directories require a local filesystem");
+    return FullIdentity(handle);
+  }
+  static string FullIdentity(SafeFileHandle handle) {
+    FileId id;
+    if(!GetFileInformationByHandleEx(handle,18,out id,24)) throw OsFailure((uint)Marshal.GetLastWin32Error(),"inspect 128-bit file identity",true,true);
+    Require(id.Id!=null && id.Id.Length==16,"EIO","file identity is incomplete");
+    return id.Volume.ToString("x16")+":"+BitConverter.ToString(id.Id).Replace("-","").ToLowerInvariant();
+  }
+  static string FileIdentity(SafeFileHandle handle, uint expectedLinks) {
+    var info=Information(handle);
+    Require((info.Attributes&0x400)==0,"ELOOP","private file must not be a reparse point");
+    Require((info.Attributes&0x10)==0 && GetFileType(handle)==1,"EINVAL","private file must be a regular disk file");
+    Require(info.Links==expectedLinks,"EIO","private file link count changed");
+    return FullIdentity(handle);
+  }
+  static string FinalPath(SafeFileHandle handle, uint flags) {
+    int capacity=512;
+    for(int attempt=0;attempt<4;attempt++) {
+      var path=new StringBuilder(capacity);
+      uint length=GetFinalPathNameByHandleW(handle,path,(uint)capacity,flags);
+      if(length==0) throw OsFailure((uint)Marshal.GetLastWin32Error(),"inspect handle locality");
+      if(length<capacity) return path.ToString();
+      Require(length<32768,"EIO","final handle path exceeds the inspection budget");
+      capacity=(int)length+1;
+    }
+    throw new Failure("EIO","final handle path changed during inspection");
+  }
+  static bool IsVolumeGuidPath(string path) {
+    return path.Length>=49 && path.StartsWith(@"\\?\Volume{",StringComparison.OrdinalIgnoreCase) &&
+      path[47]=='}' && path[48]=='\\' &&
+      System.Text.RegularExpressions.Regex.IsMatch(path.Substring(11,36),@"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$");
+  }
+  static bool IsLocalFinalPath(string path) {
+    return !path.StartsWith(@"\\?\UNC\",StringComparison.Ordinal) &&
+      (!path.StartsWith(@"\\",StringComparison.Ordinal) || path.StartsWith(@"\\?\",StringComparison.Ordinal));
+  }
+  static bool IsLocal(SafeFileHandle handle) {
+    IoStatus io; var remote=new byte[]{255};
+    int status=NtQueryInformationFile(handle,out io,remote,1,51);
+    if(status==0 && io.Information.ToUInt64()==1 && remote[0]<=1) return remote[0]==0;
+    try {
+      if(IsVolumeGuidPath(FinalPath(handle,9))) return true;
+    } catch(Failure) { }
+    return IsLocalFinalPath(FinalPath(handle,0));
+  }
+  static string Sid(SecurityIdentifier sid) {
+    Require(sid!=null,"EIO","security descriptor SID is missing");
+    return sid.Value.ToLowerInvariant();
+  }
+  static Dictionary<string,object> Security(SafeFileHandle handle, bool requireLocality=true) {
+    IntPtr owner,group,dacl,sacl,descriptor;
+    uint error=GetSecurityInfo(handle,1,5,out owner,out group,out dacl,out sacl,out descriptor);
+    if(error!=0) throw OsFailure(error,"read owner and DACL");
+    try {
+      Require(descriptor!=IntPtr.Zero && owner!=IntPtr.Zero,"EIO","security descriptor is incomplete");
+      uint length=GetSecurityDescriptorLength(descriptor);
+      Require(length>=20 && length<=1024*1024,"EIO","security descriptor exceeds the inspection budget");
+      var bytes=new byte[length]; Marshal.Copy(descriptor,bytes,0,(int)length);
+      var raw=new RawSecurityDescriptor(bytes,0);
+      string ownerSid=Sid(raw.Owner), currentSid;
+      using(var current=WindowsIdentity.GetCurrent()) currentSid=Sid(current.User);
+      var aces=new List<object>(); var unsupported=new List<int>();
+      if(raw.DiscretionaryAcl!=null) foreach(GenericAce ace in raw.DiscretionaryAcl) {
+        var basic=ace as CommonAce;
+        if(basic==null || basic.IsCallback || (ace.AceType!=AceType.AccessAllowed && ace.AceType!=AceType.AccessDenied)) {
+          unsupported.Add((int)ace.AceType); continue;
+        }
+        byte flags=(byte)ace.AceFlags;
+        aces.Add(Row("sid",Sid(basic.SecurityIdentifier),"mask",unchecked((uint)basic.AccessMask),
+          "aceType",ace.AceType==AceType.AccessAllowed ? "allow" : "deny",
+          "flags",Row("raw",flags,"objectInherit",(flags&1)!=0,"containerInherit",(flags&2)!=0,
+            "noPropagateInherit",(flags&4)!=0,"inheritOnly",(flags&8)!=0,"inherited",(flags&16)!=0,
+            "successfulAccess",(flags&64)!=0,"failedAccess",(flags&128)!=0)));
+      }
+      bool isLocal;
+      try { isLocal=IsLocal(handle); }
+      catch(Failure) { if(requireLocality) throw; isLocal=false; }
+      return Row("ownerSid",ownerSid,"currentUserSid",currentSid,"daclPresent",raw.DiscretionaryAcl!=null,
+        "daclProtected",(raw.ControlFlags&ControlFlags.DiscretionaryAclProtected)!=0,
+        "isLocal",isLocal,"aceListComplete",unsupported.Count==0,"unsupportedAceTypes",unsupported.ToArray(),"aces",aces.ToArray());
+    } finally { if(descriptor!=IntPtr.Zero) LocalFree(descriptor); }
+  }
+  static byte[] PrivateSecurity(bool inherit=true) {
+    SecurityIdentifier current;
+    using(var identity=WindowsIdentity.GetCurrent()) current=identity.User;
+    var acl=new RawAcl(2,3);
+    var principals=new[]{current,new SecurityIdentifier("S-1-5-18"),new SecurityIdentifier("S-1-5-32-544")};
+    var flags=inherit ? AceFlags.ObjectInherit|AceFlags.ContainerInherit : AceFlags.None;
+    foreach(var principal in principals) acl.InsertAce(acl.Count,new CommonAce(flags,AceQualifier.AccessAllowed,0x1f01ff,principal,false,null));
+    var descriptor=new RawSecurityDescriptor(ControlFlags.DiscretionaryAclPresent|ControlFlags.DiscretionaryAclProtected|ControlFlags.SelfRelative,current,null,null,acl);
+    var bytes=new byte[descriptor.BinaryLength]; descriptor.GetBinaryForm(bytes,0); return bytes;
+  }
+  static SafeFileHandle CreateRelative(SafeFileHandle parent,string name) {
+    byte[] security=PrivateSecurity();
+    var pin=GCHandle.Alloc(security,GCHandleType.Pinned);
+    IntPtr nameBuffer=Marshal.StringToHGlobalUni(name), unicodeBuffer=IntPtr.Zero;
+    try {
+      int byteLength=checked(name.Length*2);
+      Require(byteLength>0 && byteLength<=65532,"EINVAL","private directory name is invalid");
+      var unicode=new UnicodeString { Length=(ushort)byteLength, MaximumLength=(ushort)(byteLength+2), Buffer=nameBuffer };
+      unicodeBuffer=Marshal.AllocHGlobal(Marshal.SizeOf(typeof(UnicodeString))); Marshal.StructureToPtr(unicode,unicodeBuffer,false);
+      var attributes=new ObjectAttributes { Length=(uint)Marshal.SizeOf(typeof(ObjectAttributes)),RootDirectory=parent.DangerousGetHandle(),
+        ObjectName=unicodeBuffer,Attributes=0x40|0x1000,SecurityDescriptor=pin.AddrOfPinnedObject() };
+      IoStatus io; SafeFileHandle created;
+      int status=NtCreateFile(out created,0x00130180,ref attributes,out io,IntPtr.Zero,0,7,2,0x00200021,IntPtr.Zero,0);
+      if(status<0) { if(created!=null) created.Dispose(); throw CreateFailure(RtlNtStatusToDosError(status)); }
+      return created;
+    } finally { if(unicodeBuffer!=IntPtr.Zero) Marshal.FreeHGlobal(unicodeBuffer); Marshal.FreeHGlobal(nameBuffer); pin.Free(); }
+  }
+  static void RequirePrivate(Dictionary<string,object> facts, bool requireProtected=true, bool requirePrivateChildren=false, bool allowAdministratorsOwner=false) {
+    string current=(string)facts["currentUserSid"], owner=(string)facts["ownerSid"];
+    Require((bool)facts["isLocal"] && (bool)facts["daclPresent"] && (!requireProtected || (bool)facts["daclProtected"]) &&
+      (bool)facts["aceListComplete"] && (owner==current || (allowAdministratorsOwner && owner=="s-1-5-32-544")),
+      "EACCES","private object security was not enforced");
+    foreach(Dictionary<string,object> ace in (object[])facts["aces"]) {
+      var flags=(Dictionary<string,object>)ace["flags"];
+      string sid=(string)ace["sid"];
+      if((string)ace["aceType"]=="deny" || sid==current || sid=="s-1-5-18" || sid=="s-1-5-32-544") continue;
+      if((bool)flags["inheritOnly"] && (!requirePrivateChildren || (!(bool)flags["objectInherit"] && !(bool)flags["containerInherit"]))) continue;
+      uint mask=(uint)ace["mask"];
+      Require((mask&0xd00d01dfu)==0,"EACCES","private object permits untrusted access");
+    }
+  }
+  static void SplitParent(string path, out string parentPath, out string name) {
+    // JavaScript has already admitted and resolved this spelling. Keep extended
+    // Win32 paths out of .NET Framework's separate pathname normalization.
+    int separator=path.LastIndexOf('\\');
+    Require(separator>0 && separator<path.Length-1,"EINVAL","private object must name a child");
+    parentPath=path.Substring(0,separator); name=path.Substring(separator+1);
+    if(parentPath.EndsWith(":")) parentPath+="\\";
+  }
+  static string ExpectedIdentity(string variable, bool required=true) {
+    string identity=Environment.GetEnvironmentVariable(variable) ?? "";
+    Require((!required && identity.Length==0) || System.Text.RegularExpressions.Regex.IsMatch(identity,@"\A[0-9a-f]{16}:[0-9a-f]{32}\z"),
+      "EINVAL","complete expected Windows identity is required");
+    return identity;
+  }
+  static void CheckParent(SafeFileHandle parent, string path, string identity) {
+    Require(DirectoryIdentity(parent,true)==identity,"EIO","retained private parent changed");
+    using(var named=Open(path,0x80,true)) Require(DirectoryIdentity(named,true)==identity,"EIO","private parent pathname changed");
+  }
+  static object InspectDirectory(string path) {
+    bool requirePrivate=Environment.GetEnvironmentVariable("FS_SAFE_WINDOWS_SECURITY_REQUIRE_PRIVATE")=="1";
+    using(var handle=Open(path,requirePrivate ? 0x00020080u : 0x80u,true)) {
+      string identity=DirectoryIdentity(handle,true);
+      if(requirePrivate) RequirePrivate(Security(handle),true,true);
+      return Row("identity",identity);
+    }
+  }
+  static void ProtectFileSecurity(SafeFileHandle handle) {
+    byte[] security=PrivateSecurity(false);
+    var pin=GCHandle.Alloc(security,GCHandleType.Pinned);
+    try {
+      bool present,defaulted; IntPtr dacl,owner;
+      if(!GetSecurityDescriptorDacl(pin.AddrOfPinnedObject(),out present,out dacl,out defaulted)) {
+        throw OsFailure((uint)Marshal.GetLastWin32Error(),"inspect private file DACL");
+      }
+      Require(present && dacl!=IntPtr.Zero,"EIO","private file DACL is incomplete");
+      if(!GetSecurityDescriptorOwner(pin.AddrOfPinnedObject(),out owner,out defaulted)) {
+        throw OsFailure((uint)Marshal.GetLastWin32Error(),"inspect private file owner");
+      }
+      Require(owner!=IntPtr.Zero,"EIO","private file owner is incomplete");
+      uint error=SetSecurityInfo(handle,1,0x80000005u,owner,IntPtr.Zero,dacl,IntPtr.Zero);
+      if(error!=0) throw OsFailure(error,"protect private file owner and DACL");
+    } finally { pin.Free(); }
+  }
+  static void CheckFileAssociation(SafeFileHandle held, string path, string identity, uint links, SafeFileHandle parent, string parentPath, string parentIdentity) {
+    Require(FileIdentity(held,links)==identity,"EIO","retained private file changed");
+    using(var named=Open(path,0x80,true)) Require(FileIdentity(named,links)==identity,"EIO","private file pathname changed");
+    CheckParent(parent,parentPath,parentIdentity);
+  }
+  static object PrivateFile(string path, bool protect) {
+    string expectedParent=ExpectedIdentity("FS_SAFE_WINDOWS_SECURITY_PARENT_IDENTITY");
+    string expectedFile=protect ? "" : ExpectedIdentity("FS_SAFE_WINDOWS_SECURITY_FILE_IDENTITY");
+    uint links=1;
+    if(!protect) Require(uint.TryParse(Environment.GetEnvironmentVariable("FS_SAFE_WINDOWS_SECURITY_EXPECTED_LINKS"),
+      System.Globalization.NumberStyles.None,System.Globalization.CultureInfo.InvariantCulture,out links) && links>0,
+      "EINVAL","private file expected link count is invalid");
+    string parentPath,name; SplitParent(path,out parentPath,out name);
+    using(var held=new SafeFileHandle(GetStdHandle(-10),false)) {
+      Require(!held.IsInvalid,"EBADF","inherited file handle is unavailable");
+      string identity=FileIdentity(held,links);
+      if(!protect) Require(identity==expectedFile,"EIO","private file identity changed");
+      // Windows can use Administrators as the creating token's default owner.
+      // The inherited ACL must already be private: later changes cannot revoke
+      // an earlier reader handle.
+      RequirePrivate(Security(held),requireProtected:!protect,allowAdministratorsOwner:protect);
+      using(var parent=Open(parentPath,0x80,true)) {
+        CheckFileAssociation(held,path,identity,links,parent,parentPath,expectedParent);
+        if(protect) using(var writable=Open(path,0x000e0080,true)) {
+          Require(FileIdentity(writable,links)==identity,"EIO","private file changed before owner and DACL protection");
+          RequirePrivate(Security(writable),requireProtected:false,allowAdministratorsOwner:true);
+          CheckParent(parent,parentPath,expectedParent);
+          ProtectFileSecurity(writable);
+          RequirePrivate(Security(writable));
+        }
+        RequirePrivate(Security(held));
+        CheckFileAssociation(held,path,identity,links,parent,parentPath,expectedParent);
+        return Row("identity",identity);
+      }
+    }
+  }
+  static object CreatePrivate(string path) {
+    string parentPath,name; SplitParent(path,out parentPath,out name);
+    string expectedParent=ExpectedIdentity("FS_SAFE_WINDOWS_SECURITY_PARENT_IDENTITY",false);
+    using(var parent=Open(parentPath,0xa4,true)) {
+      string parentId=DirectoryIdentity(parent,true);
+      if(expectedParent.Length!=0) Require(parentId==expectedParent,"EIO","private parent changed before creation");
+      using(var created=CreateRelative(parent,name)) {
+        try {
+          string createdId=DirectoryIdentity(created);
+          RequirePrivate(Security(created));
+          Require(DirectoryIdentity(parent)==parentId,"EIO","retained private parent changed");
+          using(var namedParent=Open(parentPath,0x80,true)) Require(DirectoryIdentity(namedParent,true)==parentId,"EIO","private parent pathname changed");
+          using(var named=Open(path,0x80,true)) {
+            Require(DirectoryIdentity(named,true)==createdId,"EIO","private directory pathname changed");
+          }
+          return Row("created",true,"identity",createdId);
+        } catch(Exception primary) {
+          uint flags=0x13;
+          if(!SetFileInformationByHandle(created,21,ref flags,4)) {
+            var failure=primary as Failure;
+            throw new Failure(failure==null ? "EIO" : failure.Code,
+              (failure==null ? "private directory validation failed" : failure.Message)+
+              "; owned-handle cleanup failed with Windows error "+Marshal.GetLastWin32Error());
+          }
+          throw;
+        }
+      }
+    }
+  }
+  public static object Execute(string operation,string path) {
+    try {
+      object result;
+      if(operation=="create") result=CreatePrivate(path);
+      else if(operation=="directory") result=InspectDirectory(path);
+      else if(operation=="protect-file" || operation=="verify-file") result=PrivateFile(path,operation=="protect-file");
+      else if(operation=="descriptor") {
+        using(var handle=new SafeFileHandle(GetStdHandle(-10),false)) {
+          Require(!handle.IsInvalid,"EBADF","inherited file handle is unavailable");
+          result=Row("identity",Identity(handle),"security",Security(handle));
+        }
+      } else if(operation=="path") {
+        // Raw reporting retains ACL facts when locality is unknown; admission remains strict.
+        using(var handle=Open(path,0x00020080,false)) result=Security(handle,false);
+      } else throw new Failure("EINVAL","unknown Windows security operation");
+      return Row("ok",true,"result",result);
+    } catch(Failure error) { return Row("ok",false,"code",error.Code,"message",error.Message); }
+      catch(Exception) { return Row("ok",false,"code","EIO","message","Windows security descriptor processing failed"); }
+  }
+}

package/dist/windows-security-bridge.ps1

@@ -0,0 +1,15 @@
+param(
+  [Parameter(Mandatory = $true)]
+  [ValidateSet('path', 'descriptor', 'create', 'directory', 'protect-file', 'verify-file')]
+  [string] $Operation
+)
+
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+# Avoid scanning unrelated installed modules before loading system cmdlets.
+$env:PSModulePath = [IO.Path]::Combine($PSHOME, 'Modules')
+[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+
+Microsoft.PowerShell.Utility\Add-Type -LiteralPath ([IO.Path]::Combine($PSScriptRoot, 'windows-security-bridge.cs'))
+$targetPath = [Environment]::GetEnvironmentVariable('FS_SAFE_WINDOWS_SECURITY_PATH')
+[FsSafeWindowsBridge]::Execute($Operation, $targetPath) | Microsoft.PowerShell.Utility\ConvertTo-Json -Depth 8 -Compress

package/dist/windows-security-command.d.ts

@@ -0,0 +1,26 @@
+import type { NativeWindowsDescriptorSecurityFacts, NativeWindowsSecurityFacts } from "./native-binding.js";
+/** Cleanup must preserve stages still reachable by an unsettled command. */
+export declare function hasUnsettledWindowsSecurityCommand(error: unknown): boolean;
+export declare function readWindowsSecurityFactsCommand(targetPath: string): NativeWindowsSecurityFacts;
+export declare function inspectWindowsDescriptorCommand(fd: number): Promise<NativeWindowsDescriptorSecurityFacts>;
+export declare function createPrivateWindowsDirectoryCommand(targetPath: string, expectedParentIdentity?: string): Promise<{
+    identity: string;
+}>;
+export declare function createPrivateWindowsDirectoryCommandSync(targetPath: string, expectedParentIdentity?: string): {
+    identity: string;
+};
+export declare function inspectWindowsDirectoryCommandSync(targetPath: string, requirePrivate: boolean): {
+    identity: string;
+};
+export declare function inspectWindowsDirectoryCommand(targetPath: string, requirePrivate: boolean): Promise<{
+    identity: string;
+}>;
+export declare function protectPrivateWindowsFileCommandSync(fd: number, targetPath: string, expectedParentIdentity: string): {
+    identity: string;
+};
+export declare function protectPrivateWindowsFileCommand(fd: number, targetPath: string, expectedParentIdentity: string): Promise<{
+    identity: string;
+}>;
+export declare function verifyPrivateWindowsFileCommandSync(fd: number, targetPath: string, expectedFileIdentity: string, expectedParentIdentity: string, expectedLinks?: number): void;
+export declare function verifyPrivateWindowsFileCommand(fd: number, targetPath: string, expectedFileIdentity: string, expectedParentIdentity: string, expectedLinks?: number): Promise<void>;
+//# sourceMappingURL=windows-security-command.d.ts.map

package/dist/windows-security-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows-security-command.d.ts","sourceRoot":"","sources":["../src/windows-security-command.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oCAAoC,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AA2J5G,4EAA4E;AAC5E,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAqB1E;AAwHD,wBAAgB,+BAA+B,CAAC,UAAU,EAAE,MAAM,GAAG,0BAA0B,CAE9F;AAED,wBAAsB,+BAA+B,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,oCAAoC,CAAC,CAM/G;AAED,wBAAsB,oCAAoC,CAAC,UAAU,EAAE,MAAM,EAAE,sBAAsB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAE7I;AAED,wBAAgB,wCAAwC,CAAC,UAAU,EAAE,MAAM,EAAE,sBAAsB,CAAC,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAElI;AAYD,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAEpH;AAED,wBAAsB,8BAA8B,CAAC,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAE/H;AAED,wBAAgB,oCAAoC,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAGzI;AAED,wBAAsB,gCAAgC,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAGpJ;AAED,wBAAgB,mCAAmC,CACjD,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,aAAa,SAAI,GAC9G,IAAI,CAMN;AAED,wBAAsB,+BAA+B,CACnD,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,aAAa,SAAI,GAC9G,OAAO,CAAC,IAAI,CAAC,CAMf"}