@openclaw/fs-safe 0.1.0

package/dist/move-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"move-path.d.ts","sourceRoot":"","sources":["../src/move-path.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,+BAA+B,GAAG;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAef"}

package/dist/move-path.js

@@ -0,0 +1,18 @@
+import fs from "node:fs/promises";
+export async function movePathWithCopyFallback(options) {
+    try {
+        await fs.rename(options.from, options.to);
+        return;
+    }
+    catch (error) {
+        if (error?.code !== "EXDEV") {
+            throw error;
+        }
+    }
+    await fs.cp(options.from, options.to, {
+        recursive: true,
+        force: true,
+        dereference: false,
+    });
+    await fs.rm(options.from, { recursive: true, force: true });
+}

package/dist/path-alias-guards.d.ts

@@ -0,0 +1,19 @@
+import { type RootPathAliasPolicy } from "./root-path.js";
+export type PathAliasPolicy = RootPathAliasPolicy;
+export declare const PATH_ALIAS_POLICIES: {
+    readonly strict: Readonly<{
+        allowFinalSymlinkForUnlink: false;
+        allowFinalHardlinkForUnlink: false;
+    }>;
+    readonly unlinkTarget: Readonly<{
+        allowFinalSymlinkForUnlink: true;
+        allowFinalHardlinkForUnlink: true;
+    }>;
+};
+export declare function assertNoPathAliasEscape(params: {
+    absolutePath: string;
+    rootPath: string;
+    boundaryLabel: string;
+    policy?: PathAliasPolicy;
+}): Promise<void>;
+//# sourceMappingURL=path-alias-guards.d.ts.map

package/dist/path-alias-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-alias-guards.d.ts","sourceRoot":"","sources":["../src/path-alias-guards.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAGxB,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAElD,eAAO,MAAM,mBAAmB;;;;;;;;;CAA2B,CAAC;AAE5D,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhB"}

package/dist/path-alias-guards.js

@@ -0,0 +1,21 @@
+import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath, } from "./root-path.js";
+import { assertNoHardlinkedFinalPath } from "./hardlink-guards.js";
+export const PATH_ALIAS_POLICIES = ROOT_PATH_ALIAS_POLICIES;
+export async function assertNoPathAliasEscape(params) {
+    const resolved = await resolveRootPath({
+        absolutePath: params.absolutePath,
+        rootPath: params.rootPath,
+        boundaryLabel: params.boundaryLabel,
+        policy: params.policy,
+    });
+    const allowFinalSymlink = params.policy?.allowFinalSymlinkForUnlink === true;
+    if (allowFinalSymlink && resolved.kind === "symlink") {
+        return;
+    }
+    await assertNoHardlinkedFinalPath({
+        filePath: resolved.absolutePath,
+        root: resolved.rootPath,
+        boundaryLabel: params.boundaryLabel,
+        allowFinalHardlinkForUnlink: params.policy?.allowFinalHardlinkForUnlink,
+    });
+}

package/dist/path-guards.d.ts

@@ -0,0 +1,7 @@
+export declare function normalizeWindowsPathForComparison(input: string): string;
+export declare function isNodeError(value: unknown): value is NodeJS.ErrnoException;
+export declare function hasNodeErrorCode(value: unknown, code: string): boolean;
+export declare function isNotFoundPathError(value: unknown): boolean;
+export declare function isSymlinkOpenError(value: unknown): boolean;
+export declare function isPathInside(root: string, target: string): boolean;
+//# sourceMappingURL=path-guards.d.ts.map

package/dist/path-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-guards.d.ts","sourceRoot":"","sources":["../src/path-guards.ts"],"names":[],"mappings":"AAQA,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASvE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAI1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA0BlE"}

