@openclaw/fs-safe 0.2.3 → 0.2.4

package/dist/secure-temp-workspace.d.ts

@@ -0,0 +1,25 @@
+export type SecureTempWorkspaceOptions = {
+    rootDir: string;
+    prefix: string;
+    dirMode?: number;
+    fileMode?: number;
+};
+export type SecureTempWorkspace = {
+    dir: string;
+    path(fileName: string): string;
+    writePrivate(fileName: string, data: string | Uint8Array): Promise<string>;
+    read(fileName: string): Promise<Buffer>;
+    cleanup(): Promise<void>;
+};
+export type SecureTempWorkspaceSync = {
+    dir: string;
+    path(fileName: string): string;
+    writePrivate(fileName: string, data: string | Uint8Array): string;
+    read(fileName: string): Buffer;
+    cleanup(): void;
+};
+export declare function createSecureTempWorkspace(options: SecureTempWorkspaceOptions): Promise<SecureTempWorkspace>;
+export declare function withSecureTempWorkspace<T>(options: SecureTempWorkspaceOptions, run: (workspace: SecureTempWorkspace) => Promise<T>): Promise<T>;
+export declare function createSecureTempWorkspaceSync(options: SecureTempWorkspaceOptions): SecureTempWorkspaceSync;
+export declare function withSecureTempWorkspaceSync<T>(options: SecureTempWorkspaceOptions, run: (workspace: SecureTempWorkspaceSync) => T): T;
+//# sourceMappingURL=secure-temp-workspace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secure-temp-workspace.d.ts","sourceRoot":"","sources":["../src/secure-temp-workspace.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3E,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IAClE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,OAAO,IAAI,IAAI,CAAC;CACjB,CAAC;AAgDF,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,mBAAmB,CAAC,CA0B9B;AAED,wBAAsB,uBAAuB,CAAC,CAAC,EAC7C,OAAO,EAAE,0BAA0B,EACnC,GAAG,EAAE,CAAC,SAAS,EAAE,mBAAmB,KAAK,OAAO,CAAC,CAAC,CAAC,GAClD,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,0BAA0B,GAClC,uBAAuB,CAsCzB;AAED,wBAAgB,2BAA2B,CAAC,CAAC,EAC3C,OAAO,EAAE,0BAA0B,EACnC,GAAG,EAAE,CAAC,SAAS,EAAE,uBAAuB,KAAK,CAAC,GAC7C,CAAC,CAUH"}

package/dist/secure-temp-workspace.js

