@openclaw/matrix 2026.9.6 → 2026.9.8

package/node_modules/@openclaw/fs-safe/dist/creation-boundary.js

@@ -0,0 +1,371 @@
+import fs, {} from "node:fs";
+import fsAsync from "node:fs/promises";
+import path from "node:path";
+import { assertDirectoryIdentitySync, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { nodeDarwinDirectoryMetadataFlags, nodeDirectorySearchOnlyFlags } from "./directory-mode-node.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { warnNativeFallback } from "./native-fallback-warning.js";
+import { assertNoNulPathInput } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
+import { inspectWindowsDirectoryCommand, inspectWindowsDirectoryCommandSync, protectPrivateWindowsFileCommand, protectPrivateWindowsFileCommandSync, verifyPrivateWindowsFileCommand, verifyPrivateWindowsFileCommandSync, hasUnsettledWindowsSecurityCommand, } from "./windows-security-command.js";
+export function resolveCreationPermissions(options, directory) {
+    const privatePath = options.private;
+    const mode = options.mode;
+    if (privatePath !== undefined && typeof privatePath !== "boolean") {
+        throw new TypeError("private must be a boolean");
+    }
+    if (mode !== undefined && (!Number.isInteger(mode) || mode < 0 || mode > 0o7777)) {
+        throw new RangeError("mode must contain only permission bits");
+    }
+    if (privatePath && mode !== undefined && (mode & 0o7077) !== 0) {
+        throw new FsSafeError("insecure-permissions", "private creation requires owner-only permission bits");
+    }
+    if (privatePath)
+        assertDarwinPrivateCreationAvailable();
+    if (privatePath && directory)
+        assertDarwinPrivateDirectoryMode(mode ?? 0o700);
+    return { private: privatePath === true, mode: mode ?? (privatePath ? directory ? 0o700 : 0o600 : undefined) };
+}
+function assertPrivatePosixDirectory(stat) {
+    if (typeof process.getuid !== "function" || stat.uid !== BigInt(process.getuid())) {
+        throw new FsSafeError("not-owned", "private directory must belong to the current user");
+    }
+    if ((stat.mode & 3647n) !== 0n) {
+        throw new FsSafeError("insecure-permissions", "existing directory is not private");
+    }
+}
+function unavailable() {
+    throw new FsSafeError("helper-unavailable", "private Windows creation requires an up-to-date native helper");
+}
+export function assertPrivateFileCreationAvailable() {
+    const native = getNativeBinding();
+    if (process.platform !== "win32" || getFsSafeNativeConfig().mode !== "require")
+        return;
+    if (typeof native?.createPrivateDirectoryWithParentIdentity !== "function" ||
+        typeof native.inspectWindowsDirectory !== "function" ||
+        typeof native.protectPrivateWindowsFile !== "function" ||
+        typeof native.verifyPrivateWindowsFile !== "function")
+        unavailable();
+}
+function commandFallback() {
+    if (getFsSafeNativeConfig().mode === "require")
+        unavailable();
+    warnNativeFallback("windows-private-creation", "Private Windows creation uses a slower built-in system command.");
+}
+function creationOperation(name) {
+    const native = getNativeBinding();
+    const operation = native?.[name];
+    if (typeof operation === "function")
+        return operation.bind(native);
+    commandFallback();
+    return undefined;
+}
+/** Full Windows identity, with security validation when requested; no repairs. */
+export function inspectCreationDirectorySync(targetPath, privatePath) {
+    assertNoWindowsPathAlias(targetPath, "filesystem");
+    const inspect = creationOperation("inspectWindowsDirectory");
+    return (inspect ? inspect(targetPath, privatePath) : inspectWindowsDirectoryCommandSync(targetPath, privatePath)).identity;
+}
+export async function inspectCreationDirectory(targetPath, privatePath) {
+    assertNoWindowsPathAlias(targetPath, "filesystem");
+    const inspect = creationOperation("inspectWindowsDirectory");
+    return (inspect ? inspect(targetPath, privatePath) : await inspectWindowsDirectoryCommand(targetPath, privatePath)).identity;
+}
+export function assertPrivateDirectorySync(targetPath) {
+    const stat = inspectDirectoryIdentitySync(targetPath);
+    if (process.platform === "win32")
+        inspectCreationDirectorySync(targetPath, true);
+    else {
+        assertPrivatePosixDirectory(stat);
+        assertDarwinCreationDirectoryAcl(targetPath, stat);
+    }
+    inspectDirectoryIdentitySync(targetPath, stat);
+}
+export async function assertPrivateDirectory(targetPath) {
+    const stat = inspectDirectoryIdentitySync(targetPath);
+    if (process.platform === "win32")
+        await inspectCreationDirectory(targetPath, true);
+    else {
+        assertPrivatePosixDirectory(stat);
+        assertDarwinCreationDirectoryAcl(targetPath, stat);
+    }
+    inspectDirectoryIdentitySync(targetPath, stat);
+}
+export function protectCreatedFileSync(fd, targetPath, parentIdentity) {
+    const protect = creationOperation("protectPrivateWindowsFile");
+    return (protect ? protect(fd, targetPath, parentIdentity)
+        : protectPrivateWindowsFileCommandSync(fd, targetPath, parentIdentity)).identity;
+}
+export async function protectCreatedFile(fd, targetPath, parentIdentity) {
+    const protect = creationOperation("protectPrivateWindowsFile");
+    return (protect ? protect(fd, targetPath, parentIdentity)
+        : await protectPrivateWindowsFileCommand(fd, targetPath, parentIdentity)).identity;
+}
+export function verifyCreatedFileSync(fd, targetPath, identity, parentIdentity, links = 1) {
+    const verify = creationOperation("verifyPrivateWindowsFile");
+    if (verify)
+        verify(fd, targetPath, identity, parentIdentity, links);
+    else
+        verifyPrivateWindowsFileCommandSync(fd, targetPath, identity, parentIdentity, links);
+}
+export async function verifyCreatedFile(fd, targetPath, identity, parentIdentity, links = 1) {
+    const verify = creationOperation("verifyPrivateWindowsFile");
+    if (verify)
+        verify(fd, targetPath, identity, parentIdentity, links);
+    else
+        await verifyPrivateWindowsFileCommand(fd, targetPath, identity, parentIdentity, links);
+}
+function inspector() {
+    const native = getNativeBinding();
+    if (typeof native?.inspectDarwinAcl !== "function") {
+        throw new FsSafeError("helper-unavailable", "private Darwin creation requires native descriptor ACL inspection");
+    }
+    return native.inspectDarwinAcl.bind(native);
+}
+export function assertDarwinPrivateCreationAvailable() {
+    if (process.platform === "darwin")
+        inspector();
+}
+export function assertDarwinPrivateDirectoryMode(mode) {
+    if (process.platform === "darwin" && ((mode & ~process.umask()) & 0o500) === 0) {
+        throw new FsSafeError("helper-unavailable", "private Darwin directory ACL inspection requires owner read or search permission");
+    }
+}
+export function assertDarwinCreationAcl(fd, inheritanceTarget) {
+    if (process.platform !== "darwin")
+        return;
+    const inspect = inspector();
+    const state = inspect(fd, inheritanceTarget)?.state;
+    if (state === "present") {
+        throw new FsSafeError("insecure-permissions", inheritanceTarget
+            ? "private creation parent has inheritable Darwin ACL entries"
+            : "private creation object has Darwin ACL entries");
+    }
+    if (state !== "absent" && state !== "empty") {
+        throw new FsSafeError("helper-unavailable", "native Darwin ACL inspection returned incomplete facts");
+    }
+}
+export function assertDarwinCreationDirectoryAcl(pathname, expected, inheritanceTarget) {
+    if (process.platform !== "darwin")
+        return;
+    assertDarwinPrivateCreationAvailable();
+    let fd;
+    try {
+        fd = fs.openSync(pathname, nodeDarwinDirectoryMetadataFlags());
+    }
+    catch (error) {
+        if (error.code !== "EACCES")
+            throw error;
+        const search = nodeDirectorySearchOnlyFlags();
+        if (!search)
+            throw error;
+        try {
+            fd = fs.openSync(pathname, search.flags | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+        }
+        catch (cause) {
+            if (cause.code !== "EACCES")
+                throw cause;
+            throw new FsSafeError("helper-unavailable", "private Darwin directory ACL inspection requires owner read or search permission", { cause });
+        }
+    }
+    try {
+        const opened = inspectFileIdentitySync(() => fs.fstatSync(fd, { bigint: true }), expected);
+        if (!opened.isDirectory())
+            throw new FsSafeError("path-mismatch", "ACL target is not the admitted directory");
+        assertDarwinCreationAcl(fd, inheritanceTarget);
+        inspectDirectoryIdentitySync(pathname, expected);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function assertCreationFile(fd, pathname, expected) {
+    const opened = inspectFileIdentitySync(() => fs.fstatSync(fd, { bigint: true }), expected);
+    const named = inspectFileIdentitySync(() => fs.lstatSync(pathname, { bigint: true }), opened);
+    if (!opened.isFile() || !named.isFile() || named.isSymbolicLink() || opened.nlink !== 1n || named.nlink !== 1n) {
+        throw new FsSafeError("path-mismatch", "created file is not the expected single-linked regular file");
+    }
+    return opened;
+}
+export function assertPrivateCreationFile(stat, fd) {
+    if (process.platform === "win32")
+        return;
+    if (typeof process.getuid !== "function" || stat.uid !== BigInt(process.getuid())) {
+        throw new FsSafeError("not-owned", "created private file must belong to the current user");
+    }
+    if ((stat.mode & 3647n) !== 0n) {
+        throw new FsSafeError("insecure-permissions", "created private file is not owner-only");
+    }
+    assertDarwinCreationAcl(fd);
+}
+function assertRecordedFile(current, identity) {
+    if (!current.isFile() || current.isSymbolicLink() || !sameFileIdentityForCleanup(current, identity)) {
+        throw new FsSafeError("path-mismatch", "created file cleanup preserved a replacement");
+    }
+}
+export function removeRecordedCreationFileSync(pathname, identity, assertParent) {
+    assertParent();
+    let current;
+    try {
+        current = fs.lstatSync(pathname, { bigint: true });
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return;
+        throw error;
+    }
+    assertRecordedFile(current, identity);
+    fs.unlinkSync(pathname);
+}
+export async function removeRecordedCreationFile(pathname, identity, assertParent) {
+    assertParent();
+    let current;
+    try {
+        current = await fsAsync.lstat(pathname, { bigint: true });
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return;
+        throw error;
+    }
+    assertParent();
+    assertRecordedFile(current, identity);
+    // Recheck after the awaited observation before dispatching the unlink.
+    assertRecordedFile(fs.lstatSync(pathname, { bigint: true }), identity);
+    await fsAsync.unlink(pathname);
+}
+export function creationPublicationAfterFailure(error, recorded) {
+    if (error instanceof FsSafeError) {
+        const publication = error.details?.publication;
+        if (publication && typeof publication === "object" && "status" in publication &&
+            publication.status === "indeterminate")
+            return "indeterminate";
+    }
+    return recorded;
+}
+export function hasPreservedCreationArtifacts(error) {
+    if (!(error instanceof FsSafeError))
+        return false;
+    if (error.details?.cleanup === "preserved" || error.details?.cleanup === "failed")
+        return true;
+    const publication = error.details?.publication;
+    return publication !== null && typeof publication === "object" && "status" in publication &&
+        (publication.status === "published" || publication.status === "indeterminate");
+}
+export function rethrowPrivateStageCreationFailure(error, path, stageDirectory) {
+    if (error instanceof FsSafeError && error.code === "already-exists") {
+        throw new FsSafeError("helper-failed", "private file staging path already exists", {
+            cause: error, details: { publication: { status: "not-published" }, path, stageDirectory },
+        });
+    }
+    const publication = error instanceof FsSafeError ? error.details?.publication : undefined;
+    const created = error instanceof FsSafeError && error.details?.path === stageDirectory &&
+        publication !== null && typeof publication === "object" && "status" in publication &&
+        publication.status === "published";
+    let unconfirmed = hasUnsettledWindowsSecurityCommand(error);
+    if (error !== null && (typeof error === "object" || typeof error === "function")) {
+        try {
+            const outcome = Object.getOwnPropertyDescriptor(error, "creationOutcome");
+            unconfirmed ||= Boolean(outcome && "value" in outcome && outcome.value === "unconfirmed");
+        }
+        catch {
+            unconfirmed = true;
+        }
+    }
+    if (created || unconfirmed) {
+        throw privateFileSettlementFailure({
+            primary: error, cleanup: [], publication: "not-published", path, stageDirectory, preserved: true,
+        });
+    }
+    throw error;
+}
+export function privateFileSettlementFailure(params) {
+    return new FsSafeError("helper-failed", "file creation or staging settlement failed", {
+        cause: params.cleanup.length
+            ? new AggregateError([params.primary, ...params.cleanup], "file creation and cleanup failed")
+            : params.primary,
+        details: {
+            publication: { status: params.publication }, path: params.path, stageDirectory: params.stageDirectory,
+            cleanup: params.preserved || params.publication === "indeterminate" ? "preserved" : params.cleanup.length ? "failed" : "removed",
+        },
+    });
+}
+export function assertBeforeCreation(selected, permissions, assertion, kind) {
+    if (permissions.private)
+        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, kind);
+    assertSynchronousCallbackResult(assertion?.(), "assertBeforeMutation");
+    selected.assertParent();
+    if (permissions.private && kind === "directory")
+        assertDarwinPrivateDirectoryMode(permissions.mode);
+    if (permissions.private)
+        assertDarwinCreationDirectoryAcl(selected.parent.dir, selected.parent.stat, kind);
+}
+export function creationAdmissionFromParent(parent) {
+    const { dev, ino } = parent.stat;
+    if (typeof dev !== "bigint" || typeof ino !== "bigint") {
+        throw new FsSafeError("path-mismatch", "private creation requires an exact parent identity");
+    }
+    const identity = inspectDirectoryIdentitySync(parent.dir, { dev, ino });
+    return { expectedParentIdentity: { dev: identity.dev, ino: identity.ino, realPath: parent.realPath } };
+}
+export function prepareCreationPath(input, expectedParent) {
+    expectedParent = expectedParent && { dev: expectedParent.dev, ino: expectedParent.ino, realPath: expectedParent.realPath };
+    assertNoNulPathInput(input);
+    assertNoWindowsPathAlias(input, "filesystem");
+    if (process.platform === "win32" && input.replaceAll("/", "\\").split("\\")
+        .some(component => component.endsWith(".") || component.endsWith(" "))) {
+        throw new FsSafeError("invalid-path", "creation path contains an ambiguous Windows component");
+    }
+    const target = resolvePathPreservingWindowsRoot(input);
+    const directory = path.dirname(target);
+    if (target === directory || input.length === 0) {
+        throw new FsSafeError("invalid-path", "creation requires a child name");
+    }
+    if (expectedParent)
+        assertDirectoryIdentitySync(directory, expectedParent);
+    const stat = inspectDirectoryIdentitySync(directory);
+    const realPath = realpathSync.native(directory);
+    const parent = { dir: directory, realPath, stat };
+    const assertParent = () => {
+        assertDirectoryIdentitySync(directory, { dev: stat.dev, ino: stat.ino, realPath });
+        if (expectedParent)
+            assertDirectoryIdentitySync(directory, expectedParent);
+    };
+    assertParent();
+    return { target, parent, assertParent };
+}
+export function creationCollision(error) {
+    if (error?.code === "EEXIST") {
+        return new FsSafeError("already-exists", "creation target already exists", { cause: error });
+    }
+    return error;
+}
+/** Remove only the recorded empty stage; never traverse a replaced directory. */
+export function removeCreationDirectory(directory, identity, assertParent) {
+    assertParent();
+    try {
+        assertDirectoryIdentitySync(directory, identity);
+        fs.rmdirSync(directory);
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+}
+export async function removeCreationDirectoryAsync(directory, identity, assertParent) {
+    assertParent();
+    try {
+        assertDirectoryIdentitySync(directory, identity);
+        await fsAsync.rmdir(directory);
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/deny-mutation-match.d.ts

@@ -0,0 +1,2 @@
+/** Cache observations only within one synchronous policy check, never across mutations or callbacks. */
+export declare function createMutationDenyMatcher(): (target: string, denied: string, prefix: boolean, protectAncestors?: boolean) => boolean;

package/node_modules/@openclaw/fs-safe/dist/deny-mutation-match.js

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { isPathInside } from "./path.js";
+import { probePathCaseInsensitiveSync } from "./path-case.js";
+import { observeMutationPath } from "./pinned-mutation-observation.js";
+function foldedName(name) {
+    // Decompose before folding so combining marks precede an expanded Greek subscript.
+    // Default folding preserves dotless i even though its uppercase mapping is I.
+    return name.normalize("NFD").replace(/[^\u0131]+/gu, part => part.toLowerCase().toUpperCase().toLowerCase()).normalize("NFC");
+}
+function asciiCasePair(left, right) {
+    return /^[\x00-\x7f]*$/.test(left) && /^[\x00-\x7f]*$/.test(right) &&
+        left.toLowerCase() === right.toLowerCase();
+}
+/** Cache observations only within one synchronous policy check, never across mutations or callbacks. */
+export function createMutationDenyMatcher() {
+    const observations = new Map();
+    const caseObservations = new Map();
+    const observe = (pathname) => {
+        if (!observations.has(pathname))
+            observations.set(pathname, observeMutationPath(pathname));
+        return observations.get(pathname);
+    };
+    const prospectiveInside = (parent, child) => {
+        const root = path.parse(parent).root;
+        if (root !== path.parse(child).root)
+            return false;
+        const left = parent.slice(root.length).split(path.sep);
+        const right = child.slice(root.length).split(path.sep).slice(0, left.length);
+        if (left.length !== right.length || !left.every((name, i) => foldedName(name) === foldedName(right[i]))) {
+            return false;
+        }
+        // Byte-identical relations were already handled without any observations.
+        if (left.every((name, i) => name === right[i]))
+            return false;
+        const alignedChild = path.join(root, ...right);
+        const a = observe(parent);
+        const b = observe(alignedChild);
+        if (!a || !b)
+            return true;
+        // Distinct existing ancestors are real objects, not prospective aliases.
+        if (a.canonicalAncestor !== b.canonicalAncestor ||
+            a.missingSegments.length === 0 || a.missingSegments.length !== b.missingSegments.length)
+            return false;
+        const missingLeft = a.missingSegments;
+        const missingRight = b.missingSegments;
+        if (!missingLeft.every((name, i) => foldedName(name) === foldedName(missingRight[i])))
+            return false;
+        const difference = missingLeft.findIndex((name, i) => name !== missingRight[i]);
+        if (difference === -1)
+            return true;
+        // A read-only ASCII observation can disprove aliasing at this existing parent.
+        // It cannot prove Unicode sensitivity or the behavior of a future directory.
+        if (difference === 0 && asciiCasePair(missingLeft[0], missingRight[0])) {
+            if (!caseObservations.has(a.canonicalAncestor)) {
+                caseObservations.set(a.canonicalAncestor, probePathCaseInsensitiveSync(path.join(a.canonicalAncestor, missingLeft[0]), { allowTemporaryProbe: false }));
+            }
+            if (caseObservations.get(a.canonicalAncestor) === false)
+                return false;
+        }
+        // Suffix probing writes directories. Policy admission has no authority for
+        // those side effects, so unproven case/normalization equivalence fails closed.
+        return true;
+    };
+    return (target, denied, prefix, protectAncestors = false) => {
+        if ((isPathInside(denied, target) && (prefix || isPathInside(target, denied))) ||
+            (protectAncestors && isPathInside(target, denied)))
+            return true;
+        return ((prefix || target.split(path.sep).length === denied.split(path.sep).length) &&
+            prospectiveInside(denied, target)) || (protectAncestors && prospectiveInside(target, denied));
+    };
+}

package/node_modules/@openclaw/fs-safe/dist/deny-mutations.d.ts

@@ -0,0 +1,11 @@
+export declare function resolveMutationComparablePaths(rawPath: string): Set<string>;
+export type DenyMutationPolicy = {
+    paths?: readonly string[];
+    prefixes?: readonly string[];
+};
+type DenyMutationCheckOptions = {
+    protectAncestors?: boolean;
+};
+export declare function assertMutationNotDenied(filePath: string, policy: DenyMutationPolicy | undefined, options?: DenyMutationCheckOptions, mode?: "root" | "sync-root-lock"): void;
+export declare function mergeDenyMutationPolicies(defaultPolicy: DenyMutationPolicy | undefined, callPolicy: DenyMutationPolicy | undefined): DenyMutationPolicy | undefined;
+export {};

package/node_modules/@openclaw/fs-safe/dist/deny-mutations.js

@@ -0,0 +1,96 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createMutationDenyMatcher } from "./deny-mutation-match.js";
+import { FsSafeError } from "./errors.js";
+import { assertNoNulPathInput, isNotFoundPathError } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { resolveExistingAncestor } from "./root-path-existing.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+export function resolveMutationComparablePaths(rawPath) {
+    assertNoNulPathInput(rawPath, "path contains a NUL byte");
+    assertNoWindowsPathAlias(rawPath, "filesystem", "mutation path uses a Windows filesystem namespace alias");
+    const resolved = resolvePathPreservingWindowsRoot(rawPath);
+    assertNoWindowsPathAlias(resolved, "filesystem", "mutation path uses a Windows filesystem namespace alias");
+    const canonical = resolveExistingAncestor(resolved, "native");
+    assertNoWindowsPathAlias(canonical, "filesystem", "mutation path uses a Windows filesystem namespace alias");
+    return new Set([resolved, canonical]);
+}
+function strictMutationComparablePaths(pathname) {
+    const resolved = resolvePathPreservingWindowsRoot(pathname);
+    assertNoWindowsPathAlias(resolved, "filesystem", "mutation path uses a Windows filesystem namespace alias");
+    let cursor = resolved;
+    const filesystemRoot = path.parse(resolved).root;
+    while (cursor !== filesystemRoot) {
+        try {
+            fs.lstatSync(pathForWindowsFilesystem(cursor));
+            break;
+        }
+        catch (error) {
+            if (!isNotFoundPathError(error))
+                throw error;
+            cursor = path.dirname(cursor);
+        }
+    }
+    // Synchronous Root locks require authority-grade canonicalization. Keep
+    // ambiguous existing ancestors distinct from Root's lexical fallback.
+    const canonicalAncestor = realpathSync.native(pathForWindowsFilesystem(cursor));
+    assertNoWindowsPathAlias(canonicalAncestor, "filesystem", "mutation path uses a Windows filesystem namespace alias");
+    const canonical = cursor === resolved
+        ? canonicalAncestor
+        : path.resolve(canonicalAncestor, `.${path.sep}${resolved.slice(cursor.length)}`);
+    assertNoWindowsPathAlias(canonical, "filesystem", "mutation path uses a Windows filesystem namespace alias");
+    return path.relative(path.resolve(resolved), path.resolve(canonical)) === ""
+        ? [resolved] : [resolved, canonical];
+}
+function policyPathEntries(entries, strict) {
+    const paths = [];
+    for (const entry of entries ?? []) {
+        if (strict && (!entry || !path.isAbsolute(entry))) {
+            throw new FsSafeError("invalid-path", "deny mutation paths must be non-empty absolute paths");
+        }
+        if (entry.length === 0) {
+            throw new FsSafeError("invalid-path", "deny mutation paths must be non-empty");
+        }
+        assertNoNulPathInput(entry, "deny mutation path contains a NUL byte");
+        assertNoWindowsPathAlias(entry, "filesystem", "deny mutation path uses a Windows filesystem namespace alias");
+        if (!strict && !path.isAbsolute(entry)) {
+            throw new FsSafeError("invalid-path", "deny mutation paths must be absolute");
+        }
+        paths.push(strict ? resolvePathPreservingWindowsRoot(entry) : entry);
+    }
+    return paths;
+}
+export function assertMutationNotDenied(filePath, policy, options = {}, mode = "root") {
+    if (!policy?.paths?.length && !policy?.prefixes?.length)
+        return;
+    const strict = mode === "sync-root-lock";
+    const comparablePaths = strict ? strictMutationComparablePaths : resolveMutationComparablePaths;
+    const targets = comparablePaths(filePath);
+    const matches = createMutationDenyMatcher();
+    // Validate one complete phase at a time. A paths denial must not read or
+    // canonicalize prefixes, and invalid later paths retain validation precedence.
+    for (const kind of ["paths", "prefixes"]) {
+        for (const entry of policyPathEntries(policy[kind], strict)) {
+            const deniedPaths = comparablePaths(entry);
+            for (const target of targets) {
+                for (const denied of deniedPaths) {
+                    if (matches(target, denied, kind === "prefixes", options.protectAncestors)) {
+                        throw new FsSafeError("denied-path", "path is denied by denyMutations policy");
+                    }
+                }
+            }
+        }
+    }
+}
+export function mergeDenyMutationPolicies(defaultPolicy, callPolicy) {
+    if (!defaultPolicy) {
+        return callPolicy;
+    }
+    if (!callPolicy) {
+        return defaultPolicy;
+    }
+    return {
+        paths: [...(defaultPolicy.paths ?? []), ...(callPolicy.paths ?? [])],
+        prefixes: [...(defaultPolicy.prefixes ?? []), ...(callPolicy.prefixes ?? [])],
+    };
+}

package/node_modules/@openclaw/fs-safe/dist/device-path.d.ts

@@ -0,0 +1,14 @@
+export type UnsafeDeviceReadPathReason = "posix-device" | "posix-fd" | "windows-device";
+export type UnsafeDeviceReadPathMatch = {
+    path: string;
+    reason: UnsafeDeviceReadPathReason;
+};
+export type UnsafeDeviceReadPathOptions = {
+    cwd?: string;
+    platform?: NodeJS.Platform;
+};
+export declare const WINDOWS_RESERVED_DEVICE_NAMES: ReadonlySet<string>;
+export declare function isWindowsReservedDeviceName(name: string): boolean;
+export declare function matchUnsafeDeviceReadPath(filePath: string, options?: UnsafeDeviceReadPathOptions): UnsafeDeviceReadPathMatch | undefined;
+export declare function isUnsafeDeviceReadPath(filePath: string, options?: UnsafeDeviceReadPathOptions): boolean;
+export declare function assertNoUnsafeDeviceReadPath(filePath: string, options?: UnsafeDeviceReadPathOptions): void;