@openclaw/fs-safe 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.4.6 - 2026-07-24
+
+### Highlights
+
+- Reject foreign-owned or unverifiable Windows files in secure reads while
+  preserving supported trusted local owners and exact extended drive paths.
+
+### Security and Correctness
+
+- Report Windows owner SIDs and whether the owner is the current user,
+  LocalSystem, or built-in Administrators so credential-bearing executable
+  checks can reject foreign-owned paths even when their visible DACL is
+  read-only. Secure reads enforce the result and remote filesystems fail
+  closed.
+- Read Windows owner and DACL data through the underlying .NET security
+  descriptor APIs so verification does not depend on PowerShell security-module
+  autoloading.
+- Invoke `icacls.exe` with its supported path-only inspection syntax and use
+  the live Windows user/domain environment for named ACE classification, so
+  ACL verification works on supported Windows hosts instead of failing on the
+  invalid `/sid` argument.
+- Normalize trailing Windows install-root separators with a bounded linear
+  scan so library-provided environment maps cannot trigger regex backtracking.
+
+### Docs and Tooling
+
+- Add the public repository governance baseline, pinned CodeQL analysis,
+  package tarball/import validation, and protected tag-driven npm trusted
+  publishing with provenance and changelog-derived GitHub releases.
+- Let tag-driven publishing continue from an expected registry miss into npm
+  trusted publishing instead of exiting before the publish attempt.
+- Publish the generated tarball through an explicit relative path so npm treats
+  it as a local artifact instead of GitHub repository shorthand.
+
 ## 0.4.5 - 2026-07-20
 
 ### Highlights

package/SECURITY.md

@@ -1,12 +1,45 @@
 # Security Policy
 
-`@openclaw/fs-safe` is a filesystem-safety library, so potential boundary bypasses should be reported privately first.
+If you believe you found a security issue in `@openclaw/fs-safe`, report it
+privately.
 
-Email security reports to Peter Steinberger at `steipete@gmail.com` with:
+## Reporting
 