@@ -0,0 +1,136 @@
+import { randomUUID } from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+function sanitizeTempPrefix(prefix) {
+    const sanitized = prefix.trim().replace(/[^a-zA-Z0-9._-]/g, "-");
+    if (!sanitized || sanitized === "." || sanitized === "..") {
+        return "fs-safe-";
+    }
+    return sanitized.endsWith("-") ? sanitized : `${sanitized}-`;
+}
+function resolveWorkspaceLeaf(dir, fileName) {
+    const raw = fileName.trim();
+    if (!raw ||
+        raw === "." ||
+        raw === ".." ||
+        raw.includes("\0") ||
+        raw.includes("/") ||
+        raw.includes("\\") ||
+        path.basename(raw) !== raw) {
+        throw new Error(`Invalid temp workspace file name: ${JSON.stringify(fileName)}`);
+    }
+    return path.join(dir, raw);
+}
+async function ensurePrivateDirectory(dir, mode) {
+    await fs.mkdir(dir, { recursive: true, mode });
+    const stat = await fs.lstat(dir);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error(`Temp root must be a directory: ${dir}`);
+    }
+    await fs.chmod(dir, mode).catch(() => undefined);
+}
+function ensurePrivateDirectorySync(dir, mode) {
+    fsSync.mkdirSync(dir, { recursive: true, mode });
+    const stat = fsSync.lstatSync(dir);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error(`Temp root must be a directory: ${dir}`);
+    }
+    try {
+        fsSync.chmodSync(dir, mode);
+    }
+    catch {
+        // Best-effort on platforms that do not enforce POSIX modes.
+    }
+}
+export async function createSecureTempWorkspace(options) {
+    const dirMode = options.dirMode ?? 0o700;
+    const fileMode = options.fileMode ?? 0o600;
+    const root = path.resolve(options.rootDir);
+    await ensurePrivateDirectory(root, dirMode);
+    const dir = await fs.mkdtemp(path.join(root, sanitizeTempPrefix(options.prefix)));
+    await fs.chmod(dir, dirMode).catch(() => undefined);
+    const stat = await fs.lstat(dir);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error(`Temp workspace must be a directory: ${dir}`);
+    }
+    return {
+        dir,
+        path: (fileName) => resolveWorkspaceLeaf(dir, fileName),
+        writePrivate: async (fileName, data) => {
+            const filePath = resolveWorkspaceLeaf(dir, fileName);
+            await fs.writeFile(filePath, data, { mode: fileMode, flag: "wx" });
+            await fs.chmod(filePath, fileMode).catch(() => undefined);
+            return filePath;
+        },
+        read: async (fileName) => await fs.readFile(resolveWorkspaceLeaf(dir, fileName)),
+        cleanup: async () => {
+            await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+        },
+    };
+}
+export async function withSecureTempWorkspace(options, run) {
+    const workspace = await createSecureTempWorkspace({
+        ...options,
+        prefix: `${sanitizeTempPrefix(options.prefix)}${randomUUID()}-`,
+    });
+    try {
+        return await run(workspace);
+    }
+    finally {
+        await workspace.cleanup();
+    }
+}
+export function createSecureTempWorkspaceSync(options) {
+    const dirMode = options.dirMode ?? 0o700;
+    const fileMode = options.fileMode ?? 0o600;
+    const root = path.resolve(options.rootDir);
+    ensurePrivateDirectorySync(root, dirMode);
+    const dir = fsSync.mkdtempSync(path.join(root, sanitizeTempPrefix(options.prefix)));
+    try {
+        fsSync.chmodSync(dir, dirMode);
+    }
+    catch {
+        // Best-effort on platforms that do not enforce POSIX modes.
+    }
+    const stat = fsSync.lstatSync(dir);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error(`Temp workspace must be a directory: ${dir}`);
+    }
+    return {
+        dir,
+        path: (fileName) => resolveWorkspaceLeaf(dir, fileName),
+        writePrivate: (fileName, data) => {
+            const filePath = resolveWorkspaceLeaf(dir, fileName);
+            fsSync.writeFileSync(filePath, data, { mode: fileMode, flag: "wx" });
+            try {
+                fsSync.chmodSync(filePath, fileMode);
+            }
+            catch {
+                // Best-effort on platforms that do not enforce POSIX modes.
+            }
+            return filePath;
+        },
+        read: (fileName) => fsSync.readFileSync(resolveWorkspaceLeaf(dir, fileName)),
+        cleanup: () => {
+            try {
+                fsSync.rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort cleanup.
+            }
+        },
+    };
+}
+export function withSecureTempWorkspaceSync(options, run) {
+    const workspace = createSecureTempWorkspaceSync({
+        ...options,
+        prefix: `${sanitizeTempPrefix(options.prefix)}${randomUUID()}-`,
+    });
+    try {
+        return run(workspace);
+    }
+    finally {
+        workspace.cleanup();
+    }
+}

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

