@openclaw/signal 2026.9.4 → 2026.9.6

package/node_modules/@openclaw/fs-safe/dist/archive-zip-directory.js

@@ -0,0 +1,263 @@
+import { assertArchiveEntryCountWithinLimit, } from "./archive-limits.js";
+import { admitZipNames, zipExtraFields, zipFormat, zipUInt64 } from "./archive-zip-names.js";
+function entryKind(attributes, directory) {
+    const type = (attributes >>> 16) & 0o170000;
+    // High-word symlinks remain links regardless of the creator or directory bits.
+    if (type === 0o120000)
+        return "symlink";
+    if ((attributes & 0x10) || type === 0o040000 || directory)
+        return "directory";
+    // Preserve the native decoder's rejection of unrecognized link-like types.
+    return (type & 0o120000) === 0o120000 ? "other" : "file";
+}
+function* read(offset, length, bound) {
+    if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 || length < 0 || length > bound - offset) {
+        zipFormat("record outside archive bounds");
+    }
+    const bytes = yield { offset, length };
+    if (bytes.length !== length)
+        zipFormat("truncated record");
+    return bytes;
+}
+const END_SIGNATURE = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
+function denseEndOffset(tail) {
+    let found = -1;
+    for (let offset = tail.length - 22; offset >= 0; offset--) {
+        if (tail.readUInt32LE(offset) === 0x06054b50 && offset + 22 + tail.readUInt16LE(offset + 20) === tail.length) {
+            if (found !== -1)
+                zipFormat("ambiguous end records");
+            found = offset;
+        }
+    }
+    if (found < 0)
+        zipFormat("end record missing");
+    return found;
+}
+function endOffset(tail) {
+    let found = -1;
+    let from = 0;
+    // Sparse signatures use native search; dense attacker-controlled markers
+    // retain the bounded byte scan instead of one native call per marker.
+    for (let candidates = 0; candidates < 16; candidates++) {
+        const offset = tail.indexOf(END_SIGNATURE, from);
+        if (offset < 0 || offset > tail.length - 22) {
+            if (found < 0)
+                zipFormat("end record missing");
+            return found;
+        }
+        if (offset + 22 + tail.readUInt16LE(offset + 20) === tail.length) {
+            if (found !== -1)
+                zipFormat("ambiguous end records");
+            found = offset;
+        }
+        from = offset + 1;
+    }
+    return denseEndOffset(tail);
+}
+function* zip64End(locator, locatorAt, size) {
+    const advertised = zipUInt64(locator, 8);
+    // Seek the advertised record, or the fixed ordinary record for a prefixed
+    // archive. Never hunt through payload bytes for a ZIP64 signature.
+    const candidates = new Set([advertised, locatorAt - 56]);
+    let found;
+    for (const at of candidates) {
+        if (at < 0 || at > locatorAt - 56)
+            continue;
+        const record = yield* read(at, 56, size);
+        if (record.readUInt32LE(0) !== 0x06064b50)
+            continue;
+        const bodySize = zipUInt64(record, 4);
+        if (bodySize < 44 || bodySize !== locatorAt - at - 12)
+            continue;
+        if (found)
+            zipFormat("ambiguous ZIP64 end records");
+        found = { at, record };
+    }
+    if (!found)
+        zipFormat("unsupported ZIP64 end record");
+    return found;
+}
+function* layout(size) {
+    const tailStart = Math.max(0, size - 65_557);
+    const tail = yield* read(tailStart, size - tailStart, size);
+    const at = endOffset(tail);
+    const end = tail.subarray(at, at + 22);
+    const physicalEnd = tailStart + at;
+    if (end.readUInt16LE(4) || end.readUInt16LE(6))
+        zipFormat("multi-disk archive");
+    let count = end.readUInt16LE(10);
+    let directorySize = end.readUInt32LE(12);
+    let offset = end.readUInt32LE(16);
+    let directoryEnd = physicalEnd;
+    const wide = count === 0xffff || end.readUInt16LE(8) === 0xffff || directorySize === 0xffffffff || offset === 0xffffffff;
+    if (wide) {
+        const locator = yield* read(physicalEnd - 20, 20, size);
+        if (locator.readUInt32LE(0) !== 0x07064b50 || locator.readUInt32LE(4) || locator.readUInt32LE(16) !== 1) {
+            zipFormat("invalid ZIP64 locator");
+        }
+        const wideEnd = yield* zip64End(locator, physicalEnd - 20, size);
+        directoryEnd = wideEnd.at;
+        const record = wideEnd.record;
+        if (record.readUInt32LE(16) || record.readUInt32LE(20))
+            zipFormat("multi-disk ZIP64 archive");
+        count = zipUInt64(record, 32);
+        directorySize = zipUInt64(record, 40);
+        offset = zipUInt64(record, 48);
+        if (zipUInt64(record, 24) !== count)
+            zipFormat("ZIP64 disk count mismatch");
+        for (const [ordinary, sentinel, value] of [
+            [end.readUInt16LE(8), 0xffff, count], [end.readUInt16LE(10), 0xffff, count],
+            [end.readUInt32LE(12), 0xffffffff, directorySize], [end.readUInt32LE(16), 0xffffffff, offset],
+        ]) {
+            if (ordinary !== sentinel && ordinary !== value)
+                zipFormat("conflicting ZIP64 end values");
+        }
+        const base = directoryEnd - directorySize - offset;
+        if (zipUInt64(locator, 8) !== directoryEnd - base)
+            zipFormat("ZIP64 locator offset mismatch");
+    }
+    else if (end.readUInt16LE(8) !== count)
+        zipFormat("disk count mismatch");
+    const start = directoryEnd - directorySize;
+    const base = start - offset;
+    if (base < 0 || start < 0 || !Number.isSafeInteger(base))
+        zipFormat("invalid central directory offset");
+    return { count, start, end: directoryEnd, base };
+}
+function wideValues(header, extra, central) {
+    let compressed = header.readUInt32LE(central ? 20 : 18);
+    let uncompressed = header.readUInt32LE(central ? 24 : 22);
+    let offset = central ? header.readUInt32LE(42) : 0;
+    let disk = central ? header.readUInt16LE(34) : 0;
+    const field = extra.get(1);
+    if (field?.length === 0)
+        zipFormat("empty ZIP64 extra field");
+    let cursor = 0;
+    const value = () => {
+        if (!field)
+            return zipFormat("ZIP64 extra field missing");
+        const result = zipUInt64(field, cursor);
+        cursor += 8;
+        return result;
+    };
+    const wide = compressed === 0xffffffff || uncompressed === 0xffffffff;
+    if (uncompressed === 0xffffffff)
+        uncompressed = value();
+    if (compressed === 0xffffffff)
+        compressed = value();
+    if (offset === 0xffffffff)
+        offset = value();
+    if (disk === 0xffff) {
+        if (!field || cursor + 4 > field.length)
+            zipFormat("ZIP64 disk field missing");
+        disk = field.readUInt32LE(cursor);
+        cursor += 4;
+    }
+    if (field && cursor !== field.length) {
+        // Some writers repeat both local sizes even when the 32-bit fields fit.
+        if (central || cursor !== 0 || field.length !== 16 ||
+            zipUInt64(field, 0) !== uncompressed || zipUInt64(field, 8) !== compressed) {
+            zipFormat("inconsistent ZIP64 extra field");
+        }
+    }
+    if (disk)
+        zipFormat("multi-disk entry");
+    return { compressed, uncompressed, offset, wide };
+}
+function* descriptorEnd(at, bound, crc, compressed, uncompressed, wide) {
+    const length = wide ? 20 : 12;
+    const bytes = yield* read(at, Math.min(length + 4, bound - at), bound);
+    const matches = [];
+    for (const skip of [0, 4]) {
+        if (skip && (bytes.length < 4 || bytes.readUInt32LE(0) !== 0x08074b50))
+            continue;
+        if (bytes.length < length + skip || bytes.readUInt32LE(skip) !== crc)
+            continue;
+        const c = wide ? zipUInt64(bytes, skip + 4) : bytes.readUInt32LE(skip + 4);
+        const u = wide ? zipUInt64(bytes, skip + 12) : bytes.readUInt32LE(skip + 8);
+        if (c === compressed && u === uncompressed)
+            matches.push(at + length + skip);
+    }
+    if (matches.length !== 1)
+        zipFormat("invalid or ambiguous data descriptor");
+    return matches[0];
+}
+export function* scanZipDirectory(size, limits, onEntry) {
+    const directory = yield* layout(size);
+    assertArchiveEntryCountWithinLimit(directory.count, limits);
+    const seen = new Set();
+    const spans = [];
+    let at = directory.start;
+    let count = 0;
+    while (at < directory.end) {
+        const central = yield* read(at, Math.min(46, directory.end - at), directory.end);
+        if (central.length >= 6 && central.readUInt32LE(0) === 0x05054b50) {
+            // The optional digital signature belongs to the directory size, not its
+            // entry count. It is opaque metadata, not an authenticity guarantee.
+            if (central.readUInt16LE(4) !== directory.end - at - 6)
+                zipFormat("invalid directory signature length");
+            at = directory.end;
+            break;
+        }
+        assertArchiveEntryCountWithinLimit(++count, limits);
+        if (central.length < 46 || central.readUInt32LE(0) !== 0x02014b50)
+            zipFormat("invalid central header");
+        const nameLength = central.readUInt16LE(28);
+        const extraLength = central.readUInt16LE(30);
+        const next = at + 46 + nameLength + extraLength + central.readUInt16LE(32);
+        if (next > directory.end)
+            zipFormat("central record exceeds directory");
+        const names = yield* read(at + 46, nameLength + extraLength, directory.end);
+        const centralName = names.subarray(0, nameLength);
+        const centralExtra = zipExtraFields(names.subarray(nameLength));
+        const values = wideValues(central, centralExtra, true);
+        const flags = central.readUInt16LE(8);
+        if (flags & ~0x080e)
+            zipFormat("unsupported entry flags");
+        const localAt = directory.base + values.offset;
+        if (localAt < directory.base)
+            zipFormat("local offset precedes archive base");
+        const local = yield* read(localAt, 30, directory.start);
+        if (local.readUInt32LE(0) !== 0x04034b50 || local.readUInt16LE(6) !== flags || local.readUInt16LE(8) !== central.readUInt16LE(10)) {
+            zipFormat("local and central framing disagree");
+        }
+        const localNameLength = local.readUInt16LE(26);
+        const localExtraLength = local.readUInt16LE(28);
+        const localNames = yield* read(localAt + 30, localNameLength + localExtraLength, directory.start);
+        const localExtra = zipExtraFields(localNames.subarray(localNameLength));
+        const admittedName = admitZipNames({ central: centralName, local: localNames.subarray(0, localNameLength), flags, centralExtra, localExtra, seen });
+        const localValues = wideValues(local, localExtra, false);
+        const crc = central.readUInt32LE(16);
+        if (!(flags & 8) && (local.readUInt32LE(14) !== crc || localValues.compressed !== values.compressed || localValues.uncompressed !== values.uncompressed)) {
+            zipFormat("local and central sizes or CRC disagree");
+        }
+        if ((flags & 8) && ((local.readUInt32LE(14) !== 0 && local.readUInt32LE(14) !== crc) ||
+            (localValues.compressed !== 0 && localValues.compressed !== values.compressed) ||
+            (localValues.uncompressed !== 0 && localValues.uncompressed !== values.uncompressed))) {
+            zipFormat("data descriptor placeholders disagree");
+        }
+        const dataStart = localAt + 30 + localNameLength + localExtraLength;
+        if (values.compressed > directory.start - dataStart)
+            zipFormat("entry data exceeds local area");
+        let dataEnd = dataStart + values.compressed;
+        if (flags & 8)
+            dataEnd = yield* descriptorEnd(dataEnd, directory.start, crc, values.compressed, values.uncompressed, values.wide || localValues.wide);
+        spans.push({ start: localAt, end: dataEnd });
+        onEntry?.({
+            index: count - 1, creatorSystem: central[5], externalAttributes: central.readUInt32LE(38),
+            size: values.uncompressed, path: admittedName.path, portableKey: admittedName.portableKey,
+            compressedSize: values.compressed, compressionMethod: central.readUInt16LE(10), crc32: crc,
+            portableDirectory: admittedName.portableDirectory,
+            kind: entryKind(central.readUInt32LE(38), admittedName.directory),
+        });
+        at = next;
+    }
+    if (count !== directory.count)
+        zipFormat("physical and declared entry counts disagree");
+    spans.sort((a, b) => a.start - b.start);
+    for (let i = 1; i < spans.length; i++) {
+        if (spans[i].start < spans[i - 1].end)
+            zipFormat("overlapping local entries");
+    }
+    return count;
+}

