cursedbelt-server 4.44.1 → 4.45.0

package/dist/server/zipStream.d.ts

@@ -0,0 +1,83 @@
+/**
+ * A streaming ZIP writer — a download of many files as one, built as it is sent.
+ *
+ * Graduated from `apps/music/src/server/zip.ts` (2026-10-15, forge task desk-updates) when desk
+ * needed the same thing for "download this folder": two copies of a hand-rolled format writer
+ * is two places for the next bug. Folders (directory entries) and file dates arrived with it,
+ * because a folder download that loses its empty folders and stamps every file 1980 is not a
+ * backup.
+ *
+ * ── Why this is hand-written rather than a dependency ───────────────────────────────────
+ * Three properties are needed together, and the popular libraries give at most two:
+ *
+ *  · **Store, never deflate.** Pictures, video, audio and `.xlsx` are already compressed.
+ *    Deflating them spends CPU — on a Worker, the scarce thing — to produce a slightly LARGER
+ *    file. Method 0 (store) is the correct encoding for them, and a few kilobytes of notes
+ *    beside them are not worth a second code path.
+ *  · **True streaming.** "Download this folder" can be thousands of files and many gigabytes.
+ *    Nothing is buffered beyond one entry: bytes arrive from the store and leave for the
+ *    browser in the same pass.
+ *  · **ZIP64.** 4 GB is an entirely reachable selection, and the classic format's 32-bit size
+ *    fields wrap silently at that point. A truncated archive that reports success is the worst
+ *    available failure, so ZIP64 is written UNCONDITIONALLY rather than only when a threshold is
+ *    crossed — a conditional format is a format that is only tested on the small path.
+ *
+ * ── Streaming means data descriptors ────────────────────────────────────────────────────
+ * A local file header must state the CRC-32 and the sizes, and none of those are known until
+ * the file's bytes have gone by. The format's answer is general-purpose flag bit 3: write zeros
+ * in the header, and follow the data with a DATA DESCRIPTOR carrying the real values. That is
+ * what makes a single forward pass possible, why this writer never seeks, and so why the
+ * response can be a `ReadableStream` and the server's memory stays flat whatever the size.
+ *
+ * ── The CPU it costs ────────────────────────────────────────────────────────────────────
+ * The CRC-32 is computed over every byte in the isolate: measured 2026-09-22 at ~280 MB of CPU
+ * per second (240 MB in 860 ms). A Worker's default budget is 30 s of CPU per request, so a
+ * caller on a Worker caps what one archive may hold — music at 4 GB / 2,000 files — and says so
+ * BEFORE the download starts, rather than letting the edge cut it off part-way.
+ */
+/** Incremental CRC-32, so it can be fed one chunk at a time as bytes stream past. */
+export declare class Crc32 {
+    private crc;
+    update(bytes: Uint8Array): void;
+    get value(): number;
+}
+/** One member of the archive: a file whose bytes are opened lazily, or a folder. */
+export type ZipEntry = {
+    /** Path inside the archive, `/`-separated. Sanitized by {@link zipStream}. */
+    name: string;
+    /**
+     * Opens the bytes — a stream, or bytes already in hand. Called only when the entry's turn
+     * comes, so a 2,000-file archive does not open 2,000 connections at once. Returning `null`
+     * (or throwing) skips the entry: a file that vanished must not abort the rest.
+     */
+    open: () => Promise<ReadableStream<Uint8Array> | Uint8Array | null>;
+    /** When the file last changed. Omitted: the archive says 1980-01-01, the format's zero. */
+    modified?: Date | string | null;
+    directory?: false;
+} | {
+    /** A folder — written so an EMPTY one survives the round trip. A trailing `/` is added. */
+    name: string;
+    directory: true;
+    modified?: Date | string | null;
+};
+/**
+ * Names inside a zip must not escape the extraction directory, and must not carry characters
+ * Windows refuses. `..` segments and absolute paths are the security half; the character set is
+ * the "it downloaded but won't extract" half. Each segment is capped, so a long name inside a
+ * deep folder keeps its folders.
+ */
+export declare function safeEntryName(name: string, fallback?: string): string;
+/** The MS-DOS date and time a zip header carries — local wall-clock, 2-second resolution, 1980 at the earliest. */
+export declare function dosDateTime(when: Date | string | null | undefined): {
+    date: number;
+    time: number;
+};
+/**
+ * Build the archive as a stream.
+ *
+ * Duplicate file names are disambiguated rather than colliding — two different files that both
+ * want `Notes/Summary.md` produce `Summary.md` and `Summary (2).md`, because a zip with two
+ * identical names extracts as one file, silently losing the other. A duplicate FOLDER is written
+ * once: its files already land in it.
+ */
+export declare function zipStream(entries: Iterable<ZipEntry> | AsyncIterable<ZipEntry>): ReadableStream<Uint8Array>;

package/dist/server/zipStream.js

