@openclaw/fs-safe 0.5.6 → 0.6.0

package/dist/secret-read-policy.js

@@ -0,0 +1,28 @@
+import { FsSafeError } from "./errors.js";
+export const DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;
+export function secretPathErrorCode(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR" ? "not-found" : "invalid-path";
+}
+export function secretReadError(code, action, label, resolvedPath, error) {
+    const cause = error instanceof Error ? error : new Error(String(error));
+    return new FsSafeError(code, `Failed to ${action} ${label} file at ${resolvedPath}: ${String(cause)}`, { cause });
+}
+export function assertSecretFilePreview(stat, label, resolvedPath, maxBytes, rejectHardlinks) {
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", `${label} file at ${resolvedPath} must be a regular file.`, { cause: undefined });
+    }
+    if (rejectHardlinks && stat.nlink > 1n) {
+        throw new FsSafeError("hardlink", `${label} file at ${resolvedPath} must not be hardlinked.`, { cause: undefined });
+    }
+    if (stat.size > maxBytes) {
+        throw new FsSafeError("too-large", `${label} file at ${resolvedPath} exceeds ${maxBytes} bytes.`, { cause: undefined });
+    }
+}
+export function trimSecretFileContent(raw, label, resolvedPath) {
+    const secret = raw.trim();
+    if (!secret) {
+        throw new FsSafeError("invalid-path", `${label} file at ${resolvedPath} is empty.`, { cause: undefined });
+    }
+    return secret;
+}

package/dist/secret.d.ts

@@ -1,3 +1,4 @@
-export { createSecretFileAtomic, DEFAULT_SECRET_FILE_MAX_BYTES, PRIVATE_SECRET_DIR_MODE, PRIVATE_SECRET_FILE_MODE, readSecretFileSync, tryReadSecretFileSync, writeSecretFileAtomic, type SecretFileReadOptions, } from "./secret-file.js";
+export { createSecretFileAtomic, PRIVATE_SECRET_DIR_MODE, PRIVATE_SECRET_FILE_MODE, readSecretFileSync, tryReadSecretFileSync, writeSecretFileAtomic, } from "./secret-file.js";
+export { DEFAULT_SECRET_FILE_MAX_BYTES, type SecretFileReadOptions } from "./secret-read-policy.js";
 export { readSecretFile, tryReadSecretFile } from "./secret-read-async.js";
 //# sourceMappingURL=secret.d.ts.map

package/dist/secret.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret.d.ts","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"secret.d.ts","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,6BAA6B,EAAE,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/secret.js

@@ -1,2 +1,3 @@
-export { createSecretFileAtomic, DEFAULT_SECRET_FILE_MAX_BYTES, PRIVATE_SECRET_DIR_MODE, PRIVATE_SECRET_FILE_MODE, readSecretFileSync, tryReadSecretFileSync, writeSecretFileAtomic, } from "./secret-file.js";
+export { createSecretFileAtomic, PRIVATE_SECRET_DIR_MODE, PRIVATE_SECRET_FILE_MODE, readSecretFileSync, tryReadSecretFileSync, writeSecretFileAtomic, } from "./secret-file.js";
+export { DEFAULT_SECRET_FILE_MAX_BYTES } from "./secret-read-policy.js";
 export { readSecretFile, tryReadSecretFile } from "./secret-read-async.js";

