@openclaw/fs-safe 0.8.1 → 0.8.2

package/dist/archive.js

@@ -9,7 +9,6 @@ import { assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWit
 import { resolveArchiveKind } from "./archive-kind.js";
 import { prepareArchiveDestinationDir, preparePrivateArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
 import { mergePlannedArchiveIntoDestination } from "./archive-merge.js";
-import { createTarEntryPreflightChecker, readTarEntryInfo, } from "./archive-tar.js";
 import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
 import { isZipSymlinkEntry, zipEntryDeclaredSize, zipEntryMode, } from "./archive-zip-entry.js";
 import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./archive-zip-integrity.js";
@@ -19,9 +18,7 @@ import { extractNativeArchive } from "./archive-native.js";
 import { stageArchiveFileForExtraction } from "./archive-input.js";
 import { getNativeBinding } from "./native.js";
 import { resolveArchiveEntryMode, resolveArchiveFilteredEntryPolicy, shouldExtractArchiveEntry, } from "./archive-policy.js";
-import { importOptionalTar, NODE_TAR_RATIO_DISABLED, normalizeTarParserError } from "./archive-tar-runtime.js";
-import { preflightTarMetadata } from "./archive-tar-meta.js";
-import { createTarAdmissionPlan } from "./archive-tar-admission.js";
+import { extractWasmTar } from "./archive-tar-extract.js";
 import { writeSiblingTempFile } from "./sibling-temp.js";
 export { isWindowsDrivePath, normalizeArchiveEntryPath, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 export { resolveArchiveKind, resolvePackedRootDir } from "./archive-kind.js";
@@ -230,117 +227,13 @@ export async function extractArchive(params) {
     }
     if (kind === "tar") {
         await withExtractionDeadline(params.timeoutMs, label, async (deadline) => {
-            const tar = await importOptionalTar();
             const stagedArchive = await stageArchiveFileForExtraction({
                 archivePath: params.archivePath,
                 limits,
                 deadline,
             });
             try {
-                const manifest = [];
-                await preflightTarMetadata({
-                    archivePath: stagedArchive.path,
-                    limits: tarLimits,
-                    signal: deadline.signal,
-                    onMember: (entry) => { manifest.push(entry); },
-                });
-                deadline.check();
-                const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
-                await withStagedArchiveDestination({
-                    destinationRealDir,
-                    run: async (stagingDir) => {
-                        deadline.check();
-                        const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
-                        const checkTarEntrySafety = createTarEntryPreflightChecker({
-                            rootDir: destinationRealDir,
-                            stripComponents: params.stripComponents,
-                            limits,
-                            entryFilter: params.entryFilter,
-                            onFiltered,
-                        });
-                        const admission = createTarAdmissionPlan(manifest, (entry) => {
-                            deadline.check();
-                            return checkTarEntrySafety(entry);
-                        }, strip);
-                        const acceptedEntries = [];
-                        // Extract privately, then merge through the safe-open boundary.
-                        const extractor = tar.x({
-                            cwd: stagingDir,
-                            // fs-safe owns stripping: node-tar counts the `.` and empty path
-                            // components that stripArchivePath() drops, so the two disagree.
-                            strip: 0,
-                            gzip: params.tarGzip,
-                            signal: deadline.signal,
-                            preservePaths: false,
-                            noChmod: true,
-                            preserveOwner: false,
-                            noMtime: true,
-                            dmode: 0o700,
-                            strict: true,
-                            maxMetaEntrySize: tarLimits.maxMetaEntryBytes,
-                            maxDecompressionRatio: NODE_TAR_RATIO_DISABLED,
-                            filter(_entryPath, entry) {
-                                try {
-                                    const info = readTarEntryInfo(entry);
-                                    const relPath = admission.consume(info);
-                                    if (!relPath) {
-                                        return false;
-                                    }
-                                    const kind = info.type === "Directory" || info.type === "GNUDumpDir" ? "directory" : "file";
-                                    // Keep archived modes before changing node-tar's creation mode.
-                                    entry.path = relPath;
-                                    acceptedEntries.push({
-                                        path: relPath,
-                                        kind,
-                                        mode: resolveArchiveEntryMode({
-                                            kind,
-                                            archivedMode: info.mode,
-                                            policy: params.entryModes,
-                                        }),
-                                    });
-                                    entry.mode = kind === "directory" ? 0o700 : 0o600;
-                                    return true;
-                                }
-                                catch (error) {
-                                    // Abort through the parser so pipeline tears down both the
-                                    // archive reader and unpacker instead of leaving a paused
-                                    // stream behind after a policy rejection.
-                                    this.abort(error instanceof Error ? error : new Error(String(error)));
-                                    return false;
-                                }
-                            },
-                            onReadEntry(entry) {
-                                try {
-                                    deadline.check();
-                                }
-                                catch (err) {
-                                    const error = err instanceof Error ? err : new Error(String(err));
-                                    // EventEmitter binds `this` to tar.Unpack, exposing abort().
-                                    const emitter = this;
-                                    emitter.abort?.(error);
-                                }
-                            },
-                        });
-                        try {
-                            await pipeline(fsSync.createReadStream(stagedArchive.path), extractor, {
-                                signal: deadline.signal,
-                            });
-                        }
-                        catch (error) {
-                            throw normalizeTarParserError(createPipelineTimeoutError(error, deadline));
-                        }
-                        admission.finish();
-                        deadline.check();
-                        await mergePlannedArchiveIntoDestination({
-                            entries: acceptedEntries,
-                            sourceDir: stagingDir,
-                            destinationDir: params.destDir,
-                            destinationRealDir,
-                            deadline,
-                        });
-                        deadline.check();
-                    },
-                });
+                await extractWasmTar({ archivePath: stagedArchive.path, options: { ...params, onFiltered }, limits, tarLimits, deadline });
             }
             finally {
                 await stagedArchive.cleanup();

package/dist/device-path.d.ts

@@ -8,6 +8,7 @@ export type UnsafeDeviceReadPathOptions = {
     platform?: NodeJS.Platform;
 };
 export declare const WINDOWS_RESERVED_DEVICE_NAMES: ReadonlySet<string>;
+export declare function isWindowsReservedDeviceName(name: string): boolean;
 export declare function matchUnsafeDeviceReadPath(filePath: string, options?: UnsafeDeviceReadPathOptions): UnsafeDeviceReadPathMatch | undefined;
 export declare function isUnsafeDeviceReadPath(filePath: string, options?: UnsafeDeviceReadPathOptions): boolean;
 export declare function assertNoUnsafeDeviceReadPath(filePath: string, options?: UnsafeDeviceReadPathOptions): void;

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

@@ -1 +1 @@
-{"version":3,"file":"device-path.d.ts","sourceRoot":"","sources":["../src/device-path.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,0BAA0B,GAClC,cAAc,GACd,UAAU,GACV,gBAAgB,CAAC;AAErB,MAAM,MAAM,yBAAyB,GAAG;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,0BAA0B,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B,CAAC;AAcF,eAAO,MAAM,6BAA6B,EAAE,WAAW,CAAC,MAAM,CAgC5D,CAAC;AAkFH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,2BAAgC,GACxC,yBAAyB,GAAG,SAAS,CAWvC;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAET;AAED,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,2BAA2B,GACpC,IAAI,CAON"}
+{"version":3,"file":"device-path.d.ts","sourceRoot":"","sources":["../src/device-path.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,0BAA0B,GAClC,cAAc,GACd,UAAU,GACV,gBAAgB,CAAC;AAErB,MAAM,MAAM,yBAAyB,GAAG;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,0BAA0B,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B,CAAC;AAcF,eAAO,MAAM,6BAA6B,EAAE,WAAW,CAAC,MAAM,CAgC5D,CAAC;AAsEH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjE;AAcD,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,2BAAgC,GACxC,yBAAyB,GAAG,SAAS,CAWvC;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAET;AAED,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,2BAA2B,GACpC,IAAI,CAON"}

package/dist/device-path.js

@@ -98,8 +98,11 @@ function normalizeWindowsDeviceBaseName(filePath) {
     const normalized = trimTrailingWindowsSeparators(filePath.replace(/\//g, "\\"));
     const lastSegment = normalized.split("\\").filter(Boolean).at(-1) ?? normalized;
     const withoutStream = lastSegment.split(":")[0] ?? lastSegment;
-    const withoutTrailingIgnoredChars = trimTrailingWindowsIgnoredChars(withoutStream);
-    return (withoutTrailingIgnoredChars.split(".")[0] ?? withoutTrailingIgnoredChars).toUpperCase();
+    const stem = withoutStream.split(".")[0] ?? withoutStream;
+    return trimTrailingWindowsIgnoredChars(stem).toUpperCase();
+}
+export function isWindowsReservedDeviceName(name) {
+    return name.length > 0 && WINDOWS_RESERVED_DEVICE_NAMES.has(normalizeWindowsDeviceBaseName(name));
 }
 function matchWindowsDeviceReadPath(filePath) {
     const normalized = filePath.replace(/\//g, "\\");

package/dist/directory-mode-owner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"directory-mode-owner.d.ts","sourceRoot":"","sources":["../src/directory-mode-owner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIlD,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC,CAAC;AACF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,KAAK,GAAG,WAAW,EAAE,MAAM,EAAE,KAAK,GAAG,WAAW,GAAG,IAAI,CAOrG;AAED,8FAA8F;AAC9F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,kBAAkB,CAoDrB"}
+{"version":3,"file":"directory-mode-owner.d.ts","sourceRoot":"","sources":["../src/directory-mode-owner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAIlD,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC,CAAC;AACF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,KAAK,GAAG,WAAW,EAAE,MAAM,EAAE,KAAK,GAAG,WAAW,GAAG,IAAI,CAOrG;AAED,8FAA8F;AAC9F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,kBAAkB,CAuDrB"}

package/dist/directory-mode-owner.js

@@ -26,6 +26,9 @@ export function ownDirectoryMode(params) {
             check?.();
         }),
         apply: (mode, checks = {}) => enqueue(async () => {
+            // inspect() reports permission bits only; chmod ignores file-type bits,
+            // so tolerate raw stat modes (e.g. S_IFDIR | 0o755) by masking up front.
+            mode &= 0o7777;
             checks.check?.();
             const currentMode = await params.inspect();
             checks.check?.();

package/dist/replace-file-descriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replace-file-descriptor.d.ts","sourceRoot":"","sources":["../src/replace-file-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAIvD,OAAO,EAA0C,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE5G,KAAK,mBAAmB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAC3E,KAAK,kBAAkB,GAAG,IAAI,CAC5B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,eAAe,CACrF,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAE5D,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,EACjC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,IAAI,CAAC,OAAO,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,WAAW,CAAC,EACrE,OAAO,EAAE,MAAM,GACd,IAAI,CAgBN;AA2BD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CA4B1C;AAED,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAC/C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,IAAI,CAcP;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9C,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CAAC,CA0BzD;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9C,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CA0BxC"}
+{"version":3,"file":"replace-file-descriptor.d.ts","sourceRoot":"","sources":["../src/replace-file-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAIvD,OAAO,EAA0C,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE5G,KAAK,mBAAmB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC;AAC3E,KAAK,kBAAkB,GAAG,IAAI,CAC5B,OAAO,MAAM,EACb,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,eAAe,CACrF,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAE5D,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,EACjC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,IAAI,CAAC,OAAO,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,WAAW,CAAC,EACrE,OAAO,EAAE,MAAM,GACd,IAAI,CAgBN;AA2BD,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CA4B1C;AAED,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAC/C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,IAAI,CAeP;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE;IAC1C,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9C,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CAAC,CA0BzD;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9C,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,CA0BxC"}

package/dist/replace-file-descriptor.js

@@ -101,7 +101,8 @@ export function applyDirectoryModeSync(params) {
     const fd = params.fsModule.openSync(params.dirPath, directoryOpenFlags());
     try {
         assertSameDirectory(expected, params.fsModule.fstatSync(fd), params.dirPath);
-        params.fchmodSync?.(fd, params.mode);
+        // chmod ignores file-type bits; mask so raw stat modes are tolerated.
+        params.fchmodSync?.(fd, params.mode & 0o7777);
     }
     finally {
         params.fsModule.closeSync(fd);

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

@@ -1 +1 @@
-{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAM/C,OAAO,EAAkF,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAShJ,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAIjC,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAwER;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAUpB;AA8JD,KAAK,qBAAqB,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAYF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,SAAS,CAAC,GAC7C,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC5C,WAAW,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAuBD;AAuDD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAezF"}
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAM/C,OAAO,EAAkF,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAUhJ,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAIjC,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAyER;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAUpB;AA8JD,KAAK,qBAAqB,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAYF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,SAAS,CAAC,GAC7C,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC5C,WAAW,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAuBD;AAuDD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAezF"}

package/dist/secret-file.js

@@ -7,6 +7,7 @@ import { normalizeMaxBytes } from "./byte-budget.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
 import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
 import { assertOwnedDirectory } from "./directory-mode-owner.js";
+import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 import { resolveHomeRelativePath } from "./home-dir.js";
 import { openPinnedFileSync } from "./pinned-open.js";
@@ -37,6 +38,7 @@ export function readSecretFileSync(filePath, label, options = {}) {
     }
     let previewStat;
     try {
+        assertNoUnsafeDeviceReadPath(resolvedPath);
         previewStat = inspectFileIdentitySync(() => inspectInput(`${label} file at ${resolvedPath} must not be a symlink.`));
     }
     catch (error) {

package/dist/secret-read-async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AAQA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA8DjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}
+{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AASA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CAgEjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}

package/dist/secret-read-async.js

@@ -2,6 +2,7 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { readFileHandleBounded } from "./bounded-read.js";
 import { normalizeMaxBytes } from "./byte-budget.js";
+import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 import { resolveHomeRelativePath } from "./home-dir.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
@@ -26,6 +27,7 @@ export async function readSecretFile(filePath, label, options = {}) {
     }
     let previewStat;
     try {
+        assertNoUnsafeDeviceReadPath(resolvedPath);
         previewStat = await inspectFileIdentity(() => inspectInput(`${label} file at ${resolvedPath} must not be a symlink.`));
     }
     catch (error) {
@@ -36,6 +38,7 @@ export async function readSecretFile(filePath, label, options = {}) {
     let raw;
     try {
         const realPath = await fs.realpath(resolvedPath);
+        assertNoUnsafeDeviceReadPath(realPath);
         handle = await fs.open(realPath, resolveReadOpenFlags());
         const openedHandle = handle;
         const openedStat = await inspectFileIdentity(async () => {

package/docs/archive.md

@@ -2,15 +2,12 @@
 
 `@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
-that omit optional dependencies can still import this subpath and use the
-native path or pure path/limit helpers.
-
-Some package managers and CI installs skip optional dependencies
-(`--no-optional`, `--omit=optional`, or equivalent). If an archive helper throws
-that an optional archive dependency is not installed, install `jszip` and/or
-`tar` explicitly in the consuming package.
+TAR admission uses one Rust core compiled into both the native binding and a
+bundled, import-free WebAssembly module. The guarded JavaScript fallback uses
+that module for TAR/gzip and optional `jszip` for ZIP. TAR needs no optional
+parser dependency, runtime download, install script, or consumer Rust toolchain.
+Installs omitting optional dependencies can import every public subpath and use
+TAR/gzip in `auto` or `off`; ZIP fallback still requires `jszip`.
 
 ```ts
 import { extractArchive, resolveArchiveKind } from "@openclaw/fs-safe/archive";
@@ -68,12 +65,12 @@ directories; ZIP UNIX creator records with zero attributes are explicit zero,
 while non-UNIX ZIP records use the absent-metadata defaults.
 
 TAR mode fields containing only NUL/ASCII-space padding use absent defaults.
-Native extraction also recognizes GNU binary modes, including signed values,
-within node-tar's JavaScript safe-integer range before masking permission bits.
-Malformed or unsupported mode representations retain existing decoder behavior:
-native falls back to zero, while JavaScript may default, parse an octal prefix,
-or reject. These representations are not newly admitted or standardized by the
-mode repair; raw framing and other numeric-field checks remain unchanged.
+Both backends recognize GNU binary modes, including signed values,
+within JavaScript's safe-integer range before masking permission bits.
+Malformed or unsupported mode fields consistently fall back to zero, matching
+the former native behavior. This replaces JavaScript's decoder-dependent octal
+prefix parsing, defaulting, or rejection for malformed fields. Ordinary octal,
+absent, explicit zero, and supported GNU binary fields retain their behavior.
 
 Final modes remain separate from private working staging permissions: files
 stay `0o600` and directories `0o700` until publication. Files receive their final
@@ -112,8 +109,8 @@ 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.
+copies the admitted payload range to this accepted output path, so depth checks,
+collision checks, writes, and mode application agree.
 
 An `entryFilter` sees the validated **canonical effective archive path before
 stripping**, entry kind, and declared size. On every JavaScript and native
@@ -127,6 +124,12 @@ Unicode Path names use the same canonicalization.
 Raw paths undergo traversal, absolute/drive-path, and NUL validation **before**
 canonicalization; normalization cannot turn an unsafe path into an accepted
 one. Stripping and output collision checks use this same canonical identity.
+On Windows, archive admission also rejects reserved device segments such as
+`NUL`, `CON.txt`, and `nul .txt` with `ArchiveSecurityError("entry-path")`,
+before extraction or bounded member reads. Ignored trailing spaces in the stem
+before an extension do not bypass this check. Ordinary members with these names
+remain valid on POSIX; this is a host-specific device guard, not a portable-name
+restriction.
 Filters that compare exact strings should use canonical pre-strip paths,
 including directory names without a trailing `/`.
 Returning `"skip"` rejects the whole archive unless `onFiltered` is
@@ -162,11 +165,10 @@ If skipping was not explicitly part of the restore contract, omit
 `onFiltered`; the first `"skip"` then rejects the complete archive with
 `ArchiveSecurityError("entry-filtered")`.
 
-Both TAR implementations finish bounded admission before TypeScript policy
-evaluation, so a rejected plan never starts extraction. The JavaScript path
-owns the extraction file stream and aborts node-tar through a pipeline on
-parser disagreement, validation, or timeout failure, destroying both ends
-instead of leaving a paused parser to drain indefinitely.
+Both TAR routes finish bounded admission before TypeScript policy evaluation,
+so a rejected plan never starts extraction. The JavaScript path owns its input,
+decoder, and WASM parser streams, joining their teardown on validation, write,
+or timeout failure.
 
 TAR character devices, block devices, and FIFOs are presented to the filter as
 `kind: "other"`. Accepted entries of these types reject with
@@ -183,8 +185,7 @@ and output collision checks in physical order. Each remaining record reaches
 `entryFilter` once with its canonical pre-strip path, `kind: "other"`, and
 declared effective size. A filter skip rejects with `"entry-filtered"` unless
 `onFiltered: "skip-entry"` is explicit. Accepted unsupported records are safely
-omitted and do not consume output payload budgets. This applies even when the
-underlying TAR parser suppresses the record. GNU long names describe one such
+omitted and do not consume output payload budgets. The shared core admits these records explicitly. GNU long names describe one such
 record and are then cleared; local PAX on unsupported types and GNU sparse
 `S` records retain their existing fail-closed format policy.
 
@@ -219,7 +220,7 @@ type ArchiveExtractLimits = {
 };
 ```
 
-Defaults exist for each (`DEFAULT_MAX_ARCHIVE_BYTES_ZIP`, `DEFAULT_MAX_ENTRIES`, `DEFAULT_MAX_EXTRACTED_BYTES`, `DEFAULT_MAX_ENTRY_BYTES`, `DEFAULT_MAX_META_ENTRY_BYTES`, `DEFAULT_MAX_ENTRY_PATH_COMPONENTS`). An explicit zero remains zero rather than selecting the default. `maxEntries` counts every archive entry, including entries removed by `stripComponents` or an explicit filter. The path-component default is 256. It is evaluated after `stripComponents` and before TypeScript accepts an entry for either JavaScript or native extraction, so rejected entries cannot cause implicit parent-directory creation. The 1 MiB metadata default matches node-tar's `maxMetaEntrySize`; fs-safe passes the same resolved value to node-tar and the native TAR meter.
+Defaults exist for each (`DEFAULT_MAX_ARCHIVE_BYTES_ZIP`, `DEFAULT_MAX_ENTRIES`, `DEFAULT_MAX_EXTRACTED_BYTES`, `DEFAULT_MAX_ENTRY_BYTES`, `DEFAULT_MAX_META_ENTRY_BYTES`, `DEFAULT_MAX_ENTRY_PATH_COMPONENTS`). An explicit zero remains zero rather than selecting the default. `maxEntries` counts every archive entry, including entries removed by `stripComponents` or an explicit filter. The path-component default is 256. It is evaluated after `stripComponents` and before TypeScript accepts an entry for either JavaScript or native extraction, so rejected entries cannot cause implicit parent-directory creation. The same resolved 1 MiB metadata default applies to the native and WASM core.
 
 A limit violation throws `ArchiveLimitError`. Its constant and string code are:
 
@@ -262,17 +263,17 @@ codes remain `"destination-not-directory"`, `"destination-symlink"`, and
 - **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.
-- **Corrupt gzip streams:** truncated compressed bodies, missing trailers, and checksum failures reject before extraction publishes files or an entry read returns bytes, on both JavaScript and native backends.
+- **Gzip container integrity:** every concatenated gzip member must have a complete valid header, body, CRC32, and ISIZE trailer. A completed member may be followed by all-zero compressed-container padding (including system-tar stdout padding), bounded by the original archive-byte limit. The padding must remain zero through physical EOF; nonzero bytes or another member after padding reject. Truncation and corruption reject before publication or selected bytes return on both backends. Compressed padding is separate from decoded TAR EOF and does not bypass its checks.
 - **Slow-loris archives:** `timeoutMs` is a hard wall-clock budget for non-mutating work. Extraction is aborted on overrun; if a destination mutation is already in flight, that mutation and rollback are joined before rejection so archive-controlled publication cannot continue afterward.
-- **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.
+- **Metadata bombs:** a streaming pass-through reader rejects oversized PAX, GNU long-name, and GNU long-link bodies before buffering their bodies. 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.
 
 ### Raw TAR framing
 
 Extraction and bounded reads admit the complete decoded TAR stream through the
-raw meter before either backend's TAR parser runs. This applies to plain TAR,
+shared Rust core. This applies to plain TAR,
 gzip, and native-supported zstd/bzip2, without changing native-mode availability
-or fallback policy. The existing TypeScript and Rust meters enforce the same
-framing rules before parser normalization:
+or fallback policy. The native and WASM builds enforce the same
+framing rules:
 
 - Every nonzero header must have a valid unsigned octal checksum, delimited
   within its field. Checksum validation precedes metadata allocation and member
@@ -301,22 +302,28 @@ Missing linknames on links and nonempty linknames on non-links still use the
 format error. PAX `x` and GNU long-name/long-link `L`/`K` payloads retain their
 existing support and metadata limits; the zero-body rule is not applied to all
 non-regular types.
-PAX effective sizes still determine regular-member framing. Admission preserves
-the input bytes, and all entry/path/byte limits and extraction deadlines remain
-in force. Native inspection now completes this admission pass before parsing,
-requiring one additional streaming read/decompression pass.
-JavaScript admission reports an ordered logical-member manifest from the raw
-meter, bounded by entry-count, manifest, and decoded limits. Policy runs once
-over that manifest; extraction checks parser-visible members against the
-accepted decisions before writing. Original member names and USTAR prefixes
-are validated even when overridden, and non-padding bytes after a fixed path
-field's NUL terminator reject rather than hiding an unsafe suffix.
-Both meters enforce the 255-byte component ceiling under NFC and NFD before
-metadata replaces a raw path, including Hangul decomposition expansion.
-Native extraction and entry reads also drain their metered readers through
-physical EOF after parser traversal, before completing directory modes,
-publishing staged files, or returning the requested bytes. Finding the requested
-member or reaching the parser's logical EOF cannot bypass trailing validation.
+PAX effective sizes determine regular-member framing. Admission preserves input
+bytes and emits an ordered manifest with exact effective names, types, modes,
+sizes, and decoded payload offsets. TypeScript owns filtering, stripping,
+collisions, permissions, and accepted-output limits. Executors replay admitted
+ranges from the immutable staged input; no second TAR parser interprets PAX,
+GNU names, or payload lengths. Native writes remain descriptor-relative;
+JavaScript writes use the shared guarded private staging and pinned-write helpers.
+
+Original member names and USTAR prefixes are validated even when overridden.
+Non-padding bytes after a fixed path field's NUL terminator reject. The core
+enforces the 255-byte component ceiling under NFC and NFD, including Hangul
+expansion. Every replay drains and validates physical EOF before publication or
+returning selected bytes. Unrequested, filtered, and stripped members cannot
+bypass validation. Decompression remains streaming; no complete decoded archive
+is retained in memory or written to a decoded spool.
+
+The WASM transport has a fixed 64 KiB input buffer, one pending member event,
+and a 256 MiB maximum linear memory per isolated parser instance. Metadata is
+bounded before allocation; allocation failure rejects. Stream backpressure
+bounds queued chunks, and completion/error destroys the instance's parser
+state. The manifest retains the existing charged budget below; linear memory
+is an additional execution resource bound, not a new public limit option.
 
 The raw meter enforces `maxEntries` before consuming each logical member's body,
 including members later skipped by filtering or stripping. PAX/GNU metadata
@@ -343,9 +350,7 @@ archive overhead with safe addition. Ordinary limits, including
 zero and the existing defaulting/rounding rules, retain their behavior.
 There is no new public option. This is an absolute decoded admission
 cap, not a decompression-ratio policy; bounded stream/codec read-ahead remains.
-After this complete preflight, the JavaScript backend disables node-tar's
-independent ratio threshold so it cannot reject data that the native backend
-accepts within the same absolute limits.
+There is no independent TAR parser decompression-ratio threshold.
 
 ### Bounded local PAX support
 
@@ -359,13 +364,14 @@ permits link creation. Effective sizes drive framing, filters, and the existing
 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`
+duplicate keys or unconsumed bytes. `path` and `linkpath` must be nonempty strict
+UTF-8 without NUL. Unicode, a leading BOM, numeric-looking names, and embedded
+newlines preserve their exact spelling; newlines inside a byte-counted value
+are data. Windows filesystem filename restrictions still apply during creation.
+Ownership names retain the existing nonempty printable-ASCII contract. Raw name,
+USTAR prefix, and link fields still require strict UTF-8 and NUL padding even
+when metadata overrides them. Raw link targets must be present only on links.
+`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;
@@ -378,8 +384,7 @@ with optional fractional digits, within JavaScript's Date range), `uid`, `gid`,
 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.
+contain NUL, non-UTF8 bytes, or newlines, including macOS provenance metadata.
 
 Global `g`, old `X`, old GNU `N`, empty/dangling/repeated local headers, mixed
 PAX/GNU extension chains, unknown keys, charset declarations, ACL extensions,
@@ -393,11 +398,11 @@ chains without introducing a new limit or changing defaults.
 
 ### Bounded GNU long names and links
 
-Both raw meters buffer GNU long-name `L` and long-link `K` bodies within
-`maxMetaEntryBytes` before either TAR parser runs. A body must contain a nonempty
+The shared core buffers GNU long-name `L` and long-link `K` bodies within
+`maxMetaEntryBytes`. A body must contain a nonempty
 UTF-8 name, with either no NUL or exactly one terminal NUL. Embedded NULs,
 additional terminal NULs, bytes after a NUL, and invalid UTF-8 reject with
-`ArchiveFormatError("archive-header-invalid")`. The meters preserve original
+`ArchiveFormatError("archive-header-invalid")`. The core preserves original
 archive bytes, including the optional terminator and block padding.
 
 One logical member may have at most one `L` and one `K`, in either order.

package/docs/contributing.md

@@ -19,7 +19,16 @@ manager version declared in `package.json`.
 pnpm build
 ```
 
-Runs `tsc -p tsconfig.json`. Output lands in `dist/`. The package's `prepack` hook re-runs the build before publishing — manual `pnpm build` is only required when you want to inspect the output or run a freshly-built copy locally.
+Runs TypeScript compilation and builds the portable Rust TAR parser for
+`wasm32-unknown-unknown`. Contributors need Rust (the native crate's declared
+minimum or newer) and `rustup target add wasm32-unknown-unknown`; Alpine's
+packaged toolchain uses `rust-wasm`. `pnpm archive:wasm` rebuilds just the parser.
+The import-free asset lands at `dist/archive-parser.wasm`; source tests and
+compiled consumers both resolve that generated artifact. Run `pnpm build`
+before source tests in a fresh checkout. Do not commit `dist/` or built WASM.
+Consumers receive the asset in the npm package and need no compiler.
+
+Output lands in `dist/`. The package's `prepack` hook re-runs the build before publishing — manual `pnpm build` is only required when you want to inspect the output or run a freshly-built copy locally.
 
 ## Test
 
@@ -59,8 +68,33 @@ pnpm check
 This runs the filesystem boundary checks, build, tests, and package
 tarball/import validation.
 
+### Real TAR producers
+
+After installing the freshly packed root (and optionally its freshly built host
+binding) in a disposable consumer, run:
+
+```bash
+pnpm archive:producer-smoke ./consumer off
+pnpm archive:producer-smoke ./consumer require
+```
+
+This uses a child bound to canonical cwd/device/inode running `/usr/bin/tar -czf - .`
+with unchanged stdout, and npm tar, on synthetic Unicode/newline/long-name files,
+then the installed package API for exact payload hashes and bounded reads.
+It also rejects a valid PAX override attached to an invalid raw UTF-8 field.
+The `require` command must resolve the freshly packed native binding; the
+`off` command uses the installed WASM asset. No live user files are read.
+
 ### Native consumer installs
 
+The CI Node 24 and native jobs also run `node scripts/device-path-proof.mjs off`
+and `node scripts/device-path-proof.mjs require` against the built package.
+This extracts real ZIP files and checks bounded member reads, preserving reserved
+device-like names on POSIX while rejecting them and ignored-space aliases on
+Windows. It also verifies ordinary secret reads and typed device-path rejection
+without replacing filesystem functions. Run after `pnpm build`, and build the
+host binding with `pnpm native:build` before the `require` case.
+
 After `pnpm build` and a fresh `pnpm native:build`, run `pnpm package:smoke`.
 It packs the real root and host binding, then runs root-only npm and the
 declared pnpm version against a disposable loopback registry. The root's exact

package/docs/install.md

@@ -85,7 +85,7 @@ Use the main entry for the common surface, or the focused subpaths when you want
 
 ## Runtime dependencies
 
-`@openclaw/fs-safe` lists `jszip` and `tar` as optional dependencies for JavaScript ZIP/TAR [archive extraction](archive.md). They are loaded lazily; the JavaScript archive fallback requires the corresponding codec and reports a missing-optional-dependency error without it. Public subpaths remain safe to import with all optional dependencies omitted, but imports do not prove native availability.
+`@openclaw/fs-safe` bundles an import-free WASM build of its Rust TAR parser for guarded JavaScript TAR/gzip [archive extraction](archive.md), including installs with optional dependencies omitted. ZIP fallback uses lazily loaded optional `jszip` and reports a missing-dependency error without it. Public subpaths remain safe to import with all optional dependencies omitted, but imports do not prove native availability.
 
 There are no peer dependencies. Exact-version optional packages carry the seven
 native targets and npm-compatible OS, CPU, and Linux libc filters install only

package/docs/native-helper.md

@@ -29,6 +29,11 @@ The equivalent environment variables are `FS_SAFE_NATIVE_MODE` and `OPENCLAW_FS_
 | `off` | Do not load a native package. Use the guarded JavaScript path deterministically. |
 | `require` | Throw `FsSafeError("helper-unavailable")` instead of falling back when an operation needs the native binding and it cannot load. |
 
+TAR/gzip in the guarded JavaScript path uses a bundled, import-free WASM build
+of the same Rust parser used by native. `off` still disables native filesystem
+code; it does not disable this portable parser. ZIP fallback still requires
+optional `jszip`, and zstd/bzip2 remain native-only.
+
 Configure the mode once during startup. Loading is lazy and cached; changing from `auto` to `require` after a failed load changes failure policy but does not repeatedly probe the binary.
 
 [`tempWorkspace()` and its scoped/sync variants](temp.md#private-temp-workspaces)