package/node_modules/@openclaw/fs-safe/dist/archive-zip-entry.d.ts

@@ -0,0 +1,24 @@
+import { type ArchiveEntryModePolicy, type ArchiveEntryKind } from "./archive-plan.js";
+import type { ZipDirectoryEntry } from "./archive-zip-directory.js";
+export type ZipEntry = {
+    name: string;
+    dir: boolean;
+    unixPermissions?: number | null;
+    dosPermissions?: number | null;
+    _data?: {
+        crc32?: number;
+        uncompressedSize?: number;
+    } | PromiseLike<unknown>;
+    nodeStream?: () => NodeJS.ReadableStream;
+    async: (type: "nodebuffer") => Promise<Buffer>;
+};
+/** Internal: register only after the complete decoder/admission association. */
+export declare function registerAdmittedZipEntry(entry: ZipEntry, physical: ZipDirectoryEntry): void;
+export declare function zipEntryIntegrityMetadata(entry: ZipEntry): {
+    crc32?: number;
+    uncompressedSize?: number;
+} | undefined;
+export declare function isZipSymlinkEntry(entry: ZipEntry): boolean;
+export declare function zipEntryKind(entry: ZipEntry): ArchiveEntryKind;
+export declare function zipEntryMode(entry: ZipEntry, policy: ArchiveEntryModePolicy | undefined): number;
+export declare function zipEntryDeclaredSize(entry: ZipEntry): number;