@@ -0,0 +1,16 @@
+export type WriteSiblingTempFileOptions<T> = {
+    dir: string;
+    writeTemp: (tempPath: string) => Promise<T>;
+    resolveFinalPath: (result: T) => string;
+    tempPrefix?: string;
+    dirMode?: number;
+    fileMode?: number;
+    syncTempFile?: boolean;
+    syncParentDir?: boolean;
+};
+export type WriteSiblingTempFileResult<T> = {
+    filePath: string;
+    result: T;
+};
+export declare function writeSiblingTempFile<T>(options: WriteSiblingTempFileOptions<T>): Promise<WriteSiblingTempFileResult<T>>;
+//# sourceMappingURL=sibling-temp-file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sibling-temp-file.d.ts","sourceRoot":"","sources":["../src/sibling-temp-file.ts"],"names":[],"mappings":"AAIA,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,MAAM,CAAC;IAClB,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;AAuCF,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CA+BxC"}

package/dist/sibling-temp-file.js

@@ -0,0 +1,73 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+function buildTempPath(dir, tempPrefix) {
+    return path.join(dir, `${tempPrefix ?? ".fs-safe-stream"}.${process.pid}.${randomUUID()}.tmp`);
+}
+async function syncFileBestEffort(filePath) {
+    const handle = await fs.open(filePath, "r+");
+    try {
+        await handle.sync();
+    }
+    catch (error) {
+        if (error.code !== "EPERM") {
+            throw error;
+        }
+    }
+    finally {
+        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);
+    if (path.dirname(resolvedFile) !== resolvedDir) {
+        throw new Error("Final path must be in the sibling temp directory.");
+    }
+}
+export async function writeSiblingTempFile(options) {
+    const dir = path.resolve(options.dir);
+    await fs.mkdir(dir, { recursive: true, mode: options.dirMode ?? 0o700 });
+    await fs.chmod(dir, options.dirMode ?? 0o700).catch(() => undefined);
+    const tempPath = buildTempPath(dir, options.tempPrefix);
+    let tempExists = false;
+    try {
+        tempExists = true;
+        const result = await options.writeTemp(tempPath);
+        if (options.fileMode !== undefined) {
+            await fs.chmod(tempPath, options.fileMode).catch(() => undefined);
+        }
+        if (options.syncTempFile) {
+            await syncFileBestEffort(tempPath);
+        }
+        const filePath = path.resolve(options.resolveFinalPath(result));
+        assertFinalPathIsSibling(dir, filePath);
+        await fs.rename(tempPath, filePath);
+        tempExists = false;
+        if (options.fileMode !== undefined) {
+            await fs.chmod(filePath, options.fileMode).catch(() => undefined);
+        }
+        if (options.syncParentDir) {
+            await syncDirectoryBestEffort(dir);
+        }
+        return { filePath, result };
+    }
+    finally {
+        if (tempExists) {
+            await fs.rm(tempPath, { force: true }).catch(() => undefined);
+        }
+    }
+}

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

@@ -0,0 +1,8 @@
+export declare function writeViaSiblingTempPath(params: {
+    rootDir: string;
+    targetPath: string;
+    writeTemp: (tempPath: string) => Promise<void>;
+    fallbackFileName?: string;
+    tempPrefix?: string;
+}): Promise<void>;
+//# sourceMappingURL=sibling-temp-write.d.ts.map

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

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

package/dist/sibling-temp-write.js