package/dist/path-guards.js

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
+const NOT_FOUND_CODES = new Set(["ENOENT", "ENOTDIR"]);
+const SYMLINK_OPEN_CODES = new Set(["ELOOP", "EINVAL", "ENOTSUP"]);
+const PARENT_SEGMENT_PREFIX = /^\.\.(?:[\\/]|$)/u;
+const POSIX_SEPARATOR_CHAR_CODE = 0x2f;
+export function normalizeWindowsPathForComparison(input) {
+    let normalized = path.win32.normalize(input);
+    if (normalized.startsWith("\\\\?\\")) {
+        normalized = normalized.slice(4);
+        if (normalized.toUpperCase().startsWith("UNC\\")) {
+            normalized = `\\\\${normalized.slice(4)}`;
+        }
+    }
+    return normalizeLowercaseStringOrEmpty(normalized.replaceAll("/", "\\"));
+}
+export function isNodeError(value) {
+    return Boolean(value && typeof value === "object" && "code" in value);
+}
+export function hasNodeErrorCode(value, code) {
+    return isNodeError(value) && value.code === code;
+}
+export function isNotFoundPathError(value) {
+    return isNodeError(value) && typeof value.code === "string" && NOT_FOUND_CODES.has(value.code);
+}
+export function isSymlinkOpenError(value) {
+    return isNodeError(value) && typeof value.code === "string" && SYMLINK_OPEN_CODES.has(value.code);
+}
+export function isPathInside(root, target) {
+    if (process.platform === "win32") {
+        const rootForCompare = normalizeWindowsPathForComparison(path.win32.resolve(root));
+        const targetForCompare = normalizeWindowsPathForComparison(path.win32.resolve(target));
+        const relative = path.win32.relative(rootForCompare, targetForCompare);
+        return (relative === "" || (!PARENT_SEGMENT_PREFIX.test(relative) && !path.win32.isAbsolute(relative)));
+    }
+    if (root.length > 0 &&
+        root.charCodeAt(0) === POSIX_SEPARATOR_CHAR_CODE &&
+        target.length >= root.length &&
+        target.charCodeAt(0) === POSIX_SEPARATOR_CHAR_CODE &&
+        !target.includes("/..") &&
+        (target === root ||
+            (target.startsWith(root) && target.charCodeAt(root.length) === POSIX_SEPARATOR_CHAR_CODE))) {
+        return true;
+    }
+    const resolvedRoot = path.resolve(root);
+    const resolvedTarget = path.resolve(target);
+    const relative = path.relative(resolvedRoot, resolvedTarget);
+    return relative === "" || (!PARENT_SEGMENT_PREFIX.test(relative) && !path.isAbsolute(relative));
+}

package/dist/path-policy.d.ts

@@ -0,0 +1,25 @@
+import { type RootPathAliasPolicy } from "./root-path.js";
+export type PathAliasPolicy = RootPathAliasPolicy;
+export declare const PATH_ALIAS_POLICIES: {
+    readonly strict: Readonly<{
+        allowFinalSymlinkForUnlink: false;
+        allowFinalHardlinkForUnlink: false;
+    }>;
+    readonly unlinkTarget: Readonly<{
+        allowFinalSymlinkForUnlink: true;
+        allowFinalHardlinkForUnlink: true;
+    }>;
+};
+export declare function assertNoPathAliasEscape(params: {
+    absolutePath: string;
+    rootPath: string;
+    boundaryLabel: string;
+    policy?: PathAliasPolicy;
+}): Promise<void>;
+export declare function assertNoHardlinkedFinalPath(params: {
+    filePath: string;
+    root: string;
+    boundaryLabel: string;
+    allowFinalHardlinkForUnlink?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=path-policy.d.ts.map

package/dist/path-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-policy.d.ts","sourceRoot":"","sources":["../src/path-policy.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAGxB,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAElD,eAAO,MAAM,mBAAmB;;;;;;;;;CAA2B,CAAC;AAE5D,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhB;AAED,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBhB"}

package/dist/path-policy.js

@@ -0,0 +1,50 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath, } from "./root-path.js";
+import { isNotFoundPathError } from "./path.js";
+export const PATH_ALIAS_POLICIES = ROOT_PATH_ALIAS_POLICIES;
+export async function assertNoPathAliasEscape(params) {
+    const resolved = await resolveRootPath({
+        absolutePath: params.absolutePath,
+        rootPath: params.rootPath,
+        boundaryLabel: params.boundaryLabel,
+        policy: params.policy,
+    });
+    const allowFinalSymlink = params.policy?.allowFinalSymlinkForUnlink === true;
+    if (allowFinalSymlink && resolved.kind === "symlink") {
+        return;
+    }
+    await assertNoHardlinkedFinalPath({
+        filePath: resolved.absolutePath,
+        root: resolved.rootPath,
+        boundaryLabel: params.boundaryLabel,
+        allowFinalHardlinkForUnlink: params.policy?.allowFinalHardlinkForUnlink,
+    });
+}
+export async function assertNoHardlinkedFinalPath(params) {
+    if (params.allowFinalHardlinkForUnlink) {
+        return;
+    }
+    let stat;
+    try {
+        stat = await fs.stat(params.filePath);
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            return;
+        }
+        throw err;
+    }
+    if (!stat.isFile()) {
+        return;
+    }
+    if (stat.nlink > 1) {
+        throw new Error(`Hardlinked path is not allowed under ${params.boundaryLabel} (${shortPath(params.root)}): ${shortPath(params.filePath)}`);
+    }
+}
+function shortPath(value) {
+    if (value.startsWith(os.homedir())) {
+        return `~${value.slice(os.homedir().length)}`;
+    }
+    return value;
+}