package/node_modules/@openclaw/fs-safe/dist/archive-zip-entry.js

@@ -0,0 +1,42 @@
+import { resolveArchiveEntryMode, } from "./archive-plan.js";
+const admittedMetadata = new WeakMap();
+/** Internal: register only after the complete decoder/admission association. */
+export function registerAdmittedZipEntry(entry, physical) {
+    const mode = physical.creatorSystem === 3 ? physical.externalAttributes >>> 16 : undefined;
+    admittedMetadata.set(entry, { kind: physical.kind, mode, size: physical.size });
+    entry.dir = physical.kind === "directory";
+    // Previously unsupported non-UNIX symlinks must also be recognizable to
+    // public preflight consumers using JSZip's conventional type inspection.
+    entry.unixPermissions = mode ?? (physical.kind === "symlink" ? 0o120000 : null);
+    entry.dosPermissions = physical.creatorSystem === 0 ? physical.externalAttributes & 0x3f : null;
+}
+export function zipEntryIntegrityMetadata(entry) {
+    const data = entry._data;
+    if (!data || "then" in data)
+        return undefined;
+    return data;
+}
+const ZIP_UNIX_FILE_TYPE_MASK = 0o170000;
+const ZIP_UNIX_SYMLINK_TYPE = 0o120000;
+export function isZipSymlinkEntry(entry) {
+    return zipEntryKind(entry) === "symlink";
+}
+export function zipEntryKind(entry) {
+    const metadata = admittedMetadata.get(entry);
+    if (metadata)
+        return metadata.kind;
+    return typeof entry.unixPermissions === "number" &&
+        (entry.unixPermissions & ZIP_UNIX_FILE_TYPE_MASK) === ZIP_UNIX_SYMLINK_TYPE
+        ? "symlink" : entry.dir ? "directory" : "file";
+}
+export function zipEntryMode(entry, policy) {
+    const metadata = admittedMetadata.get(entry);
+    return resolveArchiveEntryMode({
+        kind: entry.dir ? "directory" : "file",
+        archivedMode: metadata ? metadata.mode : entry.unixPermissions,
+        policy,
+    });
+}
+export function zipEntryDeclaredSize(entry) {
+    return admittedMetadata.get(entry)?.size ?? Math.max(0, Math.floor(zipEntryIntegrityMetadata(entry)?.uncompressedSize ?? 0));
+}

