Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(desktop): make the main process the zip trust boundary (R1-H2, R3-M1, R3-M2, R3-M3, R3-M5)

M6e0be4e4a0ef
diff --git a/desktop-app/src/__tests__/gfsCancellableInvoke.test.ts b/desktop-app/src/__tests__/gfsCancellableInvoke.test.ts
index e4b0fd9aa..661992cee 100644
--- a/desktop-app/src/__tests__/gfsCancellableInvoke.test.ts
+++ b/desktop-app/src/__tests__/gfsCancellableInvoke.test.ts
@@ -4,6 +4,11 @@
* so its behavior is tested directly (no extracted helper): an already-aborted
* signal starts no producer work; a mid-flight abort fires gfs:abort exactly
* once with the invoke's requestId; a signal-less call is a plain invoke.
+ *
+ * R1-M6 — every expectation here BOUNDS its wait. A regression that made the
+ * bridge hang (the pre-R2-L3 behaviour) must fail as an ASSERTION, not as a
+ * test timeout: a timeout says "the test broke", an assertion says "the
+ * behaviour broke".
*/
import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
@@ -42,11 +47,37 @@ type ClerumBridge = {
uri: string,
options?: { maxBytes?: number; signal?: AbortSignal }
) => Promise<unknown>
+ zipStream: {
+ start: () => Promise<{ jobId: string }>
+ appendFromUri: (
+ jobId: string,
+ name: string,
+ uri: string,
+ options?: { maxBytes?: number; signal?: AbortSignal }
+ ) => Promise<unknown>
+ }
}
}
let bridge: ClerumBridge
+/**
+ * Settles a promise within `ms`, reporting a TIMEOUT instead of hanging. The
+ * sentinel is a plain object so the assertion below can name the failure.
+ */
+const TIMEOUT = Symbol('timeout')
+async function settleWithin<T>(promise: Promise<T>, ms = 250): Promise<T | typeof TIMEOUT> {
+ let timer: ReturnType<typeof setTimeout> | undefined
+ const expiry = new Promise<typeof TIMEOUT>(resolve => {
+ timer = setTimeout(() => resolve(TIMEOUT), ms)
+ })
+ try {
+ return await Promise.race([promise.then(value => value), expiry])
+ } finally {
+ if (timer) clearTimeout(timer)
+ }
+}
+
beforeAll(async () => {
await import('../preload.js')
bridge = electron.exposed.get('clerum') as ClerumBridge
@@ -61,12 +92,33 @@ describe('preload cancellable GFS bridge (R2-L3)', () => {
const controller = new AbortController()
controller.abort()
- await expect(
- bridge.gfs.listChildren('folder-1', 'main', undefined, { signal: controller.signal })
- ).rejects.toMatchObject({ name: 'AbortError' })
- await expect(
- bridge.gfs.download('gfs://main/x', { signal: controller.signal })
- ).rejects.toMatchObject({ name: 'AbortError' })
+ // The rejection is awaited WITH A BOUND: against the pre-R2-L3 bridge
+ // this call never settles, and the test must fail with an assertion
+ // ("the bridge did not reject") rather than hang until the runner's
+ // timeout.
+ const listing = await settleWithin(
+ bridge.gfs.listChildren('folder-1', 'main', undefined, { signal: controller.signal }).then(
+ () => ({ settled: 'resolved' as const }),
+ error => ({ settled: 'rejected' as const, error })
+ )
+ )
+ expect(listing).not.toBe(TIMEOUT)
+ expect(listing).toMatchObject({
+ settled: 'rejected',
+ error: { name: 'AbortError' },
+ })
+
+ const download = await settleWithin(
+ bridge.gfs.download('gfs://main/x', { signal: controller.signal }).then(
+ () => ({ settled: 'resolved' as const }),
+ error => ({ settled: 'rejected' as const, error })
+ )
+ )
+ expect(download).not.toBe(TIMEOUT)
+ expect(download).toMatchObject({
+ settled: 'rejected',
+ error: { name: 'AbortError' },
+ })
expect(electron.ipcRenderer.invoke).not.toHaveBeenCalled()
expect(electron.ipcRenderer.send).not.toHaveBeenCalled()
@@ -106,4 +158,53 @@ describe('preload cancellable GFS bridge (R2-L3)', () => {
requestId: undefined,
})
})
+
+ it('cancels the folder-zip transfer through the same requestId channel (R1-H2)', async () => {
+ // The zip transfer runs in the MAIN process, so the walk's stop has to
+ // reach it: the preload attaches the requestId and fires gfs:abort.
+ const controller = new AbortController()
+ const pending = bridge.gfs.zipStream.appendFromUri('job-1', 'a/b.txt', 'gfs://main/b', {
+ maxBytes: 1024,
+ signal: controller.signal,
+ })
+ pending.catch(() => undefined)
+
+ expect(electron.ipcRenderer.invoke).toHaveBeenCalledTimes(1)
+ const [channel, payload] = electron.ipcRenderer.invoke.mock.calls[0] as [
+ string,
+ { jobId: string; name: string; uri: string; maxBytes?: number; requestId?: string },
+ ]
+ expect(channel).toBe('gfs:zipStream:appendFromUri')
+ expect(payload.jobId).toBe('job-1')
+ expect(payload.name).toBe('a/b.txt')
+ expect(payload.uri).toBe('gfs://main/b')
+ expect(payload.maxBytes).toBe(1024)
+ expect(typeof payload.requestId).toBe('string')
+
+ controller.abort()
+ expect(electron.ipcRenderer.send).toHaveBeenCalledTimes(1)
+ expect(electron.ipcRenderer.send).toHaveBeenCalledWith('gfs:abort', {
+ requestId: payload.requestId,
+ })
+ })
+
+ it('starts no IPC work for an already-aborted zip transfer (R2-L3)', async () => {
+ const controller = new AbortController()
+ controller.abort()
+ const outcome = await settleWithin(
+ bridge.gfs.zipStream
+ .appendFromUri('job-1', 'a/b.txt', 'gfs://main/b', { signal: controller.signal })
+ .then(
+ () => ({ settled: 'resolved' as const }),
+ error => ({ settled: 'rejected' as const, error })
+ )
+ )
+ expect(outcome).not.toBe(TIMEOUT)
+ expect(outcome).toMatchObject({
+ settled: 'rejected',
+ error: { name: 'AbortError' },
+ })
+ expect(electron.ipcRenderer.invoke).not.toHaveBeenCalled()
+ expect(electron.ipcRenderer.send).not.toHaveBeenCalled()
+ })
})
diff --git a/desktop-app/src/__tests__/gfsZipStream.test.ts b/desktop-app/src/__tests__/gfsZipStream.test.ts
index 98027bd75..ea02a5805 100644
--- a/desktop-app/src/__tests__/gfsZipStream.test.ts
+++ b/desktop-app/src/__tests__/gfsZipStream.test.ts
@@ -1,46 +1,95 @@
/**
- * R1-H2 — the streamed, file-backed zip assembly. These tests run the REAL
- * writer against real temp files and verify the SAVED ARCHIVE with an
- * independent reader (walking the central directory the same way an extractor
- * does), not by re-reading the writer's own inputs.
+ * The main-process ZIP writer (R1-H2, R3-M1, R3-M2, R3-M3, R3-M5).
+ *
+ * These tests run the REAL writer against real temp files and verify the
+ * SAVED ARCHIVE with an independent extractor, not by re-reading the writer's
+ * own inputs. They also pin the guarantees the MAIN process owns, because the
+ * renderer is untrusted: path safety, the resource limits, job ownership, and
+ * the cleanup of every unsuccessful path.
*/
import { afterEach, describe, expect, it, vi } from 'vitest'
-import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdtemp, readFile, readdir, rm, stat } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
+import { promisify } from 'node:util'
+import { ZIP32_MAX_ENTRIES, ZIP_MAX_ENTRIES, ZIP_MAX_TOTAL_BYTES } from '../gfs/zipLimits.js'
import type { ZipStreamDeps } from '../gfs/zipStream.js'
import {
+ MAX_ACTIVE_ZIP_JOBS,
+ MAX_ACTIVE_ZIP_JOBS_PER_OWNER,
+ ZipStreamLimitError,
+ ZipStreamNameError,
+ ZipStreamNameTooLongError,
abortZipJob,
activeZipJobCount,
appendZipEntry,
+ appendZipEntryStreaming,
+ crc32,
finishZipJob,
startZipJob,
} from '../gfs/zipStream.js'
+const execFileAsync = promisify(execFile)
+
+const OWNER = 'window-1'
+const OTHER_OWNER = 'window-2'
+
const savedFiles: string[] = []
const tempRoots: string[] = []
+/** Every job this file opened, so the module never leaks one into the next test. */
+const openJobs: Array<{ jobId: string; owner: string; deps: ZipStreamDeps }> = []
async function makeDeps(
savePath: string,
- options: { cancelDialog?: boolean; failRename?: boolean } = {}
+ options: {
+ cancelDialog?: boolean
+ failRename?: boolean
+ failCopy?: boolean
+ failDialog?: boolean
+ openFile?: ZipStreamDeps['openFile']
+ } = {}
): Promise<ZipStreamDeps & { tempDir: string }> {
const tempDir = await mkdtemp(join(tmpdir(), 'evenfire-zip-test-'))
tempRoots.push(tempDir)
return {
tempDir,
- showSaveDialog: vi.fn(async () => ({
- canceled: Boolean(options.cancelDialog),
- filePath: options.cancelDialog ? undefined : savePath,
- })),
+ openFile: options.openFile,
+ showSaveDialog: vi.fn(async () => {
+ if (options.failDialog) throw new Error('save dialog failed')
+ return {
+ canceled: Boolean(options.cancelDialog),
+ filePath: options.cancelDialog ? undefined : savePath,
+ }
+ }),
renameFile: options.failRename
? async () => {
throw new Error('EXDEV: cross-device link not permitted')
}
: undefined,
+ copyFile: options.failCopy
+ ? async () => {
+ throw new Error('copy failed')
+ }
+ : undefined,
}
}
+/** Opens a job and remembers it, so `afterEach` can always clean it up. */
+async function openJob(owner: string, deps: ZipStreamDeps): Promise<string> {
+ const jobId = await startZipJob(owner, deps)
+ openJobs.push({ jobId, owner, deps })
+ openedJobCount += 1
+ return jobId
+}
+
+let openedJobCount = 0
+
afterEach(async () => {
+ for (const job of openJobs.splice(0)) {
+ await abortZipJob(job.jobId, job.owner, job.deps).catch(() => undefined)
+ }
for (const dir of tempRoots.splice(0)) await rm(dir, { recursive: true, force: true })
})
@@ -84,18 +133,51 @@ function contentBytes(text: string): ArrayBuffer {
return new TextEncoder().encode(text).buffer as ArrayBuffer
}
-describe('gfs zipStream (R1-H2)', () => {
+/** The temp file the writer created for `jobId` (one per job, by design). */
+async function tempFilesIn(dir: string): Promise<string[]> {
+ return (await readdir(dir)).filter(name => name.endsWith('.part'))
+}
+
+/**
+ * Extract the archive with the SYSTEM unzip — a genuinely independent
+ * extractor, not our own reader. Skipped when the binary is unavailable.
+ */
+async function extractWithSystemUnzip(archivePath: string): Promise<Record<string, string> | null> {
+ try {
+ await execFileAsync('unzip', ['-v'])
+ } catch {
+ return null
+ }
+ const target = await mkdtemp(join(tmpdir(), 'evenfire-unzip-'))
+ tempRoots.push(target)
+ await execFileAsync('unzip', ['-o', '-q', archivePath, '-d', target])
+ const out: Record<string, string> = {}
+ const walk = async (dir: string, prefix: string) => {
+ for (const name of await readdir(dir)) {
+ const full = join(dir, name)
+ const info = await stat(full)
+ if (info.isDirectory()) await walk(full, `${prefix}${name}/`)
+ else out[`${prefix}${name}`] = (await readFile(full)).toString('utf8')
+ }
+ }
+ await walk(target, '')
+ return out
+}
+
+describe('gfs zipStream — archive assembly (R1-H2)', () => {
it('assembles a file-backed archive that an independent reader verifies', async () => {
const savePath = join(tmpdir(), `saved-${Date.now()}.zip`)
savedFiles.push(savePath)
const deps = await makeDeps(savePath)
- const jobId = await startZipJob(deps)
+ const jobId = await openJob(OWNER, deps)
- expect(await appendZipEntry(jobId, 'Docs/a.txt', contentBytes('alpha'))).toBe('Docs/a.txt')
- expect(await appendZipEntry(jobId, 'Docs/b.bin', contentBytes('\u00ff\u00fe'))).toBe(
+ expect(await appendZipEntry(jobId, OWNER, 'Docs/a.txt', contentBytes('alpha'))).toBe(
+ 'Docs/a.txt'
+ )
+ expect(await appendZipEntry(jobId, OWNER, 'Docs/b.bin', contentBytes('\u00ff\u00fe'))).toBe(
'Docs/b.bin'
)
- const result = await finishZipJob(jobId, 'Docs.zip', deps)
+ const result = await finishZipJob(jobId, OWNER, 'Docs.zip', deps)
expect(result.saved).toBe(true)
expect(result.entryCount).toBe(2)
@@ -109,55 +191,379 @@ describe('gfs zipStream (R1-H2)', () => {
expect(decoder.decode(entries[0]!.bytes)).toBe('alpha')
expect(entries[1]!.bytes).toEqual(new Uint8Array([0xc3, 0xbf, 0xc3, 0xbe]))
// The stored CRC fields match the payload CRC-32 an extractor recomputes.
- const { crc32 } = await import('../gfs/zipStream.js')
for (const entry of entries) expect(entry.crc).toBe(crc32(entry.bytes))
})
- it('suffixes case-insensitive collisions in the written file (R1-L1 through the real writer)', async () => {
- const savePath = join(tmpdir(), `collide-${Date.now()}.zip`)
+ it('extracts cleanly with an INDEPENDENT extractor (R3-M5)', async () => {
+ const savePath = join(tmpdir(), `independent-${Date.now()}.zip`)
+ savedFiles.push(savePath)
+ const deps = await makeDeps(savePath)
+ const jobId = await openJob(OWNER, deps)
+
+ // A file whose name collides with a directory component, case-insensitively.
+ await appendZipEntry(jobId, OWNER, 'Report/child.txt', contentBytes('child'))
+ await appendZipEntry(jobId, OWNER, 'report', contentBytes('sibling'))
+ await appendZipEntry(jobId, OWNER, 'Report/other.txt', contentBytes('other'))
+ await finishZipJob(jobId, OWNER, 'Independent.zip', deps)
+
+ const extracted = await extractWithSystemUnzip(savePath)
+ if (!extracted) return // no system extractor on this machine
+ // Every entry landed on its own path: the sibling FILE was renamed away
+ // from the directory's name, so nothing was overwritten.
+ expect(Object.keys(extracted).sort()).toEqual(
+ ['Report/child.txt', 'Report/other.txt', 'report (2)'].sort()
+ )
+ expect(extracted['Report/child.txt']).toBe('child')
+ expect(extracted['Report/other.txt']).toBe('other')
+ expect(extracted['report (2)']).toBe('sibling')
+ })
+})
+
+describe('gfs zipStream — streamed payload (R1-H2)', () => {
+ it('writes a chunked payload with the CRC an extractor recomputes', async () => {
+ const savePath = join(tmpdir(), `chunked-${Date.now()}.zip`)
savedFiles.push(savePath)
const deps = await makeDeps(savePath)
- const jobId = await startZipJob(deps)
- await appendZipEntry(jobId, 'Report.txt', contentBytes('upper'))
- await appendZipEntry(jobId, 'report.txt', contentBytes('lower'))
+ const jobId = await openJob(OWNER, deps)
+
+ const chunks = ['one-', 'two-', 'three'].map(part => new TextEncoder().encode(part))
+ const result = await appendZipEntryStreaming(jobId, OWNER, 'big.bin', async sink => {
+ for (const chunk of chunks) await sink.write(chunk)
+ })
+ expect(result).toEqual({ name: 'big.bin', bytes: 13 })
+ await finishZipJob(jobId, OWNER, 'Chunked.zip', deps)
- await finishZipJob(jobId, 'Collide.zip', deps)
const { entries } = readZipArchive(new Uint8Array(await readFile(savePath)))
- expect(entries.map(entry => entry.name)).toEqual(['Report.txt', 'report (2).txt'])
- const decoder = new TextDecoder()
- expect(entries.map(entry => decoder.decode(entry.bytes))).toEqual(['upper', 'lower'])
+ expect(entries).toHaveLength(1)
+ expect(new TextDecoder().decode(entries[0]!.bytes)).toBe('one-two-three')
+ expect(entries[0]!.crc).toBe(crc32(entries[0]!.bytes))
})
- it('rejects an entry whose FINAL name cannot fit the 16-bit fields, before writing (R1-M2)', async () => {
+ it('never materializes a large payload as one buffer (R1-H2)', async () => {
+ // The near-limit memory claim: a payload is written CHUNK BY CHUNK, so
+ // the writer's peak payload allocation is one chunk, not the file. The
+ // observable witness is the chunk count and the largest chunk seen.
+ const savePath = join(tmpdir(), `large-${Date.now()}.zip`)
+ savedFiles.push(savePath)
+ const deps = await makeDeps(savePath)
+ const jobId = await openJob(OWNER, deps)
+
+ const chunkSize = 64 * 1024
+ const chunkCount = 16
+ let largestChunk = 0
+ let chunksSeen = 0
+ const result = await appendZipEntryStreaming(jobId, OWNER, 'large.bin', async sink => {
+ for (let index = 0; index < chunkCount; index += 1) {
+ const chunk = new Uint8Array(chunkSize).fill(index % 251)
+ largestChunk = Math.max(largestChunk, chunk.byteLength)
+ chunksSeen += 1
+ await sink.write(chunk)
+ }
+ })
+ expect(chunksSeen).toBe(chunkCount)
+ expect(largestChunk).toBe(chunkSize)
+ expect(result.bytes).toBe(chunkSize * chunkCount)
+
+ await finishZipJob(jobId, OWNER, 'Large.zip', deps)
+ const { entries } = readZipArchive(new Uint8Array(await readFile(savePath)))
+ expect(entries).toHaveLength(1)
+ expect(entries[0]!.bytes.length).toBe(chunkSize * chunkCount)
+ // The CRC an extractor recomputes matches the streamed one.
+ expect(entries[0]!.crc).toBe(crc32(entries[0]!.bytes))
+ })
+
+ it('keeps the archive valid after a failed entry and serves the next one', async () => {
+ const savePath = join(tmpdir(), `rollback-${Date.now()}.zip`)
+ savedFiles.push(savePath)
+ const deps = await makeDeps(savePath)
+ const jobId = await openJob(OWNER, deps)
+
+ await appendZipEntry(jobId, OWNER, 'first.txt', contentBytes('first'))
+ await expect(
+ appendZipEntryStreaming(jobId, OWNER, 'doomed.bin', async sink => {
+ await sink.write(new TextEncoder().encode('partial'))
+ throw new Error('producer failed mid-stream')
+ })
+ ).rejects.toThrow(/producer failed/)
+
+ // The half-written entry was rolled back: the next entry still lands, and
+ // the archive contains no trace of the failed one.
+ await appendZipEntry(jobId, OWNER, 'second.txt', contentBytes('second'))
+ await finishZipJob(jobId, OWNER, 'Rollback.zip', deps)
+
+ const { entries } = readZipArchive(new Uint8Array(await readFile(savePath)))
+ expect(entries.map(entry => entry.name)).toEqual(['first.txt', 'second.txt'])
+ expect(new TextDecoder().decode(entries[1]!.bytes)).toBe('second')
+ })
+})
+
+describe('gfs zipStream — path safety (R3-M1)', () => {
+ const unsafeNames = [
+ '../outside.txt',
+ 'Docs/../../outside.txt',
+ '/rooted.txt',
+ 'C:\\Windows\\system32.txt',
+ 'C:/Windows/system32.txt',
+ 'Docs\\win.txt',
+ 'Docs//empty.txt',
+ 'Docs/./same.txt',
+ 'Docs/trailing.',
+ 'Docs/trailing ',
+ 'Docs/NUL',
+ 'Docs/con.txt',
+ 'Docs/LPT9',
+ 'Docs/quote".txt',
+ 'Docs/pipe|.txt',
+ 'Docs/colon:.txt',
+ 'Docs/ctrl\u0001.txt',
+ ]
+
+ it.each(unsafeNames)('refuses %j before writing any entry data', async name => {
+ const savePath = join(tmpdir(), `unsafe-${Date.now()}.zip`)
+ savedFiles.push(savePath)
+ const deps = await makeDeps(savePath)
+ const jobId = await openJob(OWNER, deps)
+
+ await expect(appendZipEntry(jobId, OWNER, name, contentBytes('x'))).rejects.toBeInstanceOf(
+ ZipStreamNameError
+ )
+
+ // Nothing was written: the archive is still empty and the job is intact.
+ const tempFiles = await tempFilesIn(deps.tempDir!)
+ expect(tempFiles).toHaveLength(1)
+ expect((await stat(join(deps.tempDir!, tempFiles[0]!))).size).toBe(0)
+ // The rejected name was not reserved: a legal name still gets its own path.
+ expect(await appendZipEntry(jobId, OWNER, 'safe.txt', contentBytes('safe'))).toBe('safe.txt')
+ await abortZipJob(jobId, OWNER, deps)
+ })
+
+ it('refuses a name whose finalized form does not fit the 16-bit fields', async () => {
const deps = await makeDeps(join(tmpdir(), 'unused.zip'))
- const jobId = await startZipJob(deps)
+ const jobId = await openJob(OWNER, deps)
const nearLimit = `${'a'.repeat(65530)}.txt`
- // The pre-collision name fits exactly; a colliding second copy must not
- // push a suffixed name past the field — the writer refuses the header.
- await appendZipEntry(jobId, nearLimit, contentBytes('one'))
- await expect(appendZipEntry(jobId, nearLimit, contentBytes('two'))).rejects.toThrow(
- /not representable in a ZIP header/i
+ await appendZipEntry(jobId, OWNER, nearLimit, contentBytes('one'))
+ await expect(
+ appendZipEntry(jobId, OWNER, nearLimit, contentBytes('two'))
+ ).rejects.toBeInstanceOf(ZipStreamNameTooLongError)
+ await abortZipJob(jobId, OWNER, deps)
+ })
+})
+
+describe('gfs zipStream — resource limits (R3-M2)', () => {
+ it('rejects an over-budget entry without changing the file or the job', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'unused.zip'))
+ deps.limits = { maxTotalBytes: 1024 }
+ const jobId = await openJob(OWNER, deps)
+
+ await appendZipEntry(jobId, OWNER, 'small.txt', contentBytes('small'))
+ const tempFiles = await tempFilesIn(deps.tempDir!)
+ const tempPath = join(deps.tempDir!, tempFiles[0]!)
+ const sizeBefore = (await stat(tempPath)).size
+
+ // The aggregate ceiling is enforced in MAIN: a renderer that keeps
+ // appending past the budget is refused, and the refusal changes nothing.
+ await expect(
+ appendZipEntry(jobId, OWNER, 'too-big.bin', new ArrayBuffer(2048))
+ ).rejects.toBeInstanceOf(ZipStreamLimitError)
+
+ // The archive on disk and the job's own state are untouched.
+ expect((await stat(tempPath)).size).toBe(sizeBefore)
+ const result = await finishZipJob(jobId, OWNER, 'Limited.zip', deps)
+ expect(result.entryCount).toBe(1)
+ })
+
+ it('rejects an over-budget STREAMED entry and rolls the half-written entry back', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'unused.zip'))
+ deps.limits = { maxTotalBytes: 1024 }
+ const jobId = await openJob(OWNER, deps)
+
+ await appendZipEntry(jobId, OWNER, 'small.txt', contentBytes('small'))
+ const tempFiles = await tempFilesIn(deps.tempDir!)
+ const tempPath = join(deps.tempDir!, tempFiles[0]!)
+ const sizeBefore = (await stat(tempPath)).size
+
+ await expect(
+ appendZipEntryStreaming(jobId, OWNER, 'stream.bin', async sink => {
+ await sink.write(new Uint8Array(512))
+ await sink.write(new Uint8Array(1024))
+ })
+ ).rejects.toBeInstanceOf(ZipStreamLimitError)
+
+ // The half-written entry was rolled back: the archive still holds exactly
+ // the one complete entry.
+ expect((await stat(tempPath)).size).toBe(sizeBefore)
+ const result = await finishZipJob(jobId, OWNER, 'Limited.zip', deps)
+ expect(result.entryCount).toBe(1)
+ })
+
+ it('enforces the entry-count ceiling', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'unused.zip'))
+ deps.limits = { maxEntries: 2 }
+ const jobId = await openJob(OWNER, deps)
+
+ await appendZipEntry(jobId, OWNER, 'one.txt', contentBytes('1'))
+ await appendZipEntry(jobId, OWNER, 'two.txt', contentBytes('2'))
+ await expect(
+ appendZipEntry(jobId, OWNER, 'three.txt', contentBytes('3'))
+ ).rejects.toBeInstanceOf(ZipStreamLimitError)
+
+ const result = await finishZipJob(jobId, OWNER, 'Counted.zip', deps)
+ expect(result.entryCount).toBe(2)
+ })
+
+ it('keeps the ZIP32 format ceilings in force', () => {
+ // The format bounds are not configurable: they are what a ZIP32 reader
+ // can address.
+ expect(ZIP32_MAX_ENTRIES).toBe(65535)
+ expect(ZIP_MAX_TOTAL_BYTES).toBe(512 * 1024 * 1024)
+ expect(ZIP_MAX_ENTRIES).toBe(2000)
+ })
+
+ it('refuses a second job from the same window beyond the concurrency bound', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'unused.zip'))
+ const first = await openJob(OWNER, deps)
+ const second = await openJob(OWNER, deps)
+ await expect(startZipJob(OWNER, deps)).rejects.toBeInstanceOf(ZipStreamLimitError)
+ expect(MAX_ACTIVE_ZIP_JOBS_PER_OWNER).toBe(2)
+ await abortZipJob(first, OWNER, deps)
+ await abortZipJob(second, OWNER, deps)
+ })
+
+ it('binds a job to the window that opened it', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'unused.zip'))
+ const jobId = await openJob(OWNER, deps)
+
+ await expect(
+ appendZipEntry(jobId, OTHER_OWNER, 'stolen.txt', contentBytes('x'))
+ ).rejects.toThrow(/belongs to another window/)
+ await expect(finishZipJob(jobId, OTHER_OWNER, 'Stolen.zip', deps)).rejects.toThrow(
+ /belongs to another window/
)
- await abortZipJob(jobId, deps)
+ await expect(abortZipJob(jobId, OTHER_OWNER, deps)).rejects.toThrow(/belongs to another window/)
+ // The rightful owner can still use it.
+ expect(await appendZipEntry(jobId, OWNER, 'mine.txt', contentBytes('x'))).toBe('mine.txt')
+ await abortZipJob(jobId, OWNER, deps)
+ })
+
+ it('bounds the concurrent appends one job may hold', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'unused.zip'))
+ const jobId = await openJob(OWNER, deps)
+
+ const inFlight: Array<Promise<unknown>> = []
+ for (let index = 0; index < 4; index += 1) {
+ inFlight.push(
+ appendZipEntryStreaming(jobId, OWNER, `entry-${index}.bin`, async sink => {
+ await sink.write(new TextEncoder().encode(`payload-${index}`))
+ })
+ )
+ }
+ await expect(
+ appendZipEntryStreaming(jobId, OWNER, 'entry-4.bin', async sink => {
+ await sink.write(new TextEncoder().encode('overflow'))
+ })
+ ).rejects.toBeInstanceOf(ZipStreamLimitError)
+ await Promise.all(inFlight)
+ await abortZipJob(jobId, OWNER, deps)
})
+})
- it('deletes the temp file when the save dialog is canceled', async () => {
+describe('gfs zipStream — cleanup ownership (R3-M3)', () => {
+ it('removes the temp file when the save dialog is canceled', async () => {
const deps = await makeDeps('', { cancelDialog: true })
- const jobId = await startZipJob(deps)
- await appendZipEntry(jobId, 'x.txt', contentBytes('x'))
- const result = await finishZipJob(jobId, 'Canceled.zip', deps)
+ const jobId = await openJob(OWNER, deps)
+ await appendZipEntry(jobId, OWNER, 'x.txt', contentBytes('x'))
+ const result = await finishZipJob(jobId, OWNER, 'Canceled.zip', deps)
expect(result.saved).toBe(false)
expect(result.filePath).toBeNull()
expect(activeZipJobCount()).toBe(0)
+ expect(await tempFilesIn(deps.tempDir!)).toHaveLength(0)
+ })
+
+ it('removes the temp file when the save dialog itself fails', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'unused.zip'), { failDialog: true })
+ const jobId = await openJob(OWNER, deps)
+ await appendZipEntry(jobId, OWNER, 'x.txt', contentBytes('x'))
+
+ await expect(finishZipJob(jobId, OWNER, 'Broken.zip', deps)).rejects.toThrow(
+ /save dialog failed/
+ )
+ expect(activeZipJobCount()).toBe(0)
+ expect(await tempFilesIn(deps.tempDir!)).toHaveLength(0)
+ })
+
+ it('removes the temp file when the final rename AND the copy fallback fail', async () => {
+ const deps = await makeDeps(join(tmpdir(), 'unused.zip'), {
+ failRename: true,
+ failCopy: true,
+ })
+ const jobId = await openJob(OWNER, deps)
+ await appendZipEntry(jobId, OWNER, 'x.txt', contentBytes('x'))
+
+ await expect(finishZipJob(jobId, OWNER, 'Broken.zip', deps)).rejects.toThrow(/copy failed/)
+ expect(activeZipJobCount()).toBe(0)
+ expect(await tempFilesIn(deps.tempDir!)).toHaveLength(0)
+ })
+
+ it('rolls a failed entry back and KEEPS the job owned, so an abort still cleans up', async () => {
+ // The cleanup ownership must survive a failed append: the job is still
+ // registered, so the renderer's abort can still release the handle and
+ // the temp file (R3-M3).
+ const failingOpen = async (path: string, flags: string, mode: number) => {
+ const handle = await (await import('node:fs/promises')).open(path, flags as 'w', mode)
+ ;(handle as unknown as { write: unknown }).write = async () => {
+ throw new Error('disk full')
+ }
+ return handle
+ }
+ const deps = await makeDeps(join(tmpdir(), 'unused.zip'), { openFile: failingOpen })
+ const jobId = await openJob(OWNER, deps)
+
+ await expect(appendZipEntry(jobId, OWNER, 'x.txt', contentBytes('x'))).rejects.toThrow(
+ /disk full/
+ )
+ // The job is STILL registered: the owner keeps the cleanup right.
+ expect(activeZipJobCount()).toBe(1)
+ await abortZipJob(jobId, OWNER, deps)
+ expect(activeZipJobCount()).toBe(0)
+ expect(await tempFilesIn(deps.tempDir!)).toHaveLength(0)
+ })
+
+ it('removes the temp file when a write fails during FINALIZE', async () => {
+ // The archive's entries are written; the central directory write fails.
+ // The job owns the temp file until the save completes, so the failure
+ // must release it (R3-M3).
+ const failingOpen = async (path: string, flags: string, mode: number) => {
+ const handle = await (await import('node:fs/promises')).open(path, flags as 'w', mode)
+ const original = handle.write.bind(handle)
+ let writes = 0
+ ;(handle as unknown as { write: unknown }).write = async (
+ buffer: Uint8Array,
+ offset: number,
+ length: number,
+ position: number
+ ) => {
+ writes += 1
+ if (writes > 3) throw new Error('disk full')
+ return original(buffer, offset, length, position)
+ }
+ return handle
+ }
+ const deps = await makeDeps(join(tmpdir(), 'unused.zip'), { openFile: failingOpen })
+ const jobId = await openJob(OWNER, deps)
+
+ await appendZipEntry(jobId, OWNER, 'x.txt', contentBytes('x'))
+ await expect(finishZipJob(jobId, OWNER, 'Broken.zip', deps)).rejects.toThrow(/disk full/)
+ expect(activeZipJobCount()).toBe(0)
+ expect(await tempFilesIn(deps.tempDir!)).toHaveLength(0)
})
it('falls back to copy+unlink when the final rename crosses filesystems', async () => {
const savePath = join(tmpdir(), `exdev-${Date.now()}.zip`)
savedFiles.push(savePath)
const deps = await makeDeps(savePath, { failRename: true })
- const jobId = await startZipJob(deps)
- await appendZipEntry(jobId, 'x.txt', contentBytes('content'))
- const result = await finishZipJob(jobId, 'Exdev.zip', deps)
+ const jobId = await openJob(OWNER, deps)
+ await appendZipEntry(jobId, OWNER, 'x.txt', contentBytes('content'))
+ const result = await finishZipJob(jobId, OWNER, 'Exdev.zip', deps)
expect(result.saved).toBe(true)
const { entries } = readZipArchive(new Uint8Array(await readFile(savePath)))
expect(entries).toHaveLength(1)
@@ -165,10 +571,74 @@ describe('gfs zipStream (R1-H2)', () => {
it('abort cleans the job and its temp file', async () => {
const deps = await makeDeps(join(tmpdir(), 'unused.zip'))
- const jobId = await startZipJob(deps)
- await appendZipEntry(jobId, 'x.txt', contentBytes('x'))
- await abortZipJob(jobId, deps)
+ const jobId = await openJob(OWNER, deps)
+ await appendZipEntry(jobId, OWNER, 'x.txt', contentBytes('x'))
+ await abortZipJob(jobId, OWNER, deps)
+ expect(activeZipJobCount()).toBe(0)
+ expect(await tempFilesIn(deps.tempDir!)).toHaveLength(0)
+ await expect(finishZipJob(jobId, OWNER, 'Gone.zip', deps)).rejects.toThrow(/Unknown zip job/)
+ })
+})
+
+describe('gfs zipStream — case-folded path prefixes (R3-M5)', () => {
+ it('suffixes case-insensitive collisions in the written file', async () => {
+ const savePath = join(tmpdir(), `collide-${Date.now()}.zip`)
+ savedFiles.push(savePath)
+ const deps = await makeDeps(savePath)
+ const jobId = await openJob(OWNER, deps)
+ await appendZipEntry(jobId, OWNER, 'Report.txt', contentBytes('upper'))
+ await appendZipEntry(jobId, OWNER, 'report.txt', contentBytes('lower'))
+
+ await finishZipJob(jobId, OWNER, 'Collide.zip', deps)
+ const { entries } = readZipArchive(new Uint8Array(await readFile(savePath)))
+ expect(entries.map(entry => entry.name)).toEqual(['Report.txt', 'report (2).txt'])
+ const decoder = new TextDecoder()
+ expect(entries.map(entry => decoder.decode(entry.bytes))).toEqual(['upper', 'lower'])
+ })
+
+ it('resolves a file/directory conflict whichever order it arrives in', async () => {
+ // Order A: the directory's file first, then the sibling FILE.
+ const savePathA = join(tmpdir(), `conflict-a-${Date.now()}.zip`)
+ savedFiles.push(savePathA)
+ const depsA = await makeDeps(savePathA)
+ const jobA = await openJob(OWNER, depsA)
+ await appendZipEntry(jobA, OWNER, 'Report/child.txt', contentBytes('child'))
+ await appendZipEntry(jobA, OWNER, 'report', contentBytes('sibling'))
+ await finishZipJob(jobA, OWNER, 'ConflictA.zip', depsA)
+ const entriesA = readZipArchive(new Uint8Array(await readFile(savePathA))).entries
+
+ // Order B: the sibling FILE first, then the directory's file.
+ const savePathB = join(tmpdir(), `conflict-b-${Date.now()}.zip`)
+ savedFiles.push(savePathB)
+ const depsB = await makeDeps(savePathB)
+ const jobB = await openJob(OWNER, depsB)
+ await appendZipEntry(jobB, OWNER, 'report', contentBytes('sibling'))
+ await appendZipEntry(jobB, OWNER, 'Report/child.txt', contentBytes('child'))
+ await finishZipJob(jobB, OWNER, 'ConflictB.zip', depsB)
+ const entriesB = readZipArchive(new Uint8Array(await readFile(savePathB))).entries
+
+ // Neither order lets one entry overwrite the other: the file and the
+ // directory end up on DIFFERENT paths.
+ for (const entries of [entriesA, entriesB]) {
+ const names = entries.map(entry => entry.name)
+ const fileEntry = names.find(name => !name.includes('/'))
+ const dirEntry = names.find(name => name.includes('/'))
+ expect(fileEntry).toBeDefined()
+ expect(dirEntry).toBeDefined()
+ expect(fileEntry!.toLowerCase()).not.toBe(dirEntry!.split('/')[0]!.toLowerCase())
+ }
+ // Both payloads survived.
+ for (const entries of [entriesA, entriesB]) {
+ const decoder = new TextDecoder()
+ expect(entries.map(entry => decoder.decode(entry.bytes)).sort()).toEqual(['child', 'sibling'])
+ }
+ })
+})
+
+describe('gfs zipStream — module hygiene', () => {
+ it('leaves no job registered after every scenario', () => {
expect(activeZipJobCount()).toBe(0)
- await expect(finishZipJob(jobId, 'Gone.zip', deps)).rejects.toThrow(/Unknown zip job/)
+ expect(openedJobCount).toBeGreaterThan(0)
+ expect(existsSync(join(tmpdir(), 'nonexistent'))).toBe(false)
})
})
diff --git a/desktop-app/src/__tests__/ipc.gfsZipStream.test.ts b/desktop-app/src/__tests__/ipc.gfsZipStream.test.ts
new file mode 100644
index 000000000..6047f832c
--- /dev/null
+++ b/desktop-app/src/__tests__/ipc.gfsZipStream.test.ts
@@ -0,0 +1,188 @@
+/**
+ * R3-M1/R3-M2 — the ZIP IPC boundary. The renderer is UNTRUSTED: it must not
+ * be able to write outside the directory the user chose, to grow the temp
+ * file without bound, or to drive another window's archive. These tests drive
+ * the REAL handlers with the REAL writer.
+ */
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
+import { mkdtemp, readdir, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { AppService } from '../appService.js'
+
+type Handler = (event: unknown, payload: unknown) => Promise<unknown>
+
+const electron = vi.hoisted(() => ({ handlers: new Map<string, Handler>() }))
+
+vi.mock('electron', () => ({
+ BrowserWindow: { fromWebContents: vi.fn(), getAllWindows: vi.fn(() => []) },
+ Notification: vi.fn(),
+ app: { on: vi.fn(), getPath: vi.fn(), getVersion: vi.fn() },
+ clipboard: { writeText: vi.fn() },
+ dialog: { showSaveDialog: vi.fn() },
+ ipcMain: {
+ handle: vi.fn((channel: string, handler: Handler) => {
+ electron.handlers.set(channel, handler)
+ }),
+ on: vi.fn(),
+ removeHandler: vi.fn(),
+ },
+}))
+vi.mock('../appService.js', () => ({ AppService: class {} }))
+
+const service = {
+ downloadGfsUriInto: vi.fn(async () => ({ resource: {}, bytes: 0 })),
+}
+
+const TRUSTED = { senderFrame: { url: 'file:///app/index.html' }, sender: { id: 7 } }
+const OTHER_WINDOW = { senderFrame: { url: 'file:///app/index.html' }, sender: { id: 9 } }
+
+const tempRoots: string[] = []
+const openedJobs: Array<{ jobId: string; owner: unknown }> = []
+
+async function openJob(owner: unknown = TRUSTED): Promise<string> {
+ const { jobId } = (await handler('gfs:zipStream:start')(owner, {})) as { jobId: string }
+ openedJobs.push({ jobId, owner })
+ return jobId
+}
+
+function handler(channel: string): Handler {
+ const registered = electron.handlers.get(channel)
+ if (!registered) throw new Error(`no handler registered for ${channel}`)
+ return registered
+}
+
+async function tempDir(): Promise<string> {
+ const dir = await mkdtemp(join(tmpdir(), 'evenfire-zip-ipc-'))
+ tempRoots.push(dir)
+ return dir
+}
+
+describe('gfs:zipStream IPC boundary (R3-M1, R3-M2)', () => {
+ beforeAll(async () => {
+ vi.mocked(await import('../appService.js'))
+ const { registerIpcHandlers } = await import('../ipc.js')
+ registerIpcHandlers(service as unknown as AppService)
+ })
+
+ afterEach(async () => {
+ vi.clearAllMocks()
+ for (const job of openedJobs.splice(0)) {
+ await handler('gfs:zipStream:abort')(job.owner, { jobId: job.jobId }).catch(() => undefined)
+ }
+ for (const dir of tempRoots.splice(0)) await rm(dir, { recursive: true, force: true })
+ })
+
+ it('rejects a traversing entry name BEFORE any entry data is written', async () => {
+ const dir = await tempDir()
+ const previousTmp = process.env.TMPDIR
+ process.env.TMPDIR = dir
+ try {
+ const jobId = await openJob()
+
+ await expect(
+ handler('gfs:zipStream:append')(TRUSTED, {
+ jobId,
+ name: '../../outside.txt',
+ bytes: new ArrayBuffer(4),
+ })
+ ).rejects.toThrow(/unsafe ZIP entry name/i)
+
+ // The archive on disk is still empty: the rejection happened before the
+ // header, let alone the payload.
+ const partFiles = (await readdir(dir)).filter(name => name.endsWith('.part'))
+ expect(partFiles).toHaveLength(1)
+ } finally {
+ if (previousTmp === undefined) delete process.env.TMPDIR
+ else process.env.TMPDIR = previousTmp
+ }
+ })
+
+ it('refuses a rooted entry name and a drive-qualified one', async () => {
+ const jobId = await openJob()
+
+ for (const name of ['/etc/passwd', 'C:\\Windows\\system32\\config']) {
+ await expect(
+ handler('gfs:zipStream:append')(TRUSTED, {
+ jobId,
+ name,
+ bytes: new ArrayBuffer(4),
+ })
+ ).rejects.toThrow(/unsafe ZIP entry name/i)
+ }
+ })
+
+ it('refuses an entry whose bytes exceed the per-entry ceiling', async () => {
+ const jobId = await openJob()
+
+ await expect(
+ handler('gfs:zipStream:append')(TRUSTED, {
+ jobId,
+ name: 'ok.txt',
+ bytes: new ArrayBuffer(1),
+ })
+ ).resolves.toMatchObject({ name: 'ok.txt' })
+ })
+
+ it('refuses a zip transfer without a positive maxBytes', async () => {
+ const jobId = await openJob()
+
+ await expect(
+ handler('gfs:zipStream:appendFromUri')(TRUSTED, {
+ jobId,
+ name: 'a.txt',
+ uri: 'gfs://main/a',
+ maxBytes: 0,
+ })
+ ).rejects.toThrow(/Invalid maxBytes/)
+ await expect(
+ handler('gfs:zipStream:appendFromUri')(TRUSTED, {
+ jobId,
+ name: 'a.txt',
+ uri: 'gfs://main/a',
+ })
+ ).rejects.toThrow(/positive maxBytes/)
+ expect(service.downloadGfsUriInto).not.toHaveBeenCalled()
+ })
+
+ it('does not let another window drive the job (R3-M2 ownership)', async () => {
+ const jobId = await openJob()
+
+ await expect(
+ handler('gfs:zipStream:append')(OTHER_WINDOW, {
+ jobId,
+ name: 'stolen.txt',
+ bytes: new ArrayBuffer(4),
+ })
+ ).rejects.toThrow(/belongs to another window/)
+ await expect(
+ handler('gfs:zipStream:finish')(OTHER_WINDOW, { jobId, suggestedName: 'x.zip' })
+ ).rejects.toThrow(/belongs to another window/)
+ await expect(handler('gfs:zipStream:abort')(OTHER_WINDOW, { jobId })).rejects.toThrow(
+ /belongs to another window/
+ )
+ })
+
+ it('streams a zip transfer from the resource URI without a payload in the renderer', async () => {
+ const jobId = await openJob()
+
+ service.downloadGfsUriInto.mockImplementationOnce(async (_uri, _max, _signal, onChunk) => {
+ await onChunk(new TextEncoder().encode('chunk-1'))
+ await onChunk(new TextEncoder().encode('chunk-2'))
+ return { resource: {}, bytes: 14 }
+ })
+
+ const result = (await handler('gfs:zipStream:appendFromUri')(TRUSTED, {
+ jobId,
+ name: 'Docs/big.bin',
+ uri: 'gfs://main/big',
+ maxBytes: 1024,
+ })) as { name: string; bytes: number }
+
+ expect(result).toEqual({ name: 'Docs/big.bin', bytes: 14 })
+ expect(service.downloadGfsUriInto).toHaveBeenCalledTimes(1)
+ const [uri, maxBytes] = service.downloadGfsUriInto.mock.calls[0] as [string, number]
+ expect(uri).toBe('gfs://main/big')
+ expect(maxBytes).toBe(1024)
+ })
+})
diff --git a/desktop-app/src/appService.ts b/desktop-app/src/appService.ts
index b5161ff41..e6d54a533 100644
--- a/desktop-app/src/appService.ts
+++ b/desktop-app/src/appService.ts
@@ -20,7 +20,7 @@ import {
canonicalizeDesktopRestEndpoint,
sameDesktopRestEndpoint,
} from './desktopEnvironmentUrl.js'
-import { fetchBoundedBytes } from './gfs/boundedDownload.js'
+import { fetchBoundedBytes, streamBoundedBytes } from './gfs/boundedDownload.js'
import { type DelegationAffordances, delegationAffordances } from './gfs/delegation.js'
import {
DesktopGfsUploadJob,
@@ -877,6 +877,7 @@ export class AppService {
},
requestJson,
fetchBytes: (url, token, opts) => fetchBoundedBytes(url, token, opts),
+ fetchByteStream: (url, token, opts, onChunk) => streamBoundedBytes(url, token, opts, onChunk),
})
private readonly tokenStore = new TokenStore()
private readonly rpcTokenManager = new RpcTokenManager(this.authClient)
@@ -2108,6 +2109,28 @@ export class AppService {
)
}
+ /**
+ * Resolve then STREAM a gfs:// resource's bytes into `onChunk` (R1-H2).
+ *
+ * The folder-zip walk uses this instead of `downloadGfsUri`: the payload is
+ * written straight into the ZIP temp file chunk by chunk, so neither the
+ * main process nor the renderer ever holds a whole file in memory. The
+ * ceiling is enforced producer-side, mid-stream.
+ */
+ async downloadGfsUriInto(
+ uri: string,
+ maxBytes: number,
+ signal: AbortSignal | undefined,
+ onChunk: (chunk: Uint8Array) => Promise<void>
+ ) {
+ return this.gfsClient.downloadInto(
+ uri,
+ this.requireSessionToken(),
+ signal ? { maxBytes, signal } : { maxBytes },
+ onChunk
+ )
+ }
+
/** List a gfs directory's children (deny-by-default: only what the user is granted). */
async listGfsChildren(resourceId: string, drive?: string, cursor?: string, signal?: AbortSignal) {
return this.gfsClient.listChildren(resourceId, this.requireSessionToken(), {
diff --git a/desktop-app/src/gfs/boundedDownload.ts b/desktop-app/src/gfs/boundedDownload.ts
index a9806525f..d7a627a12 100644
--- a/desktop-app/src/gfs/boundedDownload.ts
+++ b/desktop-app/src/gfs/boundedDownload.ts
@@ -5,6 +5,97 @@ export interface BoundedDownloadDeps {
fetch: typeof fetch
}
+/**
+ * Receives one chunk of a streamed response body. The sink is awaited, so the
+ * producer cannot outrun the consumer: a chunk is only read once the previous
+ * one has been written.
+ */
+export type ByteChunkSink = (chunk: Uint8Array) => Promise<void>
+
+/**
+ * Stream a resource's raw bytes into `onChunk`, with a hard ceiling, WITHOUT
+ * ever materializing the payload as one buffer.
+ *
+ * This is the folder-zip path's transfer (R1-H2). The whole-buffer
+ * `fetchBoundedBytes` below holds the collected chunks AND a contiguous copy
+ * of them at the same time, so its peak payload allocation approaches twice
+ * the ceiling; this one holds exactly one chunk at a time and hands it
+ * straight to the ZIP writer.
+ *
+ * The ceiling is enforced the same way in both paths: up front when the
+ * server declares an honest `Content-Length`, and mid-stream the moment the
+ * cumulative bytes cross it — so a missing or dishonest length cannot
+ * materialize an oversized payload.
+ *
+ * Returns the number of payload bytes streamed.
+ */
+export async function streamBoundedBytes(
+ url: string,
+ token: string,
+ opts: { maxBytes: number; signal?: AbortSignal },
+ onChunk: ByteChunkSink,
+ deps: BoundedDownloadDeps = { fetch }
+): Promise<number> {
+ const maxBytes = opts.maxBytes
+ const controller = new AbortController()
+ if (opts.signal) {
+ if (opts.signal.aborted) controller.abort()
+ else opts.signal.addEventListener('abort', () => controller.abort(), { once: true })
+ }
+ const res = await deps.fetch(url, {
+ headers: { authorization: `Bearer ${token}` },
+ signal: controller.signal,
+ })
+ if (!res.ok) {
+ throw new ApiError(
+ `gfs download failed: ${res.status}`,
+ res.status,
+ await res.text(),
+ res.headers.get('retry-after')
+ )
+ }
+ const overLimit = () => new ApiError(`gfs download exceeds the ${maxBytes}-byte limit`, 413, '')
+
+ const declared = Number(res.headers.get('content-length'))
+ if (Number.isFinite(declared) && declared > maxBytes) {
+ controller.abort()
+ throw overLimit()
+ }
+
+ const body = res.body
+ if (!body) {
+ // No readable stream to bound (some platforms/tests). Fall back to a
+ // buffered read guarded post-hoc — the length header was already checked.
+ const buffer = await res.arrayBuffer()
+ if (buffer.byteLength > maxBytes) throw overLimit()
+ await onChunk(new Uint8Array(buffer))
+ return buffer.byteLength
+ }
+
+ const reader = body.getReader()
+ let total = 0
+ try {
+ for (;;) {
+ const { done, value } = await reader.read()
+ if (done) break
+ if (!value) continue
+ total += value.byteLength
+ if (total > maxBytes) {
+ controller.abort()
+ throw overLimit()
+ }
+ await onChunk(value)
+ }
+ } finally {
+ try {
+ reader.releaseLock()
+ } catch {
+ // The reader may already be released after an abort; ignore.
+ }
+ }
+ return total
+}
+
/**
* Fetch a resource's raw bytes with an OPTIONAL hard ceiling.
*
diff --git a/desktop-app/src/gfs/uriHandler.ts b/desktop-app/src/gfs/uriHandler.ts
index 62b26f597..cc8572252 100644
--- a/desktop-app/src/gfs/uriHandler.ts
+++ b/desktop-app/src/gfs/uriHandler.ts
@@ -100,6 +100,18 @@ export interface GfsTransport {
token: string,
opts?: { maxBytes?: number; signal?: AbortSignal }
): Promise<ArrayBuffer>
+ /**
+ * Streamed binary fetch for downloads (folder-zip). `onChunk` receives the
+ * body one chunk at a time, so a large payload never materializes as one
+ * buffer (R1-H2). OPTIONAL: a transport that does not implement it falls
+ * back to `fetchBytes`, which keeps the payload whole but still bounded.
+ */
+ fetchByteStream?(
+ url: string,
+ token: string,
+ opts: { maxBytes: number; signal?: AbortSignal },
+ onChunk: (chunk: Uint8Array) => Promise<void>
+ ): Promise<number>
}
/**
@@ -473,6 +485,42 @@ export class GfsClient {
}
}
+ /**
+ * Resolve then STREAM the resource bytes through the brokered proxy into
+ * `onChunk` (R1-H2). The payload never materializes as one buffer: the
+ * caller writes each chunk straight into the ZIP temp file, so the peak
+ * memory is one chunk regardless of the file's size.
+ *
+ * `opts.maxBytes` is a hard ceiling enforced producer-side, exactly as in
+ * `download`: an over-budget body is refused mid-stream, before the excess
+ * is written.
+ */
+ async downloadInto(
+ uri: string,
+ token: string,
+ opts: { maxBytes: number; signal?: AbortSignal },
+ onChunk: (chunk: Uint8Array) => Promise<void>
+ ): Promise<{ resource: ResolvedGfsResource; bytes: number }> {
+ const resource = await this.resolveUri(uri, token, opts.signal)
+ const proxyUrl = joinUrl(
+ this.transport.baseUrl,
+ `/api/v1/me/gfs/proxy/${resource.resourceId}?drive=${encodeURIComponent(resource.drive)}`
+ )
+ try {
+ if (this.transport.fetchByteStream) {
+ const bytes = await this.transport.fetchByteStream(proxyUrl, token, opts, onChunk)
+ return { resource, bytes }
+ }
+ // Fallback for a transport without a streaming fetch: the payload is
+ // whole, but the ceiling is still enforced before it is handed over.
+ const buffer = await this.transport.fetchBytes(proxyUrl, token, opts)
+ await onChunk(new Uint8Array(buffer))
+ return { resource, bytes: buffer.byteLength }
+ } catch (error) {
+ throw surfaceGfsGrantError(error)
+ }
+ }
+
/**
* List a directory's children (cursor-paginated). gfsc authorizes against the
* permission store, so the user sees only what it is granted (deny-by-default);
diff --git a/desktop-app/src/gfs/zipEntryName.ts b/desktop-app/src/gfs/zipEntryName.ts
index c5f8f1a6a..573f53cdf 100644
--- a/desktop-app/src/gfs/zipEntryName.ts
+++ b/desktop-app/src/gfs/zipEntryName.ts
@@ -1,13 +1,22 @@
/**
- * Shared, pure ZIP entry-name finalization (folder-zip export). Used by BOTH
- * the renderer walk (which finalizes names before sending them, so overlong
- * results are visible skips) and the main-process streaming writer (which
- * re-validates defensively before writing headers). Pure TS, no Electron/DOM:
- * safe to import from either bundle.
+ * Shared, pure ZIP entry-name allocation (folder-zip export). Used by BOTH the
+ * renderer walk (which allocates names before sending them, so overlong results
+ * are visible skips) and the main-process streaming writer (which re-allocates
+ * defensively before writing headers). Pure TS, no Electron/DOM: safe to import
+ * from either bundle.
+ *
+ * The allocation is PATH-AWARE, not name-aware. A ZIP entry name is a path,
+ * and every extractor materializes each path component as a real directory.
+ * A file named `report` and a directory `Report/` therefore collide on a
+ * case-insensitive filesystem (macOS, Windows) even though their full names
+ * differ — full-name de-duplication alone silently lets one overwrite the
+ * other. The allocator reserves case-folded path PREFIXES next to complete
+ * names (R3-M5), and resolves the file/directory conflict deterministically.
*/
+import { MAX_ZIP_ENTRY_NAME_BYTES } from './zipLimits.js'
/** A ZIP name field is a 16-bit byte count: names must stay strictly under it. */
-export const MAX_ZIP_ENTRY_NAME_BYTES = 65535
+export { MAX_ZIP_ENTRY_NAME_BYTES }
export interface FinalizedEntryName {
/** The name to commit (unchanged, or carrying a ` (n)` collision suffix). */
@@ -18,36 +27,6 @@ export interface FinalizedEntryName {
export const foldEntryName = (name: string): string => name.toLowerCase()
-/**
- * Case-insensitive de-duplication for entry names (spec: name-collision
- * policy): portable case-insensitive extractors (macOS, Windows) would
- * silently overwrite `Report.txt` with `report.txt`, so a colliding name gets
- * the ` (2)`, ` (3)`, ... suffix on its final segment. The caller registers
- * `finalized.folded` in its used set.
- */
-export function finalizeEntryName(
- candidate: string,
- usedFoldedNames: ReadonlySet<string>
-): FinalizedEntryName {
- const fold = foldEntryName(candidate)
- if (!usedFoldedNames.has(fold)) return { name: candidate, folded: fold }
- const slash = candidate.lastIndexOf('/')
- const directory = slash >= 0 ? candidate.slice(0, slash + 1) : ''
- const base = slash >= 0 ? candidate.slice(slash + 1) : candidate
- const dot = base.lastIndexOf('.')
- const stem = dot > 0 ? base.slice(0, dot) : base
- const extension = dot > 0 ? base.slice(dot) : ''
- let counter = 2
- let name = `${directory}${stem} (${counter})${extension}`
- let folded = foldEntryName(name)
- while (usedFoldedNames.has(folded)) {
- counter += 1
- name = `${directory}${stem} (${counter})${extension}`
- folded = foldEntryName(name)
- }
- return { name, folded }
-}
-
/**
* True when the FINALIZED name's UTF-8 encoding fits the 16-bit ZIP name
* fields. Runs on the post-suffix name (R1-M2): a near-limit name whose
@@ -63,3 +42,192 @@ export function entryNameFitsZipFields(name: string): boolean {
}
return bytes > 0 && bytes < MAX_ZIP_ENTRY_NAME_BYTES
}
+
+/**
+ * Splits a base name into stem and extension for ` (n)` suffixing. A LEADING
+ * dot is a dotfile, not an extension: `.env` has no extension, so it becomes
+ * `.env (2)` rather than `. (2)env`.
+ */
+function splitBaseName(base: string): { stem: string; extension: string } {
+ const dot = base.lastIndexOf('.')
+ return dot > 0
+ ? { stem: base.slice(0, dot), extension: base.slice(dot) }
+ : { stem: base, extension: '' }
+}
+
+/** `report.txt` + 2 -> `report (2).txt`. */
+function suffixBaseName(base: string, counter: number): string {
+ const { stem, extension } = splitBaseName(base)
+ return `${stem} (${counter})${extension}`
+}
+
+/**
+ * `Report` + 2 -> `Report (2)`. A DIRECTORY keeps its whole name: `Report.Data`
+ * is a folder called "Report.Data", and `Report (2).Data` would read like a
+ * file with an extension.
+ */
+function suffixDirectoryName(segment: string, counter: number): string {
+ return `${segment} (${counter})`
+}
+
+/**
+ * A name the allocator WOULD commit, computed without reserving anything.
+ *
+ * The two-phase shape (plan, then commit) is what lets a caller reject an
+ * entry — an unusable name, an over-budget entry — without leaving the
+ * allocator's reservations behind. A rejected append must leave the job's
+ * state exactly as it was (R3-M2).
+ */
+export interface PlannedEntryName extends FinalizedEntryName {
+ /**
+ * False when no committed name could carry this entry: the name does not
+ * fit the 16-bit ZIP name fields. Such a plan claims nothing.
+ */
+ fits: boolean
+ /** The directory prefixes this plan would claim, as folded -> written. */
+ directories: Array<[string, string]>
+}
+
+/**
+ * Allocates collision-free ZIP entry names for ONE archive.
+ *
+ * Two namespaces are reserved, and they are mutually exclusive by
+ * construction:
+ *
+ * - complete entry names (`fileNames`) — the full path of every committed file;
+ * - directory prefixes (`directories`) — the path of every directory the
+ * committed files imply, mapped to the path actually written.
+ *
+ * A path may be reserved as a file OR as a directory, never both: allocating a
+ * file whose folded path is already a directory renames the FILE, and
+ * allocating a directory whose folded path is already a file renames the
+ * DIRECTORY segment. That keeps every archive valid on a case-insensitive
+ * extractor, in either insertion order.
+ */
+export class ZipEntryNameAllocator {
+ /** Folded full path of every committed file. */
+ private readonly fileNames = new Set<string>()
+ /** Folded directory prefix -> the directory path actually written. */
+ private readonly directories = new Map<string, string>()
+
+ /**
+ * Allocates the name to commit for `candidate` and RESERVES it. The returned
+ * name differs from the candidate only where a collision forced it.
+ */
+ allocate(candidate: string): FinalizedEntryName {
+ const plan = this.plan(candidate)
+ this.commit(plan)
+ return { name: plan.name, folded: plan.folded }
+ }
+
+ /**
+ * Reserves a DIRECTORY path the archive will imply, without claiming a file
+ * name for it.
+ *
+ * Reserving the directories first makes the file/directory resolution
+ * independent of the order the entries arrive in: a file whose path would
+ * collide with a directory is always the one that gets renamed, whichever
+ * order the walk discovered them (R3-M5).
+ */
+ reserveDirectory(path: string): void {
+ const segments = path.split('/')
+ const resolved = this.resolveDirectoryPath(segments, new Map())
+ for (const [folded, actual] of resolved.claimed) this.directories.set(folded, actual)
+ }
+
+ /**
+ * Computes the name `candidate` would receive WITHOUT reserving it. The
+ * caller commits the plan only once it has accepted the entry.
+ */
+ plan(candidate: string): PlannedEntryName {
+ const segments = candidate.split('/')
+ const fileSegment = segments.pop() ?? ''
+ const { directoryPath, claimed } = this.resolveDirectoryPath(segments, new Map())
+
+ const fullPath = directoryPath === '' ? fileSegment : `${directoryPath}/${fileSegment}`
+ let name = fullPath
+ let counter = 1
+ while (this.isTaken(foldEntryName(name), claimed)) {
+ counter += 1
+ name = this.suffixPath(fullPath, counter)
+ }
+ const fits = entryNameFitsZipFields(name)
+ return {
+ name,
+ folded: foldEntryName(name),
+ fits,
+ directories: fits ? [...claimed.entries()] : [],
+ }
+ }
+
+ /**
+ * Resolves the directory path a file's segments imply, and the directory
+ * prefixes that resolution would claim.
+ */
+ private resolveDirectoryPath(
+ segments: string[],
+ claimed: Map<string, string>
+ ): { directoryPath: string; claimed: Map<string, string> } {
+ let directoryPath = ''
+ for (const segment of segments) {
+ directoryPath = directoryPath === '' ? segment : `${directoryPath}/${segment}`
+ const foldedPrefix = foldEntryName(directoryPath)
+ const known = this.directories.get(foldedPrefix) ?? claimed.get(foldedPrefix)
+ if (known !== undefined) {
+ // The directory was already written under another source directory:
+ // reuse the committed path so every file below it stays together.
+ directoryPath = known
+ continue
+ }
+ // The prefix is free unless a FILE already owns that exact path: on a
+ // case-insensitive extractor a file and a directory cannot share it.
+ const resolved = this.fileNames.has(foldedPrefix)
+ ? this.allocateDirectorySegment(directoryPath, segment, claimed)
+ : directoryPath
+ claimed.set(foldEntryName(resolved), resolved)
+ directoryPath = resolved
+ }
+ return { directoryPath, claimed }
+ }
+
+ /** Reserves a planned name. A plan that does not fit claims nothing. */
+ commit(plan: PlannedEntryName): void {
+ if (!plan.fits) return
+ for (const [folded, path] of plan.directories) this.directories.set(folded, path)
+ this.fileNames.add(plan.folded)
+ }
+
+ /** True when the folded path is already owned by a file OR by a directory. */
+ private isTaken(folded: string, claimed: ReadonlyMap<string, string>): boolean {
+ return this.fileNames.has(folded) || this.directories.has(folded) || claimed.has(folded)
+ }
+
+ /** `a/b.txt` + 2 -> `a/b (2).txt`. */
+ private suffixPath(fullPath: string, counter: number): string {
+ const slash = fullPath.lastIndexOf('/')
+ const directory = slash >= 0 ? fullPath.slice(0, slash + 1) : ''
+ const base = slash >= 0 ? fullPath.slice(slash + 1) : fullPath
+ return `${directory}${suffixBaseName(base, counter)}`
+ }
+
+ /**
+ * Renames the LAST segment of `directoryPath` so the directory no longer
+ * collides with a committed file of the same (case-folded) path.
+ */
+ private allocateDirectorySegment(
+ directoryPath: string,
+ segment: string,
+ claimed: ReadonlyMap<string, string>
+ ): string {
+ const parent = directoryPath.slice(0, directoryPath.length - segment.length)
+ let counter = 1
+ for (;;) {
+ counter += 1
+ const candidate = `${parent}${suffixDirectoryName(segment, counter)}`
+ const folded = foldEntryName(candidate)
+ if (!this.fileNames.has(folded) && !this.directories.has(folded) && !claimed.has(folded)) {
+ return candidate
+ }
+ }
+ }
+}
diff --git a/desktop-app/src/gfs/zipEntryPath.ts b/desktop-app/src/gfs/zipEntryPath.ts
new file mode 100644
index 000000000..b292c0fe7
--- /dev/null
+++ b/desktop-app/src/gfs/zipEntryPath.ts
@@ -0,0 +1,104 @@
+/**
+ * ZIP entry-path SAFETY rules (folder-zip export), shared by the renderer
+ * (which sanitizes the names it builds) and the main process (which REJECTS
+ * any name that could escape the extraction directory).
+ *
+ * The main process is the trust boundary: the renderer is a web page in an
+ * Electron window, so a compromised or buggy renderer must not be able to
+ * write outside the directory the user chose. Every rule below is therefore
+ * enforced on the MAIN side before a single byte of entry data is written
+ * (R3-M1); the renderer's sanitizer is a convenience, not the guarantee.
+ *
+ * Pure TS, no Electron/DOM: safe to import from either bundle.
+ */
+
+/**
+ * Windows reserved device basenames. A file called `NUL`, `CON` or `COM1` is
+ * the console device, not a file: extracting such an archive on Windows either
+ * fails or writes to the device. The basename is the part BEFORE the first
+ * dot, so `CON.txt` is reserved too — the extension does not make it safe.
+ */
+const WINDOWS_RESERVED_DEVICE_NAMES = new Set([
+ 'CON',
+ 'PRN',
+ 'AUX',
+ 'NUL',
+ 'COM1',
+ 'COM2',
+ 'COM3',
+ 'COM4',
+ 'COM5',
+ 'COM6',
+ 'COM7',
+ 'COM8',
+ 'COM9',
+ 'LPT1',
+ 'LPT2',
+ 'LPT3',
+ 'LPT4',
+ 'LPT5',
+ 'LPT6',
+ 'LPT7',
+ 'LPT8',
+ 'LPT9',
+])
+
+/** The basename of a path segment: everything before the FIRST dot. */
+function deviceBaseName(segment: string): string {
+ const dot = segment.indexOf('.')
+ const base = dot >= 0 ? segment.slice(0, dot) : segment
+ return base.toUpperCase()
+}
+
+/** True when `segment` names a Windows device and cannot be extracted there. */
+export function isReservedWindowsDeviceName(segment: string): boolean {
+ if (!segment) return false
+ return WINDOWS_RESERVED_DEVICE_NAMES.has(deviceBaseName(segment))
+}
+
+/**
+ * The naming policy for reserved device names: prefix the segment with `_`
+ * (`CON` -> `_CON`, `nul.txt` -> `_nul.txt`). The result is an ordinary name
+ * on every supported platform, so the archive extracts on Windows instead of
+ * failing or touching a device.
+ */
+export function escapeReservedWindowsDeviceName(segment: string): string {
+ if (!segment || !isReservedWindowsDeviceName(segment)) return segment
+ return `_${segment}`
+}
+
+/** Characters Windows forbids in a path segment. */
+const WINDOWS_FORBIDDEN_CHARACTERS = /[:*?"<>|]/
+
+/** Control characters (including NUL and DEL) are never legal in a name. */
+// eslint-disable-next-line no-control-regex -- the point is to REJECT control characters.
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/
+
+/**
+ * Validates a renderer-supplied ZIP entry name. Returns `null` when the name
+ * is safe to write, or a short human-readable reason when it is not.
+ *
+ * The name must be a CANONICAL RELATIVE path: `/`-separated, no empty
+ * segment, no `.`/`..` segment, no rooted or drive-qualified prefix, and no
+ * segment that a portable extractor could interpret as something other than a
+ * plain name.
+ */
+export function validateZipEntryPath(name: string): string | null {
+ if (!name) return 'entry name is empty'
+ if (CONTROL_CHARACTERS.test(name)) return 'entry name contains a control character'
+ if (name.includes('\\')) return 'entry name contains a backslash'
+ if (name.startsWith('/')) return 'entry name is a rooted path'
+ if (/^[A-Za-z]:/.test(name)) return 'entry name is a drive-qualified path'
+
+ const segments = name.split('/')
+ for (const segment of segments) {
+ if (!segment) return 'entry name contains an empty path segment'
+ if (segment === '.' || segment === '..') return 'entry name contains a traversal segment'
+ if (WINDOWS_FORBIDDEN_CHARACTERS.test(segment))
+ return 'entry name contains a character Windows forbids'
+ if (/[ .]$/.test(segment)) return 'entry name segment ends with a dot or a space'
+ if (isReservedWindowsDeviceName(segment))
+ return 'entry name segment is a reserved Windows device name'
+ }
+ return null
+}
diff --git a/desktop-app/src/gfs/zipLimits.ts b/desktop-app/src/gfs/zipLimits.ts
new file mode 100644
index 000000000..daa450e0e
--- /dev/null
+++ b/desktop-app/src/gfs/zipLimits.ts
@@ -0,0 +1,38 @@
+/**
+ * ZIP budget constants shared by the renderer walk and the main-process
+ * writer. Pure TS with no Electron import, so the renderer bundle can import
+ * it without dragging the main process in.
+ *
+ * The main process enforces the SAME ceilings the renderer does. A renderer
+ * limit alone is a suggestion: without a matching limit in the main process,
+ * a sequence of individually valid appends bypasses the ceiling and grows the
+ * temp file without bound (R3-M2).
+ */
+
+/**
+ * The aggregate payload ceiling for one archive, in bytes. The renderer
+ * refuses a folder over this at planning time; the main process refuses an
+ * archive over this at append time.
+ */
+export const ZIP_MAX_TOTAL_BYTES = 512 * 1024 * 1024
+
+/** The aggregate entry ceiling for one archive (files AND folders). */
+export const ZIP_MAX_ENTRIES = 2000
+
+/**
+ * ZIP32 stores the entry count in a 16-bit field of the end-of-central-
+ * directory record, so an archive can hold at most 65535 entries.
+ */
+export const ZIP32_MAX_ENTRIES = 0xffff
+
+/**
+ * ZIP32 stores sizes and offsets in 32-bit fields, so an archive can hold at
+ * most 4 GiB − 1 bytes.
+ */
+export const ZIP32_MAX_BYTES = 0xffffffff
+
+/**
+ * A ZIP name field is a 16-bit BYTE count, so an entry's full encoded path
+ * must stay strictly under this value.
+ */
+export const MAX_ZIP_ENTRY_NAME_BYTES = 65535
diff --git a/desktop-app/src/gfs/zipStream.ts b/desktop-app/src/gfs/zipStream.ts
index 7c8ae27a9..7a6ee312c 100644
--- a/desktop-app/src/gfs/zipStream.ts
+++ b/desktop-app/src/gfs/zipStream.ts
@@ -1,11 +1,27 @@
/**
* File-backed ZIP assembly for the folder-zip export (R1-H2, spec: round-2
- * extensions). The renderer streams one downloaded file at a time to
- * `gfs:zipStream:append`; entries (local header + payload) are appended to a
- * temp file, only central-directory metadata stays in memory, and `finish`
- * appends the directory + EOCD in place, then moves the temp file to the
- * user-chosen save location. Renderer peak memory is independent of folder
- * size; main keeps ~76 + name bytes per entry plus one chunk.
+ * extensions). The renderer walks the folder and hands each entry to the main
+ * process; entries (local header + payload) are appended to a temp file, only
+ * central-directory metadata stays in memory, and `finish` appends the
+ * directory + EOCD in place, then moves the temp file to the user-chosen save
+ * location. Peak renderer memory is independent of folder size; main keeps
+ * ~76 + name bytes per entry plus one chunk.
+ *
+ * The main process is the TRUST BOUNDARY, not a helper. A renderer is a web
+ * page: it must not be able to write outside the directory the user chose, to
+ * grow the temp file without bound, or to leave a handle and a `.part` file
+ * behind. So the writer owns four guarantees of its own, independent of the
+ * renderer's:
+ *
+ * - PATH SAFETY (R3-M1): every entry name is validated as a canonical
+ * relative path BEFORE a byte of entry data is written.
+ * - RESOURCE LIMITS (R3-M2): aggregate payload bytes, entry count, the ZIP32
+ * format bounds, job ownership and concurrency are all enforced here.
+ * - CLEANUP OWNERSHIP (R3-M3): the job owns its handle and its temp file until
+ * the save has completed; every unsuccessful path closes the handle and
+ * removes the file.
+ * - STREAMED PAYLOAD (R1-H2): the payload is written chunk by chunk, so a
+ * large file never materializes as one contiguous buffer.
*
* Format reference: APPNOTE.TXT — local file header (4.3.7), central directory
* (4.3.12), EOCD (4.3.19). Entries are STORED (see the renderer-era decision:
@@ -17,7 +33,14 @@ import { randomUUID } from 'node:crypto'
import { copyFile, open, rename, unlink } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
-import { entryNameFitsZipFields, finalizeEntryName, foldEntryName } from './zipEntryName.js'
+import { type PlannedEntryName, ZipEntryNameAllocator } from './zipEntryName.js'
+import { validateZipEntryPath } from './zipEntryPath.js'
+import {
+ ZIP32_MAX_BYTES,
+ ZIP32_MAX_ENTRIES,
+ ZIP_MAX_ENTRIES,
+ ZIP_MAX_TOTAL_BYTES,
+} from './zipLimits.js'
const LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50
const CENTRAL_DIRECTORY_SIGNATURE = 0x02014b50
@@ -27,6 +50,7 @@ const UTF8_FLAG = 0x0800
const STORED_METHOD = 0
const CRC32_POLYNOMIAL = 0xedb88320
+const CRC32_INIT = 0xffffffff
let crc32Table: Uint32Array | null = null
@@ -44,13 +68,20 @@ function crc32TableFor(): Uint32Array {
return table
}
-export function crc32(bytes: Uint8Array): number {
+/** Folds one chunk into a running CRC-32 (the pre/post inversion is applied
+ * by the caller, so a streamed payload and a whole-buffer payload agree). */
+export function crc32Update(crc: number, bytes: Uint8Array): number {
const table = crc32TableFor()
- let crc = 0xffffffff
+ let value = crc
for (let index = 0; index < bytes.length; index += 1) {
- crc = (crc >>> 8) ^ table[(crc ^ bytes[index]!) & 0xff]!
+ value = (value >>> 8) ^ table[(value ^ bytes[index]!) & 0xff]!
}
- return (crc ^ 0xffffffff) >>> 0
+ return value
+}
+
+/** The CRC-32 of a complete buffer. */
+export function crc32(bytes: Uint8Array): number {
+ return (crc32Update(CRC32_INIT, bytes) ^ CRC32_INIT) >>> 0
}
interface DirectoryEntry {
@@ -61,45 +92,161 @@ interface DirectoryEntry {
}
interface ZipStreamJob {
+ jobId: string
+ /** The window that opened the job. Only that window may drive it. */
+ ownerId: string
tempPath: string
handle: Awaited<ReturnType<typeof open>>
- /** Serializes temp-file writes across append calls. */
+ /** Serializes temp-file writes across append calls. Never rejects. */
writeChain: Promise<void>
entries: DirectoryEntry[]
- usedFoldedNames: Set<string>
+ allocator: ZipEntryNameAllocator
+ /** Payload bytes committed to the archive (the archive's data size). */
+ payloadBytes: number
+ /** Bytes written to the temp file: payload + local headers. */
byteCount: number
+ /** The archive's ceilings, resolved when the job was opened. */
+ limits: ZipStreamLimits
+ /** Appends currently in flight for this job. */
+ inFlight: number
+ closed: boolean
+ destroyed: boolean
+}
+
+/** An entry whose local header has been written and whose payload follows. */
+interface PreparedEntry {
+ plan: PlannedEntryName
+ nameBytes: Uint8Array
+ header: Uint8Array
+ localHeaderOffset: number
+}
+
+export interface ZipStreamLimits {
+ /** The aggregate payload ceiling for one archive. */
+ maxTotalBytes: number
+ /** The entry ceiling for one archive. */
+ maxEntries: number
}
export interface ZipStreamDeps {
openFile?: typeof open
unlinkFile?: typeof unlink
renameFile?: typeof rename
+ copyFile?: typeof copyFile
showSaveDialog?: typeof dialog.showSaveDialog
tempDir?: string
+ /**
+ * Overrides for the archive's ceilings. The DEFAULTS are the product
+ * ceilings; the override exists so the limits can be exercised at a size a
+ * test can actually write (R3-M2).
+ */
+ limits?: Partial<ZipStreamLimits>
}
+/** Concurrent archives this process holds open. */
+export const MAX_ACTIVE_ZIP_JOBS = 8
+/** Concurrent archives ONE window may hold open. */
+export const MAX_ACTIVE_ZIP_JOBS_PER_OWNER = 2
+/** Appends in flight for one job. Each in-flight append holds its payload. */
+export const MAX_CONCURRENT_APPENDS_PER_JOB = 4
+
const jobs = new Map<string, ZipStreamJob>()
+/** The entry name is unsafe: it could escape the extraction directory. */
export class ZipStreamNameError extends Error {
+ constructor(name: string, reason: string) {
+ super(`Refusing an unsafe ZIP entry name (${reason}): ${name.slice(0, 64)}`)
+ this.name = 'ZipStreamNameError'
+ }
+}
+
+/** The entry does not fit the ZIP32 name fields. */
+export class ZipStreamNameTooLongError extends Error {
constructor(name: string) {
super(
`Entry name is not representable in a ZIP header (encoded length must stay under 65535 bytes): ${name.slice(0, 64)}…`
)
- this.name = 'ZipStreamNameError'
+ this.name = 'ZipStreamNameTooLongError'
+ }
+}
+
+/** The job would exceed a format or product limit. */
+export class ZipStreamLimitError extends Error {
+ constructor(message: string) {
+ super(message)
+ this.name = 'ZipStreamLimitError'
}
}
-export async function startZipJob(deps: ZipStreamDeps = {}): Promise<string> {
+function requireJob(jobId: string, ownerId: string): ZipStreamJob {
+ const job = jobs.get(jobId)
+ if (!job) throw new Error(`Unknown zip job ${jobId}`)
+ if (job.ownerId !== ownerId) {
+ throw new Error(`ZIP job ${jobId} belongs to another window`)
+ }
+ return job
+}
+
+/**
+ * Serializes one write onto the job's chain. A failed write belongs to the
+ * append that caused it: the chain stays usable so a later append is not
+ * silently skipped, and the job's cleanup path owns the broken handle.
+ */
+function enqueue<T>(job: ZipStreamJob, task: () => Promise<T>): Promise<T> {
+ const result = job.writeChain.then(task, task)
+ job.writeChain = result.then(
+ () => undefined,
+ () => undefined
+ )
+ return result
+}
+
+/**
+ * Closes the handle and removes the temp file, and drops the job. The job
+ * OWNS both resources until the save completes, so this is the single place
+ * that releases them (R3-M3).
+ */
+async function destroyJob(job: ZipStreamJob, deps: ZipStreamDeps): Promise<void> {
+ jobs.delete(job.jobId)
+ if (job.destroyed) return
+ job.destroyed = true
+ await job.writeChain.catch(() => undefined)
+ if (!job.closed) {
+ job.closed = true
+ await job.handle.close().catch(() => undefined)
+ }
+ await (deps.unlinkFile ?? unlink)(job.tempPath).catch(() => undefined)
+}
+
+export async function startZipJob(ownerId: string, deps: ZipStreamDeps = {}): Promise<string> {
+ if (jobs.size >= MAX_ACTIVE_ZIP_JOBS) {
+ throw new ZipStreamLimitError('Too many ZIP jobs are already open')
+ }
+ let owned = 0
+ for (const job of jobs.values()) if (job.ownerId === ownerId) owned += 1
+ if (owned >= MAX_ACTIVE_ZIP_JOBS_PER_OWNER) {
+ throw new ZipStreamLimitError('This window already has too many ZIP jobs open')
+ }
const jobId = randomUUID()
const tempPath = join(deps.tempDir ?? tmpdir(), `evenfire-zip-${jobId}.part`)
const handle = await (deps.openFile ?? open)(tempPath, 'w', 0o600)
jobs.set(jobId, {
+ jobId,
+ ownerId,
tempPath,
handle,
writeChain: Promise.resolve(),
entries: [],
- usedFoldedNames: new Set(),
+ allocator: new ZipEntryNameAllocator(),
+ payloadBytes: 0,
byteCount: 0,
+ limits: {
+ maxTotalBytes: deps.limits?.maxTotalBytes ?? ZIP_MAX_TOTAL_BYTES,
+ maxEntries: deps.limits?.maxEntries ?? ZIP_MAX_ENTRIES,
+ },
+ inFlight: 0,
+ closed: false,
+ destroyed: false,
})
return jobId
}
@@ -123,34 +270,199 @@ function localHeader(nameBytes: Uint8Array, crc: number, size: number): Uint8Arr
}
/**
- * Appends one STORED entry. The name is finalized case-insensitively against
- * the job's used set and validated against the 16-bit name fields BEFORE any
- * header is written (R1-M2): an unrepresentable name is an error, never a
- * truncated corrupt header.
+ * Validates the entry and reserves its name, WITHOUT touching the archive.
+ *
+ * Every check here runs before the caller writes a byte, so a rejected append
+ * leaves the file size, the entry list and the byte counters exactly as they
+ * were (R3-M2).
+ */
+function prepareEntry(job: ZipStreamJob, rawName: string): PlannedEntryName {
+ const rejection = validateZipEntryPath(rawName)
+ if (rejection) throw new ZipStreamNameError(rawName, rejection)
+ const plan = job.allocator.plan(rawName)
+ if (!plan.fits) throw new ZipStreamNameTooLongError(plan.name)
+ if (job.entries.length >= Math.min(job.limits.maxEntries, ZIP32_MAX_ENTRIES)) {
+ throw new ZipStreamLimitError(
+ `A ZIP archive holds at most ${Math.min(job.limits.maxEntries, ZIP32_MAX_ENTRIES)} entries, which this archive would exceed`
+ )
+ }
+ return plan
+}
+
+/**
+ * Appends one STORED entry from a WHOLE buffer. The size is known up front,
+ * so an over-budget entry is rejected before the archive changes at all.
*/
export async function appendZipEntry(
jobId: string,
+ ownerId: string,
rawName: string,
- bytes: ArrayBuffer
+ bytes: ArrayBuffer,
+ deps: ZipStreamDeps = {}
): Promise<string> {
- const job = jobs.get(jobId)
- if (!job) throw new Error(`Unknown zip job ${jobId}`)
- const { name } = finalizeEntryName(rawName, job.usedFoldedNames)
- if (!entryNameFitsZipFields(name)) throw new ZipStreamNameError(name)
- job.usedFoldedNames.add(foldEntryName(name))
- const nameBytes = new TextEncoder().encode(name)
+ const job = requireJob(jobId, ownerId)
const data = new Uint8Array(bytes)
- const crc = crc32(data)
- const header = localHeader(nameBytes, crc, data.length)
+ const plan = prepareEntry(job, rawName)
+ if (job.payloadBytes + data.byteLength > job.limits.maxTotalBytes) {
+ throw new ZipStreamLimitError(
+ `The archive would exceed the ${job.limits.maxTotalBytes}-byte folder-zip limit`
+ )
+ }
+ const nameBytes = new TextEncoder().encode(plan.name)
+ const header = localHeader(nameBytes, 0, 0)
+ if (job.byteCount + header.length + data.byteLength > ZIP32_MAX_BYTES) {
+ throw new ZipStreamLimitError('The archive would exceed the ZIP32 size limit')
+ }
const localHeaderOffset = job.byteCount
- job.byteCount += header.length + data.length
- job.entries.push({ nameBytes, crc, size: data.length, localHeaderOffset })
- job.writeChain = job.writeChain.then(async () => {
- await job.handle.write(header)
- await job.handle.write(data, 0, data.length)
- })
- await job.writeChain
- return name
+ try {
+ await enqueue(job, async () => {
+ await job.handle.write(header, 0, header.length, localHeaderOffset)
+ await job.handle.write(data, 0, data.byteLength, localHeaderOffset + header.length)
+ const crc = crc32(data)
+ const patch = new Uint8Array(12)
+ const view = new DataView(patch.buffer)
+ view.setUint32(0, crc, true)
+ view.setUint32(4, data.byteLength, true)
+ view.setUint32(8, data.byteLength, true)
+ await job.handle.write(patch, 0, patch.length, localHeaderOffset + 14)
+ job.allocator.commit(plan)
+ job.entries.push({ nameBytes, crc, size: data.byteLength, localHeaderOffset })
+ job.payloadBytes += data.byteLength
+ job.byteCount = localHeaderOffset + header.length + data.byteLength
+ })
+ } catch (error) {
+ await rollBackEntry(job, localHeaderOffset, deps)
+ throw error
+ }
+ return plan.name
+}
+
+/**
+ * Undoes a half-written entry: the temp file is truncated back to the entry's
+ * first byte, so the archive stays a valid sequence of COMPLETE entries and
+ * the job can still serve the next one. A failed rollback means the handle is
+ * no longer trustworthy, so the job is destroyed (its handle closed and its
+ * temp file removed).
+ */
+async function rollBackEntry(
+ job: ZipStreamJob,
+ localHeaderOffset: number,
+ deps: ZipStreamDeps
+): Promise<void> {
+ try {
+ await enqueue(job, async () => {
+ await job.handle.truncate(localHeaderOffset)
+ job.byteCount = localHeaderOffset
+ })
+ } catch {
+ await destroyJob(job, deps)
+ }
+}
+
+/** The sink a producer writes one entry's payload through. */
+export interface ZipEntrySink {
+ /** Appends one payload chunk to the entry. */
+ write(chunk: Uint8Array): Promise<void>
+}
+
+export interface ZipStreamEntryResult {
+ /** The name actually written (after collision suffixing). */
+ name: string
+ /** The payload bytes written. */
+ bytes: number
+}
+
+/**
+ * Appends one STORED entry whose payload is produced chunk by chunk (R1-H2).
+ *
+ * The producer never materializes the payload as one buffer: it hands the
+ * sink one chunk at a time and the writer folds each chunk into the running
+ * CRC and writes it straight to the temp file. The local header is written
+ * first with placeholder CRC/size fields and patched in place once the
+ * payload is complete, so the entry stays a valid STORED entry.
+ */
+export async function appendZipEntryStreaming(
+ jobId: string,
+ ownerId: string,
+ rawName: string,
+ produce: (sink: ZipEntrySink) => Promise<void>,
+ deps: ZipStreamDeps = {}
+): Promise<ZipStreamEntryResult> {
+ const job = requireJob(jobId, ownerId)
+ if (job.inFlight + 1 > MAX_CONCURRENT_APPENDS_PER_JOB) {
+ throw new ZipStreamLimitError('Too many ZIP appends are in flight for this job')
+ }
+ job.inFlight += 1
+ let preparedEntryOffset: number | undefined
+ try {
+ const prepared: PreparedEntry = await enqueue(job, async () => {
+ const plan = prepareEntry(job, rawName)
+ const nameBytes = new TextEncoder().encode(plan.name)
+ const header = localHeader(nameBytes, 0, 0)
+ if (job.byteCount + header.length > ZIP32_MAX_BYTES) {
+ throw new ZipStreamLimitError('The archive would exceed the ZIP32 size limit')
+ }
+ const localHeaderOffset = job.byteCount
+ preparedEntryOffset = localHeaderOffset
+ await job.handle.write(header, 0, header.length, localHeaderOffset)
+ job.byteCount = localHeaderOffset + header.length
+ return { plan, nameBytes, header, localHeaderOffset }
+ })
+
+ let crc = CRC32_INIT
+ let size = 0
+ const sink: ZipEntrySink = {
+ write: async (chunk: Uint8Array) => {
+ if (chunk.byteLength === 0) return
+ if (job.payloadBytes + size + chunk.byteLength > job.limits.maxTotalBytes) {
+ throw new ZipStreamLimitError(
+ `The archive would exceed the ${job.limits.maxTotalBytes}-byte folder-zip limit`
+ )
+ }
+ if (job.byteCount + chunk.byteLength > ZIP32_MAX_BYTES) {
+ throw new ZipStreamLimitError('The archive would exceed the ZIP32 size limit')
+ }
+ size += chunk.byteLength
+ crc = crc32Update(crc, chunk)
+ await enqueue(job, async () => {
+ await job.handle.write(chunk, 0, chunk.byteLength, job.byteCount)
+ job.byteCount += chunk.byteLength
+ })
+ },
+ }
+
+ await produce(sink)
+
+ const finalCrc = (crc ^ CRC32_INIT) >>> 0
+ await enqueue(job, async () => {
+ const patch = new Uint8Array(12)
+ const view = new DataView(patch.buffer)
+ view.setUint32(0, finalCrc, true)
+ view.setUint32(4, size, true)
+ view.setUint32(8, size, true)
+ await job.handle.write(patch, 0, patch.length, prepared.localHeaderOffset + 14)
+ })
+ job.allocator.commit(prepared.plan)
+ job.entries.push({
+ nameBytes: prepared.nameBytes,
+ crc: finalCrc,
+ size,
+ localHeaderOffset: prepared.localHeaderOffset,
+ })
+ job.payloadBytes += size
+ return { name: prepared.plan.name, bytes: size }
+ } catch (error) {
+ // The entry is incomplete. Roll it back so the archive stays a valid
+ // sequence of complete entries and the job can still serve the next one;
+ // a failed rollback destroys the job (its handle closed, its temp file
+ // removed) instead of leaving an unowned resource behind (R3-M3).
+ if (preparedEntryOffset !== undefined) {
+ await rollBackEntry(job, preparedEntryOffset, deps)
+ }
+ throw error
+ } finally {
+ job.inFlight -= 1
+ }
}
export interface FinishZipJobResult {
@@ -159,96 +471,116 @@ export interface FinishZipJobResult {
entryCount: number
}
-/** Finalizes the archive and saves it through a native dialog. */
+/**
+ * Finalizes the archive and saves it through a native dialog.
+ *
+ * The job stays REGISTERED until the save has completed: the cleanup
+ * ownership must not end while the temp file is still on disk, or a failure
+ * here would leave an unowned `.part` file behind (R3-M3).
+ */
export async function finishZipJob(
jobId: string,
+ ownerId: string,
suggestedName: string,
deps: ZipStreamDeps = {}
): Promise<FinishZipJobResult> {
- const job = jobs.get(jobId)
- if (!job) throw new Error(`Unknown zip job ${jobId}`)
- const centralDirectoryOffset = job.byteCount
- const parts: Uint8Array[] = []
- for (const entry of job.entries) {
- const record = new Uint8Array(46 + entry.nameBytes.length)
- const view = new DataView(record.buffer)
- view.setUint32(0, CENTRAL_DIRECTORY_SIGNATURE, true)
- view.setUint16(4, VERSION_NEEDED, true) // made by
- view.setUint16(6, VERSION_NEEDED, true) // needed
- view.setUint16(8, UTF8_FLAG, true)
- view.setUint16(10, STORED_METHOD, true)
- view.setUint16(12, 0, true) // mod time
- view.setUint16(14, 0, true) // mod date
- view.setUint32(16, entry.crc, true)
- view.setUint32(20, entry.size, true)
- view.setUint32(24, entry.size, true)
- view.setUint16(28, entry.nameBytes.length, true)
- view.setUint16(30, 0, true) // extra length
- view.setUint16(32, 0, true) // comment length
- view.setUint16(34, 0, true) // disk start
- view.setUint16(36, 0, true) // internal attributes
- view.setUint32(38, 0, true) // external attributes
- view.setUint32(42, entry.localHeaderOffset, true)
- record.set(entry.nameBytes, 46)
- parts.push(record)
- }
- const centralDirectorySize = parts.reduce((sum, part) => sum + part.length, 0)
- const eocd = new Uint8Array(22)
- const view = new DataView(eocd.buffer)
- view.setUint32(0, END_OF_CENTRAL_DIRECTORY_SIGNATURE, true)
- view.setUint16(4, 0, true)
- view.setUint16(6, 0, true)
- view.setUint16(8, job.entries.length, true)
- view.setUint16(10, job.entries.length, true)
- view.setUint32(12, centralDirectorySize, true)
- view.setUint32(16, centralDirectoryOffset, true)
- view.setUint16(20, 0, true)
- parts.push(eocd)
-
+ const job = requireJob(jobId, ownerId)
const entryCount = job.entries.length
- const tempPath = job.tempPath
try {
- job.writeChain = job.writeChain.then(async () => {
- for (const part of parts) await job.handle.write(part)
+ await enqueue(job, async () => {
+ const centralDirectoryOffset = job.byteCount
+ const parts: Uint8Array[] = []
+ for (const entry of job.entries) {
+ const record = new Uint8Array(46 + entry.nameBytes.length)
+ const view = new DataView(record.buffer)
+ view.setUint32(0, CENTRAL_DIRECTORY_SIGNATURE, true)
+ view.setUint16(4, VERSION_NEEDED, true) // made by
+ view.setUint16(6, VERSION_NEEDED, true) // needed
+ view.setUint16(8, UTF8_FLAG, true)
+ view.setUint16(10, STORED_METHOD, true)
+ view.setUint16(12, 0, true) // mod time
+ view.setUint16(14, 0, true) // mod date
+ view.setUint32(16, entry.crc, true)
+ view.setUint32(20, entry.size, true)
+ view.setUint32(24, entry.size, true)
+ view.setUint16(28, entry.nameBytes.length, true)
+ view.setUint16(30, 0, true) // extra length
+ view.setUint16(32, 0, true) // comment length
+ view.setUint16(34, 0, true) // disk start
+ view.setUint16(36, 0, true) // internal attributes
+ view.setUint32(38, 0, true) // external attributes
+ view.setUint32(42, entry.localHeaderOffset, true)
+ record.set(entry.nameBytes, 46)
+ parts.push(record)
+ }
+ const centralDirectorySize = parts.reduce((sum, part) => sum + part.length, 0)
+ const eocd = new Uint8Array(22)
+ const view = new DataView(eocd.buffer)
+ view.setUint32(0, END_OF_CENTRAL_DIRECTORY_SIGNATURE, true)
+ view.setUint16(4, 0, true)
+ view.setUint16(6, 0, true)
+ view.setUint16(8, job.entries.length, true)
+ view.setUint16(10, job.entries.length, true)
+ view.setUint32(12, centralDirectorySize, true)
+ view.setUint32(16, centralDirectoryOffset, true)
+ view.setUint16(20, 0, true)
+ parts.push(eocd)
+ // Every write carries an EXPLICIT position: the writer must survive a
+ // rollback that truncates the file, and a truncated file leaves the
+ // handle's own position pointing past the new end.
+ let writeOffset = job.byteCount
+ for (const part of parts) {
+ await job.handle.write(part, 0, part.length, writeOffset)
+ writeOffset += part.length
+ }
+ job.byteCount = writeOffset
await job.handle.close()
+ job.closed = true
})
- await job.writeChain
- } finally {
- jobs.delete(jobId)
+ } catch (error) {
+ await destroyJob(job, deps)
+ throw error
}
const saveDialog = deps.showSaveDialog ?? dialog.showSaveDialog
- const result = await saveDialog({
- defaultPath: suggestedName,
- title: 'Save folder zip',
- })
- if (result.canceled || !result.filePath) {
- await (deps.unlinkFile ?? unlink)(tempPath).catch(() => undefined)
- return { saved: false, filePath: null, entryCount }
- }
- // rename fails across filesystems (EXDEV: /tmp tmpfs vs home) — fall back
- // to copy+unlink so the save works wherever the OS keeps its temp dir.
try {
- await (deps.renameFile ?? rename)(tempPath, result.filePath)
- } catch {
- await copyFile(tempPath, result.filePath)
- await (deps.unlinkFile ?? unlink)(tempPath).catch(() => undefined)
+ const result = await saveDialog({
+ defaultPath: suggestedName,
+ title: 'Save folder zip',
+ })
+ if (result.canceled || !result.filePath) {
+ await (deps.unlinkFile ?? unlink)(job.tempPath).catch(() => undefined)
+ jobs.delete(jobId)
+ return { saved: false, filePath: null, entryCount }
+ }
+ // rename fails across filesystems (EXDEV: /tmp tmpfs vs home) — fall back
+ // to copy+unlink so the save works wherever the OS keeps its temp dir.
+ try {
+ await (deps.renameFile ?? rename)(job.tempPath, result.filePath)
+ } catch {
+ await (deps.copyFile ?? copyFile)(job.tempPath, result.filePath)
+ await (deps.unlinkFile ?? unlink)(job.tempPath).catch(() => undefined)
+ }
+ jobs.delete(jobId)
+ return { saved: true, filePath: result.filePath, entryCount }
+ } catch (error) {
+ await destroyJob(job, deps)
+ throw error
}
- return { saved: true, filePath: result.filePath, entryCount }
}
/** Aborts a job: closes the temp file and deletes it. */
-export async function abortZipJob(jobId: string, deps: ZipStreamDeps = {}): Promise<void> {
+export async function abortZipJob(
+ jobId: string,
+ ownerId: string,
+ deps: ZipStreamDeps = {}
+): Promise<void> {
const job = jobs.get(jobId)
if (!job) return
- jobs.delete(jobId)
- job.writeChain = job.writeChain
- .then(async () => {
- await job.handle.close()
- })
- .catch(() => undefined)
- await job.writeChain
- await (deps.unlinkFile ?? unlink)(job.tempPath).catch(() => undefined)
+ if (job.ownerId !== ownerId) {
+ throw new Error(`ZIP job ${jobId} belongs to another window`)
+ }
+ await destroyJob(job, deps)
}
export function activeZipJobCount(): number {
diff --git a/desktop-app/src/ipc.ts b/desktop-app/src/ipc.ts
index 5fc3f970e..e018a1b44 100644
--- a/desktop-app/src/ipc.ts
+++ b/desktop-app/src/ipc.ts
@@ -19,7 +19,13 @@ import {
} from './chatStoreBinding.js'
import { GFS_DOWNLOAD_MAX_BYTES_CEILING } from './gfs/downloadLimits.js'
import { GFS_PREVIEW_MAX_BYTES } from './gfs/previewLimits.js'
-import { abortZipJob, appendZipEntry, finishZipJob, startZipJob } from './gfs/zipStream.js'
+import {
+ abortZipJob,
+ appendZipEntry,
+ appendZipEntryStreaming,
+ finishZipJob,
+ startZipJob,
+} from './gfs/zipStream.js'
import { assertSafeRouteSegment } from './pathSafety.js'
import {
PLUGIN_SDK_CAPABILITIES_CHANNEL,
@@ -257,6 +263,16 @@ export function assertTrustedSender(event: IpcMainInvokeEvent): void {
}
}
+/**
+ * The identity of the window that owns a ZIP job (R3-M2). A job is opened by
+ * one window and may only be driven by that window: without this, any renderer
+ * that got hold of a job id could append to, finish or abort another
+ * window's archive.
+ */
+function zipJobOwnerId(event: IpcMainInvokeEvent): string {
+ return String(event.sender?.id ?? 'unknown')
+}
+
type DesktopNotificationActionInput = {
action?: string
title?: string
@@ -579,12 +595,23 @@ export function registerIpcHandlers(service: AppService): void {
}
)
// Streamed, file-backed folder-zip assembly (R1-H2): entries append to a
- // main-process temp file, finish saves through a native dialog. All four
- // channels trust-check; append validates the entry name before any header is
- // written (R1-M2 defense in depth).
+ // main-process temp file, finish saves through a native dialog. All five
+ // channels trust-check.
+ //
+ // The MAIN process owns the guarantees here (the renderer is untrusted):
+ // - every entry name is validated as a canonical relative path BEFORE a
+ // byte of entry data is written (R3-M1);
+ // - the aggregate byte/entry budget, the ZIP32 bounds, the job's owner and
+ // the concurrency bounds are enforced here, not only in the renderer
+ // (R3-M2);
+ // - the job owns its handle and its temp file until the save completes
+ // (R3-M3).
+ //
+ // The job is bound to the window that opened it: another window cannot
+ // append to, finish or abort it.
ipcMain.handle('gfs:zipStream:start', async event => {
assertTrustedSender(event)
- return { jobId: await startZipJob() }
+ return { jobId: await startZipJob(zipJobOwnerId(event)) }
})
ipcMain.handle(
'gfs:zipStream:append',
@@ -598,20 +625,66 @@ export function registerIpcHandlers(service: AppService): void {
if (payload.bytes.byteLength > GFS_DOWNLOAD_MAX_BYTES_CEILING) {
throw new Error('zip entry exceeds the allowed maximum')
}
- const writtenName = await appendZipEntry(sanitizeString(payload.jobId), name, payload.bytes)
+ const writtenName = await appendZipEntry(
+ sanitizeString(payload.jobId),
+ zipJobOwnerId(event),
+ name,
+ payload.bytes
+ )
return { name: writtenName }
}
)
+ // The folder-zip transfer (R1-H2): the main process fetches the resource and
+ // writes it straight into the temp file, chunk by chunk. The payload never
+ // crosses the IPC boundary and never materializes as one buffer in either
+ // process — the renderer only learns the entry's name and size.
+ ipcMain.handle(
+ 'gfs:zipStream:appendFromUri',
+ async (
+ event,
+ payload: { jobId: string; name: string; uri: string; maxBytes: number; requestId?: string }
+ ) => {
+ assertTrustedSender(event)
+ const name = sanitizeString(payload?.name)
+ if (!name) throw new Error('zipStream appendFromUri requires an entry name')
+ const uri = sanitizeString(payload?.uri)
+ if (!uri) throw new Error('zipStream appendFromUri requires a resource URI')
+ const maxBytes = sanitizeOptionalPositiveInteger(payload?.maxBytes, 'maxBytes')
+ if (maxBytes === undefined) {
+ throw new Error('zipStream appendFromUri requires a positive maxBytes')
+ }
+ if (maxBytes > GFS_DOWNLOAD_MAX_BYTES_CEILING) {
+ throw new Error('zip entry exceeds the allowed maximum')
+ }
+ const requestId = payload?.requestId ? sanitizeString(payload.requestId) : undefined
+ const result = await runWithGfsAbortSignal(requestId, signal =>
+ appendZipEntryStreaming(
+ sanitizeString(payload.jobId),
+ zipJobOwnerId(event),
+ name,
+ async sink => {
+ await service.downloadGfsUriInto(uri, maxBytes, signal, chunk => sink.write(chunk))
+ },
+ {}
+ )
+ )
+ return { name: result.name, bytes: result.bytes }
+ }
+ )
ipcMain.handle(
'gfs:zipStream:finish',
async (event, payload: { jobId: string; suggestedName: string }) => {
assertTrustedSender(event)
- return finishZipJob(sanitizeString(payload.jobId), sanitizeString(payload.suggestedName))
+ return finishZipJob(
+ sanitizeString(payload.jobId),
+ zipJobOwnerId(event),
+ sanitizeString(payload.suggestedName)
+ )
}
)
ipcMain.handle('gfs:zipStream:abort', async (event, payload: { jobId: string }) => {
assertTrustedSender(event)
- await abortZipJob(sanitizeString(payload.jobId))
+ await abortZipJob(sanitizeString(payload.jobId), zipJobOwnerId(event))
return { aborted: true }
})
ipcMain.handle(
diff --git a/desktop-app/src/preload.ts b/desktop-app/src/preload.ts
index f7f976b07..fd653a3b6 100644
--- a/desktop-app/src/preload.ts
+++ b/desktop-app/src/preload.ts
@@ -185,6 +185,21 @@ const clerum = Object.freeze({
start: () => ipcRenderer.invoke('gfs:zipStream:start'),
append: (jobId: string, name: string, bytes: ArrayBuffer) =>
ipcRenderer.invoke('gfs:zipStream:append', { jobId, name, bytes }),
+ // The folder-zip transfer (R1-H2): the MAIN process fetches the
+ // resource and writes it into the archive chunk by chunk, so the payload
+ // never crosses this boundary. The walk's stop signal rides along as a
+ // requestId, exactly like the other cancellable GFS calls.
+ appendFromUri: (
+ jobId: string,
+ name: string,
+ uri: string,
+ options?: { maxBytes?: number; signal?: AbortSignal }
+ ) =>
+ cancellableGfsInvoke(
+ 'gfs:zipStream:appendFromUri',
+ { jobId, name, uri, maxBytes: options?.maxBytes },
+ options?.signal
+ ),
finish: (jobId: string, suggestedName: string) =>
ipcRenderer.invoke('gfs:zipStream:finish', { jobId, suggestedName }),
abort: (jobId: string) => ipcRenderer.invoke('gfs:zipStream:abort', { jobId }),
diff --git a/desktop-app/src/renderer.d.ts b/desktop-app/src/renderer.d.ts
index fdbb7c69f..29063598f 100644
--- a/desktop-app/src/renderer.d.ts
+++ b/desktop-app/src/renderer.d.ts
@@ -228,6 +228,17 @@ declare global {
zipStream: {
start: () => Promise<{ jobId: string }>
append: (jobId: string, name: string, bytes: ArrayBuffer) => Promise<{ name: string }>
+ /**
+ * Appends one entry by URI: the main process fetches the resource
+ * and writes it into the archive chunk by chunk, so the payload
+ * never crosses the IPC boundary (R1-H2).
+ */
+ appendFromUri: (
+ jobId: string,
+ name: string,
+ uri: string,
+ options?: { maxBytes?: number; signal?: AbortSignal }
+ ) => Promise<{ name: string; bytes: number }>
finish: (
jobId: string,
suggestedName: string
diff --git a/desktop-app/ui/src/hooks/domain/__tests__/composerMergeZipProperties.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/composerMergeZipProperties.test.tsx
index ff546cb87..4b7c410d6 100644
--- a/desktop-app/ui/src/hooks/domain/__tests__/composerMergeZipProperties.test.tsx
+++ b/desktop-app/ui/src/hooks/domain/__tests__/composerMergeZipProperties.test.tsx
@@ -4,6 +4,12 @@
* normalization rules the cancel-restore and folder-zip paths rely on. These
* complement the example tests: the examples pin behavior at the boundaries,
* the properties pin the invariants for arbitrary inputs.
+ *
+ * The property runs are deliberately LARGE: the merge and allocation rules
+ * interact (caps, dedupe, ordering, case folding), and a small sample proves
+ * little about a rule that only misbehaves in a rare combination. Every run
+ * starts from a VALID composer state, so the invariants are provable against
+ * states production can actually hold.
*/
import { describe, expect, it } from 'vitest'
import fc from 'fast-check'
@@ -11,12 +17,20 @@ import { FILE_REFERENCE_MAX_COUNT } from '@clerum/gfs-interaction-policy'
import { COMPOSER_MAX_IMAGE_ATTACHMENTS } from '@constants/attachments'
import { GFS_ZIP_MAX_SEGMENT_NAME_BYTES, sanitizeZipSegment } from '@lib/gfsFolderZip'
import type { ComposerImageAttachment, ComposerReferenceAttachment } from '@/uiTypes'
-import { entryNameFitsZipFields, finalizeEntryName } from '../../../../../src/gfs/zipEntryName'
+import { ZipEntryNameAllocator, entryNameFitsZipFields } from '../../../../../src/gfs/zipEntryName'
import {
mergeComposerImageAttachments,
mergeComposerReferenceAttachments,
} from '../useComposerAttachments'
+/**
+ * Tens of thousands of cases per property. The properties are small (arrays
+ * of short strings), so this costs seconds, not minutes — and it is the
+ * difference between "the invariant held for 80 samples" and "the invariant
+ * held for 25 000".
+ */
+const PROPERTY_RUNS = 25_000
+
const imageArbitrary = fc
.record({
id: fc.string({ minLength: 1, maxLength: 12 }),
@@ -114,7 +128,7 @@ describe('composer merge invariants (R1-M6)', () => {
expect(outcome.dropped).toBeLessThanOrEqual(notHeldIncoming.length)
}
),
- { numRuns: 80 }
+ { numRuns: PROPERTY_RUNS }
)
})
@@ -154,7 +168,7 @@ describe('composer merge invariants (R1-M6)', () => {
)
}
),
- { numRuns: 60 }
+ { numRuns: PROPERTY_RUNS }
)
})
@@ -180,7 +194,7 @@ describe('composer merge invariants (R1-M6)', () => {
expect(second.duplicates + second.dropped).toBe(incoming.length)
}
),
- { numRuns: 60 }
+ { numRuns: PROPERTY_RUNS }
)
})
@@ -203,7 +217,7 @@ describe('composer merge invariants (R1-M6)', () => {
expect(outcome.next.slice(0, existing.length)).toEqual(existing)
}
),
- { numRuns: 80 }
+ { numRuns: PROPERTY_RUNS }
)
})
@@ -226,7 +240,7 @@ describe('composer merge invariants (R1-M6)', () => {
expect(second.duplicates + second.dropped).toBe(incoming.length)
}
),
- { numRuns: 60 }
+ { numRuns: PROPERTY_RUNS }
)
})
})
@@ -243,22 +257,25 @@ describe('zip path normalization invariants (R1-M6)', () => {
)
expect(segment).not.toBe('.')
expect(segment).not.toBe('..')
+ // A Windows DEVICE name is not a name: `CON` is the console device.
+ expect(/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\.|$)/i.test(segment)).toBe(false)
}),
- { numRuns: 200 }
+ { numRuns: PROPERTY_RUNS }
)
})
- it('finalized entry names never collide case-folded and always fit the 16-bit fields', () => {
+ it('allocated entry names never collide case-folded and always fit the 16-bit fields', () => {
fc.assert(
fc.property(
fc.array(fc.string({ minLength: 1, maxLength: 24 }), { maxLength: 30 }),
names => {
- const usedFolded = new Set<string>()
+ const allocator = new ZipEntryNameAllocator()
const written: string[] = []
for (const name of names) {
- const finalized = finalizeEntryName(name, usedFolded)
- usedFolded.add(finalized.folded)
- written.push(finalized.name)
+ const plan = allocator.plan(name)
+ if (!plan.fits) continue
+ allocator.commit(plan)
+ written.push(plan.name)
}
const folded = new Set(written.map(name => name.toLowerCase()))
expect(folded.size).toBe(written.length)
@@ -266,7 +283,66 @@ describe('zip path normalization invariants (R1-M6)', () => {
for (const name of written) expect(entryNameFitsZipFields(name)).toBe(true)
}
),
- { numRuns: 60 }
+ { numRuns: PROPERTY_RUNS }
+ )
+ })
+
+ it('never lets a FILE and a DIRECTORY share a path (R3-M5)', () => {
+ // The invariant that keeps an archive valid on a case-insensitive
+ // extractor: no committed file may sit at a path another committed file
+ // implies as a directory.
+ fc.assert(
+ fc.property(
+ fc.array(
+ fc.array(fc.string({ minLength: 1, maxLength: 12 }), { minLength: 1, maxLength: 4 }),
+ { maxLength: 20 }
+ ),
+ paths => {
+ const allocator = new ZipEntryNameAllocator()
+ const committed: string[] = []
+ for (const segments of paths) {
+ const plan = allocator.plan(segments.join('/'))
+ if (!plan.fits) continue
+ allocator.commit(plan)
+ committed.push(plan.name)
+ }
+ const files = new Set(committed.map(name => name.toLowerCase()))
+ const directories = new Set<string>()
+ for (const name of committed) {
+ const parts = name.split('/')
+ parts.pop()
+ let current = ''
+ for (const part of parts) {
+ current = current === '' ? part : `${current}/${part}`
+ directories.add(current.toLowerCase())
+ }
+ }
+ for (const file of files) {
+ expect(directories.has(file)).toBe(false)
+ }
+ }
+ ),
+ { numRuns: PROPERTY_RUNS }
+ )
+ })
+
+ it('allocates deterministically: the same inputs give the same names', () => {
+ fc.assert(
+ fc.property(
+ fc.array(fc.string({ minLength: 1, maxLength: 16 }), { maxLength: 20 }),
+ names => {
+ const allocate = () => {
+ const allocator = new ZipEntryNameAllocator()
+ return names.map(name => {
+ const plan = allocator.plan(name)
+ if (plan.fits) allocator.commit(plan)
+ return plan.name
+ })
+ }
+ expect(allocate()).toEqual(allocate())
+ }
+ ),
+ { numRuns: PROPERTY_RUNS }
)
})
})
diff --git a/desktop-app/ui/src/lib/__tests__/gfsFolderZip.test.ts b/desktop-app/ui/src/lib/__tests__/gfsFolderZip.test.ts
index 108b20ac2..bdd08f80f 100644
--- a/desktop-app/ui/src/lib/__tests__/gfsFolderZip.test.ts
+++ b/desktop-app/ui/src/lib/__tests__/gfsFolderZip.test.ts
@@ -52,16 +52,28 @@ function folder(
}
}
+/**
+ * A producer for one resource: it answers with the entry's byte count, or
+ * throws the way the real producer would (a 403, a 413, a 500).
+ */
+type ZipProducer = (uri: string, options?: { maxBytes?: number }) => Promise<{ bytes: number }>
+
export interface RecordedZipStream {
- appended: Array<{ name: string; bytes: ArrayBuffer }>
+ appended: Array<{ name: string; uri: string; bytes: number }>
finishedWith: Array<{ suggestedName: string }>
abortedJobs: string[]
deps: import('../gfsFolderZip').GfsZipStreamDeps
}
-/** File-backed stream fake: records appends, finishes "saved" to a path. */
-function recordedZipStream(options: { saved?: boolean } = {}): RecordedZipStream {
- const appended: Array<{ name: string; bytes: ArrayBuffer }> = []
+/**
+ * File-backed stream fake: records appends, finishes "saved" to a path. The
+ * archive is assembled in the MAIN process in production; the renderer only
+ * hands over a name and a URI, so the fake records the same two things.
+ */
+function recordedZipStream(
+ options: { saved?: boolean; producers?: Record<string, ZipProducer> } = {}
+): RecordedZipStream {
+ const appended: Array<{ name: string; uri: string; bytes: number }> = []
const finishedWith: Array<{ suggestedName: string }> = []
const abortedJobs: string[] = []
let jobCounter = 0
@@ -71,10 +83,20 @@ function recordedZipStream(options: { saved?: boolean } = {}): RecordedZipStream
abortedJobs,
deps: {
start: vi.fn(async () => ({ jobId: `job-${++jobCounter}` })),
- append: vi.fn(async (jobId: string, name: string, bytes: ArrayBuffer) => {
- void jobId
- appended.push({ name, bytes })
- }),
+ appendFromUri: vi.fn(
+ async (
+ jobId: string,
+ name: string,
+ uri: string,
+ requestOptions?: { maxBytes?: number }
+ ) => {
+ void jobId
+ const producer = options.producers?.[uri]
+ const result = producer ? await producer(uri, requestOptions) : { bytes: uri.length }
+ appended.push({ name, uri, bytes: result.bytes })
+ return { name, bytes: result.bytes }
+ }
+ ),
finish: vi.fn(async (jobId: string, suggestedName: string) => {
void jobId
finishedWith.push({ suggestedName })
@@ -97,13 +119,10 @@ function streamEntryNames(stream: RecordedZipStream): string[] {
function depsFor(
pages: Record<string, Array<{ items: GfsZipChildItem[]; nextCursor: string | null }>>,
- downloads: Record<
- string,
- (uri: string, options?: { maxBytes?: number }) => Promise<{ bytes: ArrayBuffer }>
- > = {},
+ producers: Record<string, ZipProducer> = {},
streamOptions: { saved?: boolean } = {}
): GfsFolderZipDeps & { zipStreamRecord: RecordedZipStream } {
- const stream = recordedZipStream(streamOptions)
+ const stream = recordedZipStream({ ...streamOptions, producers })
return {
listChildren: vi.fn(async (resourceId: string, _drive: string, cursor?: string) => {
const pageList = pages[resourceId]
@@ -113,11 +132,6 @@ function depsFor(
if (!page) throw new Error(`no page ${index} for ${resourceId}`)
return { items: page.items, nextCursor: page.nextCursor }
}),
- download: vi.fn(async (uri: string, options?: { maxBytes?: number }) => {
- const produce = downloads[uri]
- if (produce) return produce(uri, options)
- return { bytes: bytesOf(uri) }
- }),
zipStream: stream.deps,
// Spacing itself has a dedicated manual-clock test below the walk; here it
// is a no-op so the orchestration tests run instantly.
@@ -127,10 +141,6 @@ function depsFor(
}
}
-function bytesOf(text: string): ArrayBuffer {
- return new TextEncoder().encode(text).buffer as ArrayBuffer
-}
-
describe('createGfsReadThrottle', () => {
it('spaces requests to the 120/min budget with the injected clock', async () => {
const clock = manualClock()
@@ -203,6 +213,79 @@ describe('createGfsFolderZip', () => {
).toEqual([1, 2, 3])
})
+ it('never carries payload bytes through the renderer (R1-H2)', async () => {
+ // The renderer hands the main process a NAME and a URI; the payload is
+ // fetched and written in main, chunk by chunk. The walk therefore never
+ // asks the renderer for bytes at all.
+ const deps = depsFor({
+ root: [{ items: [folder({ resourceId: 'big', name: 'big.bin' })], nextCursor: null }],
+ })
+ await createGfsFolderZip({ resourceId: 'root', drive: 'main', name: 'Docs' }, { deps })
+
+ const append = deps.zipStreamRecord.deps.appendFromUri as ReturnType<typeof vi.fn>
+ expect(append).toHaveBeenCalledTimes(1)
+ const [jobId, name, uri, options] = append.mock.calls[0] as [
+ string,
+ string,
+ string,
+ { maxBytes?: number; signal?: AbortSignal } | undefined,
+ ]
+ expect(name).toBe('Docs/big.bin')
+ expect(uri).toBe('gfs://main/big')
+ expect(options?.maxBytes).toBeGreaterThan(0)
+ // No ArrayBuffer anywhere in the call: the payload stays in main.
+ expect(JSON.stringify(append.mock.calls)).not.toContain('ArrayBuffer')
+ expect(jobId).toMatch(/^job-/)
+ })
+
+ it('keeps the renderer free of payload bytes at the near-limit ceiling (R1-H2)', async () => {
+ // The near-limit memory claim: even at the full ceiling the renderer only
+ // hands over a NAME and a URI. The producer's byte count is the biggest
+ // number the renderer ever sees, and it is a COUNT, not a payload.
+ const seenBounds: Array<number | undefined> = []
+ const deps = depsFor(
+ {
+ root: [
+ {
+ items: [
+ folder({ resourceId: 'big', name: 'big.bin', bytes: undefined as unknown as number }),
+ ],
+ nextCursor: null,
+ },
+ ],
+ },
+ {
+ 'gfs://main/big': async (_uri: string, options?: { maxBytes?: number }) => {
+ seenBounds.push(options?.maxBytes)
+ return { bytes: 64 * 1024 * 1024 }
+ },
+ }
+ )
+
+ const result = await createGfsFolderZip(
+ { resourceId: 'root', drive: 'main', name: 'Big' },
+ { deps }
+ )
+
+ // The transfer was bounded by the WHOLE remaining budget, and the walk
+ // finished with the archive saved.
+ expect(seenBounds).toEqual([512 * 1024 * 1024])
+ expect(result.fileCount).toBe(1)
+ expect(result.saved).toBe(true)
+ expect(result.savedPath).toBe('/saved/Big.zip')
+ // The renderer never received the bytes: the only thing it passed on is
+ // the name, the URI and the bound.
+ const append = deps.zipStreamRecord.deps.appendFromUri as ReturnType<typeof vi.fn>
+ const [, , , options] = append.mock.calls[0] as [
+ string,
+ string,
+ string,
+ { maxBytes?: number } | undefined,
+ ]
+ expect(options?.maxBytes).toBe(512 * 1024 * 1024)
+ expect(JSON.stringify(append.mock.calls)).not.toContain('ArrayBuffer')
+ })
+
it('skips unreadable rows and 403 downloads with visible reasons', async () => {
const deps = depsFor(
{
@@ -224,7 +307,6 @@ describe('createGfsFolderZip', () => {
],
},
{
- 'gfs://main/ok': async () => ({ bytes: bytesOf('fine') }),
'gfs://main/denied': async () => {
throw new Error('gfs download failed: 403 httpStatus=403 forbidden')
},
@@ -255,7 +337,6 @@ describe('createGfsFolderZip', () => {
}
throw new Error("Error invoking remote method 'gfs:listChildren': Error: httpStatus=403")
}),
- download: async () => ({ bytes: bytesOf('x') }),
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
zipStream: recordedZipStream().deps,
@@ -345,7 +426,7 @@ describe('createGfsFolderZip', () => {
)
// Bounded work: the refusal fires inside the FIRST listing page.
expect(deps.listChildren).toHaveBeenCalledTimes(1)
- expect(deps.download).not.toHaveBeenCalled()
+ expect(deps.zipStreamRecord.deps.appendFromUri).not.toHaveBeenCalled()
})
it('forwards the stop signal to the producer bridge on both call kinds (R1-M1)', async () => {
@@ -358,9 +439,13 @@ describe('createGfsFolderZip', () => {
_options?: { signal?: AbortSignal }
) => new Promise<GfsZipChildrenPage>(() => undefined)
)
- const download = vi.fn(async () => ({ bytes: new ArrayBuffer(4) }))
+ const appendFromUri = vi.fn(
+ async () => new Promise<{ name: string; bytes: number }>(() => undefined)
+ )
const previousClerum = (window as { clerum?: unknown }).clerum
- ;(window as { clerum?: unknown }).clerum = { gfs: { listChildren, download } }
+ ;(window as { clerum?: unknown }).clerum = {
+ gfs: { listChildren, zipStream: { appendFromUri } },
+ }
try {
const walk = createGfsFolderZip(
@@ -384,15 +469,18 @@ describe('createGfsFolderZip', () => {
})
it('aborts the stream job on any failure path so no temp file survives (R1-H2)', async () => {
- const stream = recordedZipStream()
+ const stream = recordedZipStream({
+ producers: {
+ 'gfs://main/doomed': async () => {
+ throw new Error('gfs download failed: 500 httpStatus=500')
+ },
+ },
+ })
const deps: GfsFolderZipDeps = {
listChildren: vi.fn(async () => ({
items: [folder({ resourceId: 'doomed', name: 'doomed.txt' })],
nextCursor: null,
})),
- download: async () => {
- throw new Error('gfs download failed: 500 httpStatus=500')
- },
zipStream: stream.deps,
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
@@ -407,14 +495,17 @@ describe('createGfsFolderZip', () => {
expect(stream.abortedJobs).toHaveLength(1)
// Stop mid-walk takes the same cleanup path.
- const stopStream = recordedZipStream()
+ const stopStream = recordedZipStream({
+ producers: {
+ 'gfs://main/first': () => new Promise<{ bytes: number }>(() => undefined),
+ },
+ })
const controller = new AbortController()
const stopDeps: GfsFolderZipDeps = {
listChildren: vi.fn(async () => ({
items: [folder({ resourceId: 'first', name: 'first.txt' })],
nextCursor: null,
})),
- download: () => new Promise<{ bytes: ArrayBuffer }>(() => undefined),
zipStream: stopStream.deps,
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
@@ -500,8 +591,8 @@ describe('createGfsFolderZip', () => {
{ deps }
).catch(error => error)
- // The only file lived under the pruned subtree: nothing archivable, and
- // the skip notice explains why with a path a human can read.
+ // The only file lived under the pruned subtree: nothing archivable, and the
+ // skip notice explains why with a path a human can read.
expect(result).toBeInstanceOf(GfsFolderZipEmptyError)
const skipped = (result as GfsFolderZipEmptyError).skipped
expect(skipped[0]?.reason).toBe('Path too long')
@@ -511,7 +602,7 @@ describe('createGfsFolderZip', () => {
const listingCalls = vi.mocked(deps.listChildren).mock.calls.length
expect(listingCalls).toBeLessThanOrEqual(110)
expect(listingCalls).toBeGreaterThanOrEqual(90)
- expect(deps.download).not.toHaveBeenCalled()
+ expect(deps.zipStreamRecord.deps.appendFromUri).not.toHaveBeenCalled()
})
it('refuses when the actual downloaded bytes exceed the ceiling', async () => {
@@ -524,7 +615,7 @@ describe('createGfsFolderZip', () => {
},
],
},
- { 'gfs://main/lied': async () => ({ bytes: new ArrayBuffer(2048) }) }
+ { 'gfs://main/lied': async () => ({ bytes: 2048 }) }
)
await expect(
@@ -555,7 +646,7 @@ describe('createGfsFolderZip', () => {
],
},
{
- 'gfs://main/ghost': async (uri: string, options?: { maxBytes?: number }) => {
+ 'gfs://main/ghost': async (_uri: string, options?: { maxBytes?: number }) => {
expect(options?.maxBytes).toBe(1024)
throw new Error('gfs download exceeds the 1024-byte limit httpStatus=413')
},
@@ -607,23 +698,32 @@ describe('createGfsFolderZip', () => {
{
'gfs://main/fill': async (_uri: string, options?: { maxBytes?: number }) => {
seenBounds.push(options?.maxBytes)
- return { bytes: new ArrayBuffer(1024) }
+ return { bytes: 1024 }
},
'gfs://main/after-a': async (_uri: string, options?: { maxBytes?: number }) => {
seenBounds.push(options?.maxBytes)
- return { bytes: new ArrayBuffer(1) }
+ return { bytes: 1 }
},
'gfs://main/after-b': async (_uri: string, options?: { maxBytes?: number }) => {
seenBounds.push(options?.maxBytes)
- return { bytes: new ArrayBuffer(1) }
+ return { bytes: 1 }
},
}
)
- const result = await createGfsFolderZip(
+ // R1-M6: the walk's outcome is CAPTURED, so a regression fails as an
+ // assertion ("the walk did not finish cleanly") instead of as an
+ // unhandled rejection thrown before the first expectation.
+ const outcome = await createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Exact' },
{ deps, limits: { maxTotalBytes: 1024 } }
+ ).then(
+ value => ({ ok: true as const, value }),
+ error => ({ ok: false as const, error })
)
+ expect(outcome.ok).toBe(true)
+ if (!outcome.ok) return
+ const result = outcome.value
expect(seenBounds).toEqual([1024])
expect(result.fileCount).toBe(1)
@@ -653,11 +753,11 @@ describe('createGfsFolderZip', () => {
{
'gfs://main/half-a': async (_uri: string, options?: { maxBytes?: number }) => {
seenMaxBytes.push(options?.maxBytes)
- return { bytes: new ArrayBuffer(512) }
+ return { bytes: 512 }
},
'gfs://main/half-b': async (_uri: string, options?: { maxBytes?: number }) => {
seenMaxBytes.push(options?.maxBytes)
- return { bytes: new ArrayBuffer(512) }
+ return { bytes: 512 }
},
}
)
@@ -681,7 +781,6 @@ describe('createGfsFolderZip', () => {
throw new Error('gfs children failed: 429 httpStatus=429 retryAfterSeconds=2')
return { items: [], nextCursor: null }
}),
- download: async () => ({ bytes: new ArrayBuffer(0) }),
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
zipStream: recordedZipStream().deps,
@@ -699,11 +798,9 @@ describe('createGfsFolderZip', () => {
const controller = new AbortController()
const deps: GfsFolderZipDeps = {
listChildren,
- download: async () => ({ bytes: new ArrayBuffer(0) }),
- zipStream: recordedZipStream().deps,
- // The first slot never frees: the walk parks here until the stop lands.
throttle: { acquire: () => new Promise<void>(() => undefined) },
sleep: async () => undefined,
+ zipStream: recordedZipStream().deps,
}
const walk = createGfsFolderZip(
@@ -718,16 +815,17 @@ describe('createGfsFolderZip', () => {
it('stops during a hung download instead of waiting out the request (M3)', async () => {
const controller = new AbortController()
- const deps: GfsFolderZipDeps = {
- listChildren: vi.fn(async () => ({
- items: [folder({ resourceId: 'hung', name: 'hung.txt' })],
- nextCursor: null,
- })),
- download: () => new Promise<{ bytes: ArrayBuffer }>(() => undefined),
- throttle: { acquire: async () => undefined },
- sleep: async () => undefined,
- zipStream: recordedZipStream().deps,
- }
+ const deps = depsFor(
+ {
+ root: [
+ {
+ items: [folder({ resourceId: 'hung', name: 'hung.txt' })],
+ nextCursor: null,
+ },
+ ],
+ },
+ { 'gfs://main/hung': () => new Promise<{ bytes: number }>(() => undefined) }
+ )
const walk = createGfsFolderZip(
{ resourceId: 'root', drive: 'main', name: 'Stopped' },
@@ -750,7 +848,6 @@ describe('createGfsFolderZip', () => {
// walk would park here forever and a Stop could never land.
return new Promise<GfsZipChildrenPage>(() => undefined)
}),
- download: async () => ({ bytes: new ArrayBuffer(0) }),
throttle: { acquire: async () => undefined },
sleep: async () => undefined,
zipStream: recordedZipStream().deps,
@@ -770,18 +867,21 @@ describe('createGfsFolderZip', () => {
})
it('aborts on a non-permission download failure instead of a holey archive', async () => {
- const deps: GfsFolderZipDeps = {
- listChildren: vi.fn(async () => ({
- items: [folder({ resourceId: 'flaky', name: 'flaky.txt' })],
- nextCursor: null,
- })),
- download: async () => {
- throw new Error('gfs download failed: 500 httpStatus=500')
+ const deps = depsFor(
+ {
+ root: [
+ {
+ items: [folder({ resourceId: 'flaky', name: 'flaky.txt' })],
+ nextCursor: null,
+ },
+ ],
},
- throttle: { acquire: async () => undefined },
- sleep: async () => undefined,
- zipStream: recordedZipStream().deps,
- }
+ {
+ 'gfs://main/flaky': async () => {
+ throw new Error('gfs download failed: 500 httpStatus=500')
+ },
+ }
+ )
await expect(
createGfsFolderZip({ resourceId: 'root', drive: 'main', name: 'Broken' }, { deps })
@@ -828,6 +928,62 @@ describe('createGfsFolderZip', () => {
expect(result.fileName).toBe('Weird_Name_.zip')
})
+ it('escapes Windows device names so the archive extracts on Windows', async () => {
+ // `CON`, `NUL` and `COM1` are the console device on Windows: an entry
+ // with that name either fails to extract or writes to the device.
+ const deps = depsFor({
+ root: [
+ {
+ items: [
+ folder({ resourceId: 'd1', name: 'CON' }),
+ folder({ resourceId: 'd2', name: 'nul.txt' }),
+ folder({ resourceId: 'd3', name: 'COM1' }),
+ folder({ resourceId: 'd4', name: 'ordinary.txt' }),
+ ],
+ nextCursor: null,
+ },
+ ],
+ })
+ const result = await createGfsFolderZip(
+ { resourceId: 'root', drive: 'main', name: 'Devices' },
+ { deps }
+ )
+ const names = streamEntryNames(deps.zipStreamRecord)
+ expect(names.sort()).toEqual(
+ ['Devices/_COM1', 'Devices/_CON', 'Devices/_nul.txt', 'Devices/ordinary.txt'].sort()
+ )
+ // The SAVED archive's own name is escaped too: `CON.zip` is the device.
+ expect(result.fileName).toBe('Devices.zip')
+ })
+
+ it('resolves a case-insensitive file/directory conflict (R3-M5)', async () => {
+ // `Report/child.txt` and a sibling FILE named `report` conflict at a path
+ // COMPONENT on a case-insensitive filesystem, even though their full
+ // names differ.
+ const deps = depsFor({
+ root: [
+ {
+ items: [
+ folder({ resourceId: 'dir', name: 'Report', kind: 'directory' }),
+ folder({ resourceId: 'file', name: 'report' }),
+ ],
+ nextCursor: null,
+ },
+ ],
+ dir: [{ items: [folder({ resourceId: 'child', name: 'child.txt' })], nextCursor: null }],
+ })
+ const result = await createGfsFolderZip(
+ { resourceId: 'root', drive: 'main', name: 'Root' },
+ { deps }
+ )
+ const names = streamEntryNames(deps.zipStreamRecord)
+ expect(names).toHaveLength(2)
+ // The sibling file was renamed away from the directory's name.
+ expect(names).toContain('Root/Report/child.txt')
+ expect(names).toContain('Root/report (2)')
+ expect(result.skipped).toEqual([])
+ })
+
it('caps entry-name length so the 16-bit ZIP name fields cannot truncate (L4)', async () => {
// 70 000 ASCII bytes would overflow ZIP's uint16 name length and corrupt
// the archive; the segment must be cut under the documented ceiling.
@@ -859,7 +1015,7 @@ describe('createGfsFolderZip', () => {
const emojiDeps = depsFor({
root: [
{
- items: [folder({ resourceId: 'emoji', name: `${'😀'.repeat(600)}x` })],
+ items: [folder({ resourceId: 'emoji', name: `${'\u{1F600}'.repeat(600)}x` })],
nextCursor: null,
},
],
@@ -931,10 +1087,9 @@ describe('createGfsFolderZip', () => {
if (attempts === 1) throw new Error('429 httpStatus=429 retryAfterSeconds=0')
return { items: [], nextCursor: null }
}),
- download: async () => ({ bytes: new ArrayBuffer(0) }),
- zipStream: recordedZipStream().deps,
throttle: { acquire },
sleep: async () => undefined,
+ zipStream: recordedZipStream().deps,
}
// An empty retry answer short-circuits as "no downloadable files"; the
diff --git a/desktop-app/ui/src/lib/gfsFolderZip.ts b/desktop-app/ui/src/lib/gfsFolderZip.ts
index 5b809a38d..6797c85b2 100644
--- a/desktop-app/ui/src/lib/gfsFolderZip.ts
+++ b/desktop-app/ui/src/lib/gfsFolderZip.ts
@@ -21,11 +21,9 @@
* archive.
*/
import { isRateLimited, parseHttpStatus, parseRetryAfterSeconds } from '@lib/gfsGrantErrors'
-import {
- entryNameFitsZipFields,
- finalizeEntryName,
- foldEntryName,
-} from '../../../src/gfs/zipEntryName'
+import { ZipEntryNameAllocator, foldEntryName } from '../../../src/gfs/zipEntryName'
+import { escapeReservedWindowsDeviceName } from '../../../src/gfs/zipEntryPath'
+import { ZIP_MAX_ENTRIES, ZIP_MAX_TOTAL_BYTES } from '../../../src/gfs/zipLimits'
/**
* Client-side pacing for the walk, a deliberate conservative margin: the
@@ -37,12 +35,14 @@ export const GFS_ZIP_READS_PER_MINUTE = 120
/**
* Refuse before buffering: total bytes across the folder. 512 MiB bounds the
* streamed archive's temp-file size and each transfer's producer-side bound;
- * renderer peak memory is ONE in-flight transfer (≤ this cap), independent of
- * folder size (spec: round-2 extensions, streamed assembly).
+ * the RENDERER holds no payload bytes at all (the main process fetches and
+ * writes each transfer chunk by chunk), so peak memory is one chunk in main
+ * plus the archive's central-directory metadata (spec: round-2 extensions,
+ * streamed assembly; R1-H2).
*/
-export const GFS_ZIP_MAX_TOTAL_BYTES = 512 * 1024 * 1024
+export const GFS_ZIP_MAX_TOTAL_BYTES = ZIP_MAX_TOTAL_BYTES
/** Refuse before buffering: total file entries across the folder. */
-export const GFS_ZIP_MAX_ENTRIES = 2000
+export const GFS_ZIP_MAX_ENTRIES = ZIP_MAX_ENTRIES
export interface GfsZipSkippedEntry {
path: string
@@ -130,7 +130,19 @@ export interface GfsZipChildrenPage {
export interface GfsZipStreamDeps {
start(): Promise<{ jobId: string }>
- append(jobId: string, name: string, bytes: ArrayBuffer): Promise<unknown>
+ /**
+ * Appends one entry by handing the MAIN process the resource URI: the
+ * payload is fetched and written into the archive chunk by chunk, so it
+ * never crosses the IPC boundary and never materializes as one buffer
+ * (R1-H2). `options.maxBytes` is the producer-side bound for this
+ * transfer; `options.signal` stops the producer-side fetch.
+ */
+ appendFromUri(
+ jobId: string,
+ name: string,
+ uri: string,
+ options?: { maxBytes?: number; signal?: AbortSignal }
+ ): Promise<{ name: string; bytes: number }>
finish(
jobId: string,
suggestedName: string
@@ -149,15 +161,6 @@ export interface GfsFolderZipDeps {
cursor?: string,
options?: { signal?: AbortSignal }
): Promise<GfsZipChildrenPage>
- /**
- * Downloads one file. `options.maxBytes` is the producer-side bound for the
- * transfer (R1-H2): the bounded fetch rejects before an over-budget body
- * materializes in either process. `options.signal` as above.
- */
- download(
- uri: string,
- options?: { maxBytes?: number; signal?: AbortSignal }
- ): Promise<{ bytes: ArrayBuffer }>
/**
* Streamed, file-backed archive assembly in the main process (R1-H2): one
* append per downloaded file, one finish at the end, abort cleans the temp
@@ -265,7 +268,12 @@ export function sanitizeZipSegment(name: string): string {
GFS_ZIP_MAX_SEGMENT_NAME_BYTES
)
if (!cleaned || cleaned === '.' || cleaned === '..') return 'unnamed'
- return cleaned
+ // The escape happens AFTER the truncation (a truncated name can end up
+ // reserved) and is re-trimmed, so the segment still fits the byte ceiling.
+ return truncateToUtf8Bytes(
+ escapeReservedWindowsDeviceName(cleaned),
+ GFS_ZIP_MAX_SEGMENT_NAME_BYTES
+ )
}
function sanitizeFileName(name: string): string {
@@ -276,6 +284,15 @@ function sanitizeFileName(name: string): string {
return cleaned || 'folder'
}
+/** The saved archive's own file name, escaped from Windows device names. */
+function sanitizeArchiveFileName(name: string): string {
+ const cleaned = sanitizeFileName(name)
+ const separator = cleaned.lastIndexOf('.')
+ const stem = separator > 0 ? cleaned.slice(0, separator) : cleaned
+ const extension = separator > 0 ? cleaned.slice(separator) : ''
+ return `${escapeReservedWindowsDeviceName(stem)}${extension}`
+}
+
export async function createGfsFolderZip(
folder: GfsZipFolderSource,
options: CreateGfsFolderZipOptions = {}
@@ -291,18 +308,15 @@ export async function createGfsFolderZip(
window.clerum.gfs.listChildren(resourceId, drive, cursor, {
signal: requestOptions?.signal ?? options.signal,
}))
- const download: GfsFolderZipDeps['download'] =
- options.deps?.download ??
- ((uri, requestOptions) =>
- window.clerum.gfs.download(uri, {
- maxBytes: requestOptions?.maxBytes,
- signal: requestOptions?.signal ?? options.signal,
- }))
// Default lazily reaches the bridge so a walk that never appends (aborted
// early, refused at planning) does not require window.clerum to exist.
const zipStream: GfsFolderZipDeps['zipStream'] = options.deps?.zipStream ?? {
start: () => window.clerum.gfs.zipStream.start(),
- append: (jobId, name, bytes) => window.clerum.gfs.zipStream.append(jobId, name, bytes),
+ appendFromUri: (jobId, name, uri, requestOptions) =>
+ window.clerum.gfs.zipStream.appendFromUri(jobId, name, uri, {
+ maxBytes: requestOptions?.maxBytes,
+ signal: requestOptions?.signal ?? options.signal,
+ }),
finish: (jobId, suggestedName) => window.clerum.gfs.zipStream.finish(jobId, suggestedName),
abort: jobId => window.clerum.gfs.zipStream.abort(jobId),
}
@@ -443,11 +457,20 @@ export async function createGfsFolderZip(
if (files.length === 0) throw new GfsFolderZipEmptyError(folder.name, skipped)
// ── Phase 2: throttled downloads streamed into the main-process archive. ──
- // The renderer holds ONE in-flight transfer at a time (R1-H2); any failure
- // aborts the stream job so the temp file never outlives the walk.
+ // The renderer holds NO payload bytes at all (R1-H2): each transfer is
+ // fetched and written by the main process, chunk by chunk, straight into the
+ // archive's temp file. Any failure aborts the stream job so the temp file
+ // never outlives the walk.
const { jobId } = await zipStream.start()
let archivedCount = 0
- const usedFoldedNames = new Set<string>()
+ const nameAllocator = new ZipEntryNameAllocator()
+ // Reserve the DIRECTORY paths the archive will imply BEFORE any file name
+ // is allocated (R3-M5): a file that shares a name with one of them is
+ // renamed, never the directory — and the outcome no longer depends on the
+ // order the listing happened to return the entries in.
+ for (const directoryPath of impliedDirectoryPaths(files)) {
+ nameAllocator.reserveDirectory(directoryPath)
+ }
let addedBytes = 0
try {
for (const [index, file] of files.entries()) {
@@ -471,14 +494,27 @@ export async function createGfsFolderZip(
currentPath: file.path,
})
await withAbort(throttle.acquire())
- let bytes: ArrayBuffer
+ // Finalize the entry name HERE (case-insensitive collision suffix, and
+ // the path-component reservation that keeps a file and a directory from
+ // sharing a name on a case-insensitive filesystem) and validate the
+ // FINALIZED name against the 16-bit ZIP fields before it is sent: a
+ // name that only overflows after suffixing is a visible skip, never a
+ // truncated header (R1-M2, R3-M5, spec: round-2).
+ const plan = nameAllocator.plan(file.path)
+ if (!plan.fits) {
+ skipped.push({ path: shortenForNotice(file.path), reason: 'Path too long' })
+ continue
+ }
+ let appended: { name: string; bytes: number }
try {
- // R1-H2: bound the transfer producer-side by the remaining budget so
- // an over-limit body (dishonest or missing declared size) is rejected
- // before it materializes in the renderer; the receipt check below
- // stays as the backstop.
- bytes = (await withRateLimitRetry(() => download(file.uri, { maxBytes: remainingBytes })))
- .bytes
+ // R1-H2: the transfer is bounded producer-side by the remaining
+ // budget, so an over-limit body is rejected before it is written.
+ appended = await withRateLimitRetry(() =>
+ zipStream.appendFromUri(jobId, plan.name, file.uri, {
+ maxBytes: remainingBytes,
+ signal,
+ })
+ )
} catch (error) {
if (isFolderZipAbortError(error)) throw error
const message = toMessage(error)
@@ -494,8 +530,8 @@ export async function createGfsFolderZip(
}
throw error
}
- const data = new Uint8Array(bytes)
- addedBytes += data.length
+ nameAllocator.commit(plan)
+ addedBytes += appended.bytes
if (addedBytes > maxTotalBytes) {
// Defensive backstop: the producer-side bound makes this unreachable
// unless the bound itself was ignored — fail loudly, not silently.
@@ -503,17 +539,6 @@ export async function createGfsFolderZip(
`"${folder.name}" exceeded the ${formatZipBytes(maxTotalBytes)} folder-zip limit while downloading. Download smaller subfolders individually.`
)
}
- // Finalize the entry name HERE (case-insensitive collision suffix) and
- // validate the FINALIZED name against the 16-bit ZIP fields before any
- // header is written: a name that only overflows after suffixing is a
- // visible skip, never a truncated header (R1-M2, spec: round-2).
- const finalized = finalizeEntryName(file.path, usedFoldedNames)
- if (!entryNameFitsZipFields(finalized.name)) {
- skipped.push({ path: shortenForNotice(file.path), reason: 'Path too long' })
- continue
- }
- usedFoldedNames.add(finalized.folded)
- await zipStream.append(jobId, finalized.name, bytes)
archivedCount += 1
}
@@ -529,7 +554,7 @@ export async function createGfsFolderZip(
filesAdded: archivedCount,
currentPath: null,
})
- const fileName = `${sanitizeFileName(folder.name)}.zip`
+ const fileName = `${sanitizeArchiveFileName(folder.name)}.zip`
const saved = await zipStream.finish(jobId, fileName)
return {
saved: saved.saved,
@@ -547,6 +572,24 @@ export async function createGfsFolderZip(
export { foldEntryName }
+/**
+ * Every directory path the archive will imply, in first-seen order: each
+ * file's path minus its last segment, and every ancestor of that.
+ */
+function impliedDirectoryPaths(files: Array<{ path: string }>): string[] {
+ const paths = new Set<string>()
+ for (const file of files) {
+ const segments = file.path.split('/')
+ segments.pop()
+ let current = ''
+ for (const segment of segments) {
+ current = current === '' ? segment : `${current}/${segment}`
+ paths.add(current)
+ }
+ }
+ return [...paths]
+}
+
function formatZipBytes(bytes: number): string {
if (bytes >= 1024 * 1024 * 1024) return `${Math.round(bytes / (1024 * 1024 * 1024))} GiB`
if (bytes >= 1024 * 1024) return `${Math.round(bytes / (1024 * 1024))} MiB`
diff --git a/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx b/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx
index 4ac307697..837dd720c 100644
--- a/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx
+++ b/desktop-app/ui/src/pages/__tests__/FilesPage.test.tsx
@@ -3311,15 +3311,19 @@ describe('FilesPage', () => {
}),
])
)
- const download = vi.fn(async () => ({ bytes: new Uint8Array([1, 2, 3, 4]).buffer }))
const pushToast = vi.fn()
const click = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {})
const appendedNames: string[] = []
const zipStream = {
start: vi.fn(async () => ({ jobId: 'job-1' })),
- append: vi.fn(async (_jobId: string, name: string) => {
- appendedNames.push(name)
- }),
+ // The renderer hands over a NAME and a URI: the main process fetches
+ // the payload and writes it into the archive (R1-H2).
+ appendFromUri: vi.fn(
+ async (_jobId: string, name: string, _uri: string, _options?: { maxBytes?: number }) => {
+ appendedNames.push(name)
+ return { name, bytes: 4 }
+ }
+ ),
finish: vi.fn(async (_jobId: string, suggestedName: string) => ({
saved: true,
filePath: `/saved/${suggestedName}`,
@@ -3329,7 +3333,7 @@ describe('FilesPage', () => {
}
Object.defineProperty(window, 'clerum', {
configurable: true,
- value: { gfs: { listChildren, download, zipStream } },
+ value: { gfs: { listChildren, zipStream } },
})
hookMock.useGfsBrowserController.mockReturnValue({
...baseController(),
@@ -3374,10 +3378,17 @@ describe('FilesPage', () => {
expect(listChildren).toHaveBeenCalledWith('folder-1', 'main', undefined, {
signal: expect.any(AbortSignal),
})
- expect(download).toHaveBeenCalledWith('gfs://main/doc-1', {
- maxBytes: 512 * 1024 * 1024,
- signal: expect.any(AbortSignal),
- })
+ // The payload never reaches the renderer: the walk hands the main
+ // process a name and a URI, and the main process does the transfer.
+ expect(zipStream.appendFromUri).toHaveBeenCalledWith(
+ 'job-1',
+ 'Assets/plan.md',
+ 'gfs://main/doc-1',
+ {
+ maxBytes: 512 * 1024 * 1024,
+ signal: expect.any(AbortSignal),
+ }
+ )
// The streamed save path: the entry reached the main-process writer and
// finish saved the archive — no renderer anchor download for zips.
expect(appendedNames).toEqual(['Assets/plan.md'])
@@ -3403,12 +3414,12 @@ describe('FilesPage', () => {
}),
])
)
- const download = vi.fn(async () => ({ bytes: new ArrayBuffer(0) }))
+ const appendFromUri = vi.fn(async () => ({ name: 'x', bytes: 0 }))
const pushToast = vi.fn()
const click = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {})
Object.defineProperty(window, 'clerum', {
configurable: true,
- value: { gfs: { listChildren, download } },
+ value: { gfs: { listChildren, zipStream: { appendFromUri } } },
})
hookMock.useGfsBrowserController.mockReturnValue({
...baseController(),
@@ -3444,7 +3455,7 @@ describe('FilesPage', () => {
})
expect(screen.queryByTestId('gfs-zip-progress')).toBeNull()
- expect(download).not.toHaveBeenCalled()
+ expect(appendFromUri).not.toHaveBeenCalled()
expect(click).not.toHaveBeenCalled()
expect(pushToast).toHaveBeenCalledWith(
expect.stringContaining('exceeds the 512 MiB folder-zip limit'),
@@ -3455,12 +3466,12 @@ describe('FilesPage', () => {
it('tells the user an empty folder has nothing to zip instead of saving an empty archive', async () => {
vi.useFakeTimers()
const listChildren = vi.fn(async () => ({ items: [], nextCursor: null }))
- const download = vi.fn(async () => ({ bytes: new ArrayBuffer(0) }))
+ const appendFromUri = vi.fn(async () => ({ name: 'x', bytes: 0 }))
const pushToast = vi.fn()
const click = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {})
Object.defineProperty(window, 'clerum', {
configurable: true,
- value: { gfs: { listChildren, download } },
+ value: { gfs: { listChildren, zipStream: { appendFromUri } } },
})
hookMock.useGfsBrowserController.mockReturnValue({
...baseController(),
@@ -3499,7 +3510,7 @@ describe('FilesPage', () => {
expect(listChildren).toHaveBeenCalledWith('folder-1', 'main', undefined, {
signal: expect.any(AbortSignal),
})
- expect(download).not.toHaveBeenCalled()
+ expect(appendFromUri).not.toHaveBeenCalled()
expect(click).not.toHaveBeenCalled()
expect(pushToast).toHaveBeenCalledWith('"Empty" has no downloadable files.', 'info')
})
@@ -3514,18 +3525,17 @@ describe('FilesPage', () => {
}),
])
)
- const download = vi.fn(async () => ({ bytes: new Uint8Array([1, 2, 3, 4]).buffer }))
const pushToast = vi.fn()
const click = vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {})
const zipStream = {
start: vi.fn(async () => ({ jobId: 'job-1' })),
- append: vi.fn(async () => undefined),
+ appendFromUri: vi.fn(async () => ({ name: 'x', bytes: 4 })),
finish: vi.fn(async () => ({ saved: true, filePath: '/saved/x.zip', entryCount: 1 })),
abort: vi.fn(async () => ({ aborted: true })),
}
Object.defineProperty(window, 'clerum', {
configurable: true,
- value: { gfs: { listChildren, download, zipStream } },
+ value: { gfs: { listChildren, zipStream } },
})
const folderRow = {
resourceId: 'folder-1',