package/dist/path-safety.d.ts

@@ -0,0 +1,12 @@
+import fs from "node:fs";
+export declare function resolveSafeBaseDir(rootDir: string): string;
+export declare function isWithinDir(rootDir: string, targetPath: string): boolean;
+export declare function isPathInside(baseDir: string, targetPath: string): boolean;
+export declare function safeRealpathSync(targetPath: string, cache?: Map<string, string>): string | null;
+export declare function isPathInsideWithRealpath(basePath: string, candidatePath: string, opts?: {
+    requireRealpath?: boolean;
+    cache?: Map<string, string>;
+}): boolean;
+export declare function safeStatSync(targetPath: string): fs.Stats | null;
+export declare function formatPosixMode(mode: number): string;
+//# sourceMappingURL=path-safety.d.ts.map

package/dist/path-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.d.ts","sourceRoot":"","sources":["../src/path-safety.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAIzB,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAEzE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAa/F;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChE,OAAO,CAUT;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK,GAAG,IAAI,CAMhE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/path-safety.js

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isPathInside as isRootPathInside } from "./path-guards.js";
+export function resolveSafeBaseDir(rootDir) {
+    const resolved = path.resolve(rootDir);
+    return resolved.endsWith(path.sep) ? resolved : `${resolved}${path.sep}`;
+}
+export function isWithinDir(rootDir, targetPath) {
+    return isRootPathInside(rootDir, targetPath);
+}
+export function isPathInside(baseDir, targetPath) {
+    return isRootPathInside(baseDir, targetPath);
+}
+export function safeRealpathSync(targetPath, cache) {
+    const cached = cache?.get(targetPath);
+    if (cached) {
+        return cached;
+    }
+    try {
+        const resolved = fs.realpathSync(targetPath);
+        cache?.set(targetPath, resolved);
+        cache?.set(resolved, resolved);
+        return resolved;
+    }
+    catch {
+        return null;
+    }
+}
+export function isPathInsideWithRealpath(basePath, candidatePath, opts) {
+    if (!isPathInside(basePath, candidatePath)) {
+        return false;
+    }
+    const baseReal = safeRealpathSync(basePath, opts?.cache);
+    const candidateReal = safeRealpathSync(candidatePath, opts?.cache);
+    if (!baseReal || !candidateReal) {
+        return opts?.requireRealpath === false;
+    }
+    return isPathInside(baseReal, candidateReal);
+}
+export function safeStatSync(targetPath) {
+    try {
+        return fs.statSync(targetPath);
+    }
+    catch {
+        return null;
+    }
+}
+export function formatPosixMode(mode) {
+    return (mode & 0o777).toString(8).padStart(3, "0");
+}