package/node_modules/@openclaw/fs-safe/dist/archive-zip-integrity.d.ts

@@ -0,0 +1,4 @@
+import { Transform } from "node:stream";
+import { type ZipEntry } from "./archive-zip-entry.js";
+export declare function normalizeZipIntegrityError(error: unknown): Error;
+export declare function createZipIntegrityTransform(entry: ZipEntry): Transform;

package/node_modules/@openclaw/fs-safe/dist/archive-zip-integrity.js

@@ -0,0 +1,40 @@
+import { Transform } from "node:stream";
+import { ArchiveFormatError } from "./archive-errors.js";
+import { zipEntryIntegrityMetadata, } from "./archive-zip-entry.js";
+import { updateCrc32 } from "./archive-crc32.js";
+export function normalizeZipIntegrityError(error) {
+    if (error instanceof Error &&
+        error.message.includes("uncompressed data size mismatch")) {
+        return new ArchiveFormatError(`invalid ZIP entry data: ${error.message}`, { cause: error });
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
+export function createZipIntegrityTransform(entry) {
+    const metadata = zipEntryIntegrityMetadata(entry);
+    const expectedCrc32 = metadata?.crc32;
+    const expectedSize = metadata?.uncompressedSize;
+    if (typeof expectedCrc32 !== "number" ||
+        !Number.isInteger(expectedCrc32) ||
+        typeof expectedSize !== "number" ||
+        !Number.isSafeInteger(expectedSize) ||
+        expectedSize < 0) {
+        throw new ArchiveFormatError(`zip entry has invalid integrity metadata: ${entry.name}`);
+    }
+    let actualCrc32 = 0;
+    let actualSize = 0;
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            const buffer = chunk instanceof Buffer ? chunk : Buffer.from(chunk);
+            actualCrc32 = updateCrc32(actualCrc32, buffer);
+            actualSize += buffer.byteLength;
+            callback(null, buffer);
+        },
+        flush(callback) {
+            if (actualSize !== expectedSize || actualCrc32 !== (expectedCrc32 >>> 0)) {
+                callback(new ArchiveFormatError(`zip entry integrity check failed: ${entry.name}`));
+                return;
+            }
+            callback();
+        },
+    });
+}