package/dist/secure-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAYrC,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAK1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAgLF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAc/B"}
+{"version":3,"file":"secure-file.d.ts","sourceRoot":"","sources":["../src/secure-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAYrC,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAC;AAM1B,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,WAAW,CAAC,EAAE,2BAA2B,CAAC;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,EAAE,CAAC,EAAE,mBAAmB,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE7D,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAyLF,wBAAsB,cAAc,CAClC,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAc/B"}

package/dist/secure-file.js

@@ -4,10 +4,11 @@ import path from "node:path";
 import { readFileHandleBounded } from "./bounded-read.js";
 import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
 import { isWindowsDriveLetterPath, isWindowsNetworkPath } from "./local-file-access.js";
 import { isPathInside, isSymlinkOpenError } from "./path.js";
+import { formatPermissionErrorDetail } from "./permission-exec.js";
 import { inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, } from "./permissions.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
 const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
 const OPEN_READ_FLAGS = fsConstants.O_RDONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
 function isAbsolutePathname(value) {
@@ -52,20 +53,18 @@ async function openSecureHandle(options) {
         if (!openedStat.isFile()) {
             throw new FsSafeError("not-file", `${label(options)} must be a file: ${options.filePath}`);
         }
-        const pathStat = options.trust?.allowSymlink
-            ? await fs.stat(options.filePath)
-            : await fs.lstat(options.filePath);
-        if (!options.trust?.allowSymlink && pathStat.isSymbolicLink()) {
-            throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
-        }
-        if (!sameFileIdentity(pathStat, openedStat)) {
-            throw new FsSafeError("path-mismatch", `${label(options)} changed during open.`);
-        }
+        const openedIdentity = await inspectFileIdentity(() => handle.stat({ bigint: true }));
+        await inspectFileIdentity(async () => {
+            const pathStat = options.trust?.allowSymlink
+                ? await fs.stat(options.filePath, { bigint: true })
+                : await fs.lstat(options.filePath, { bigint: true });
+            if (!options.trust?.allowSymlink && pathStat.isSymbolicLink()) {
+                throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
+            }
+            return pathStat;
+        }, openedIdentity);
         const realPath = await fs.realpath(options.filePath);
-        const realStat = await fs.stat(realPath);
-        if (!sameFileIdentity(realStat, openedStat)) {
-            throw new FsSafeError("path-mismatch", `${label(options)} real path changed during open.`);
-        }
+        await inspectFileIdentity(() => fs.stat(realPath, { bigint: true }), openedIdentity);
         if (options.io?.maxBytes !== undefined && openedStat.size > options.io.maxBytes) {
             throw new FsSafeError("too-large", `${label(options)} exceeded maxBytes (${options.io.maxBytes}).`);
         }
@@ -111,11 +110,21 @@ async function assertSecurePermissions(options, stat, realPath) {
     const permissions = platform === "win32"
         ? await inspectPathPermissions(realPath, options.inject)
         : inspectOpenedPermissions(stat, platform);
+    const reason = permissions.error ? `: ${formatPermissionErrorDetail(permissions.error)}` : "";
+    const diagnostics = {
+        ...(permissions.errorCause !== undefined ? { cause: permissions.errorCause } : {}),
+        ...(permissions.ownerError || permissions.errorDetail ? {
+            details: {
+                ...(permissions.ownerError ? { ownerError: formatPermissionErrorDetail(permissions.ownerError) } : {}),
+                ...permissions.errorDetail,
+            },
+        } : {}),
+    };
     if (!permissions.ok) {
-        throw new FsSafeError("permission-unverified", `${label(options)} permissions could not be verified: ${realPath}`);
+        throw new FsSafeError("permission-unverified", `${label(options)} permissions could not be verified: ${realPath}${reason}`, diagnostics);
     }
     if (platform === "win32" && permissions.source === "unknown") {
-        throw new FsSafeError("permission-unverified", `${label(options)} ACL verification unavailable on Windows for ${realPath}.`);
+        throw new FsSafeError("permission-unverified", `${label(options)} ACL verification unavailable on Windows for ${realPath}${reason || "."}`, diagnostics);
     }
     if (platform === "win32" && permissions.ownerTrusted !== true) {
         throw new FsSafeError(permissions.ownerTrusted === false ? "not-owned" : "permission-unverified", `${label(options)} owner could not be trusted on Windows: ${realPath}`);

package/dist/staged-directory.d.ts

@@ -0,0 +1,16 @@
+import type { DirectoryReceipt } from "./directory-durability.js";
+import type { FileIdentityStat } from "./file-identity.js";
+import type { StagedFileReceipt } from "./staged-file-types.js";
+type DirectorySnapshot = StagedFileReceipt["directory"];
+export declare function exactIdentityMatches(expected: FileIdentityStat, actual: Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>): boolean;
+export declare function describeStagedDirectory(fd: number, pathname: string): DirectorySnapshot;
+export declare function assertStagedDirectoryCurrent(receipt: DirectorySnapshot): void;
+export declare function openStagedDirectory(directory: string | DirectoryReceipt): {
+    fd: number;
+    receipt: DirectorySnapshot;
+};
+export {};
+//# sourceMappingURL=staged-directory.d.ts.map

package/dist/staged-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-directory.d.ts","sourceRoot":"","sources":["../src/staged-directory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhE,KAAK,iBAAiB,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;AAExD,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,GAC7C,OAAO,CAKT;AAED,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAYvF;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAQ7E;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,iBAAiB,CAAC;CAC5B,CA+BA"}

package/dist/staged-directory.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+export function exactIdentityMatches(expected, actual) {
+    return ["dev", "ino"].every((key) => {
+        const value = expected[key];
+        return (typeof value === "bigint" || Number.isSafeInteger(value)) && BigInt(value) === actual[key];
+    });
+}
+export function describeStagedDirectory(fd, pathname) {
+    const identity = fs.fstatSync(fd, { bigint: true });
+    if (!identity.isDirectory()) {
+        throw new FsSafeError("not-file", "staging parent must be a directory");
+    }
+    const receipt = Object.freeze({
+        path: path.resolve(pathname),
+        realPath: fs.realpathSync(pathname),
+        identity: Object.freeze({ dev: identity.dev, ino: identity.ino }),
+    });
+    assertStagedDirectoryCurrent(receipt);
+    return receipt;
+}
+export function assertStagedDirectoryCurrent(receipt) {
+    const current = fs.lstatSync(receipt.path, { bigint: true });
+    if (!current.isDirectory() || !exactIdentityMatches(receipt.identity, current) ||
+        fs.realpathSync(receipt.path) !== receipt.realPath) {
+        throw new FsSafeError("path-mismatch", "staging directory pathname changed");
+    }
+}
+export function openStagedDirectory(directory) {
+    // Copy supplied facts before any asynchronous work; receipts are not authority.
+    const pathname = path.resolve(typeof directory === "string" ? directory : directory.path);
+    const expected = typeof directory === "string" ? undefined : {
+        realPath: directory.realPath, dev: directory.identity.dev, ino: directory.identity.ino,
+    };
+    const before = fs.lstatSync(pathname, { bigint: true });
+    if (!before.isDirectory()) {
+        throw new FsSafeError("not-file", "staging parent must be a real directory");
+    }
+    if (expected && (!exactIdentityMatches(expected, before) || fs.realpathSync(pathname) !== expected.realPath)) {
+        throw new FsSafeError("path-mismatch", "stale staging directory receipt");
+    }
+    const fd = fs.openSync(pathname, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    try {
+        const receipt = describeStagedDirectory(fd, pathname);
+        if (!exactIdentityMatches(before, receipt.identity)) {
+            throw new FsSafeError("path-mismatch", "staging directory changed while opening");
+        }
+        return { fd, receipt };
+    }
+    catch (error) {
+        try {
+            fs.closeSync(fd);
+        }
+        catch (closeError) {
+            throw new AggregateError([error, closeError], "staging directory admission and close failed");
+        }
+        throw error;
+    }
+}

package/dist/staged-file-types.d.ts

@@ -0,0 +1,56 @@
+export type StagedFileReceipt = Readonly<{
+    directory: Readonly<{
+        path: string;
+        realPath: string;
+        identity: Readonly<{
+            dev: bigint;
+            ino: bigint;
+        }>;
+    }>;
+    temporaryBasename: string;
+    /** Preparation-time metadata of the private stage, not a final-file fingerprint. */
+    identity: Readonly<{
+        dev: bigint;
+        ino: bigint;
+        mode: number;
+        nlink: bigint;
+        size: bigint;
+        uid: number;
+        gid: number;
+        mtimeNs: bigint;
+        ctimeNs: bigint;
+    }>;
+}>;
+export type PublishedFileReceipt = Readonly<{
+    status: "published";
+    staged: StagedFileReceipt;
+    basename: string;
+    overwrite: boolean;
+}>;
+export type StagedFilePublication = Readonly<{
+    status: "not-published";
+}> | PublishedFileReceipt | Readonly<{
+    status: "indeterminate";
+    basename: string;
+    overwrite: boolean;
+}>;
+export type StagedFileCleanupReceipt = Readonly<{
+    temporaryBasename: string;
+    publication: StagedFilePublication;
+    status: "removed" | "name-absent" | "preserved" | "failed" | "not-needed";
+    resources: "closed" | "close-failed";
+}>;
+export type StagedFileFailureDetails = Readonly<{
+    phase: "prepare" | "publish" | "cleanup";
+    publication: StagedFilePublication;
+    cleanup?: StagedFileCleanupReceipt;
+}>;
+export interface StagedFile extends AsyncDisposable {
+    readonly receipt: StagedFileReceipt;
+    assertCurrent(): Promise<void>;
+    publish(basename: string, options: {
+        overwrite: boolean;
+    }): Promise<PublishedFileReceipt>;
+    cleanup(): Promise<StagedFileCleanupReceipt>;
+}
+//# sourceMappingURL=staged-file-types.d.ts.map

package/dist/staged-file-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-file-types.d.ts","sourceRoot":"","sources":["../src/staged-file-types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,SAAS,EAAE,QAAQ,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,QAAQ,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAClD,CAAC,CAAC;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,EAAE,QAAQ,CAAC;QACjB,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ,CAAC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAC7B,QAAQ,CAAC;IAAE,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC,GACrC,oBAAoB,GACpB,QAAQ,CAAC;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAEhF,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,qBAAqB,CAAC;IACnC,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;IAC1E,SAAS,EAAE,QAAQ,GAAG,cAAc,CAAC;CACtC,CAAC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACzC,WAAW,EAAE,qBAAqB,CAAC;IACnC,OAAO,CAAC,EAAE,wBAAwB,CAAC;CACpC,CAAC,CAAC;AAEH,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC1F,OAAO,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAC9C"}

package/dist/staged-file-types.js

@@ -0,0 +1 @@
+export {};

package/dist/staged-file.d.ts

@@ -0,0 +1,10 @@
+import type { DirectoryReceipt } from "./directory-durability.js";
+import type { StagedFile } from "./staged-file-types.js";
+export type { PublishedFileReceipt, StagedFile, StagedFileCleanupReceipt, StagedFileFailureDetails, StagedFilePublication, StagedFileReceipt, } from "./staged-file-types.js";
+export declare function stageFileInDirectory(options: {
+    directory: string | DirectoryReceipt;
+    content: string | Uint8Array;
+    /** Published mode; the unpublished stage stays at 0600. Defaults to 0600. */
+    mode?: number;
+}): Promise<StagedFile>;
+//# sourceMappingURL=staged-file.d.ts.map

package/dist/staged-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staged-file.d.ts","sourceRoot":"","sources":["../src/staged-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAKlE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,YAAY,EACV,oBAAoB,EAAE,UAAU,EAAE,wBAAwB,EAAE,wBAAwB,EACpF,qBAAqB,EAAE,iBAAiB,GACzC,MAAM,wBAAwB,CAAC;AAEhC,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACrC,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,UAAU,CAAC,CAUtB"}

package/dist/staged-file.js

@@ -0,0 +1,15 @@
+import { FsSafeError } from "./errors.js";
+import { assertNativeStaging, createNativeStage } from "./native-staged-file.js";
+import { requireNativeBinding } from "./native.js";
+import { openStagedDirectory } from "./staged-directory.js";
+export async function stageFileInDirectory(options) {
+    if (process.platform !== "linux" && process.platform !== "darwin") {
+        throw new FsSafeError("unsupported-platform", "retained-directory staging requires Linux or macOS");
+    }
+    const binding = requireNativeBinding();
+    assertNativeStaging(binding);
+    const input = { kind: "buffer", data: Buffer.from(options.content) };
+    const mode = options.mode ?? 0o600;
+    const parent = openStagedDirectory(options.directory);
+    return await createNativeStage(binding, parent.fd, parent.receipt, input, mode);
+}

package/dist/strict-file-identity.d.ts

@@ -0,0 +1,6 @@
+import type { BigIntStats } from "node:fs";
+type ExactFileIdentity = Pick<BigIntStats, "dev" | "ino">;
+export declare function inspectFileIdentity<T extends ExactFileIdentity>(inspect: () => Promise<T>, expected?: ExactFileIdentity, platform?: NodeJS.Platform): Promise<T>;
+export declare function inspectFileIdentitySync<T extends ExactFileIdentity>(inspect: () => T, expected?: ExactFileIdentity, platform?: NodeJS.Platform): T;
+export {};
+//# sourceMappingURL=strict-file-identity.d.ts.map

package/dist/strict-file-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strict-file-identity.d.ts","sourceRoot":"","sources":["../src/strict-file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C,KAAK,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AA6B1D,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,EACnE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,iBAAiB,EACjE,OAAO,EAAE,MAAM,CAAC,EAChB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,CAAC,CAOH"}

package/dist/strict-file-identity.js

@@ -0,0 +1,48 @@
+import { FsSafeError } from "./errors.js";
+function identityMismatch() {
+    return new FsSafeError("path-mismatch", "file identity changed or could not be verified");
+}
+function identityCheck(expected, platform) {
+    const known = {};
+    const check = (stat) => {
+        let complete = true;
+        for (const field of ["dev", "ino"]) {
+            const value = stat[field];
+            // Numeric receipts cannot recover identity bits already lost to rounding.
+            if (typeof value !== "bigint")
+                throw identityMismatch();
+            if (platform === "win32" && value === 0n) {
+                complete = false;
+            }
+            else {
+                if (known[field] !== undefined && known[field] !== value)
+                    throw identityMismatch();
+                known[field] = value;
+            }
+        }
+        return complete;
+    };
+    if (expected && !check(expected))
+        throw identityMismatch();
+    return check;
+}
+// Retry only unknown Windows identities, retaining every known component so a
+// later observation cannot erase a definite mismatch. Never reopen the file.
+export async function inspectFileIdentity(inspect, expected, platform = process.platform) {
+    const check = identityCheck(expected, platform);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const stat = await inspect();
+        if (check(stat))
+            return stat;
+    }
+    throw identityMismatch();
+}
+export function inspectFileIdentitySync(inspect, expected, platform = process.platform) {
+    const check = identityCheck(expected, platform);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const stat = inspect();
+        if (check(stat))
+            return stat;
+    }
+    throw identityMismatch();
+}

package/dist/windows-owner.d.ts

@@ -1,3 +1,4 @@
+import { type PermissionCommandFailure } from "./permission-exec.js";
 export type WindowsOwnerExec = (command: string, args: string[]) => Promise<{
     stdout: string;
     stderr: string;
@@ -10,6 +11,8 @@ export type WindowsOwnerSummary = {
     remote?: boolean;
     trusted?: boolean;
     error?: string;
+    errorDetail?: PermissionCommandFailure;
+    errorCause?: unknown;
 };
 export declare function resolveWindowsPrincipalSids(params: {
     principals: string[];

package/dist/windows-owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"windows-owner.d.ts","sourceRoot":"","sources":["../src/windows-owner.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AA4DF,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAyBlC;AAED,wBAAsB,4BAA4B,CAAC,MAAM,EAAE;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWzB;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA2C/B"}
+{"version":3,"file":"windows-owner.d.ts","sourceRoot":"","sources":["../src/windows-owner.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAG9B,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AA4DF,wBAAsB,2BAA2B,CAAC,MAAM,EAAE;IACxD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAyBlC;AAED,wBAAsB,4BAA4B,CAAC,MAAM,EAAE;IACzD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWzB;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,IAAI,EAAE,gBAAgB,CAAC;CACxB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAkD/B"}

package/dist/windows-owner.js

@@ -1,3 +1,4 @@
+import { formatPermissionErrorDetail, getPermissionCommandFailure, } from "./permission-exec.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
 const SID_RE = /^\*?s-\d+-\d+(-\d+)+$/i;
 const TRUSTED_OWNER_SIDS = new Set(["s-1-5-18", "s-1-5-32-544"]);
@@ -83,8 +84,11 @@ export async function resolveWindowsCurrentUserSid(params) {
     }
 }
 export async function inspectWindowsOwner(params) {
+    let command = "";
+    let startedAt = performance.now();
     try {
-        const command = resolveWindowsSystemCommand(String.raw `WindowsPowerShell\v1.0\powershell.exe`, params.env);
+        command = resolveWindowsSystemCommand(String.raw `WindowsPowerShell\v1.0\powershell.exe`, params.env);
+        startedAt = performance.now();
         const { stdout } = await params.exec(command, [
             "-NoLogo",
             "-NoProfile",
@@ -113,6 +117,10 @@ export async function inspectWindowsOwner(params) {
         };
     }
     catch (err) {
-        return { error: String(err) };
+        return {
+            error: formatPermissionErrorDetail(String(err)),
+            errorDetail: getPermissionCommandFailure(err, command, performance.now() - startedAt),
+            errorCause: err,
+        };
     }
 }

package/docs/advanced.md

@@ -26,13 +26,22 @@ The exports group into a handful of themes. Each documented helper has its own p
 | Export | Page | Notes |
 |---|---|---|
 | `pathScope`, `PathScope`, `PathScopeOptions`, `PathScopeResolveOptions` | [path-scope.md](path-scope.md) | Absolute-path boundary helper with `Result`-shaped returns. |
-| `ensureDirectoryWithinRoot` | – | Create a directory while enforcing the root boundary. |
+| `ensureDirectoryWithinRoot` | [path-scope.md](path-scope.md#ensuredir-rel-options) | Create a directory while enforcing the root boundary; same result contract as `pathScope().ensureDir()`. |
 | `resolvePathWithinRoot`, `resolvePathsWithinRoot` | – | Resolve one or many relative paths against a trusted root. |
 | `resolveExistingPathsWithinRoot`, `resolveStrictExistingPathsWithinRoot` | – | Same, but require the targets to exist. |
 | `resolveWritablePathWithinRoot` | – | Resolve a write target inside a root. |
 | `resolveRootPath`, `resolveRootPathSync`, `ResolvedRootPath`, `ROOT_PATH_ALIAS_POLICIES`, `RootPathAliasPolicy` | – | Resolve a root directory honoring alias policy. |
 | `resolvePathViaExistingAncestorSync` | – | Walk to an existing ancestor for paths whose tail does not yet exist. |
 
+`ensureDirectoryWithinRoot({ rootDir, requestedPath, scopeLabel, defaultDirName?, mode? })`
+returns `{ ok: true, path }` or `{ ok: false, error: string, diagnostic?: FsSafeError }`.
+It does not throw filesystem failures: operational failures carry a
+`helper-failed` diagnostic with the original `cause` and a bounded, escaped
+message naming the native code/syscall when available. Policy failures omit
+`diagnostic`. Missing parents already created before a failure remain in place.
+The diagnostic contract is specific to directory preparation, not the other
+root-path result helpers.
+
 ### Absolute path helpers
 
 | Export | Page | Notes |
@@ -107,6 +116,7 @@ component is followed by another segment, both helpers throw
 
 | Export | Page | Notes |
 |---|---|---|
+| `stageFileInDirectory`, `StagedFile`, `StagedFileReceipt`, `PublishedFileReceipt`, `StagedFilePublication`, `StagedFileCleanupReceipt`, `StagedFileFailureDetails` | [staged-file.md](staged-file.md) | Native-required Linux/macOS lifecycle retaining the original directory for abort cleanup. |
 | `tempFile`, `withTempFile`, `TempFile`, `buildRandomTempFilePath`, `sanitizeTempFileName` | [temp.md](temp.md) | One-file temp primitive; prefer `tempWorkspace` from `@openclaw/fs-safe/temp` for the stable surface. |
 | `writeSiblingTempFile`, `writeViaSiblingTempPath`, `WriteSiblingTempFileOptions`, `WriteSiblingTempFileResult` | – | Sibling-temp write building block used by `replaceFileAtomic`. |
 

package/docs/archive.md

@@ -1,6 +1,6 @@
 # Archive extraction
 
-`@openclaw/fs-safe/archive` extracts ZIP and TAR archives behind one API, with traversal checks, blocked-link-type rejection, and entry-count and byte budgets. When the bundled native binding is available for the current platform, Rust streams ZIP, TAR, gzip, zstd, and bzip2 while TypeScript remains the sole policy owner; every accepted output is created fd-relative in a private staging root. Extraction then merges through the same safe-open boundary used by direct writes — a symlinked entry can't trick the merge into following an out-of-tree path.
+`@openclaw/fs-safe/archive` extracts ZIP and TAR archives behind one API, with traversal checks, blocked-link-type rejection, and entry-count and byte budgets. When the native binding is available for the current platform, Rust streams ZIP, TAR, gzip, zstd, and bzip2 while TypeScript remains the sole policy owner; every accepted output is created fd-relative in a private staging root. Extraction then merges through the same safe-open boundary used by direct writes — a symlinked entry can't trick the merge into following an out-of-tree path.
 
 The guarded JavaScript fallback uses optional runtime dependencies: `jszip` for
 ZIP and `tar` for TAR/gzip. The native path does not use those packages. Installs
@@ -72,8 +72,19 @@ accepted-entry plan back to Rust. Rust only performs decompression and the
 fd-relative `mkdirBeneath`/exclusive-open writes. This keeps policy identical
 between native and JavaScript paths rather than reimplementing it in Rust.
 
-An `entryFilter` sees the validated archive path, entry kind, and declared
-size. Returning `"skip"` rejects the whole archive unless `onFiltered` is
+ZIP extraction and bounded reads admit every physical central-directory record and its referenced local header before either decoder can normalize or collapse names. Raw names and valid Unicode Path names must pass traversal checks before stripping, filtering, or selecting a requested member; duplicate or colliding names reject with `entry-path`, even in unrelated or skipped members. Materially conflicting local/central or Unicode interpretations, malformed critical metadata, and ambiguous framing reject with `ArchiveFormatError`. Harmless separator and dot-component equivalence is allowed only after validation. Ordinary legacy filename decoding remains backend-selected.
+
+`stripComponents` removes leading nonempty, non-`.` path components after
+normalizing separators. For example, `./pkg/hello.txt` with
+`stripComponents: 1` extracts to `hello.txt` on both backends. Entries with no
+remaining components are skipped before the filter callback, but still count
+toward `maxEntries` and undergo traversal validation. JavaScript TAR extraction
+passes node-tar this accepted output path with its own stripping disabled, so
+depth checks, collision checks, writes, and mode application agree.
+
+An `entryFilter` sees the validated effective archive path **before stripping**
+(including a local PAX `path` override), entry kind, and declared size.
+Returning `"skip"` rejects the whole archive unless `onFiltered` is
 explicitly `"skip-entry"`. Path traversal and archive-wide entry-count checks
 still apply to skipped entries.
 
@@ -149,22 +160,58 @@ codes remain `"destination-not-directory"`, `"destination-symlink"`, and
 ## What it defends against
 
 - **Path traversal:** entries with `..`, absolute paths, NUL bytes, or Windows drive-relative segments such as `C:secret` and `nested/C:secret` are rejected (`ArchiveSecurityError`). On Windows, path segments containing `:` are also rejected as alternate data stream names before either backend writes to the filesystem.
-- **Symlink/hardlink entries:** rejected by default. Some archives ship symlink/hardlink entries that point outside the destination once resolved; `extractArchive` does not follow them.
+- **Symlink/hardlink entries:** rejected by default, including ZIP entries whose Unix mode says symlink while their name ends in a slash or their DOS directory bit is set. An explicit `entryFilter` with `onFiltered: "skip-entry"` can omit these entries. Some archives ship symlink/hardlink entries that point outside the destination once resolved; `extractArchive` does not follow them.
 - **Ambiguous output names:** duplicate names and distinct names that collide after `stripComponents`, case normalization, or Unicode normalization are rejected instead of relying on backend- or volume-specific overwrite order.
 - **TOCTOU during merge:** extraction first writes to a private temp dir, then merges into `destDir` using the same boundary checks as `root().write()`. Destination symlink swaps are checked with the selected platform mechanism; non-Linux routes retain the best-effort race window documented in the [security model](security-model.md#containment-guarantees-by-platform).
 - **Zip bombs:** `maxExtractedBytes` and `maxEntryBytes` apply to *post-decompression* bytes, so highly-compressed payloads hit the cap before they exhaust disk.
 - **Corrupt ZIP payloads:** streamed output must match both the central-directory CRC and declared uncompressed size before it can leave private staging.
 - **Slow-loris archives:** `timeoutMs` is a hard wall-clock budget. Extraction is aborted on overrun.
-- **Metadata bombs:** a fixed-header pass-through reader rejects oversized PAX, GNU long-name, and GNU long-link bodies before either TAR implementation buffers them. It understands octal and base-256 size fields without interpreting metadata content.
-
-PAX headers can override the next entry's size from inside their content. The
-fixed-header meter deliberately never interprets that content, so PAX and GNU
-sparse entries are rejected with
-`ArchiveFormatError("archive-header-invalid")` rather than guessing. GNU sparse
-extension blocks are still metered in 512-byte units before rejection, ensuring
-malformed or excessive chains cannot bypass the metadata ceiling. GNU long-name
-and long-link entries remain supported because their fixed header size fully
-determines their layout.
+- **Metadata bombs:** a streaming pass-through reader rejects oversized PAX, GNU long-name, and GNU long-link bodies before either TAR implementation buffers them. It understands octal and base-256 fixed sizes and validates bounded local PAX bodies before using their size overrides for member framing. Original archive bytes remain unchanged.
+
+### Bounded local PAX support
+
+Extraction and single-entry reads accept one nonempty local POSIX `x` header
+(USTAR or GNU header format) immediately before one regular/contiguous file,
+directory, symlink, or hardlink. `path`, `linkpath`, and `size` override that
+member only. Effective paths still pass traversal validation before stripping,
+then the output paths pass depth and collision checks. The filter receives the
+effective pre-strip path, followed by link policy checks. PAX never permits link
+creation. Effective sizes drive framing, filters, and the existing output-byte
+budgets; `maxEntries` still counts members, not their metadata headers.
+
+Records must have exact byte lengths, ASCII keys, a final newline, and no
+duplicate keys, embedded newlines, or unconsumed bytes. Structural `path` and
+`linkpath` values and ownership names must be nonempty printable ASCII. A PAX
+member's raw name, USTAR prefix, and raw link target must also be printable
+ASCII; raw link targets must be present only on links, even when overridden.
+Unicode
+PAX structural text is deliberately unsupported because the underlying parsers
+do not agree when UTF-8 is split across input chunks. `size`, `uid`, and `gid`
+must be canonical unsigned decimal safe integers (zero is valid; signs, leading
+zeros, fractions, and exponents are not). Padded member sizes must also fit the
+safe integer range. Raw and effective directory/link sizes must both be zero;
+non-directory paths ending with a separator and `linkpath` on non-links are
+rejected rather than allowing parser-specific type or framing changes.
+
+The descriptive allowlist is `mtime`, `atime`, `ctime` (signed decimal seconds
+with optional fractional digits, within JavaScript's Date range), `uid`, `gid`,
+`uname`, and `gname`. These attributes are accepted but not restored to the
+destination. `LIBARCHIVE.xattr.*` and `SCHILY.xattr.*` with nonempty ASCII
+alphanumeric/dot/underscore/hyphen suffixes are also accepted as inert metadata,
+never restored as extended attributes. Their values are byte-counted and may
+contain NUL or non-UTF8 bytes, including macOS provenance metadata; embedded
+newlines are rejected because they can disrupt downstream record parsing.
+
+Global `g`, old `X`, old GNU `N`, empty/dangling/repeated local headers, mixed
+PAX/GNU extension chains, unknown keys, charset declarations, ACL extensions,
+and all sparse extensions (including `GNU.sparse.*`, `SCHILY.filetype`,
+`SCHILY.realsize`, and `SCHILY.size`) fail closed with
+`ArchiveFormatError("archive-header-invalid")`. Standalone GNU long-name `L`
+and long-link `K` support is unchanged. GNU sparse extension blocks are still
+metered in 512-byte units before rejection, preserving metadata-limit errors
+for excessive chains. The per-body `maxMetaEntryBytes` limit bounds PAX storage
+and duplicate-key state; one local header per member prevents local metadata
+chains without introducing a new limit or changing defaults.
 
 ## `resolveArchiveKind`
 
@@ -257,7 +304,7 @@ import {
 
 - `validateArchiveEntryPath(raw, opts)` — throws `ArchiveSecurityError` for `..`, absolute, NUL-containing, drive-relative, or otherwise unsafe entry paths, including alternate data stream names on Windows.
 - `normalizeArchiveEntryPath(raw)` — converts backslashes in the entry path to forward slashes.
-- `stripArchivePath(entryPath, n)` — strip the leading N path components, returning `null` if not enough remain.
+- `stripArchivePath(entryPath, n)` — normalize separators, drop empty and `.` components, then strip the leading N components, returning `null` if none remain.
 - `resolveArchiveOutputPath({ destDir, entryPath })` — combines the entry path with the destination, after validation.
 - `isWindowsDrivePath(value)` — detects drive-relative segments such as `C:secret` or `nested/C:secret` that should be rejected.
 

package/docs/config.md

@@ -78,6 +78,13 @@ configureFsSafeLocks({
 });
 ```
 
+These defaults apply to both `acquireFileLock()` / `withFileLock()` and
+`acquireFileLockSync()` / `withFileLockSync()`. Each acquisition resolves
+`retry`, `staleMs`, `staleRecovery`, and `timeoutMs` from the per-call option
+first, then the process configuration, then the package default. Explicit zero
+values are preserved. A per-call `retry` object replaces the configured object
+as a whole; omitted retry fields use package defaults, not configured fields.
+
 Individual lock calls can override any default. Switching the global stale
 recovery mode does not provide the application-owned liveness proof required
 by `shouldRemoveStaleLock`.