@openclaw/fs-safe 0.2.4 → 0.2.6

package/docs/root.md

@@ -102,15 +102,14 @@ operations that Node's `fs` API does not expose ergonomically.
 ```ts
 import { configureFsSafePython } from "@openclaw/fs-safe/config";
 
-configureFsSafePython({ mode: "off" });     // Node-only fallback path
+configureFsSafePython({ mode: "off" });     // disable helper; some writes fail closed
 configureFsSafePython({ mode: "require" }); // fail if fd-relative helper unavailable
 ```
 
-`auto` is the default. Configure the mode before creating roots. Without the
-helper, root methods still run, but same-UID races that swap parent directories
-between validation and mutation are harder to close completely. Use `require`
-when that downgrade should be treated as a deployment failure. See
-[Python helper policy](python-helper.md) for deployment guidance.
+`auto` is the default. Configure the mode before creating roots. On POSIX,
+write methods that require fd-relative parent commits fail closed without the
+helper. Use `require` when any helper loss should be treated as a deployment
+failure. See [Python helper policy](python-helper.md) for deployment guidance.
 
 ### Properties
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "license": "MIT",
   "repository": {
@@ -99,7 +99,7 @@
   },
   "scripts": {
     "benchmark": "node scripts/benchmark.mjs",
-    "build": "tsc -p tsconfig.json",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "lint:file-size": "node scripts/check-file-size.mjs",
     "lint:fs-boundary": "node scripts/check-fs-boundary-primitives.mjs",
     "prepack": "node scripts/prepack-build.mjs",
@@ -115,9 +115,9 @@
   },
   "devDependencies": {
     "@types/node": "^22.15.19",
-    "@vitest/coverage-v8": "3.2.4",
+    "@vitest/coverage-v8": "4.1.6",
     "typescript": "^5.8.3",
-    "vitest": "^3.1.4"
+    "vitest": "^4.1.6"
   },
   "engines": {
     "node": ">=20.11"

package/dist/archive-utils.d.ts

@@ -1,3 +0,0 @@
-export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T>;
-export declare function fileExists(filePath: string): Promise<boolean>;
-//# sourceMappingURL=archive-utils.d.ts.map

package/dist/archive-utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"archive-utils.d.ts","sourceRoot":"","sources":["../src/archive-utils.ts"],"names":[],"mappings":"AAEA,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE"}

package/dist/archive-utils.js