@@ -0,0 +1,40 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { sanitizeUntrustedFileName } from "./filename.js";
+import { safeRoot } from "./safe-root.js";
+function buildSiblingTempPath(params) {
+    const id = crypto.randomUUID();
+    const safeTail = sanitizeUntrustedFileName(path.basename(params.targetPath), params.fallbackFileName);
+    return path.join(path.dirname(params.targetPath), `${params.tempPrefix}${id}-${safeTail}.part`);
+}
+export async function writeViaSiblingTempPath(params) {
+    const rootDir = await fs
+        .realpath(path.resolve(params.rootDir))
+        .catch(() => path.resolve(params.rootDir));
+    const requestedTargetPath = path.resolve(params.targetPath);
+    const targetPath = await fs
+        .realpath(path.dirname(requestedTargetPath))
+        .then((realDir) => path.join(realDir, path.basename(requestedTargetPath)))
+        .catch(() => requestedTargetPath);
+    const relativeTargetPath = path.relative(rootDir, targetPath);
+    if (!relativeTargetPath ||
+        relativeTargetPath === ".." ||
+        relativeTargetPath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativeTargetPath)) {
+        throw new Error("Target path is outside the allowed root");
+    }
+    const tempPath = buildSiblingTempPath({
+        targetPath,
+        fallbackFileName: params.fallbackFileName ?? "output.bin",
+        tempPrefix: params.tempPrefix ?? ".fs-safe-output-",
+    });
+    try {
+        await params.writeTemp(tempPath);
+        const root = await safeRoot(rootDir);
+        await root.copyFileFrom(tempPath, relativeTargetPath, { mkdir: false });
+    }
+    finally {
+        await fs.rm(tempPath, { force: true }).catch(() => { });
+    }
+}

package/dist/sidecar-lock.d.ts

@@ -5,7 +5,13 @@ export type SidecarLockRetryOptions = {
     maxTimeout?: number;
     randomize?: boolean;
 };
-export type SidecarLockStaleRecovery = "fail-closed";
+export type SidecarLockStaleRecovery = "fail-closed" | "remove-if-unchanged";
+export type SidecarLockStaleSnapshot = {
+    lockPath: string;
+    normalizedTargetPath: string;
+    raw: string;
+    payload: Record<string, unknown> | null;
+};
 export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>> = {
     targetPath: string;
     lockPath?: string;
@@ -23,6 +29,7 @@ export type SidecarLockAcquireOptions<TPayload extends Record<string, unknown>>
         nowMs: number;
         heldByThisProcess: boolean;
     }) => boolean | Promise<boolean>;