package/dist/path-scope.d.ts

@@ -0,0 +1,2 @@
+export { pathScope, type PathScope, type PathScopeOptions, type PathScopeResolveOptions, } from "./root-paths.js";
+//# sourceMappingURL=path-scope.d.ts.map

package/dist/path-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-scope.d.ts","sourceRoot":"","sources":["../src/path-scope.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,iBAAiB,CAAC"}

package/dist/path-scope.js

@@ -0,0 +1 @@
+export { pathScope, } from "./root-paths.js";

package/dist/path.d.ts

@@ -0,0 +1,18 @@
+import fs from "node:fs";
+export declare function normalizeWindowsPathForComparison(input: string): string;
+export declare function isNodeError(value: unknown): value is NodeJS.ErrnoException;
+export declare function hasNodeErrorCode(value: unknown, code: string): boolean;
+export declare function isNotFoundPathError(value: unknown): boolean;
+export declare function isSymlinkOpenError(value: unknown): boolean;
+export declare function isPathInside(root: string, target: string): boolean;
+export declare function resolveSafeBaseDir(rootDir: string): string;
+export declare function isWithinDir(rootDir: string, targetPath: string): boolean;
+export declare function safeRealpathSync(targetPath: string, cache?: Map<string, string>): string | null;
+export declare function isPathInsideWithRealpath(basePath: string, candidatePath: string, opts?: {
+    requireRealpath?: boolean;
+    cache?: Map<string, string>;
+}): boolean;
+export declare function safeStatSync(targetPath: string): fs.Stats | null;
+export declare function splitSafeRelativePath(relativePath: string): string[];
+export declare function resolveSafeRelativePath(rootDir: string, relativePath: string): string;
+//# sourceMappingURL=path.d.ts.map

package/dist/path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAWzB,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASvE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAI1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA0BlE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAa/F;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChE,OAAO,CAUT;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK,GAAG,IAAI,CAMhE;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAyBpE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAOrF"}

package/dist/path.js