-- affected version or commit
-- platform and filesystem details
-- minimal reproduction steps
-- expected impact
+Open a private report through
+[GitHub Security Advisories](https://github.com/openclaw/fs-safe/security/advisories/new)
+or email `security@openclaw.ai`.
 
-Please do not open a public issue for traversal, symlink, hardlink, archive extraction, or credential-file bugs until we have coordinated disclosure.
+Include:
+
+1. affected version or commit
+2. Node.js version, operating system, filesystem, and mount details
+3. minimal reproduction
+4. demonstrated impact
+5. suggested remediation, if known
+
+Do not open a public issue until maintainers have coordinated disclosure.
+
+## Scope
+
+Security issues in scope generally include:
+
+- traversal or root-confinement bypasses
+- symlink, hardlink, rename, or identity-swap races that cross a documented
+  filesystem boundary
+- archive extraction outside the intended destination
+- unsafe secret-file, permission, ownership, or temporary-file behavior
+- package or release-pipeline compromise affecting the published package
+
+Reports must demonstrate a concrete boundary bypass or impact. Applications
+remain responsible for operating-system isolation, authorization, and choosing
+trusted root directories unless this package documents and fails to enforce a
+specific invariant.
+
+## Operational Guidance
+
+- Keep `@openclaw/fs-safe`, Node.js, and optional archive dependencies current.
+- Treat pathnames and archive contents as untrusted.
+- Use OS-level sandboxing when the threat model includes a hostile process.
+- Pin and review dependency updates before publishing.
+
+There is currently no paid bug bounty program.

package/dist/local-file-access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-file-access.d.ts","sourceRoot":"","sources":["../src/local-file-access.ts"],"names":[],"mappings":"AAWA,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAMT;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAET;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,IAAI,CAIjF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAmBzD;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMxE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgB3E"}
+{"version":3,"file":"local-file-access.d.ts","sourceRoot":"","sources":["../src/local-file-access.ts"],"names":[],"mappings":"AAWA,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAeT;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAET;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,IAAI,CAIjF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAmBzD;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMxE;AAED,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgB3E"}

package/dist/local-file-access.js

@@ -14,7 +14,15 @@ export function isWindowsNetworkPath(filePath, platform = process.platform) {
         return false;
     }
     const normalized = filePath.replace(/\//g, "\\");
-    return normalized.startsWith("\\\\?\\UNC\\") || normalized.startsWith("\\\\");
+    const extendedDrive = normalized.length >= 7 &&
+        normalized.startsWith("\\\\?\\") &&
+        /^[a-z]$/i.test(normalized[4] ?? "") &&
+        normalized[5] === ":" &&
+        normalized[6] === "\\";
+    if (extendedDrive) {
+        return false;
+    }
+    return normalized.startsWith("\\\\");
 }
 export function isWindowsDriveLetterPath(filePath, platform = process.platform) {
     return platform === "win32" && /^[A-Za-z]:[\\/]/.test(filePath);

package/dist/permissions.d.ts

@@ -13,6 +13,12 @@ export type PermissionCheck = {
     groupWritable: boolean;
     worldReadable: boolean;
     groupReadable: boolean;
+    /** Canonical Windows owner SID when the owner query succeeds. */
+    ownerSid?: string;
+    /** Whether the Windows owner is the current user, LocalSystem, or Administrators. */
+    ownerTrusted?: boolean;
+    /** Owner-query failure detail when Windows ownership could not be verified. */
+    ownerError?: string;
     aclSummary?: string;
     error?: string;
 };
@@ -32,6 +38,8 @@ export type SafeStatResult = {
 };
 export type WindowsAclEntry = {
     principal: string;
+    /** Canonical principal SID when resolved from Windows. */
+    sid?: string;
     rights: string[];
     rawRights: string;
     canRead: boolean;
@@ -75,6 +83,9 @@ export declare function summarizeWindowsAcl(entries: WindowsAclEntry[], env?: No
 export declare function inspectWindowsAcl(targetPath: string, opts?: {
     env?: NodeJS.ProcessEnv;
     exec?: PermissionExec;
+    currentUserSid?: string;
+    principalSids?: Record<string, string>;
+    principalTranslationFailed?: boolean;
 }): Promise<WindowsAclSummary>;
 export declare function formatWindowsAclSummary(summary: WindowsAclSummary): string;
 export declare function formatIcaclsResetCommand(targetPath: string, opts: IcaclsResetCommandOptions): string;

package/dist/permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"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"}

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/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/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/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/package.json

@@ -1,12 +1,28 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
+  "keywords": [
+    "filesystem",
+    "openclaw",
+    "path-traversal",
+    "security",
+    "typescript"
+  ],
+  "homepage": "https://fs-safe.io",
+  "bugs": {
+    "url": "https://github.com/openclaw/fs-safe/issues"
+  },
   "license": "MIT",
+  "author": "OpenClaw Team <dev@openclaw.ai>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/openclaw/fs-safe.git"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
@@ -95,7 +111,8 @@
     "./test-hooks": {
       "types": "./dist/test-hooks.d.ts",
       "default": "./dist/test-hooks.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
     "benchmark": "node scripts/benchmark.mjs",
@@ -106,9 +123,11 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:security": "vitest run test/fs-safe.test.ts test/read-boundary-bypass.test.ts test/write-boundary-bypass.test.ts test/additional-boundary-bypass.test.ts test/adversarial-boundary-payloads.test.ts",
-    "check": "pnpm lint:file-size && pnpm lint:fs-boundary && pnpm build && pnpm test",
+    "check": "pnpm lint:file-size && pnpm lint:fs-boundary && pnpm build && pnpm test && node scripts/check-pack.mjs",
     "docs:site": "node scripts/build-docs-site.mjs",
+    "pack:check": "pnpm build && node scripts/check-pack.mjs",
     "check:changed": "pnpm run check",
+    "release:notes": "node scripts/release-notes.mjs",
     "test:changed": "pnpm run test",
     "crabbox:hydrate": "crabbox actions hydrate",
     "crabbox:run": "crabbox run",