+    shouldRemoveStaleLock?: (snapshot: SidecarLockStaleSnapshot) => boolean | Promise<boolean>;
     metadata?: Record<string, unknown>;
 };
 export type SidecarLockHandle = {

package/dist/sidecar-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sidecar-lock.d.ts","sourceRoot":"","sources":["../src/sidecar-lock.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,aAAa,GAAG,qBAAqB,CAAC;AAE7E,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,yBAAyB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,EAAE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5C,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE;QACvB,QAAQ,EAAE,MAAM,CAAC;QACjB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;QACxC,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,iBAAiB,EAAE,OAAO,CAAC;KAC5B,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,qBAAqB,CAAC,EAAE,CACtB,QAAQ,EAAE,wBAAwB,KAC/B,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,YAAY,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,sBAAsB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CACjF,yBAAyB,CAAC,QAAQ,CAAC,EACnC,YAAY,CACb,GAAG;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AA2OF,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM;cAW3B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACpD,yBAAyB,CAAC,QAAQ,CAAC,KAC3C,OAAO,CAAC,iBAAiB,CAAC;eAiIL,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WACxD,yBAAyB,CAAC,QAAQ,CAAC,MACxC,MAAM,OAAO,CAAC,CAAC,CAAC,KACnB,OAAO,CAAC,CAAC,CAAC;iBASW,OAAO,CAAC,IAAI,CAAC;iBAQnB,IAAI;uBAIE,oBAAoB,EAAE;EAW/C;AAED,wBAAsB,eAAe,CAAC,CAAC,EAAE,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/E,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,EACzC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAMZ"}

package/dist/sidecar-lock.js

@@ -64,6 +64,33 @@ async function lockSnapshotStillPresent(lockPath, observed) {
     const current = await readLockSnapshot(lockPath);
     return !!current && !!observed && snapshotMatches(current, observed);
 }
+async function removeStaleLockIfAllowed(params) {
+    if (!params.shouldRemoveStaleLock) {
+        return "not-approved";
+    }
+    if (params.snapshot.raw === undefined) {
+        return "not-approved";
+    }
+    if (!(await params.shouldRemoveStaleLock({
+        lockPath: params.lockPath,
+        normalizedTargetPath: params.normalizedTargetPath,
+        raw: params.snapshot.raw,
+        payload: params.snapshot.payload,
+    }))) {
+        return "not-approved";
+    }
+    const current = await readLockSnapshot(params.lockPath);
+    if (!current || !snapshotMatches(current, params.snapshot)) {
+        return "changed";
+    }
+    try {
+        await fs.rm(params.lockPath, { force: true });
+    }
+    catch {
+        return "not-approved";
+    }
+    return "removed";
+}
 function snapshotMatchesSync(lockPath, observed) {
     try {
         const stat = fsSync.lstatSync(lockPath);
@@ -248,17 +275,23 @@ export function createSidecarLockManager(key) {
                     if (!(await lockSnapshotStillPresent(lockPath, snapshot))) {
                         continue;
                     }
-                    // Node exposes only path-based unlink/rename here. A stale-lock
-                    // reclaimer cannot bind the delete to the file it inspected, so a
-                    // concurrent release+fresh-acquire could otherwise lose its lock.
-                    // Fail closed and let callers choose a higher-level recovery path.
-                    if ((options.staleRecovery ?? "fail-closed") === "fail-closed") {
-                        throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
-                            code: "file_lock_stale",
+                    const staleRecovery = options.staleRecovery ?? "fail-closed";
+                    if (staleRecovery === "remove-if-unchanged") {
+                        const removal = await removeStaleLockIfAllowed({
                             lockPath,
                             normalizedTargetPath,
+                            snapshot,
+                            shouldRemoveStaleLock: options.shouldRemoveStaleLock,
                         });
+                        if (removal === "removed" || removal === "changed") {
+                            continue;
+                        }
                     }
+                    throw Object.assign(new Error(`file lock stale for ${normalizedTargetPath}`), {
+                        code: "file_lock_stale",
+                        lockPath,
+                        normalizedTargetPath,
+                    });
                 }
                 const elapsed = Date.now() - startedAt;
                 if ((options.timeoutMs !== undefined &&

package/docs/config.md

@@ -56,7 +56,7 @@ Return the effective configuration: programmatic overrides win, then env vars, t
 function configureFsSafeLocks(config: Partial<FsSafeLockConfig>): void;
 
 type FsSafeLockConfig = {
-  staleRecovery: "fail-closed";
+  staleRecovery: "fail-closed" | "remove-if-unchanged";
   staleMs?: number;
   timeoutMs?: number;
   retry?: FileLockRetryOptions;
@@ -65,7 +65,7 @@ type FsSafeLockConfig = {
 
 Set process-wide defaults for sidecar lock options. This does **not** turn locking on globally; callers still need to pass `lock: true` or a lock options object for the specific JSON store/resource that needs cross-process coordination.
 
-`staleRecovery` currently supports `"fail-closed"` only. Stale third-party sidecars are not deleted by path because Node cannot atomically bind that deletion to the file that was inspected.
+`staleRecovery` defaults to `"fail-closed"`. `"remove-if-unchanged"` is available for callers that also pass `shouldRemoveStaleLock`; fs-safe re-reads the observed sidecar and removes it only when the raw content and file identity still match.
 
 ## `getFsSafeLockConfig()`
 

package/docs/sidecar-lock.md

@@ -51,7 +51,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   staleMs?: number;                      // default 30_000
   timeoutMs?: number;                    // overall acquire deadline; default unbounded
   retry?: FileLockRetryOptions;
-  staleRecovery?: "fail-closed";         // default
+  staleRecovery?: "fail-closed" | "remove-if-unchanged"; // default "fail-closed"
   allowReentrant?: boolean;              // if this process already holds it, increment a count instead of failing
   payload: () => TPayload | Promise<TPayload>;
   shouldReclaim?: (params: {
@@ -62,6 +62,12 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
     nowMs: number;
     heldByThisProcess: boolean;
   }) => boolean | Promise<boolean>;
+  shouldRemoveStaleLock?: (snapshot: {
+    lockPath: string;
+    normalizedTargetPath: string;
+    raw: string;
+    payload: Record<string, unknown> | null;
+  }) => boolean | Promise<boolean>;
   metadata?: Record<string, unknown>;    // attached to heldEntries() output for diagnostics
 };
 
@@ -101,7 +107,7 @@ try {
 }
 ```
 
-If your process dies before `release()` runs and skips the exit handler, the sidecar remains. Once `staleMs` elapses (or your `shouldReclaim` returns true), acquisition fails closed instead of deleting by path, because Node cannot atomically bind that deletion to the file that was inspected.
+If your process dies before `release()` runs and skips the exit handler, the sidecar remains. Once `staleMs` elapses (or your `shouldReclaim` returns true), acquisition fails closed by default instead of deleting by path.
 
 ## `withFileLock` — common shape made one-liner
 
@@ -164,18 +170,40 @@ const handle = await acquireFileLock(targetPath, {
 });
 ```
 
-`heldByThisProcess` is true when this manager already holds the lock (relevant for the reentrant case). A `true` result does not delete the sidecar; it lets the acquire loop stop waiting once the retry/timeout policy says to give up.
+`heldByThisProcess` is true when this manager already holds the lock (relevant for the reentrant case). A `true` result marks the observed sidecar as stale; `staleRecovery` then decides whether acquisition fails closed or tries caller-approved removal.
+
+## Stale recovery: `remove-if-unchanged`
+
+The default `staleRecovery: "fail-closed"` never removes third-party sidecars. Use `staleRecovery: "remove-if-unchanged"` only when your app has a reliable owner-liveness policy and can prove a stale owner cannot still be writing.
+
+```ts
+const handle = await acquireFileLock(targetPath, {
+  staleMs: 60_000,
+  staleRecovery: "remove-if-unchanged",
+  payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
+  shouldReclaim: ({ payload }) => {
+    const pid = Number(payload?.pid);
+    return Number.isInteger(pid) && pid > 0 && ownerIsDefinitelyDead(pid);
+  },
+  shouldRemoveStaleLock: ({ payload }) => {
+    const pid = Number(payload?.pid);
+    return Number.isInteger(pid) && pid > 0 && ownerIsDefinitelyDead(pid);
+  },
+});
+```
+
+`shouldRemoveStaleLock` receives the exact lock snapshot that `fs-safe` inspected. `fs-safe` re-reads the sidecar and removes it only if the raw content and file identity are unchanged. If the callback is missing, returns false, or the file changed, acquisition fails closed or keeps retrying according to the normal retry policy.
 
 ## What sidecar locks defend against
 
 - **Two processes writing the same file at once.** `acquire` serializes the critical section.
-- **Accidentally deleting a fresh lock during stale recovery.** Stale third-party locks fail closed because safe compare-and-unlink is not available through Node's path APIs.
+- **Accidentally deleting a fresh lock during stale recovery.** Stale third-party locks fail closed by default. Opt-in removal rechecks the observed snapshot before unlinking.
 - **Race between simultaneous acquire attempts.** `O_CREAT | O_EXCL` ensures one wins.
 
 ## What they do **not** defend against
 
 - **Misbehaving holders that ignore the lock.** Locks are advisory — only callers that go through `acquire` are bound.
-- **Automatic stale lock deletion.** If a process crashes, use the payload and your own supervisor/process table to decide when to remove the sidecar.
+- **Automatic stale lock deletion.** If a process crashes, use the payload and your own supervisor/process table to decide when removal is safe, then opt into `remove-if-unchanged`.
 - **Multi-host coordination over network filesystems.** Behavior depends on the underlying filesystem's `O_EXCL` semantics; treat as best-effort.
 
 ## Common patterns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "license": "MIT",
   "repository": {