@@ -1,26 +0,0 @@
-import fs from "node:fs/promises";
-export async function withTimeout(promise, timeoutMs, label) {
-    let timeoutId;
-    try {
-        return await Promise.race([
-            promise,
-            new Promise((_, reject) => {
-                timeoutId = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
-            }),
-        ]);
-    }
-    finally {
-        if (timeoutId) {
-            clearTimeout(timeoutId);
-        }
-    }
-}
-export async function fileExists(filePath) {
-    try {
-        await fs.stat(filePath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}

package/dist/boundary-file-read.d.ts

@@ -1,44 +0,0 @@
-import fs from "node:fs";
-import type { PathAliasPolicy } from "./path-alias-guards.js";
-import { type SafeOpenSyncAllowedType, type SafeOpenSyncFailureReason } from "./safe-open-sync.js";
-type BoundaryReadFs = Pick<typeof fs, "closeSync" | "constants" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "realpathSync">;
-export type BoundaryFileOpenFailureReason = SafeOpenSyncFailureReason | "validation";
-export type BoundaryFileOpenResult = {
-    ok: true;
-    path: string;
-    fd: number;
-    stat: fs.Stats;
-    rootRealPath: string;
-} | {
-    ok: false;
-    reason: BoundaryFileOpenFailureReason;
-    error?: unknown;
-};
-export type BoundaryFileOpenFailure = Extract<BoundaryFileOpenResult, {
-    ok: false;
-}>;
-export type OpenBoundaryFileSyncParams = {
-    absolutePath: string;
-    rootPath: string;
-    boundaryLabel: string;
-    rootRealPath?: string;
-    maxBytes?: number;
-    rejectHardlinks?: boolean;
-    allowedType?: SafeOpenSyncAllowedType;
-    skipLexicalRootCheck?: boolean;
-    ioFs?: BoundaryReadFs;
-};
-export type OpenBoundaryFileParams = OpenBoundaryFileSyncParams & {
-    aliasPolicy?: PathAliasPolicy;
-};
-export declare function canUseBoundaryFileOpen(ioFs: typeof fs): boolean;
-export declare function openBoundaryFileSync(params: OpenBoundaryFileSyncParams): BoundaryFileOpenResult;
-export declare function matchBoundaryFileOpenFailure<T>(failure: BoundaryFileOpenFailure, handlers: {
-    path?: (failure: BoundaryFileOpenFailure) => T;
-    validation?: (failure: BoundaryFileOpenFailure) => T;
-    io?: (failure: BoundaryFileOpenFailure) => T;
-    fallback: (failure: BoundaryFileOpenFailure) => T;
-}): T;
-export declare function openBoundaryFile(params: OpenBoundaryFileParams): Promise<BoundaryFileOpenResult>;
-export {};
-//# sourceMappingURL=boundary-file-read.d.ts.map

package/dist/boundary-file-read.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"boundary-file-read.d.ts","sourceRoot":"","sources":["../src/boundary-file-read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAOzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC/B,MAAM,qBAAqB,CAAC;AAE7B,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,EAAE,EACP,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,cAAc,GACd,cAAc,CACjB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,yBAAyB,GAAG,YAAY,CAAC;AAErF,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,6BAA6B,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1E,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAErF,MAAM,MAAM,0BAA0B,GAAG;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,0BAA0B,GAAG;IAChE,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAQF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAW/D;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,0BAA0B,GAAG,sBAAsB,CAuB/F;AAED,wBAAgB,4BAA4B,CAAC,CAAC,EAC5C,OAAO,EAAE,uBAAuB,EAChC,QAAQ,EAAE;IACR,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;IAC/C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;IACrD,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;IAC7C,QAAQ,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;CACnD,GACA,CAAC,CAUH;AAoDD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,sBAAsB,CAAC,CAsBjC"}

package/dist/boundary-file-read.js

@@ -1,129 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { resolveBoundaryPath, resolveBoundaryPathSync, } from "./boundary-path.js";
-import { openVerifiedFileSync, } from "./safe-open-sync.js";
-export function canUseBoundaryFileOpen(ioFs) {
-    return (typeof ioFs.openSync === "function" &&
-        typeof ioFs.closeSync === "function" &&
-        typeof ioFs.fstatSync === "function" &&
-        typeof ioFs.lstatSync === "function" &&
-        typeof ioFs.realpathSync === "function" &&
-        typeof ioFs.readFileSync === "function" &&
-        typeof ioFs.constants === "object" &&
-        ioFs.constants !== null);
-}
-export function openBoundaryFileSync(params) {
-    const ioFs = params.ioFs ?? fs;
-    const resolved = resolveBoundaryFilePathGeneric({
-        absolutePath: params.absolutePath,
-        resolve: (absolutePath) => resolveBoundaryPathSync({
-            absolutePath,
-            rootPath: params.rootPath,
-            rootCanonicalPath: params.rootRealPath,
-            boundaryLabel: params.boundaryLabel,
-            skipLexicalRootCheck: params.skipLexicalRootCheck,
-        }),
-    });
-    if (resolved instanceof Promise) {
-        return toBoundaryValidationError(new Error("Unexpected async boundary resolution"));
-    }
-    return finalizeBoundaryFileOpen({
-        resolved,
-        maxBytes: params.maxBytes,
-        rejectHardlinks: params.rejectHardlinks,
-        allowedType: params.allowedType,
-        ioFs,
-    });
-}
-export function matchBoundaryFileOpenFailure(failure, handlers) {
-    switch (failure.reason) {
-        case "path":
-            return handlers.path ? handlers.path(failure) : handlers.fallback(failure);
-        case "validation":
-            return handlers.validation ? handlers.validation(failure) : handlers.fallback(failure);
-        case "io":
-            return handlers.io ? handlers.io(failure) : handlers.fallback(failure);
-    }
-    return handlers.fallback(failure);
-}
-function openBoundaryFileResolved(params) {
-    const opened = openVerifiedFileSync({
-        filePath: params.absolutePath,
-        resolvedPath: params.resolvedPath,
-        rejectHardlinks: params.rejectHardlinks ?? true,
-        maxBytes: params.maxBytes,
-        allowedType: params.allowedType,
-        ioFs: params.ioFs,
-    });
-    if (!opened.ok) {
-        return opened;
-    }
-    return {
-        ok: true,
-        path: opened.path,
-        fd: opened.fd,
-        stat: opened.stat,
-        rootRealPath: params.rootRealPath,
-    };
-}
-function finalizeBoundaryFileOpen(params) {
-    if ("ok" in params.resolved) {
-        return params.resolved;
-    }
-    return openBoundaryFileResolved({
-        absolutePath: params.resolved.absolutePath,
-        resolvedPath: params.resolved.resolvedPath,
-        rootRealPath: params.resolved.rootRealPath,
-        maxBytes: params.maxBytes,
-        rejectHardlinks: params.rejectHardlinks,
-        allowedType: params.allowedType,
-        ioFs: params.ioFs,
-    });
-}
-export async function openBoundaryFile(params) {
-    const ioFs = params.ioFs ?? fs;
-    const maybeResolved = resolveBoundaryFilePathGeneric({
-        absolutePath: params.absolutePath,
-        resolve: (absolutePath) => resolveBoundaryPath({
-            absolutePath,
-            rootPath: params.rootPath,
-            rootCanonicalPath: params.rootRealPath,
-            boundaryLabel: params.boundaryLabel,
-            policy: params.aliasPolicy,
-            skipLexicalRootCheck: params.skipLexicalRootCheck,
-        }),
-    });
-    const resolved = maybeResolved instanceof Promise ? await maybeResolved : maybeResolved;
-    return finalizeBoundaryFileOpen({
-        resolved,
-        maxBytes: params.maxBytes,
-        rejectHardlinks: params.rejectHardlinks,
-        allowedType: params.allowedType,
-        ioFs,
-    });
-}
-function toBoundaryValidationError(error) {
-    return { ok: false, reason: "validation", error };
-}
-function mapResolvedBoundaryPath(absolutePath, resolved) {
-    return {
-        absolutePath,
-        resolvedPath: resolved.canonicalPath,
-        rootRealPath: resolved.rootCanonicalPath,
-    };
-}
-function resolveBoundaryFilePathGeneric(params) {
-    const absolutePath = path.resolve(params.absolutePath);
-    try {
-        const resolved = params.resolve(absolutePath);
-        if (resolved instanceof Promise) {
-            return resolved
-                .then((value) => mapResolvedBoundaryPath(absolutePath, value))
-                .catch((error) => toBoundaryValidationError(error));
-        }
-        return mapResolvedBoundaryPath(absolutePath, resolved);
-    }
-    catch (error) {
-        return toBoundaryValidationError(error);
-    }
-}

package/dist/boundary-path.d.ts

@@ -1,39 +0,0 @@
-type BoundaryPathIntent = "read" | "write" | "create" | "delete" | "stat";
-export type BoundaryPathAliasPolicy = {
-    allowFinalSymlinkForUnlink?: boolean;
-    allowFinalHardlinkForUnlink?: boolean;
-};
-export declare const BOUNDARY_PATH_ALIAS_POLICIES: {
-    readonly strict: Readonly<{
-        allowFinalSymlinkForUnlink: false;
-        allowFinalHardlinkForUnlink: false;
-    }>;
-    readonly unlinkTarget: Readonly<{
-        allowFinalSymlinkForUnlink: true;
-        allowFinalHardlinkForUnlink: true;
-    }>;
-};
-type ResolveBoundaryPathParams = {
-    absolutePath: string;
-    rootPath: string;
-    boundaryLabel: string;
-    intent?: BoundaryPathIntent;
-    policy?: BoundaryPathAliasPolicy;
-    skipLexicalRootCheck?: boolean;
-    rootCanonicalPath?: string;
-};
-type ResolvedBoundaryPathKind = "missing" | "file" | "directory" | "symlink" | "other";
-export type ResolvedBoundaryPath = {
-    absolutePath: string;
-    canonicalPath: string;
-    rootPath: string;
-    rootCanonicalPath: string;
-    relativePath: string;
-    exists: boolean;
-    kind: ResolvedBoundaryPathKind;
-};
-export declare function resolveBoundaryPath(params: ResolveBoundaryPathParams): Promise<ResolvedBoundaryPath>;
-export declare function resolveBoundaryPathSync(params: ResolveBoundaryPathParams): ResolvedBoundaryPath;
-export declare function resolvePathViaExistingAncestorSync(targetPath: string): string;
-export {};
-//# sourceMappingURL=boundary-path.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"boundary-path.d.ts","sourceRoot":"","sources":["../src/boundary-path.ts"],"names":[],"mappings":"AAMA,KAAK,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE1E,MAAM,MAAM,uBAAuB,GAAG;IACpC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC;AAEF,eAAO,MAAM,4BAA4B;;;;;;;;;CAS/B,CAAC;AAEX,KAAK,yBAAyB,GAAG;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,KAAK,wBAAwB,GAAG,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAEvF,MAAM,MAAM,oBAAoB,GAAG;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,wBAAwB,CAAC;CAChC,CAAC;AAEF,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,yBAAyB,GAChC,OAAO,CAAC,oBAAoB,CAAC,CA+B/B;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,yBAAyB,GAAG,oBAAoB,CA+B/F;AAmkBD,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA6B7E"}