@@ -0,0 +1,320 @@
+/**
+ * A streaming ZIP writer — a download of many files as one, built as it is sent.
+ *
+ * Graduated from `apps/music/src/server/zip.ts` (2026-10-15, forge task desk-updates) when desk
+ * needed the same thing for "download this folder": two copies of a hand-rolled format writer
+ * is two places for the next bug. Folders (directory entries) and file dates arrived with it,
+ * because a folder download that loses its empty folders and stamps every file 1980 is not a
+ * backup.
+ *
+ * ── Why this is hand-written rather than a dependency ───────────────────────────────────
+ * Three properties are needed together, and the popular libraries give at most two:
+ *
+ *  · **Store, never deflate.** Pictures, video, audio and `.xlsx` are already compressed.
+ *    Deflating them spends CPU — on a Worker, the scarce thing — to produce a slightly LARGER
+ *    file. Method 0 (store) is the correct encoding for them, and a few kilobytes of notes
+ *    beside them are not worth a second code path.
+ *  · **True streaming.** "Download this folder" can be thousands of files and many gigabytes.
+ *    Nothing is buffered beyond one entry: bytes arrive from the store and leave for the
+ *    browser in the same pass.
+ *  · **ZIP64.** 4 GB is an entirely reachable selection, and the classic format's 32-bit size
+ *    fields wrap silently at that point. A truncated archive that reports success is the worst
+ *    available failure, so ZIP64 is written UNCONDITIONALLY rather than only when a threshold is
+ *    crossed — a conditional format is a format that is only tested on the small path.
+ *
+ * ── Streaming means data descriptors ────────────────────────────────────────────────────
+ * A local file header must state the CRC-32 and the sizes, and none of those are known until
+ * the file's bytes have gone by. The format's answer is general-purpose flag bit 3: write zeros
+ * in the header, and follow the data with a DATA DESCRIPTOR carrying the real values. That is
+ * what makes a single forward pass possible, why this writer never seeks, and so why the
+ * response can be a `ReadableStream` and the server's memory stays flat whatever the size.
+ *
+ * ── The CPU it costs ────────────────────────────────────────────────────────────────────
+ * The CRC-32 is computed over every byte in the isolate: measured 2026-09-22 at ~280 MB of CPU
+ * per second (240 MB in 860 ms). A Worker's default budget is 30 s of CPU per request, so a
+ * caller on a Worker caps what one archive may hold — music at 4 GB / 2,000 files — and says so
+ * BEFORE the download starts, rather than letting the edge cut it off part-way.
+ */
+// ── CRC-32 ──────────────────────────────────────────────────────────────────────────────
+/** The standard IEEE 802.3 table, built once. */
+const CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+        let c = i;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[i] = c >>> 0;
+    }
+    return table;
+})();
+/** Incremental CRC-32, so it can be fed one chunk at a time as bytes stream past. */
+export class Crc32 {
+    crc = 0xffffffff;
+    update(bytes) {
+        let crc = this.crc;
+        for (let i = 0; i < bytes.length; i++)
+            crc = CRC_TABLE[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8);
+        this.crc = crc;
+    }
+    get value() {
+        return (this.crc ^ 0xffffffff) >>> 0;
+    }
+}
+// ── Little-endian writing ───────────────────────────────────────────────────────────────
+class ByteWriter {
+    parts = [];
+    u16(n) {
+        const b = new Uint8Array(2);
+        new DataView(b.buffer).setUint16(0, n, true);
+        this.parts.push(b);
+        return this;
+    }
+    u32(n) {
+        const b = new Uint8Array(4);
+        new DataView(b.buffer).setUint32(0, n >>> 0, true);
+        this.parts.push(b);
+        return this;
+    }
+    /** 64-bit, via BigInt — a whole-library download can pass 2^32, and Number would quietly lose precision past 2^53. */
+    u64(n) {
+        const b = new Uint8Array(8);
+        new DataView(b.buffer).setBigUint64(0, BigInt(n), true);
+        this.parts.push(b);
+        return this;
+    }
+    raw(bytes) {
+        this.parts.push(bytes);
+        return this;
+    }
+    done() {
+        const total = this.parts.reduce((n, p) => n + p.length, 0);
+        const out = new Uint8Array(total);
+        let at = 0;
+        for (const part of this.parts) {
+            out.set(part, at);
+            at += part.length;
+        }
+        return out;
+    }
+}
+const encoder = new TextEncoder();
+/** ZIP64 needs version 4.5; bit 3 = sizes/CRC follow in a data descriptor; bit 11 = UTF-8
+ *  names, which every accented and non-Latin file name needs. */
+const VERSION_ZIP64 = 45;
+const FLAG_DATA_DESCRIPTOR = 0x08;
+const FLAG_UTF8 = 0x0800;
+const METHOD_STORE = 0;
+/** MS-DOS directory attribute, in the low byte of the external attributes. */
+const ATTR_DIRECTORY = 0x10;
+/**
+ * Names inside a zip must not escape the extraction directory, and must not carry characters
+ * Windows refuses. `..` segments and absolute paths are the security half; the character set is
+ * the "it downloaded but won't extract" half. Each segment is capped, so a long name inside a
+ * deep folder keeps its folders.
+ */
+export function safeEntryName(name, fallback = "file") {
+    // Control characters (< 0x20) and the set Windows refuses. Filtered by code point rather than
+    // by a regex class, because a literal control character inside a regex is unreadable and the
+    // linter is right to object to it.
+    const FORBIDDEN = new Set(["<", ">", ":", '"', "|", "?", "*"]);
+    const segments = name
+        .split(/[/\\]/)
+        .filter((seg) => seg !== "" && seg !== "." && seg !== "..")
+        .map((seg) => {
+        let out = "";
+        for (const ch of seg)
+            out += ch.codePointAt(0) < 0x20 || FORBIDDEN.has(ch) ? "_" : ch;
+        // Windows also refuses a segment ending in a dot or a space; trimmed rather than replaced.
+        return out.slice(0, 200).replace(/[. ]+$/, "") || fallback;
+    });
+    return segments.join("/") || fallback;
+}
+/** The MS-DOS date and time a zip header carries — local wall-clock, 2-second resolution, 1980 at the earliest. */
+export function dosDateTime(when) {
+    const at = when ? new Date(when) : null;
+    if (!at || Number.isNaN(at.getTime()) || at.getUTCFullYear() < 1980)
+        return { date: (0 << 9) | (1 << 5) | 1, time: 0 };
+    // UTC, not the server's zone: a Worker has none, and the same archive should not depend on where it was built.
+    const year = Math.min(at.getUTCFullYear(), 2107) - 1980;
+    return {
+        date: (year << 9) | ((at.getUTCMonth() + 1) << 5) | at.getUTCDate(),
+        time: (at.getUTCHours() << 11) | (at.getUTCMinutes() << 5) | Math.floor(at.getUTCSeconds() / 2),
+    };
+}
+function asStream(body) {
+    if (!(body instanceof Uint8Array))
+        return body;
+    return new ReadableStream({
+        start(controller) {
+            if (body.byteLength > 0)
+                controller.enqueue(body);
+            controller.close();
+        },
+    });
+}
+/**
+ * Build the archive as a stream.
+ *
+ * Duplicate file names are disambiguated rather than colliding — two different files that both
+ * want `Notes/Summary.md` produce `Summary.md` and `Summary (2).md`, because a zip with two
+ * identical names extracts as one file, silently losing the other. A duplicate FOLDER is written
+ * once: its files already land in it.
+ */
+export function zipStream(entries) {
+    const central = [];
+    let offset = 0n;
+    const used = new Set();
+    const iterator = Symbol.asyncIterator in entries ? entries[Symbol.asyncIterator]() : entries[Symbol.iterator]();
+    return new ReadableStream({
+        async pull(controller) {
+            // One entry per pull keeps backpressure honest: the next file is not opened until the
+            // consumer has taken the previous one.
+            //
+            // 🔴 The loop is not decoration. A `pull` that returns having enqueued NOTHING is not
+            // guaranteed to be called again, so an entry that turns out to be unreadable would stall
+            // the entire archive — the consumer waits forever for bytes that will never come. Skipping
+            // therefore has to continue to the next entry within the SAME pull. (Measured in music:
+            // two tests hung for the full 5 s timeout before this loop existed.)
+            while (true) {
+                const next = await iterator.next();
+                if (next.done)
+                    break;
+                const entry = next.value;
+                const directory = entry.directory === true;
+                let name = safeEntryName(entry.name);
+                if (directory) {
+                    name = `${name}/`;
+                    if (used.has(name))
+                        continue;
+                }
+                else if (used.has(name)) {
+                    const slash = name.lastIndexOf("/");
+                    const dot = name.lastIndexOf(".");
+                    const cut = dot > slash + 1 ? dot : name.length;
+                    const stem = name.slice(0, cut);
+                    const ext = name.slice(cut);
+                    let n = 2;
+                    while (used.has(`${stem} (${n})${ext}`))
+                        n++;
+                    name = `${stem} (${n})${ext}`;
+                }
+                let body = null;
+                if (!directory) {
+                    const opened = await entry.open().catch(() => null);
+                    // A file whose bytes have gone is skipped, not fatal: one missing file must not abort
+                    // a 2,000-file download that is otherwise fine. `continue`, never `return` — see the
+                    // note on the loop above.
+                    if (!opened)
+                        continue;
+                    body = asStream(opened);
+                }
+                used.add(name);
+                const nameBytes = encoder.encode(name);
+                const { date, time } = dosDateTime(entry.modified);
+                // ZIP64 extra field, sizes zeroed — the data descriptor carries the truth.
+                const localExtra = new ByteWriter().u16(0x0001).u16(16).u64(0).u64(0).done();
+                const header = new ByteWriter()
+                    .u32(0x04034b50)
+                    .u16(VERSION_ZIP64)
+                    .u16(FLAG_DATA_DESCRIPTOR | FLAG_UTF8)
+                    .u16(METHOD_STORE)
+                    .u16(time)
+                    .u16(date)
+                    .u32(0) // crc, in the descriptor
+                    .u32(0xffffffff) // compressed size → see ZIP64 extra
+                    .u32(0xffffffff) // uncompressed size → see ZIP64 extra
+                    .u16(nameBytes.length)
+                    .u16(localExtra.length)
+                    .raw(nameBytes)
+                    .raw(localExtra)
+                    .done();
+                controller.enqueue(header);
+                const entryOffset = offset;
+                offset += BigInt(header.length);
+                const crc = new Crc32();
+                let size = 0n;
+                if (body) {
+                    const reader = body.getReader();
+                    while (true) {
+                        const { done, value } = await reader.read();
+                        if (done)
+                            break;
+                        crc.update(value);
+                        size += BigInt(value.length);
+                        controller.enqueue(value);
+                    }
+                }
+                offset += size;
+                // ZIP64 data descriptor: 8-byte sizes, unlike the 4-byte classic form.
+                const descriptor = new ByteWriter().u32(0x08074b50).u32(crc.value).u64(size).u64(size).done();
+                controller.enqueue(descriptor);
+                offset += BigInt(descriptor.length);
+                central.push({ name: nameBytes, crc: crc.value, size, offset: entryOffset, date, time, directory });
+                return;
+            }
+            // Central directory, then the ZIP64 end records, then the classic end record.
+            const start = offset;
+            for (const item of central) {
+                const extra = new ByteWriter().u16(0x0001).u16(24).u64(item.size).u64(item.size).u64(item.offset).done();
+                const record = new ByteWriter()
+                    .u32(0x02014b50)
+                    .u16(VERSION_ZIP64) // version made by (MS-DOS attributes)
+                    .u16(VERSION_ZIP64) // version needed
+                    .u16(FLAG_DATA_DESCRIPTOR | FLAG_UTF8)
+                    .u16(METHOD_STORE)
+                    .u16(item.time)
+                    .u16(item.date)
+                    .u32(item.crc)
+                    .u32(0xffffffff)
+                    .u32(0xffffffff)
+                    .u16(item.name.length)
+                    .u16(extra.length)
+                    .u16(0) // comment length
+                    .u16(0) // disk number
+                    .u16(0) // internal attrs
+                    .u32(item.directory ? ATTR_DIRECTORY : 0) // external attrs
+                    .u32(0xffffffff) // local header offset → ZIP64 extra
+                    .raw(item.name)
+                    .raw(extra)
+                    .done();
+                controller.enqueue(record);
+                offset += BigInt(record.length);
+            }
+            const centralSize = offset - start;
+            const zip64End = new ByteWriter()
+                .u32(0x06064b50)
+                .u64(44) // size of this record, minus its first 12 bytes
+                .u16(VERSION_ZIP64)
+                .u16(VERSION_ZIP64)
+                .u32(0)
+                .u32(0)
+                .u64(central.length)
+                .u64(central.length)
+                .u64(centralSize)
+                .u64(start)
+                .done();
+            controller.enqueue(zip64End);
+            const locator = new ByteWriter()
+                .u32(0x07064b50)
+                .u32(0)
+                .u64(offset) // where the ZIP64 end record starts
+                .u32(1)
+                .done();
+            controller.enqueue(locator);
+            // The classic record still has to be there for every reader to find the archive; its
+            // 0xffff/0xffffffff sentinels say "look at the ZIP64 record instead".
+            const end = new ByteWriter()
+                .u32(0x06054b50)
+                .u16(0)
+                .u16(0)
+                .u16(central.length > 0xffff ? 0xffff : central.length)
+                .u16(central.length > 0xffff ? 0xffff : central.length)
+                .u32(0xffffffff)
+                .u32(0xffffffff)
+                .u16(0)
+                .done();
+            controller.enqueue(end);
+            controller.close();
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.44.1",
+	"version": "4.45.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
@@ -355,6 +355,12 @@
 			"source": "./src/server/youtube/ytdlp.ts",
 			"import": "./dist/server/youtube/ytdlp.js"
 		},
+		"./zip-stream": {
+			"types": "./dist/server/zipStream.d.ts",
+			"bun": "./src/server/zipStream.ts",
+			"source": "./src/server/zipStream.ts",
+			"import": "./dist/server/zipStream.js"
+		},
 		"./ws": {
 			"types": "./dist/server/ws/index.d.ts",
 			"bun": "./src/server/ws/index.ts",

package/src/leafSubpathsImportNothing.spec.ts

@@ -243,6 +243,14 @@ const LEAVES = [
      */
     evaluates: 'createYtDlp',
   },
+  {
+    subpath: './zip-stream',
+    /**
+     * The streaming ZIP64 writer (4.45.0, forge task desk-updates) — out of Music so desk's folder
+     * downloads share it. Both run it on a Worker, so it imports nothing at all.
+     */
+    evaluates: 'zipStream',
+  },
 ] as const;
 
 /**

package/src/server/zipStream.spec.ts

@@ -0,0 +1,264 @@
+/**
+ * The zip writer is hand-rolled (see the file header for why), so it is verified against a REAL
+ * unzip rather than against itself: a self-consistent archive that no extractor accepts is exactly
+ * the failure a hand-rolled format writer produces. Moved here from `apps/music/src/server/zip.test.ts`
+ * with the writer (2026-10-15); the folder and date cases arrived with desk.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdtempSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Crc32, dosDateTime, safeEntryName, type ZipEntry, zipStream } from './zipStream';
+
+const bytesOf = (text: string): Uint8Array => new TextEncoder().encode(text);
+
+const entryFrom = (name: string, body: string): ZipEntry => ({
+  name,
+  open: async () =>
+    new ReadableStream<Uint8Array>({
+      start(controller) {
+        // Two chunks, so the streaming CRC and size accumulation are exercised rather than a
+        // single-chunk fast path that would hide an accumulator bug.
+        const half = Math.ceil(body.length / 2);
+        controller.enqueue(bytesOf(body.slice(0, half)));
+        controller.enqueue(bytesOf(body.slice(half)));
+        controller.close();
+      },
+    }),
+});
+
+const collect = async (stream: ReadableStream<Uint8Array>): Promise<Uint8Array> => new Uint8Array(await new Response(stream).arrayBuffer());
+
+/** Run the system `unzip` over the archive in a throwaway directory. */
+async function unzip(archive: Uint8Array, args: string[]): Promise<{ out: string; dir: string; cleanup: () => void }> {
+  const dir = mkdtempSync(join(tmpdir(), 'cbs-zip-'));
+  const path = join(dir, 'test.zip');
+  writeFileSync(path, archive);
+  const proc = Bun.spawn(['unzip', ...args, path], { cwd: dir, stdout: 'pipe', stderr: 'pipe' });
+  const out = await new Response(proc.stdout).text();
+  await proc.exited;
+  return { out, dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+/** Write the archive out and list it with the system `unzip` — the real test. */
+async function unzipList(archive: Uint8Array): Promise<string> {
+  const run = await unzip(archive, ['-l']);
+  run.cleanup();
+  return run.out;
+}
+
+/** Extract and read one member back, proving the BYTES survive, not just the listing. */
+async function unzipRead(archive: Uint8Array, member: string): Promise<string> {
+  const dir = mkdtempSync(join(tmpdir(), 'cbs-zip-'));
+  const path = join(dir, 'test.zip');
+  writeFileSync(path, archive);
+  const proc = Bun.spawn(['unzip', '-p', path, member], { stdout: 'pipe', stderr: 'pipe' });
+  const out = await new Response(proc.stdout).text();
+  await proc.exited;
+  rmSync(dir, { recursive: true, force: true });
+  return out;
+}
+
+describe("Crc32", () => {
+  test("matches the known IEEE check value for '123456789'", () => {
+    const crc = new Crc32();
+    crc.update(bytesOf("123456789"));
+    expect(crc.value).toBe(0xcbf43926);
+  });
+
+  test("is order-dependent across chunks, i.e. genuinely incremental", () => {
+    const whole = new Crc32();
+    whole.update(bytesOf("hello world"));
+    const split = new Crc32();
+    split.update(bytesOf("hello "));
+    split.update(bytesOf("world"));
+    expect(split.value).toBe(whole.value);
+  });
+});
+
+describe("safeEntryName", () => {
+  test("🔴 strips '..' and absolute paths — an archive must not escape its extract dir", () => {
+    expect(safeEntryName("../../etc/passwd")).toBe("etc/passwd");
+    expect(safeEntryName("/etc/passwd")).toBe("etc/passwd");
+    expect(safeEntryName("a/../../b")).toBe("a/b");
+  });
+
+  test("replaces characters Windows refuses, so the archive extracts everywhere", () => {
+    expect(safeEntryName('a:b"c|d?e*f.mp3')).toBe("a_b_c_d_e_f.mp3");
+  });
+
+  test("never yields an empty name", () => {
+    expect(safeEntryName("")).toBe("file");
+    expect(safeEntryName("../..")).toBe("file");
+    expect(safeEntryName("", "track")).toBe("track");
+  });
+
+  test("keeps ordinary nested paths intact", () => {
+    expect(safeEntryName("In Sides/01 - Belfast.mp3")).toBe("In Sides/01 - Belfast.mp3");
+  });
+});
+
+describe("zipStream", () => {
+  test("produces an archive a real unzip accepts and lists", async () => {
+    const archive = await collect(
+      zipStream([entryFrom("one.mp3", "first body"), entryFrom("two.mp3", "second body")]),
+    );
+    const listing = await unzipList(archive);
+    expect(listing).toContain("one.mp3");
+    expect(listing).toContain("two.mp3");
+    // unzip prints this banner for anything it could not parse.
+    expect(listing).not.toContain("cannot find zipfile directory");
+  });
+
+  test("the extracted BYTES round-trip exactly", async () => {
+    const body = "the quick brown fox jumps over the lazy dog";
+    const archive = await collect(zipStream([entryFrom("song.mp3", body)]));
+    expect(await unzipRead(archive, "song.mp3")).toBe(body);
+  });
+
+  test("🔴 duplicate names are disambiguated, not silently collapsed to one file", async () => {
+    // Two different rips of one song produce the same "Artist - Title.mp3". A zip with
+    // two identical names extracts as ONE file, losing the other without a word.
+    const archive = await collect(
+      zipStream([entryFrom("same.mp3", "copy one"), entryFrom("same.mp3", "copy two")]),
+    );
+    const listing = await unzipList(archive);
+    expect(listing).toContain("same.mp3");
+    expect(listing).toContain("same (2).mp3");
+    expect(await unzipRead(archive, "same.mp3")).toBe("copy one");
+    expect(await unzipRead(archive, "same (2).mp3")).toBe("copy two");
+  });
+
+  test("🔴 a member whose bytes have gone is SKIPPED, not fatal", async () => {
+    // One missing track must not abort a 2,000-file download that is otherwise fine.
+    const archive = await collect(
+      zipStream([
+        entryFrom("good.mp3", "here"),
+        { name: "gone.mp3", open: async () => null },
+        entryFrom("also-good.mp3", "also here"),
+      ]),
+    );
+    const listing = await unzipList(archive);
+    expect(listing).toContain("good.mp3");
+    expect(listing).toContain("also-good.mp3");
+    expect(listing).not.toContain("gone.mp3");
+  });
+
+  test("an entry whose open() THROWS is skipped rather than killing the archive", async () => {
+    const archive = await collect(
+      zipStream([
+        {
+          name: "broken.mp3",
+          open: async () => {
+            throw new Error("upstream said no");
+          },
+        },
+        entryFrom("fine.mp3", "fine"),
+      ]),
+    );
+    expect(await unzipRead(archive, "fine.mp3")).toBe("fine");
+  });
+
+  test("an empty selection still produces a structurally valid (empty) archive", async () => {
+    const archive = await collect(zipStream([]));
+    const listing = await unzipList(archive);
+    expect(listing).not.toContain("cannot find zipfile directory");
+  });
+
+  test("nested paths survive, so a big archive extracts into album folders", async () => {
+    const archive = await collect(zipStream([entryFrom("In Sides/Belfast.mp3", "b")]));
+    expect(await unzipRead(archive, "In Sides/Belfast.mp3")).toBe("b");
+  });
+
+  test("UTF-8 names are stored as UTF-8 bytes with the UTF-8 flag set", async () => {
+    // Asserted on the ARCHIVE, not on `unzip -l`: macOS ships Info-ZIP 6.0, whose
+    // listing mangles non-ASCII for display regardless of what the file contains.
+    // This library has accented and non-Latin titles, so the encoding has to be right.
+    const name = "Björk - Jóga.mp3";
+    const archive = await collect(zipStream([entryFrom(name, "x")]));
+    const encoded = new TextEncoder().encode(name);
+    const found = archive.some((_, i) => encoded.every((b, k) => archive[i + k] === b));
+    expect(found).toBe(true);
+
+    // General-purpose flag bit 11 (0x0800) = "the name is UTF-8". It sits at offset 6
+    // of the local file header, which starts the archive.
+    const flags = archive[6]! | (archive[7]! << 8);
+    expect(flags & 0x0800).toBe(0x0800);
+  });
+
+  test("writes the ZIP64 end-of-central-directory record unconditionally", async () => {
+    // Written for every archive rather than only past 4 GB: a conditional format is a
+    // format that is only ever tested on the small path. 0x06064b50, little-endian.
+    const archive = await collect(zipStream([entryFrom("a.mp3", "a")]));
+    const signature = [0x50, 0x4b, 0x06, 0x06];
+    const found = archive.some((_, i) => signature.every((b, k) => archive[i + k] === b));
+    expect(found).toBe(true);
+  });
+
+  test("streams lazily — a later entry is not opened before an earlier one is consumed", async () => {
+    // This is what keeps a 2,000-file archive from opening 2,000 connections at once.
+    const opened: string[] = [];
+    const lazy = (name: string): ZipEntry => ({
+      name,
+      open: async () => {
+        opened.push(name);
+        return new ReadableStream<Uint8Array>({
+          start(controller) {
+            controller.enqueue(bytesOf("x"));
+            controller.close();
+          },
+        });
+      },
+    });
+    const stream = zipStream([lazy("1.mp3"), lazy("2.mp3"), lazy("3.mp3")]);
+    const reader = stream.getReader();
+    await reader.read();
+    expect(opened).toEqual(["1.mp3"]);
+    await reader.cancel();
+  });
+});
+
+describe('folders and dates (desk)', () => {
+  test('🔴 an EMPTY folder survives extraction — a folder download that drops it is not a backup', async () => {
+    const archive = await collect(zipStream([{ name: 'Project/Empty', directory: true }, entryFrom('Project/a.md', 'a')]));
+    const run = await unzip(archive, ['-o', '-q', '-d', 'out']);
+    try {
+      expect(statSync(join(run.dir, 'out/Project/Empty')).isDirectory()).toBe(true);
+      expect(existsSync(join(run.dir, 'out/Project/a.md'))).toBe(true);
+    } finally {
+      run.cleanup();
+    }
+  });
+
+  test('a folder named twice is written once', async () => {
+    const listing = await unzipList(await collect(zipStream([{ name: 'A', directory: true }, { name: 'A/', directory: true }])));
+    expect(listing.match(/ A\//g)?.length).toBe(1);
+  });
+
+  test("a duplicate inside a dotted folder numbers the FILE, not the folder's dot", async () => {
+    const listing = await unzipList(await collect(zipStream([entryFrom('v1.2/notes', 'a'), entryFrom('v1.2/notes', 'b')])));
+    expect(listing).toContain('v1.2/notes (2)');
+  });
+
+  test('a file keeps its date', async () => {
+    const listing = await unzipList(await collect(zipStream([{ ...entryFrom('dated.txt', 'x'), modified: '2026-10-15T12:34:56Z' }])));
+    expect(listing).toMatch(/10-15-2026\s+12:34/);
+  });
+
+  test('dosDateTime: before 1980 or unreadable is the format zero, never a wrapped year', () => {
+    expect(dosDateTime('1970-01-01T00:00:00Z')).toEqual({ date: 33, time: 0 });
+    expect(dosDateTime('not a date')).toEqual({ date: 33, time: 0 });
+    expect(dosDateTime(null)).toEqual({ date: 33, time: 0 });
+  });
+
+  test('bytes in hand and an async iterable of entries both work', async () => {
+    async function* entries(): AsyncGenerator<ZipEntry> {
+      yield { name: 'inline.txt', open: async () => bytesOf('inline bytes') };
+      yield { name: 'empty.txt', open: async () => new Uint8Array(0) };
+    }
+    const archive = await collect(zipStream(entries()));
+    expect(await unzipRead(archive, 'inline.txt')).toBe('inline bytes');
+    expect(await unzipList(archive)).toContain('empty.txt');
+  });
+});

package/src/server/zipStream.ts

@@ -0,0 +1,372 @@
+/**
+ * A streaming ZIP writer — a download of many files as one, built as it is sent.
+ *
+ * Graduated from `apps/music/src/server/zip.ts` (2026-10-15, forge task desk-updates) when desk
+ * needed the same thing for "download this folder": two copies of a hand-rolled format writer
+ * is two places for the next bug. Folders (directory entries) and file dates arrived with it,
+ * because a folder download that loses its empty folders and stamps every file 1980 is not a
+ * backup.
+ *
+ * ── Why this is hand-written rather than a dependency ───────────────────────────────────
+ * Three properties are needed together, and the popular libraries give at most two:
+ *
+ *  · **Store, never deflate.** Pictures, video, audio and `.xlsx` are already compressed.
+ *    Deflating them spends CPU — on a Worker, the scarce thing — to produce a slightly LARGER
+ *    file. Method 0 (store) is the correct encoding for them, and a few kilobytes of notes
+ *    beside them are not worth a second code path.
+ *  · **True streaming.** "Download this folder" can be thousands of files and many gigabytes.
+ *    Nothing is buffered beyond one entry: bytes arrive from the store and leave for the
+ *    browser in the same pass.
+ *  · **ZIP64.** 4 GB is an entirely reachable selection, and the classic format's 32-bit size
+ *    fields wrap silently at that point. A truncated archive that reports success is the worst
+ *    available failure, so ZIP64 is written UNCONDITIONALLY rather than only when a threshold is
+ *    crossed — a conditional format is a format that is only tested on the small path.
+ *
+ * ── Streaming means data descriptors ────────────────────────────────────────────────────
+ * A local file header must state the CRC-32 and the sizes, and none of those are known until
+ * the file's bytes have gone by. The format's answer is general-purpose flag bit 3: write zeros
+ * in the header, and follow the data with a DATA DESCRIPTOR carrying the real values. That is
+ * what makes a single forward pass possible, why this writer never seeks, and so why the
+ * response can be a `ReadableStream` and the server's memory stays flat whatever the size.
+ *
+ * ── The CPU it costs ────────────────────────────────────────────────────────────────────
+ * The CRC-32 is computed over every byte in the isolate: measured 2026-09-22 at ~280 MB of CPU
+ * per second (240 MB in 860 ms). A Worker's default budget is 30 s of CPU per request, so a
+ * caller on a Worker caps what one archive may hold — music at 4 GB / 2,000 files — and says so
+ * BEFORE the download starts, rather than letting the edge cut it off part-way.
+ */
+
+// ── CRC-32 ──────────────────────────────────────────────────────────────────────────────
+
+/** The standard IEEE 802.3 table, built once. */
+const CRC_TABLE: Uint32Array = (() => {
+  const table = new Uint32Array(256);
+  for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[i] = c >>> 0;
+  }
+  return table;
+})();
+
+/** Incremental CRC-32, so it can be fed one chunk at a time as bytes stream past. */
+export class Crc32 {
+  private crc = 0xffffffff;
+
+  update(bytes: Uint8Array): void {
+    let crc = this.crc;
+    for (let i = 0; i < bytes.length; i++) crc = CRC_TABLE[(crc ^ (bytes[i] as number)) & 0xff]! ^ (crc >>> 8);
+    this.crc = crc;
+  }
+
+  get value(): number {
+    return (this.crc ^ 0xffffffff) >>> 0;
+  }
+}
+
+// ── Little-endian writing ───────────────────────────────────────────────────────────────
+
+class ByteWriter {
+  private parts: Uint8Array[] = [];
+
+  u16(n: number): this {
+    const b = new Uint8Array(2);
+    new DataView(b.buffer).setUint16(0, n, true);
+    this.parts.push(b);
+    return this;
+  }
+
+  u32(n: number): this {
+    const b = new Uint8Array(4);
+    new DataView(b.buffer).setUint32(0, n >>> 0, true);
+    this.parts.push(b);
+    return this;
+  }
+
+  /** 64-bit, via BigInt — a whole-library download can pass 2^32, and Number would quietly lose precision past 2^53. */
+  u64(n: number | bigint): this {
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, BigInt(n), true);
+    this.parts.push(b);
+    return this;
+  }
+
+  raw(bytes: Uint8Array): this {
+    this.parts.push(bytes);
+    return this;
+  }
+
+  done(): Uint8Array {
+    const total = this.parts.reduce((n, p) => n + p.length, 0);
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const part of this.parts) {
+      out.set(part, at);
+      at += part.length;
+    }
+    return out;
+  }
+}
+
+/** One member of the archive: a file whose bytes are opened lazily, or a folder. */
+export type ZipEntry =
+  | {
+      /** Path inside the archive, `/`-separated. Sanitized by {@link zipStream}. */
+      name: string;
+      /**
+       * Opens the bytes — a stream, or bytes already in hand. Called only when the entry's turn
+       * comes, so a 2,000-file archive does not open 2,000 connections at once. Returning `null`
+       * (or throwing) skips the entry: a file that vanished must not abort the rest.
+       */
+      open: () => Promise<ReadableStream<Uint8Array> | Uint8Array | null>;
+      /** When the file last changed. Omitted: the archive says 1980-01-01, the format's zero. */
+      modified?: Date | string | null;
+      directory?: false;
+    }
+  | {
+      /** A folder — written so an EMPTY one survives the round trip. A trailing `/` is added. */
+      name: string;
+      directory: true;
+      modified?: Date | string | null;
+    };
+
+const encoder = new TextEncoder();
+
+/** ZIP64 needs version 4.5; bit 3 = sizes/CRC follow in a data descriptor; bit 11 = UTF-8
+ *  names, which every accented and non-Latin file name needs. */
+const VERSION_ZIP64 = 45;
+const FLAG_DATA_DESCRIPTOR = 0x08;
+const FLAG_UTF8 = 0x0800;
+const METHOD_STORE = 0;
+/** MS-DOS directory attribute, in the low byte of the external attributes. */
+const ATTR_DIRECTORY = 0x10;
+
+/**
+ * Names inside a zip must not escape the extraction directory, and must not carry characters
+ * Windows refuses. `..` segments and absolute paths are the security half; the character set is
+ * the "it downloaded but won't extract" half. Each segment is capped, so a long name inside a
+ * deep folder keeps its folders.
+ */
+export function safeEntryName(name: string, fallback = "file"): string {
+  // Control characters (< 0x20) and the set Windows refuses. Filtered by code point rather than
+  // by a regex class, because a literal control character inside a regex is unreadable and the
+  // linter is right to object to it.
+  const FORBIDDEN = new Set(["<", ">", ":", '"', "|", "?", "*"]);
+  const segments = name
+    .split(/[/\\]/)
+    .filter((seg) => seg !== "" && seg !== "." && seg !== "..")
+    .map((seg) => {
+      let out = "";
+      for (const ch of seg) out += ch.codePointAt(0)! < 0x20 || FORBIDDEN.has(ch) ? "_" : ch;
+      // Windows also refuses a segment ending in a dot or a space; trimmed rather than replaced.
+      return out.slice(0, 200).replace(/[. ]+$/, "") || fallback;
+    });
+  return segments.join("/") || fallback;
+}
+
+/** The MS-DOS date and time a zip header carries — local wall-clock, 2-second resolution, 1980 at the earliest. */
+export function dosDateTime(when: Date | string | null | undefined): { date: number; time: number } {
+  const at = when ? new Date(when) : null;
+  if (!at || Number.isNaN(at.getTime()) || at.getUTCFullYear() < 1980) return { date: (0 << 9) | (1 << 5) | 1, time: 0 };
+  // UTC, not the server's zone: a Worker has none, and the same archive should not depend on where it was built.
+  const year = Math.min(at.getUTCFullYear(), 2107) - 1980;
+  return {
+    date: (year << 9) | ((at.getUTCMonth() + 1) << 5) | at.getUTCDate(),
+    time: (at.getUTCHours() << 11) | (at.getUTCMinutes() << 5) | Math.floor(at.getUTCSeconds() / 2),
+  };
+}
+
+function asStream(body: ReadableStream<Uint8Array> | Uint8Array): ReadableStream<Uint8Array> {
+  if (!(body instanceof Uint8Array)) return body;
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      if (body.byteLength > 0) controller.enqueue(body);
+      controller.close();
+    },
+  });
+}
+
+/**
+ * Build the archive as a stream.
+ *
+ * Duplicate file names are disambiguated rather than colliding — two different files that both
+ * want `Notes/Summary.md` produce `Summary.md` and `Summary (2).md`, because a zip with two
+ * identical names extracts as one file, silently losing the other. A duplicate FOLDER is written
+ * once: its files already land in it.
+ */
+export function zipStream(entries: Iterable<ZipEntry> | AsyncIterable<ZipEntry>): ReadableStream<Uint8Array> {
+  interface Central {
+    name: Uint8Array;
+    crc: number;
+    size: bigint;
+    offset: bigint;
+    date: number;
+    time: number;
+    directory: boolean;
+  }
+
+  const central: Central[] = [];
+  let offset = 0n;
+  const used = new Set<string>();
+  const iterator: AsyncIterator<ZipEntry> | Iterator<ZipEntry> =
+    Symbol.asyncIterator in entries ? (entries as AsyncIterable<ZipEntry>)[Symbol.asyncIterator]() : (entries as Iterable<ZipEntry>)[Symbol.iterator]();
+
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      // One entry per pull keeps backpressure honest: the next file is not opened until the
+      // consumer has taken the previous one.
+      //
+      // 🔴 The loop is not decoration. A `pull` that returns having enqueued NOTHING is not
+      // guaranteed to be called again, so an entry that turns out to be unreadable would stall
+      // the entire archive — the consumer waits forever for bytes that will never come. Skipping
+      // therefore has to continue to the next entry within the SAME pull. (Measured in music:
+      // two tests hung for the full 5 s timeout before this loop existed.)
+      while (true) {
+        const next = await iterator.next();
+        if (next.done) break;
+        const entry = next.value;
+
+        const directory = entry.directory === true;
+        let name = safeEntryName(entry.name);
+        if (directory) {
+          name = `${name}/`;
+          if (used.has(name)) continue;
+        } else if (used.has(name)) {
+          const slash = name.lastIndexOf("/");
+          const dot = name.lastIndexOf(".");
+          const cut = dot > slash + 1 ? dot : name.length;
+          const stem = name.slice(0, cut);
+          const ext = name.slice(cut);
+          let n = 2;
+          while (used.has(`${stem} (${n})${ext}`)) n++;
+          name = `${stem} (${n})${ext}`;
+        }
+
+        let body: ReadableStream<Uint8Array> | null = null;
+        if (!directory) {
+          const opened = await entry.open().catch(() => null);
+          // A file whose bytes have gone is skipped, not fatal: one missing file must not abort
+          // a 2,000-file download that is otherwise fine. `continue`, never `return` — see the
+          // note on the loop above.
+          if (!opened) continue;
+          body = asStream(opened);
+        }
+        used.add(name);
+        const nameBytes = encoder.encode(name);
+        const { date, time } = dosDateTime(entry.modified);
+
+        // ZIP64 extra field, sizes zeroed — the data descriptor carries the truth.
+        const localExtra = new ByteWriter().u16(0x0001).u16(16).u64(0).u64(0).done();
+        const header = new ByteWriter()
+          .u32(0x04034b50)
+          .u16(VERSION_ZIP64)
+          .u16(FLAG_DATA_DESCRIPTOR | FLAG_UTF8)
+          .u16(METHOD_STORE)
+          .u16(time)
+          .u16(date)
+          .u32(0) // crc, in the descriptor
+          .u32(0xffffffff) // compressed size → see ZIP64 extra
+          .u32(0xffffffff) // uncompressed size → see ZIP64 extra
+          .u16(nameBytes.length)
+          .u16(localExtra.length)
+          .raw(nameBytes)
+          .raw(localExtra)
+          .done();
+
+        controller.enqueue(header);
+        const entryOffset = offset;
+        offset += BigInt(header.length);
+
+        const crc = new Crc32();
+        let size = 0n;
+        if (body) {
+          const reader = body.getReader();
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            crc.update(value);
+            size += BigInt(value.length);
+            controller.enqueue(value);
+          }
+        }
+        offset += size;
+
+        // ZIP64 data descriptor: 8-byte sizes, unlike the 4-byte classic form.
+        const descriptor = new ByteWriter().u32(0x08074b50).u32(crc.value).u64(size).u64(size).done();
+        controller.enqueue(descriptor);
+        offset += BigInt(descriptor.length);
+
+        central.push({ name: nameBytes, crc: crc.value, size, offset: entryOffset, date, time, directory });
+        return;
+      }
+
+      // Central directory, then the ZIP64 end records, then the classic end record.
+      const start = offset;
+      for (const item of central) {
+        const extra = new ByteWriter().u16(0x0001).u16(24).u64(item.size).u64(item.size).u64(item.offset).done();
+        const record = new ByteWriter()
+          .u32(0x02014b50)
+          .u16(VERSION_ZIP64) // version made by (MS-DOS attributes)
+          .u16(VERSION_ZIP64) // version needed
+          .u16(FLAG_DATA_DESCRIPTOR | FLAG_UTF8)
+          .u16(METHOD_STORE)
+          .u16(item.time)
+          .u16(item.date)
+          .u32(item.crc)
+          .u32(0xffffffff)
+          .u32(0xffffffff)
+          .u16(item.name.length)
+          .u16(extra.length)
+          .u16(0) // comment length
+          .u16(0) // disk number
+          .u16(0) // internal attrs
+          .u32(item.directory ? ATTR_DIRECTORY : 0) // external attrs
+          .u32(0xffffffff) // local header offset → ZIP64 extra
+          .raw(item.name)
+          .raw(extra)
+          .done();
+        controller.enqueue(record);
+        offset += BigInt(record.length);
+      }
+      const centralSize = offset - start;
+
+      const zip64End = new ByteWriter()
+        .u32(0x06064b50)
+        .u64(44) // size of this record, minus its first 12 bytes
+        .u16(VERSION_ZIP64)
+        .u16(VERSION_ZIP64)
+        .u32(0)
+        .u32(0)
+        .u64(central.length)
+        .u64(central.length)
+        .u64(centralSize)
+        .u64(start)
+        .done();
+      controller.enqueue(zip64End);
+
+      const locator = new ByteWriter()
+        .u32(0x07064b50)
+        .u32(0)
+        .u64(offset) // where the ZIP64 end record starts
+        .u32(1)
+        .done();
+      controller.enqueue(locator);
+
+      // The classic record still has to be there for every reader to find the archive; its
+      // 0xffff/0xffffffff sentinels say "look at the ZIP64 record instead".
+      const end = new ByteWriter()
+        .u32(0x06054b50)
+        .u16(0)
+        .u16(0)
+        .u16(central.length > 0xffff ? 0xffff : central.length)
+        .u16(central.length > 0xffff ? 0xffff : central.length)
+        .u32(0xffffffff)
+        .u32(0xffffffff)
+        .u16(0)
+        .done();
+      controller.enqueue(end);
+
+      controller.close();
+    },
+  });
+}