package/node_modules/@openclaw/fs-safe/dist/archive-zip-loader.d.ts

@@ -0,0 +1,8 @@
+import type { ZipDirectoryEntry } from "./archive-zip-directory.js";
+import { type ZipEntry } from "./archive-zip-entry.js";
+export type ZipArchiveWithFiles = {
+    files: Record<string, unknown>;
+};
+export declare function admittedZipEntries(archive: ZipArchiveWithFiles): readonly ZipEntry[];
+/** Internal: the caller has admitted these unchanged bytes and their metadata. */
+export declare function loadAdmittedZipArchive(buffer: Buffer | Uint8Array, admitted: ZipDirectoryEntry[]): Promise<ZipArchiveWithFiles>;

package/node_modules/@openclaw/fs-safe/dist/archive-zip-loader.js

@@ -0,0 +1,147 @@
+import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
+import { validateArchiveEntryPath } from "./archive-entry.js";
+import { registerAdmittedZipEntry } from "./archive-zip-entry.js";
+import { zipPathKey } from "./archive-zip-names.js";
+const orderedEntries = new WeakMap();
+export function admittedZipEntries(archive) {
+    return orderedEntries.get(archive) ?? disagreement();
+}
+function disagreement() {
+    throw new ArchiveFormatError("ZIP decoder disagrees with admitted directory metadata");
+}
+function collision() {
+    throw new ArchiveSecurityError("entry-path", "zip archive contains duplicate or colliding entry names");
+}
+function matchesData(value, physical) {
+    if (!value || typeof value !== "object")
+        return false;
+    const data = value;
+    return Number.isInteger(data.crc32) && data.crc32 >= -0x80000000 && data.crc32 <= 0xffffffff &&
+        (data.crc32 >>> 0) === physical.crc32 && data.uncompressedSize === physical.size &&
+        data.compressedSize === physical.compressedSize && typeof data.getContentWorker === "function" &&
+        data.compression?.magic === String.fromCharCode(physical.compressionMethod & 255, physical.compressionMethod >>> 8);
+}
+/** Internal: the caller has admitted these unchanged bytes and their metadata. */
+export async function loadAdmittedZipArchive(buffer, admitted) {
+    const physicalByPath = new Map();
+    for (const entry of admitted) {
+        if (physicalByPath.has(entry.portableKey))
+            collision();
+        physicalByPath.set(entry.portableKey, entry);
+    }
+    const JSZip = await importOptionalJsZip();
+    const archive = new JSZip();
+    const originalFile = archive.file;
+    const originalDescriptor = Object.getOwnPropertyDescriptor(archive, "file");
+    const inserted = new Map();
+    const remaining = new Map(physicalByPath);
+    // JSZip's fileAdd can misclassify UNIX type bits as directories, rename an
+    // entry, and erase its payload. Intercept only this private instance's load.
+    Object.defineProperty(archive, "file", { configurable: true, writable: true,
+        value: function (...args) {
+            if (args.length === 1)
+                return originalFile.apply(this, args);
+            const [name, data, options] = args;
+            if (this !== archive || args.length !== 3 || typeof name !== "string" || !options || typeof options !== "object")
+                disagreement();
+            validateArchiveEntryPath(name);
+            const key = zipPathKey(name);
+            const physical = remaining.get(key);
+            if (!physical) {
+                if (physicalByPath.has(key))
+                    collision();
+                disagreement();
+            }
+            const fields = options;
+            const unixMode = physical.creatorSystem === 3 ? physical.externalAttributes >>> 16 : null;
+            const dosMode = physical.creatorSystem === 0 ? physical.externalAttributes & 0x3f : null;
+            const decoderDirectory = Boolean(physical.externalAttributes & 0x10) || physical.portableDirectory;
+            if (physical.index !== inserted.size || fields.unixPermissions !== unixMode || fields.dosPermissions !== dosMode ||
+                fields.dir !== decoderDirectory || !matchesData(data, physical))
+                disagreement();
+            const result = originalFile.call(this, name, data, {
+                ...fields, dir: false, unixPermissions: null, dosPermissions: null, createFolders: false,
+            });
+            const entry = archive.files[name];
+            if (!entry || typeof entry !== "object" || inserted.has(entry))
+                disagreement();
+            // fileAdd also substitutes an empty promise for declared-zero contents.
+            // Retain the original decoder object so size/CRC checks still read bytes.
+            entry._data = data;
+            inserted.set(entry, { physical, data });
+            remaining.delete(key);
+            return result;
+        },
+    });
+    try {
+        const loaded = await archive.loadAsync(buffer, { createFolders: false });
+        if (loaded !== archive)
+            disagreement();
+    }
+    catch (error) {
+        if (error instanceof ArchiveFormatError || error instanceof ArchiveSecurityError)
+            throw error;
+        throw new ArchiveFormatError(`invalid ZIP archive: ${error instanceof Error ? error.message : String(error)}`, { cause: error instanceof Error ? error : undefined });
+    }
+    finally {
+        if (originalDescriptor)
+            Object.defineProperty(archive, "file", originalDescriptor);
+        else
+            Reflect.deleteProperty(archive, "file");
+    }
+    const names = Object.keys(archive.files);
+    if (names.length !== admitted.length)
+        collision();
+    const normalized = [];
+    for (const name of names) {
+        validateArchiveEntryPath(name);
+        const entry = archive.files[name];
+        if (!entry || typeof entry.name !== "string")
+            disagreement();
+        validateArchiveEntryPath(entry.name);
+        const insertion = inserted.get(entry);
+        if (!insertion || zipPathKey(name) !== insertion.physical.portableKey || zipPathKey(entry.name) !== insertion.physical.portableKey ||
+            entry.dir !== false || entry.unixPermissions !== null || entry.dosPermissions !== null ||
+            entry._data !== insertion.data || !matchesData(entry._data, insertion.physical))
+            disagreement();
+        normalized[insertion.physical.index] = [name, entry, insertion.physical];
+        inserted.delete(entry);
+    }
+    if (remaining.size || inserted.size)
+        disagreement();
+    const files = Object.create(null);
+    const entries = [];
+    for (const [name, entry, physical] of normalized) {
+        const appendSlash = physical.kind === "directory" && !name.endsWith("/");
+        const normalizedName = appendSlash ? `${name}/` : name;
+        if (Object.hasOwn(files, normalizedName))
+            collision();
+        if (appendSlash) {
+            entry.name = `${entry.name}/`;
+        }
+        files[normalizedName] = entry;
+        registerAdmittedZipEntry(entry, physical);
+        entries.push(entry);
+    }
+    archive.files = files;
+    orderedEntries.set(archive, entries);
+    return archive;
+}
+async function importOptionalJsZip() {
+    try {
+        const module = await import("jszip");
+        const candidate = typeof module === "function" ? module : module.default;
+        if (typeof candidate !== "function" ||
+            typeof candidate.prototype?.file !== "function" ||
+            typeof candidate.prototype?.loadAsync !== "function") {
+            throw new Error('Optional archive dependency "jszip" does not expose its constructor, file(), and loadAsync().');
+        }
+        return candidate;
+    }
+    catch (err) {
+        throw missingOptionalArchiveDependencyError("jszip", err);
+    }
+}
+function missingOptionalArchiveDependencyError(packageName, cause) {
+    return new Error(`Optional archive dependency "${packageName}" is not installed. Install it to use ZIP archive helpers from @openclaw/fs-safe/archive.`, { cause });
+}