@@ -0,0 +1,123 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
+const NOT_FOUND_CODES = new Set(["ENOENT", "ENOTDIR"]);
+const SYMLINK_OPEN_CODES = new Set(["ELOOP", "EINVAL", "ENOTSUP"]);
+const PARENT_SEGMENT_PREFIX = /^\.\.(?:[\\/]|$)/u;
+const POSIX_SEPARATOR_CHAR_CODE = 0x2f;
+export function normalizeWindowsPathForComparison(input) {
+    let normalized = path.win32.normalize(input);
+    if (normalized.startsWith("\\\\?\\")) {
+        normalized = normalized.slice(4);
+        if (normalized.toUpperCase().startsWith("UNC\\")) {
+            normalized = `\\\\${normalized.slice(4)}`;
+        }
+    }
+    return normalizeLowercaseStringOrEmpty(normalized.replaceAll("/", "\\"));
+}
+export function isNodeError(value) {
+    return Boolean(value && typeof value === "object" && "code" in value);
+}
+export function hasNodeErrorCode(value, code) {
+    return isNodeError(value) && value.code === code;
+}
+export function isNotFoundPathError(value) {
+    return isNodeError(value) && typeof value.code === "string" && NOT_FOUND_CODES.has(value.code);
+}
+export function isSymlinkOpenError(value) {
+    return isNodeError(value) && typeof value.code === "string" && SYMLINK_OPEN_CODES.has(value.code);
+}
+export function isPathInside(root, target) {
+    if (process.platform === "win32") {
+        const rootForCompare = normalizeWindowsPathForComparison(path.win32.resolve(root));
+        const targetForCompare = normalizeWindowsPathForComparison(path.win32.resolve(target));
+        const relative = path.win32.relative(rootForCompare, targetForCompare);
+        return (relative === "" || (!PARENT_SEGMENT_PREFIX.test(relative) && !path.win32.isAbsolute(relative)));
+    }
+    if (root.length > 0 &&
+        root.charCodeAt(0) === POSIX_SEPARATOR_CHAR_CODE &&
+        target.length >= root.length &&
+        target.charCodeAt(0) === POSIX_SEPARATOR_CHAR_CODE &&
+        !target.includes("/..") &&
+        (target === root ||
+            (target.startsWith(root) && target.charCodeAt(root.length) === POSIX_SEPARATOR_CHAR_CODE))) {
+        return true;
+    }
+    const resolvedRoot = path.resolve(root);
+    const resolvedTarget = path.resolve(target);
+    const relative = path.relative(resolvedRoot, resolvedTarget);
+    return relative === "" || (!PARENT_SEGMENT_PREFIX.test(relative) && !path.isAbsolute(relative));
+}
+export function resolveSafeBaseDir(rootDir) {
+    const resolved = path.resolve(rootDir);
+    return resolved.endsWith(path.sep) ? resolved : `${resolved}${path.sep}`;
+}
+export function isWithinDir(rootDir, targetPath) {
+    return isPathInside(rootDir, targetPath);
+}
+export function safeRealpathSync(targetPath, cache) {
+    const cached = cache?.get(targetPath);
+    if (cached) {
+        return cached;
+    }
+    try {
+        const resolved = fs.realpathSync(targetPath);
+        cache?.set(targetPath, resolved);
+        cache?.set(resolved, resolved);
+        return resolved;
+    }
+    catch {
+        return null;
+    }
+}
+export function isPathInsideWithRealpath(basePath, candidatePath, opts) {
+    if (!isPathInside(basePath, candidatePath)) {
+        return false;
+    }
+    const baseReal = safeRealpathSync(basePath, opts?.cache);
+    const candidateReal = safeRealpathSync(candidatePath, opts?.cache);
+    if (!baseReal || !candidateReal) {
+        return opts?.requireRealpath === false;
+    }
+    return isPathInside(baseReal, candidateReal);
+}
+export function safeStatSync(targetPath) {
+    try {
+        return fs.statSync(targetPath);
+    }
+    catch {
+        return null;
+    }
+}
+export function splitSafeRelativePath(relativePath) {
+    if (relativePath.length === 0 || relativePath === ".") {
+        return [];
+    }
+    if (relativePath.includes("\0")) {
+        throw new FsSafeError("invalid-path", "relative path contains a NUL byte");
+    }
+    if (relativePath.includes("\\")) {
+        throw new FsSafeError("invalid-path", "relative path must use forward slashes");
+    }
+    if (path.posix.isAbsolute(relativePath) ||
+        path.win32.isAbsolute(relativePath) ||
+        relativePath.startsWith("//")) {
+        throw new FsSafeError("invalid-path", "relative path must not be absolute");
+    }
+    const segments = relativePath.split("/").filter((segment) => segment.length > 0 && segment !== ".");
+    for (const segment of segments) {
+        if (segment === "..") {
+            throw new FsSafeError("invalid-path", "relative path must not contain '..'");
+        }
+    }
+    return segments;
+}
+export function resolveSafeRelativePath(rootDir, relativePath) {
+    const root = path.resolve(rootDir);
+    const target = path.resolve(root, ...splitSafeRelativePath(relativePath));
+    if (target !== root && !target.startsWith(root + path.sep)) {
+        throw new FsSafeError("outside-workspace", "relative path escapes root");
+    }
+    return target;
+}

package/dist/permissions-public.d.ts

@@ -0,0 +1,2 @@
+export { formatOctal, formatPermissionDetail, formatPermissionRemediation, inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, safeStat, type PermissionCheck, type PermissionCheckOptions, type SafeStatResult, } from "./permissions.js";
+//# sourceMappingURL=permissions-public.d.ts.map

