@openclaw/fs-safe 0.4.5 → 0.4.7

package/dist/permissions.js

@@ -4,6 +4,8 @@ import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
+import { resolveWindowsSystemCommand } from "./windows-command.js";
+import { inspectWindowsOwner, resolveWindowsCurrentUserSid, resolveWindowsPrincipalSids, } from "./windows-owner.js";
 const execFileAsync = promisify(execFile);
 const INHERIT_FLAGS = new Set(["I", "OI", "CI", "IO", "NP"]);
 const WORLD_PRINCIPALS = new Set(["everyone", "users", "builtin\\users", "authenticated users", "nt authority\\authenticated users", "anonymous logon", "nt authority\\anonymous logon", "guests", "builtin\\guests", "interactive", "nt authority\\interactive", "network", "nt authority\\network", "local"]);
@@ -100,7 +102,23 @@ export async function inspectPathPermissions(targetPath, opts) {
     const bits = modeBits(effectiveMode);
     const platform = opts?.platform ?? process.platform;
     if (platform === "win32") {
-        const acl = await inspectWindowsAcl(targetPath, { env: opts?.env, exec: opts?.exec });
+        const owner = await inspectWindowsOwner({
+            targetPath,
+            env: opts?.env,
+            exec: opts?.exec ?? defaultPermissionExec,
+        });
+        const acl = await inspectWindowsAcl(targetPath, {
+            env: opts?.env,
+            exec: opts?.exec,
+            currentUserSid: owner.currentUserSid,
+            principalSids: owner.principalSids,
+            principalTranslationFailed: owner.principalTranslationFailed,
+        });
+        const ownerFields = {
+            ...(owner.sid ? { ownerSid: owner.sid } : {}),
+            ...(owner.trusted !== undefined ? { ownerTrusted: owner.trusted } : {}),
+            ...(owner.error ? { ownerError: owner.error } : {}),
+        };
         if (!acl.ok) {
             return {
                 ok: true,
@@ -113,6 +131,7 @@ export async function inspectPathPermissions(targetPath, opts) {
                 groupWritable: false,
                 worldReadable: false,
                 groupReadable: false,
+                ...ownerFields,
                 error: acl.error,
             };
         }
@@ -127,6 +146,7 @@ export async function inspectPathPermissions(targetPath, opts) {
             groupWritable: acl.untrustedGroup.some((entry) => entry.canWrite),
             worldReadable: acl.untrustedWorld.some((entry) => entry.canRead),
             groupReadable: acl.untrustedGroup.some((entry) => entry.canRead),
+            ...ownerFields,
             aclSummary: formatWindowsAclSummary(acl),
         };
     }
@@ -204,36 +224,6 @@ function buildTrustedPrincipals(env) {
     }
     return trusted;
 }
-function getEnvValueCaseInsensitive(env, name) {
-    const direct = env[name];
-    if (direct !== undefined) {
-        return direct;
-    }
-    const lower = name.toLowerCase();
-    for (const [key, value] of Object.entries(env)) {
-        if (key.toLowerCase() === lower) {
-            return value;
-        }
-    }
-    return undefined;
-}
-function normalizeWindowsInstallRoot(value) {
-    const trimmed = value?.trim();
-    if (!trimmed || !path.win32.isAbsolute(trimmed)) {
-        return null;
-    }
-    return trimmed.replace(/[\\/]+$/, "");
-}
-function resolveWindowsSystemRoot(env) {
-    const source = env ?? process.env;
-    return (normalizeWindowsInstallRoot(getEnvValueCaseInsensitive(source, "SystemRoot")) ??
-        normalizeWindowsInstallRoot(getEnvValueCaseInsensitive(source, "WINDIR")) ??
-        "C:\\Windows");
-}
-function resolveWindowsSystemCommand(command, env) {
-    const root = resolveWindowsSystemRoot(env);
-    return path.win32.join(root, "System32", command);
-}
 function classifyPrincipal(principal, trustedPrincipals) {
     const normalized = normalize(principal);
     if (SID_RE.test(normalized)) {
@@ -290,7 +280,14 @@ function parseAceEntry(entry) {
     const rights = tokens.filter((token) => !INHERIT_FLAGS.has(token.toUpperCase()));
     if (rights.length === 0)
         return null;
-    return { principal, rights, rawRights, ...rightsFromTokens(rights) };
+    const normalizedPrincipal = normalizeSid(principal);
+    return {
+        principal,
+        ...(SID_RE.test(normalizedPrincipal) ? { sid: normalizedPrincipal } : {}),
+        rights,
+        rawRights,
+        ...rightsFromTokens(rights),
+    };
 }
 export function parseIcaclsOutput(output, targetPath) {
     const entries = [];
@@ -325,7 +322,7 @@ export function summarizeWindowsAcl(entries, env) {
     const untrustedWorld = [];
     const untrustedGroup = [];
     for (const entry of entries) {
-        const classification = classifyPrincipal(entry.principal, trustedPrincipals);
+        const classification = classifyPrincipal(entry.sid ?? entry.principal, trustedPrincipals);
         if (classification === "trusted")
             trusted.push(entry);
         else if (classification === "world")
@@ -335,37 +332,41 @@ export function summarizeWindowsAcl(entries, env) {
     }
     return { trusted, untrustedWorld, untrustedGroup };
 }
-async function resolveCurrentUserSid(exec, env) {
-    try {
-        const { stdout, stderr } = await exec(resolveWindowsSystemCommand("whoami.exe", env), [
-            "/user",
-            "/fo",
-            "csv",
-            "/nh",
-        ]);
-        const match = `${stdout}\n${stderr}`.match(/\*?S-\d+-\d+(?:-\d+)+/i);
-        return match ? normalizeSid(match[0]) : null;
-    }
-    catch {
-        return null;
-    }
-}
 export async function inspectWindowsAcl(targetPath, opts) {
     const exec = opts?.exec ?? defaultPermissionExec;
     try {
+        if (opts?.principalTranslationFailed) {
+            throw new Error("Windows ACL principal SID translation failed");
+        }
         const { stdout, stderr } = await exec(resolveWindowsSystemCommand("icacls.exe", opts?.env), [
             targetPath,
-            "/sid",
         ]);
-        const entries = parseIcaclsOutput(`${stdout}\n${stderr}`.trim(), targetPath);
-        let effectiveEnv = opts?.env;
+        let entries = parseIcaclsOutput(`${stdout}\n${stderr}`.trim(), targetPath);
+        const unresolvedPrincipals = entries
+            .filter((entry) => !entry.sid)
+            .map((entry) => entry.principal);
+        const principalSids = await resolveWindowsPrincipalSids({
+            principals: unresolvedPrincipals,
+            known: opts?.principalSids,
+            env: opts?.env,
+            exec,
+        });
+        entries = entries.map((entry) => {
+            const sid = entry.sid ?? principalSids[entry.principal.toLowerCase()];
+            if (!sid) {
+                throw new Error(`Windows ACL principal SID could not be verified: ${entry.principal}`);
+            }
+            return { ...entry, sid };
+        });
+        let currentUserSid = normalizeSid(opts?.currentUserSid ?? "");
+        let effectiveEnv = currentUserSid ? { USERSID: currentUserSid } : undefined;
         let { trusted, untrustedWorld, untrustedGroup } = summarizeWindowsAcl(entries, effectiveEnv);
-        const needsUserSidResolution = !effectiveEnv?.USERSID &&
-            untrustedGroup.some((entry) => SID_RE.test(normalize(entry.principal)));
+        const needsUserSidResolution = !currentUserSid && untrustedGroup.some((entry) => entry.sid && !TRUSTED_SIDS.has(entry.sid));
         if (needsUserSidResolution) {
-            const currentUserSid = await resolveCurrentUserSid(exec, effectiveEnv);
+            currentUserSid =
+                (await resolveWindowsCurrentUserSid({ exec, env: opts?.env })) ?? "";
             if (currentUserSid) {
-                effectiveEnv = { ...effectiveEnv, USERSID: currentUserSid };
+                effectiveEnv = { USERSID: currentUserSid };
                 ({ trusted, untrustedWorld, untrustedGroup } = summarizeWindowsAcl(entries, effectiveEnv));
             }
         }

package/dist/secure-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAYrC,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAK1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AA0KF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAc/B"}
+{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAYrC,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAK1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAgLF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAc/B"}

package/dist/secure-file.js

@@ -117,6 +117,9 @@ async function assertSecurePermissions(options, stat, realPath) {
     if (platform === "win32" && permissions.source === "unknown") {
         throw new FsSafeError("permission-unverified", `${label(options)} ACL verification unavailable on Windows for ${realPath}.`);
     }
+    if (platform === "win32" && permissions.ownerTrusted !== true) {
+        throw new FsSafeError(permissions.ownerTrusted === false ? "not-owned" : "permission-unverified", `${label(options)} owner could not be trusted on Windows: ${realPath}`);
+    }
     const writableByOthers = permissions.worldWritable || permissions.groupWritable;
     const readableByOthers = permissions.worldReadable || permissions.groupReadable;
     if (writableByOthers || (!options.permissions?.allowReadableByOthers && readableByOthers)) {

package/dist/sibling-temp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5C,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AA0CF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAyCxC;AAkBD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8ChB"}
+{"version":3,"file":"sibling-temp.d.ts","sourceRoot":"","sources":["../src/sibling-temp.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,2BAA2B,CAAC,CAAC,IAAI;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5C,gBAAgB,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AA8BF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAyCxC;AAkBD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8ChB"}

package/dist/sibling-temp.js

@@ -2,6 +2,7 @@ import crypto, { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { syncDirectoryBestEffort } from "./directory-durability.js";
 import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
 import { sanitizeUntrustedFileName } from "./filename.js";
 import { root } from "./root.js";
@@ -30,19 +31,6 @@ async function syncFileBestEffort(filePath) {
         await handle.close();
     }
 }
-async function syncDirectoryBestEffort(dirPath) {
-    let handle;
-    try {
-        handle = await fs.open(dirPath, "r");
-        await handle.sync();
-    }
-    catch {
-        // Best-effort on platforms/filesystems that do not support directory fsync.
-    }
-    finally {
-        await handle?.close().catch(() => undefined);
-    }
-}
 function assertFinalPathIsSibling(dir, filePath) {
     const resolvedDir = path.resolve(dir);
     const resolvedFile = path.resolve(filePath);

package/dist/windows-command.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveWindowsSystemCommand(command: string, env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=windows-command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"windows-command.d.ts","sourceRoot":"","sources":["../src/windows-command.ts"],"names":[],"mappings":"AAwCA,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GACtB,MAAM,CAER"}

package/dist/windows-command.js

@@ -0,0 +1,34 @@
+import path from "node:path";
+function getEnvValueCaseInsensitive(env, name) {
+    const direct = env[name];
+    if (direct !== undefined) {
+        return direct;
+    }
+    const lower = name.toLowerCase();
+    for (const [key, value] of Object.entries(env)) {
+        if (key.toLowerCase() === lower) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function normalizeWindowsInstallRoot(value) {
+    const trimmed = value?.trim();
+    if (!trimmed || !path.win32.isAbsolute(trimmed)) {
+        return null;
+    }
+    let end = trimmed.length;
+    while (end > 0 && (trimmed[end - 1] === "\\" || trimmed[end - 1] === "/")) {
+        end -= 1;
+    }
+    return trimmed.slice(0, end);
+}
+function resolveWindowsSystemRoot(env) {
+    const source = env ?? process.env;
+    return (normalizeWindowsInstallRoot(getEnvValueCaseInsensitive(source, "SystemRoot")) ??
+        normalizeWindowsInstallRoot(getEnvValueCaseInsensitive(source, "WINDIR")) ??
+        "C:\\Windows");
+}
+export function resolveWindowsSystemCommand(command, env) {
+    return path.win32.join(resolveWindowsSystemRoot(env), "System32", command);
+}

package/dist/windows-owner.d.ts

@@ -0,0 +1,29 @@
+export type WindowsOwnerExec = (command: string, args: string[]) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export type WindowsOwnerSummary = {
+    sid?: string;
+    currentUserSid?: string;
+    principalSids?: Record<string, string>;
+    principalTranslationFailed?: boolean;
+    remote?: boolean;
+    trusted?: boolean;
+    error?: string;
+};
+export declare function resolveWindowsPrincipalSids(params: {
+    principals: string[];
+    known?: Record<string, string>;
+    env?: NodeJS.ProcessEnv;
+    exec: WindowsOwnerExec;
+}): Promise<Record<string, string>>;
+export declare function resolveWindowsCurrentUserSid(params: {
+    env?: NodeJS.ProcessEnv;
+    exec: WindowsOwnerExec;
+}): Promise<string | null>;
+export declare function inspectWindowsOwner(params: {
+    targetPath: string;
+    env?: NodeJS.ProcessEnv;
+    exec: WindowsOwnerExec;
+}): Promise<WindowsOwnerSummary>;
+//# sourceMappingURL=windows-owner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"windows-owner.d.ts","sourceRoot":"","sources":["../src/windows-owner.ts"],"names":[],"mappings":"AAEA,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,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA4DF,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAyBlC;AAED,wBAAsB,4BAA4B,CAAC,MAAM,EAAE;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWzB;AAED,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,CA2C/B"}

package/dist/windows-owner.js

@@ -0,0 +1,118 @@
+import { resolveWindowsSystemCommand } from "./windows-command.js";
+const SID_RE = /^\*?s-\d+-\d+(-\d+)+$/i;
+const TRUSTED_OWNER_SIDS = new Set(["s-1-5-18", "s-1-5-32-544"]);
+function normalizeSid(value) {
+    const normalized = value.trim().toLowerCase();
+    return normalized.startsWith("*") ? normalized.slice(1) : normalized;
+}
+function encodePowerShellCommand(source) {
+    return Buffer.from(source, "utf16le").toString("base64");
+}
+function windowsOwnerQueryCommand(targetPath) {
+    const encodedPath = Buffer.from(targetPath, "utf8").toString("base64");
+    return [
+        "$ErrorActionPreference='Stop'",
+        `$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)}",
+        "$ownerSid=$acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value",
+        "$currentSid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value",
+        "$root=[IO.Path]::GetPathRoot($p)",
+        "$extendedDrive=$p.Length -ge 7 -and $p.StartsWith('\\\\?\\') -and [char]::IsLetter($p[4]) -and $p[5] -eq ':' -and $p[6] -eq '\\'",
+        "$driveRoot=if($extendedDrive){$p.Substring(4,3)}else{$root}",
+        "$namespacePath=$p.StartsWith('\\\\')",
+        "$remote=($namespacePath -and -not $extendedDrive) -or ([IO.DriveInfo]::new($driveRoot).DriveType -eq [IO.DriveType]::Network)",
+        "$rules=$acl.GetAccessRules($true,$true,[System.Security.Principal.SecurityIdentifier])",
+        "$principalSids=@($rules|ForEach-Object {$identity=$_.IdentityReference;$sid=$identity.Value;@{name=$sid;sid=$sid};try{@{name=$identity.Translate([System.Security.Principal.NTAccount]).Value;sid=$sid}}catch{}})",
+        "@{ownerSid=$ownerSid;currentUserSid=$currentSid;principalSids=$principalSids;principalTranslationFailed=$false;remote=$remote}|ConvertTo-Json -Depth 4 -Compress",
+    ].join(";");
+}
+function windowsPrincipalQueryCommand(principals) {
+    const encodedPrincipals = Buffer.from(JSON.stringify(principals), "utf8").toString("base64");
+    return [
+        "$ErrorActionPreference='Stop'",
+        `$names=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${encodedPrincipals}'))|ConvertFrom-Json`,
+        "$rows=@($names|ForEach-Object {@{name=$_;sid=(New-Object System.Security.Principal.NTAccount($_)).Translate([System.Security.Principal.SecurityIdentifier]).Value}})",
+        "ConvertTo-Json -InputObject $rows -Compress",
+    ].join(";");
+}
+function parsePrincipalSidRows(value) {
+    const rows = Array.isArray(value) ? value : value ? [value] : [];
+    const result = {};
+    for (const row of rows) {
+        if (!row || typeof row !== "object") {
+            continue;
+        }
+        const name = "name" in row && typeof row.name === "string" ? row.name.trim() : "";
+        const sid = "sid" in row && typeof row.sid === "string" ? normalizeSid(row.sid) : "";
+        if (name && SID_RE.test(sid)) {
+            result[name.toLowerCase()] = sid;
+        }
+    }
+    return result;
+}
+export async function resolveWindowsPrincipalSids(params) {
+    const principals = [...new Set(params.principals.map((value) => value.trim()).filter(Boolean))];
+    const known = Object.fromEntries(Object.entries(params.known ?? {}).map(([name, sid]) => [name.toLowerCase(), normalizeSid(sid)]));
+    const unresolved = principals.filter((principal) => !known[principal.toLowerCase()]);
+    if (unresolved.length === 0) {
+        return known;
+    }
+    const command = resolveWindowsSystemCommand(String.raw `WindowsPowerShell\v1.0\powershell.exe`, params.env);
+    const { stdout } = await params.exec(command, [
+        "-NoLogo",
+        "-NoProfile",
+        "-NonInteractive",
+        "-EncodedCommand",
+        encodePowerShellCommand(windowsPrincipalQueryCommand(unresolved)),
+    ]);
+    const resolved = { ...known, ...parsePrincipalSidRows(JSON.parse(stdout.trim())) };
+    if (principals.some((principal) => !resolved[principal.toLowerCase()])) {
+        throw new Error("Windows ACL principal translation returned incomplete SID data");
+    }
+    return resolved;
+}
+export async function resolveWindowsCurrentUserSid(params) {
+    try {
+        const { stdout, stderr } = await params.exec(resolveWindowsSystemCommand("whoami.exe", params.env), ["/user", "/fo", "csv", "/nh"]);
+        const match = `${stdout}\n${stderr}`.match(/\*?S-\d+-\d+(?:-\d+)+/i);
+        return match ? normalizeSid(match[0]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function inspectWindowsOwner(params) {
+    try {
+        const command = resolveWindowsSystemCommand(String.raw `WindowsPowerShell\v1.0\powershell.exe`, params.env);
+        const { stdout } = await params.exec(command, [
+            "-NoLogo",
+            "-NoProfile",
+            "-NonInteractive",
+            "-EncodedCommand",
+            encodePowerShellCommand(windowsOwnerQueryCommand(params.targetPath)),
+        ]);
+        const parsed = JSON.parse(stdout.trim());
+        const ownerSid = typeof parsed.ownerSid === "string" && SID_RE.test(parsed.ownerSid)
+            ? normalizeSid(parsed.ownerSid)
+            : undefined;
+        const currentUserSid = typeof parsed.currentUserSid === "string" && SID_RE.test(parsed.currentUserSid)
+            ? normalizeSid(parsed.currentUserSid)
+            : undefined;
+        if (!ownerSid || !currentUserSid) {
+            return { error: "Windows owner query returned invalid SID data" };
+        }
+        const remote = parsed.remote === true;
+        return {
+            sid: ownerSid,
+            currentUserSid,
+            principalSids: parsePrincipalSidRows(parsed.principalSids),
+            principalTranslationFailed: parsed.principalTranslationFailed === true,
+            remote,
+            trusted: !remote && (ownerSid === currentUserSid || TRUSTED_OWNER_SIDS.has(ownerSid)),
+        };
+    }
+    catch (err) {
+        return { error: String(err) };
+    }
+}

package/docs/advanced.md

@@ -5,7 +5,7 @@ description: "Lower-level composition helpers under @openclaw/fs-safe/advanced.
 
 # `@openclaw/fs-safe/advanced`
 
-Composition primitives that OpenClaw uses to build higher-level APIs. They are public — semver applies — but treated as a less stable surface than the focused subpaths (`root`, `json`, `store`, `temp`, `archive`, `errors`). Reach for them only when you are building a primitive of your own and the focused subpaths do not cover it.
+Composition primitives that OpenClaw uses to build higher-level APIs. They are public — semver applies — but treated as a less stable surface than the focused subpaths (`root`, `json`, `store`, `temp`, `archive`, `durability`, `errors`). Reach for them only when you are building a primitive of your own and the focused subpaths do not cover it.
 
 ```ts
 import {

package/docs/contributing.md

@@ -10,7 +10,8 @@ cd fs-safe
 pnpm install
 ```
 
-Node 22 or newer. The dev toolchain uses pnpm; `npm install` works too but pnpm is what the lockfile is keyed against.
+Node 22 or newer. The dev toolchain and lockfile use pnpm; use the package
+manager version declared in `package.json`.
 
 ## Build
 
@@ -34,9 +35,16 @@ pnpm test test/archive.test.ts
 
 Use `vi.mock` sparingly. Most tests should drive real disk operations in a `mkdtemp`-created scratch directory, asserting on observable behavior. The library has [test hooks](testing.md) for the rare cases where you need to inject a TOCTOU race deterministically.
 
-## Format and types
+## Checks
 
-The repo doesn't ship a separate lint config; `tsc --noEmit` (run by `pnpm build`) is the type gate. Format with your editor's TypeScript Language Server defaults — keep diffs tight.
+Run the complete repository gate before handoff:
+
+```bash
+pnpm check
+```
+
+This runs the filesystem boundary checks, build, tests, and package
+tarball/import validation.
 
 ## Docs
 
@@ -69,7 +77,14 @@ Small, focused PRs land faster. The general shape:
 
 ## Releases
 
-Release process lives in the maintainer's runbook. External contributors don't need to do anything beyond getting the PR merged.
+Maintainers publish from a protected `vX.Y.Z` tag on `main` through
+`.github/workflows/release.yml`. The workflow requires the package version and a
+dated `CHANGELOG.md` section to match the tag, then publishes with npm trusted
+publishing and provenance before creating the GitHub release.
+
+External contributors do not need to do anything beyond getting the pull
+request merged. Maintainers must not publish locally or add npm automation
+tokens.
 
 ## Reporting security issues
 

package/docs/durability.md

@@ -0,0 +1,89 @@
+---
+title: Directory durability
+description: "Pin directory identities, fsync publication metadata, and durably create nested directory paths."
+---
+
+# Directory durability
+
+`@openclaw/fs-safe/durability` provides the directory side of crash-safe file
+publication. Flushing a file does not guarantee that its containing directory
+entry reached storage; callers that promise durable create, link, rename, or
+unlink operations must also synchronize the affected directory.
+
+```ts
+import {
+  ensureDurableDirectory,
+  pinDirectory,
+} from "@openclaw/fs-safe/durability";
+
+const repository = await ensureDurableDirectory({
+  directoryPath: "/srv/backups/sqlite",
+  mode: 0o700,
+});
+
+const pinned = await pinDirectory(repository, { label: "backup repository" });
+try {
+  await publishSnapshot();
+  const outcome = await pinned.sync();
+  if (outcome.status === "unsupported") {
+    // Decide at the product boundary whether this platform can weaken the promise.
+  }
+} finally {
+  await pinned.close();
+}
+```
+
+## Outcomes and failure semantics
+
+`syncDirectory()` and `PinnedDirectory.sync()` return:
+
+```ts
+type DirectorySyncOutcome =
+  | { status: "synced" }
+  | { status: "unsupported"; code?: string };
+```
+
+POSIX synchronization failures propagate. Windows directory handles do not
+portably support `FlushFileBuffers`; the known unsupported error family is
+reported as `unsupported` after the pathname and pinned identity are checked
+again. Directory-open access failures and other Windows I/O failures still
+propagate.
+
+`syncDirectoryBestEffort()` and `syncDirectoryBestEffortSync()` intentionally
+discard both unsupported outcomes and failures. Use them only when the primary
+write remains useful without a crash-durability promise.
+
+## Pinned directories
+
+`pinDirectory()` rejects final symlinks and non-directories. On POSIX it opens
+with `O_DIRECTORY`, `O_NOFOLLOW`, and `O_NONBLOCK`, then compares the open
+descriptor, pathname identity, and canonical path. `assertCurrent()` repeats
+those checks. This prevents a pathname replacement from turning a later sync
+into proof for a different directory.
+
+Call `close()` in `finally`. Closing is idempotent; using a closed pin fails.
+
+## Durable directory creation
+
+`ensureDurableDirectory()` finds and pins the nearest existing ancestor,
+creates the requested path, opens every new directory segment, and synchronizes
+each new parent-to-child edge from the leaf upward. It returns the final
+directory receipt plus the aggregate parent-sync outcome.
+
+By default it uses fs-safe's guarded one-segment-at-a-time absolute-directory
+creator. Advanced callers can pass `create` when directory creation needs
+platform-specific ACLs or another product-owned policy. The callback owns the
+safety of its mutations and must create exactly `directoryPath`; fs-safe
+validates and pins every resulting segment before any synchronization is
+accepted.
+
+`expectedExistingIdentity` binds an existing target to an identity observed by
+the caller before a separate permission or policy check. A missing or replaced
+target fails with `FsSafeError("path-mismatch")`.
+
+## Scope
+
+These primitives establish path identity and filesystem synchronization. They
+do not decide application commit protocols, marker formats, permission policy,
+or whether an unsupported platform is acceptable. Keep those decisions at the
+owning product boundary.

package/docs/index.md

@@ -52,6 +52,7 @@ await fs.remove("notes/archive/today.txt");
 | [`@openclaw/fs-safe/config`](config.md) | Process-global Python helper and lock-option defaults. |
 | [Python helper policy](python-helper.md) | Choose `auto`, `off`, or `require` for POSIX fd-relative hardening. |
 | [`replaceFileAtomic`](atomic.md) | Sibling-temp + rename, fsync hooks, mode preservation, copy fallback. |
+| [Directory durability](durability.md) | Pinned directory identities, explicit sync outcomes, and durable nested-directory creation. |
 | [`writeExternalFileWithinRoot`](output.md) | Stage external-library file output in private temp storage, then finalize under a root. |
 | [`writeJson` / `readJson*`](json.md) | JSON state files with strict and lenient read variants. |
 | [`@openclaw/fs-safe/store`](store.md) | Overview of `fileStore`, `fileStoreSync`, and `jsonStore`. |

package/docs/permissions.md

@@ -38,7 +38,7 @@ isWorldReadable(bits);
 isGroupReadable(bits);
 ```
 
-`inspectPathPermissions()` follows symlink targets for the effective mode but tells you whether the original path was a symlink. On POSIX it reports owner/group/world bits. On Windows it delegates to the ACL helpers below.
+`inspectPathPermissions()` follows symlink targets for the effective mode but tells you whether the original path was a symlink. On POSIX it reports owner/group/world bits. On Windows it delegates to the ACL helpers below and also reports `ownerSid` plus `ownerTrusted` when ownership can be verified. `ownerTrusted` is true only for a local volume owned by the current user, LocalSystem, or built-in Administrators; remote filesystems fail closed. Secure reads and callers that protect credential-bearing execution require `ownerTrusted === true`.
 
 ## Advanced Windows ACL helpers
 
@@ -82,6 +82,9 @@ type PermissionCheck = {
   groupWritable: boolean;
   worldReadable: boolean;
   groupReadable: boolean;
+  ownerSid?: string;
+  ownerTrusted?: boolean;
+  ownerError?: string;
   aclSummary?: string;
   error?: string;
 };

package/docs/security-model.md

@@ -61,6 +61,19 @@ When `hardlinks: "reject"` is set, reads stat the target and refuse if `nlink >
 
 Within one process, async writes to the same target are queued so their temp-write/rename phases do not overlap. Cross-process writers still need an external protocol such as the sidecar lock helpers.
 
+### Directory durability
+
+`pinDirectory()` opens a directory without following its final component on
+POSIX, verifies the descriptor against the pathname identity and canonical
+path, and repeats those checks around synchronization. `ensureDurableDirectory()`
+pins the nearest existing ancestor and each newly created segment before
+synchronizing every new directory edge from the leaf upward.
+
+Known Windows directory-flush limitations are returned as an explicit
+`unsupported` outcome. POSIX and other I/O failures propagate from the strict
+API. The separately named best-effort helpers intentionally provide no crash
+durability guarantee.
+
 ### Archive extraction
 
 `extractArchive` first stages into a private temp directory (mode 0700) outside the destination, validates each entry path against `..` and absolute prefixes, refuses link-type entries by default, enforces entry count and byte budgets, and only then merges the staged tree into the destination through the same boundary checks used by direct writes.