package/node_modules/@openclaw/fs-safe/dist/archive-zip-manifest.d.ts

@@ -0,0 +1,4 @@
+import type { NativeArchiveEntry } from "./native-binding.js";
+import type { ZipDirectoryEntry } from "./archive-zip-directory.js";
+/** Associate all native entries with physical admission before exposing any. */
+export declare function validateNativeZipManifest(manifest: NativeArchiveEntry[], admitted: ZipDirectoryEntry[]): void;

package/node_modules/@openclaw/fs-safe/dist/archive-zip-manifest.js

@@ -0,0 +1,22 @@
+import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
+import { stripArchivePath } from "./archive-entry.js";
+/** Associate all native entries with physical admission before exposing any. */
+export function validateNativeZipManifest(manifest, admitted) {
+    if (manifest.length !== admitted.length) {
+        throw new ArchiveSecurityError("entry-path", "zip decoder collapsed entry names");
+    }
+    for (const [ordinal, entry] of manifest.entries()) {
+        const physical = admitted[ordinal];
+        const physicalPath = physical?.path;
+        const pathMatches = physicalPath === undefined || entry.path === physicalPath ||
+            stripArchivePath(entry.path, 0) === stripArchivePath(physicalPath, 0);
+        // Native indices are physical central-directory ordinals. Legacy name
+        // decoding remains native-selected; compare names when admission knows them.
+        if (!physical || physical.index !== ordinal || entry.index !== ordinal ||
+            entry.size !== physical.size || entry.kind !== physical.kind ||
+            !pathMatches ||
+            (physical.creatorSystem === 3 && entry.mode !== physical.externalAttributes >>> 16)) {
+            throw new ArchiveFormatError("ZIP decoder disagrees with admitted directory metadata");
+        }
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/archive-zip-names.d.ts

@@ -0,0 +1,17 @@
+export declare function zipFormat(message: string): never;
+export declare function zipUInt64(bytes: Buffer, offset: number): number;
+export declare function zipExtraFields(bytes: Buffer): Map<number, Buffer>;
+export declare function zipPathKey(name: string): string;
+export declare function admitZipNames(params: {
+    central: Buffer;
+    local: Buffer;
+    flags: number;
+    centralExtra: Map<number, Buffer>;
+    localExtra: Map<number, Buffer>;
+    seen: Set<string>;
+}): {
+    path?: string;
+    portableKey: string;
+    portableDirectory: boolean;
+    directory: boolean;
+};