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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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 = 65535diff --git a/desktop-app/src/gfs/zipStream.ts b/desktop-app/src/gfs/zipStream.tsindex 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 = 0x04034b50const CENTRAL_DIRECTORY_SIGNATURE = 0x02014b50@@ -27,6 +50,7 @@ const UTF8_FLAG = 0x0800const STORED_METHOD = 0const CRC32_POLYNOMIAL = 0xedb88320+const CRC32_INIT = 0xfffffffflet 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 = crcfor (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: stringtempPath: stringhandle: 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 openunlinkFile?: typeof unlinkrenameFile?: typeof rename+ copyFile?: typeof copyFileshowSaveDialog?: typeof dialog.showSaveDialogtempDir?: 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.tempPathtry {- 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 = writeOffsetawait 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.tsindex 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?: stringtitle?: 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.tsindex 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.tsindex 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: stringdiff --git a/desktop-app/ui/src/hooks/domain/__tests__/composerMergeZipProperties.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/composerMergeZipProperties.test.tsxindex 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.tsindex 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 } = {}): RecordedZipStreamabortedJobs,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 jobIdfinishedWith.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).skippedexpect(skipped[0]?.reason).toBe('Path too long')@@ -511,7 +602,7 @@ describe('createGfsFolderZip', () => {const listingCalls = vi.mocked(deps.listChildren).mock.calls.lengthexpect(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.valueexpect(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"; thediff --git a/desktop-app/ui/src/lib/gfsFolderZip.ts b/desktop-app/ui/src/lib/gfsFolderZip.tsindex 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_ENTRIESexport 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 = 0try {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 errorconst 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.bytesif (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.tsxindex 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',