@openclaw/fs-safe 0.5.6 → 0.7.0

package/dist/archive-staging.js

@@ -1,16 +1,20 @@
 import fs from "node:fs/promises";
-import fsSync from "node:fs";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { ownExtractionDestinationMutation, } from "./archive-deadline.js";
 import { ArchiveSecurityError, } from "./archive-errors.js";
 import { FsSafeError } from "./errors.js";
 import { formatErrorDetail } from "./error-detail.js";
 import { resolveOpenedFileRealPathForHandle, root } from "./root.js";
 import { isNotFoundPathError, isPathInside } from "./path.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK = "archive entry traverses symlink in destination";
 const ARCHIVE_STAGING_MODE = 0o700;
+function checkExtractionDeadline(deadline) {
+    deadline?.check();
+}
 export { ArchiveSecurityError } from "./archive-errors.js";
 function symlinkTraversalError(originalPath) {
     return new ArchiveSecurityError("destination-symlink-traversal", `${ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK}: ${formatErrorDetail(originalPath)}`);
@@ -105,55 +109,79 @@ async function mkdirArchiveOutput(params) {
     }
 }
 export async function prepareArchiveOutputPath(params) {
+    checkExtractionDeadline(params.deadline);
     const targetRoot = await root(params.destinationRealDir);
+    checkExtractionDeadline(params.deadline);
     const destinationGuard = await createDirectoryIdentityGuard(params.destinationRealDir);
+    checkExtractionDeadline(params.deadline);
     const relPath = params.relPath.split(path.sep).join(path.posix.sep);
     await assertNoSymlinkTraversal({
         rootDir: params.destinationDir,
         relPath,
         originalPath: params.originalPath,
     });
+    checkExtractionDeadline(params.deadline);
     if (params.isDirectory) {
         await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", params.outPath);
-        await assertDirectoryIdentityGuard(destinationGuard);
-        await mkdirArchiveOutput({ targetRoot, relativePath: relPath, originalPath: params.originalPath });
-        await assertDirectoryIdentityGuard(destinationGuard);
-        await assertResolvedInsideDestination({
-            destinationRealDir: params.destinationRealDir,
-            targetPath: params.outPath,
-            originalPath: params.originalPath,
+        checkExtractionDeadline(params.deadline);
+        await ownExtractionDestinationMutation(params.deadline, async () => {
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+            await mkdirArchiveOutput({
+                targetRoot,
+                relativePath: relPath,
+                originalPath: params.originalPath,
+            });
+            checkExtractionDeadline(params.deadline);
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+            await assertResolvedInsideDestination({
+                destinationRealDir: params.destinationRealDir,
+                targetPath: params.outPath,
+                originalPath: params.originalPath,
+            });
+            checkExtractionDeadline(params.deadline);
         });
         return;
     }
     const parentRel = path.posix.dirname(relPath);
     if (parentRel !== ".") {
         await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", path.dirname(params.outPath));
-        await assertDirectoryIdentityGuard(destinationGuard);
-        await mkdirArchiveOutput({
-            targetRoot,
-            relativePath: parentRel,
-            originalPath: params.originalPath,
+        checkExtractionDeadline(params.deadline);
+        await ownExtractionDestinationMutation(params.deadline, async () => {
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+            await mkdirArchiveOutput({
+                targetRoot,
+                relativePath: parentRel,
+                originalPath: params.originalPath,
+            });
+            checkExtractionDeadline(params.deadline);
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
         });
-        await assertDirectoryIdentityGuard(destinationGuard);
     }
     await assertResolvedInsideDestination({
         destinationRealDir: params.destinationRealDir,
         targetPath: path.dirname(params.outPath),
         originalPath: params.originalPath,
     });
+    checkExtractionDeadline(params.deadline);
 }
 async function chmodInsideDestinationBestEffort(params) {
     await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("chmod", params.destinationPath);
+    checkExtractionDeadline(params.deadline);
     const destinationGuard = await createDirectoryIdentityGuard(params.destinationRealDir);
+    checkExtractionDeadline(params.deadline);
     await assertDirectoryIdentityGuard(destinationGuard);
-    const noFollowFlag = process.platform !== "win32" && "O_NOFOLLOW" in fsSync.constants
-        ? fsSync.constants.O_NOFOLLOW
-        : 0;
+    checkExtractionDeadline(params.deadline);
     const handle = await fs
-        .open(params.destinationPath, fsSync.constants.O_RDONLY | noFollowFlag)
+        .open(params.destinationPath, resolveReadOpenFlags())
         .catch(() => null);
+    checkExtractionDeadline(params.deadline);
     if (!handle) {
         const stat = await fs.lstat(params.destinationPath).catch(() => null);
+        checkExtractionDeadline(params.deadline);
         if (stat?.isSymbolicLink()) {
             throw symlinkTraversalError(params.originalPath);
         }
@@ -161,35 +189,45 @@ async function chmodInsideDestinationBestEffort(params) {
     }
     try {
         const stat = await handle.stat();
+        checkExtractionDeadline(params.deadline);
         if (!stat.isDirectory() && !stat.isFile()) {
             return;
         }
         const realPath = await resolveOpenedFileRealPathForHandle(handle, params.destinationPath);
+        checkExtractionDeadline(params.deadline);
         if (!isPathInside(params.destinationRealDir, realPath)) {
             throw symlinkTraversalError(params.originalPath);
         }
-        await handle.chmod(params.mode).catch(() => undefined);
-        await assertDirectoryIdentityGuard(destinationGuard);
+        await ownExtractionDestinationMutation(params.deadline, async () => {
+            await handle.chmod(params.mode).catch(() => undefined);
+            checkExtractionDeadline(params.deadline);
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+        });
     }
     finally {
         await handle.close().catch(() => undefined);
     }
 }
 async function applyStagedEntryMode(params) {
+    checkExtractionDeadline(params.deadline);
     const destinationPath = path.join(params.destinationRealDir, params.relPath);
     await assertResolvedInsideDestination({
         destinationRealDir: params.destinationRealDir,
         targetPath: destinationPath,
         originalPath: params.originalPath,
     });
+    checkExtractionDeadline(params.deadline);
     if (params.mode !== 0) {
         await chmodInsideDestinationBestEffort({
             destinationRealDir: params.destinationRealDir,
             destinationPath,
             mode: params.mode,
             originalPath: params.originalPath,
+            deadline: params.deadline,
         });
     }
+    checkExtractionDeadline(params.deadline);
 }
 async function assertExtractedFileHasNoHardlinkAlias(params) {
     const destinationPath = path.join(params.destinationRealDir, params.relPath);
@@ -296,6 +334,7 @@ export async function mergeExtractedTreeIntoDestination(params) {
                     outPath: destinationPath,
                     originalPath,
                     isDirectory: true,
+                    deadline: params.deadline,
                 });
                 await walk(sourcePath);
                 await applyStagedEntryMode({
@@ -303,6 +342,7 @@ export async function mergeExtractedTreeIntoDestination(params) {
                     relPath,
                     mode: sourceStat.mode & 0o777,
                     originalPath,
+                    deadline: params.deadline,
                 });
                 continue;
             }
@@ -316,31 +356,39 @@ export async function mergeExtractedTreeIntoDestination(params) {
                 outPath: destinationPath,
                 originalPath,
                 isDirectory: false,
+                deadline: params.deadline,
             });
-            try {
-                await targetRoot.copyIn(relPath, sourcePath, { mkdir: true });
-                await assertExtractedFileHasNoHardlinkAlias({
-                    destinationRealDir: params.destinationRealDir,
-                    relPath,
-                    originalPath,
-                });
-                await applyStagedEntryMode({
-                    destinationRealDir: params.destinationRealDir,
-                    relPath,
-                    mode: sourceStat.mode & 0o777,
-                    originalPath,
-                });
-            }
-            catch (err) {
-                await removeExtractedDestinationFile({
-                    destinationRealDir: params.destinationRealDir,
-                    relPath,
-                });
-                if (err instanceof FsSafeError && (err.code === "hardlink" || err.code === "path-alias")) {
-                    throw symlinkTraversalError(originalPath);
+            await ownExtractionDestinationMutation(params.deadline, async () => {
+                try {
+                    await targetRoot.copyIn(relPath, sourcePath, { mkdir: true });
+                    checkExtractionDeadline(params.deadline);
+                    await assertExtractedFileHasNoHardlinkAlias({
+                        destinationRealDir: params.destinationRealDir,
+                        relPath,
+                        originalPath,
+                    });
+                    checkExtractionDeadline(params.deadline);
+                    await applyStagedEntryMode({
+                        destinationRealDir: params.destinationRealDir,
+                        relPath,
+                        mode: sourceStat.mode & 0o777,
+                        originalPath,
+                        deadline: params.deadline,
+                    });
+                    checkExtractionDeadline(params.deadline);
                 }
-                throw err;
-            }
+                catch (err) {
+                    await removeExtractedDestinationFile({
+                        destinationRealDir: params.destinationRealDir,
+                        relPath,
+                    });
+                    if (err instanceof FsSafeError &&
+                        (err.code === "hardlink" || err.code === "path-alias")) {
+                        throw symlinkTraversalError(originalPath);
+                    }
+                    throw err;
+                }
+            });
         }
     };
     await walk(params.sourceDir);

package/dist/archive-tar-admission.d.ts

@@ -0,0 +1,7 @@
+import type { TarEntryInfo } from "./archive-tar.js";
+export declare function rawTarMember(header: Buffer, size: number, effectivePath?: string): TarEntryInfo;
+export declare function createTarAdmissionPlan(manifest: readonly TarEntryInfo[], check: (entry: TarEntryInfo) => boolean, strip: number): {
+    consume(entry: TarEntryInfo): string | null;
+    finish(): void;
+};
+//# sourceMappingURL=archive-tar-admission.d.ts.map

package/dist/archive-tar-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar-admission.d.ts","sourceRoot":"","sources":["../src/archive-tar-admission.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAYrD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,YAAY,CAS/F;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,SAAS,YAAY,EAAE,EACjC,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,EACvC,KAAK,EAAE,MAAM,GACZ;IAAE,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,IAAI,IAAI,CAAA;CAAE,CAmBjE"}

package/dist/archive-tar-admission.js

@@ -0,0 +1,43 @@
+import { ArchiveFormatError } from "./archive-errors.js";
+import { stripArchivePath, validateArchiveEntryPath } from "./archive-entry.js";
+import { readTarHeaderPaths } from "./archive-tar-header.js";
+// node-tar's normalFsTypes/ReadEntry switch. All other non-metadata types
+// bypass both its filter and entry event; they still belong to our manifest.
+// Header.decode normalizes NUL to "0" before choosing the emitted File type.
+const visibleTypes = new Map([
+    [0, "File"], [0x30, "File"], [0x31, "Link"], [0x32, "SymbolicLink"],
+    [0x33, "CharacterDevice"], [0x34, "BlockDevice"], [0x35, "Directory"],
+    [0x36, "FIFO"], [0x37, "ContiguousFile"], [0x44, "GNUDumpDir"],
+]);
+export function rawTarMember(header, size, effectivePath) {
+    const { name, prefix } = readTarHeaderPaths(header);
+    validateArchiveEntryPath(name);
+    validateArchiveEntryPath(prefix);
+    const rawPath = prefix ? `${prefix}/${name}` : name;
+    validateArchiveEntryPath(rawPath);
+    const path = effectivePath ?? rawPath;
+    validateArchiveEntryPath(path);
+    return { path, size, type: visibleTypes.get(header[156]) ?? "Unsupported" };
+}
+export function createTarAdmissionPlan(manifest, check, strip) {
+    const visible = [];
+    for (const entry of manifest) {
+        const accepted = check(entry);
+        if (entry.type !== "Unsupported") {
+            visible.push({ entry, output: accepted ? stripArchivePath(entry.path, strip) : null });
+        }
+    }
+    let index = 0;
+    const mismatch = () => new ArchiveFormatError("invalid TAR header: parser disagrees with raw admission");
+    return {
+        consume(actual) {
+            const expected = visible[index++];
+            if (!expected || expected.entry.type !== actual.type || expected.entry.size !== actual.size ||
+                stripArchivePath(expected.entry.path, 0) !== stripArchivePath(actual.path, 0))
+                throw mismatch();
+            return expected.output;
+        },
+        finish() { if (index !== visible.length)
+            throw mismatch(); },
+    };
+}

package/dist/archive-tar-gnu.d.ts

@@ -0,0 +1,2 @@
+export declare function validateGnuMetadata(body: Buffer, type: "L" | "K"): string;
+//# sourceMappingURL=archive-tar-gnu.d.ts.map

package/dist/archive-tar-gnu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar-gnu.d.ts","sourceRoot":"","sources":["../src/archive-tar-gnu.ts"],"names":[],"mappings":"AAKA,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,GAAG,GAAG,MAAM,CAazE"}

package/dist/archive-tar-gnu.js

@@ -0,0 +1,20 @@
+import { ArchiveFormatError } from "./archive-errors.js";
+import { validateArchiveEntryPath } from "./archive-entry.js";
+// Keep the byte grammar aligned with native/src/tar_meter.rs. Parsers differ
+// on embedded NULs and malformed UTF-8, so validate before either sees a name.
+export function validateGnuMetadata(body, type) {
+    const value = body.at(-1) === 0 ? body.subarray(0, -1) : body;
+    if (!value.length || value.includes(0)) {
+        throw new ArchiveFormatError("invalid GNU metadata: empty name or embedded NUL");
+    }
+    let name;
+    try {
+        name = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(value);
+    }
+    catch {
+        throw new ArchiveFormatError("invalid GNU metadata: name is not valid UTF-8");
+    }
+    if (type === "L")
+        validateArchiveEntryPath(name);
+    return name;
+}

package/dist/archive-tar-header.d.ts

@@ -0,0 +1,8 @@
+export declare function validateTarChecksum(header: Buffer): void;
+export declare function readTarHeaderPaths(header: Buffer): {
+    name: string;
+    prefix: string;
+    linkname: string;
+};
+export declare function validateTarHeader(header: Buffer): void;
+//# sourceMappingURL=archive-tar-header.d.ts.map

package/dist/archive-tar-header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar-header.d.ts","sourceRoot":"","sources":["../src/archive-tar-header.ts"],"names":[],"mappings":"AAGA,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAWxD;AAcD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CASrG;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAUtD"}

package/dist/archive-tar-header.js

@@ -0,0 +1,47 @@
+import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
+const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+export function validateTarChecksum(header) {
+    const field = header.subarray(148, 156);
+    const end = field.indexOf(0);
+    const digits = field.subarray(0, end < 0 ? field.length : end).toString("latin1").replace(/^ +| +$/g, "");
+    const sum = header.reduce((total, byte, index) => total + (index >= 148 && index < 156 ? 32 : byte), 0);
+    // Require an in-field delimiter: node-tar otherwise reads into the typeflag.
+    if (!/^[0-7]+$/.test(digits) || ![0, 32].includes(field[7]) ||
+        (end >= 0 && field.subarray(end).some((byte) => byte !== 0 && byte !== 32)) ||
+        Number.parseInt(digits, 8) !== sum) {
+        throw new ArchiveFormatError("invalid TAR header: checksum failure");
+    }
+}
+function fixedField(field) {
+    const zero = field.indexOf(0);
+    if (zero >= 0 && field.subarray(zero).some((byte) => byte !== 0)) {
+        throw new ArchiveSecurityError("entry-path", "tar entry path contains bytes after NUL");
+    }
+    try {
+        return utf8.decode(field.subarray(0, zero < 0 ? field.length : zero));
+    }
+    catch {
+        throw new ArchiveSecurityError("entry-path", "tar entry path is not valid UTF-8");
+    }
+}
+export function readTarHeaderPaths(header) {
+    // node-tar's star layout uses a 130-byte prefix followed by atime/ctime.
+    const prefixEnd = header[475] === 0 ? 475 : 500;
+    return {
+        name: fixedField(header.subarray(0, 100)),
+        prefix: header.subarray(257, 265).equals(Buffer.from("ustar\0" + "00"))
+            ? fixedField(header.subarray(345, prefixEnd)) : "",
+        linkname: fixedField(header.subarray(157, 257)),
+    };
+}
+export function validateTarHeader(header) {
+    validateTarChecksum(header);
+    const { linkname } = readTarHeaderPaths(header);
+    const isLink = header[156] === 0x31 || header[156] === 0x32;
+    if (isLink && !linkname) {
+        throw new ArchiveFormatError("invalid TAR header: linkname required on a link header");
+    }
+    if (!isLink && linkname) {
+        throw new ArchiveFormatError("invalid TAR header: linkname forbidden on a non-link header");
+    }
+}

package/dist/archive-tar-meta.d.ts

@@ -1,6 +1,34 @@
+import { Transform } from "node:stream";
+import { type TarMeterLimits } from "./archive-limits.js";
+import type { TarEntryInfo } from "./archive-tar.js";
+export declare class TarMetadataMeter extends Transform {
+    private readonly limits;
+    private readonly onMember?;
+    private readonly block;
+    private blockLength;
+    private state;
+    private pendingPax;
+    private readonly pendingGnu;
+    private pendingGnuPath;
+    private zeroBlocks;
+    private entries;
+    private remainingDecodedBytes;
+    private manifestBytes;
+    constructor(limits: TarMeterLimits, onMember?: ((entry: TarEntryInfo) => void) | undefined);
+    private countMember;
+    private invalid;
+    private paddedSize;
+    private parseSize;
+    private finishHeader;
+    private finishSparseHeader;
+    private meter;
+    _transform(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null, data?: Buffer) => void): void;
+    _flush(callback: (error?: Error | null) => void): void;
+}
 export declare function preflightTarMetadata(params: {
     archivePath: string;
-    maxMetaEntryBytes: number;
+    limits: TarMeterLimits;
     signal?: AbortSignal;
+    onMember?: (entry: TarEntryInfo) => void;
 }): Promise<void>;
 //# sourceMappingURL=archive-tar-meta.d.ts.map

package/dist/archive-tar-meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-tar-meta.d.ts","sourceRoot":"","sources":["../src/archive-tar-meta.ts"],"names":[],"mappings":"AAqJA,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}
+{"version":3,"file":"archive-tar-meta.d.ts","sourceRoot":"","sources":["../src/archive-tar-meta.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAY,MAAM,aAAa,CAAC;AAIlD,OAAO,EAAqE,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI7H,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAWrD,qBAAa,gBAAiB,SAAQ,SAAS;IAYjC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAkB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAX/E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,KAAK,CAAkC;IAC/C,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwB;IACnD,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,aAAa,CAAK;IAE1B,YAA6B,MAAM,EAAE,cAAc,EAAmB,QAAQ,CAAC,GAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,aAAA,EAM7G;IAED,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,SAAS;IA4BjB,OAAO,CAAC,YAAY;IA6EpB,OAAO,CAAC,kBAAkB;IAgB1B,OAAO,CAAC,KAAK;IAyCJ,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAc3H;IAEQ,MAAM,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAM9D;CACF;AAaD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;CAC1C,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}