package/dist/permissions-public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions-public.d.ts","sourceRoot":"","sources":["../src/permissions-public.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,2BAA2B,EAC3B,sBAAsB,EACtB,eAAe,EACf,eAAe,EACf,eAAe,EACf,eAAe,EACf,QAAQ,EACR,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC"}

package/dist/permissions-public.js

@@ -0,0 +1 @@
+export { formatOctal, formatPermissionDetail, formatPermissionRemediation, inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, safeStat, } from "./permissions.js";

package/dist/permissions.d.ts

@@ -0,0 +1,86 @@
+export type PermissionExec = (command: string, args: string[]) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export type PermissionCheck = {
+    ok: boolean;
+    isSymlink: boolean;
+    isDir: boolean;
+    mode: number | null;
+    bits: number | null;
+    source: "posix" | "windows-acl" | "unknown";
+    worldWritable: boolean;
+    groupWritable: boolean;
+    worldReadable: boolean;
+    groupReadable: boolean;
+    aclSummary?: string;
+    error?: string;
+};
+export type PermissionCheckOptions = {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    exec?: PermissionExec;
+};
+export type SafeStatResult = {
+    ok: boolean;
+    isSymlink: boolean;
+    isDir: boolean;
+    mode: number | null;
+    uid: number | null;
+    gid: number | null;
+    error?: string;
+};
+export type WindowsAclEntry = {
+    principal: string;
+    rights: string[];
+    rawRights: string;
+    canRead: boolean;
+    canWrite: boolean;
+};
+export type WindowsAclSummary = {
+    ok: boolean;
+    entries: WindowsAclEntry[];
+    untrustedWorld: WindowsAclEntry[];
+    untrustedGroup: WindowsAclEntry[];
+    trusted: WindowsAclEntry[];
+    error?: string;
+};
+export type WindowsUserInfoProvider = () => {
+    username?: string | null;
+};
+export type IcaclsResetCommandOptions = {
+    isDir: boolean;
+    env?: NodeJS.ProcessEnv;
+    userInfo?: WindowsUserInfoProvider;
+};
+export declare function safeStat(targetPath: string): Promise<SafeStatResult>;
+export declare function inspectPathPermissions(targetPath: string, opts?: PermissionCheckOptions): Promise<PermissionCheck>;
+export declare function formatPermissionDetail(targetPath: string, perms: PermissionCheck): string;
+export declare function formatPermissionRemediation(params: {
+    targetPath: string;
+    perms: PermissionCheck;
+    isDir: boolean;
+    posixMode: number;
+    env?: NodeJS.ProcessEnv;
+}): string;
+export declare function modeBits(mode: number | null): number | null;
+export declare function formatOctal(bits: number | null): string;
+export declare function isWorldWritable(bits: number | null): boolean;
+export declare function isGroupWritable(bits: number | null): boolean;
+export declare function isWorldReadable(bits: number | null): boolean;
+export declare function isGroupReadable(bits: number | null): boolean;
+export declare function resolveWindowsUserPrincipal(env?: NodeJS.ProcessEnv, userInfo?: WindowsUserInfoProvider): string | null;
+export declare function parseIcaclsOutput(output: string, targetPath: string): WindowsAclEntry[];
+export declare function summarizeWindowsAcl(entries: WindowsAclEntry[], env?: NodeJS.ProcessEnv): Pick<WindowsAclSummary, "trusted" | "untrustedWorld" | "untrustedGroup">;
+export declare function inspectWindowsAcl(targetPath: string, opts?: {
+    env?: NodeJS.ProcessEnv;
+    exec?: PermissionExec;
+}): Promise<WindowsAclSummary>;
+export declare function formatWindowsAclSummary(summary: WindowsAclSummary): string;
+export declare function formatIcaclsResetCommand(targetPath: string, opts: IcaclsResetCommandOptions): string;
+export declare function createIcaclsResetCommand(targetPath: string, opts: IcaclsResetCommandOptions): {
+    command: string;
+    args: string[];
+    display: string;
+} | null;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.d.ts.map

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