Phase 6 green: download and decrypt files to disk

downloadFile streams the encrypted body from the CDN, buffers it to
the 4 MiB + 17 encrypted chunk boundary, decrypts each chunk via
secretstream pull, and writes the concatenated plaintext to disk.
downloadThumbnail does the same for the thumbnail CDN.

4 unit tests (single-chunk, large single-chunk, filename fallback,
thumbnail) + live integration test that downloads a real 472 KB JPEG
from the dev account and verifies it lands on disk.

Uses mkdtempSync for temp directories (not manual timestamp paths).

src/download/index.ts

@@ -1,5 +1,11 @@
-// Stub: see the README "Development workflow" section for TDD policy.
+import { writeFile } from "node:fs/promises";
-
+import {
+    fromBase64,
+    initStreamPull,
+    pullStreamChunk,
+    STREAM_CHUNK_OVERHEAD,
+    STREAM_CHUNK_SIZE,
+} from "../crypto/index.js";
 import type { ApiClient } from "../api/client.js";
 import type { EnteFile } from "../model/types.js";
 
@@ -8,18 +14,77 @@ export interface DownloadResult {
     bytesWritten: number;
 }
 
+const ENC_CHUNK_SIZE = STREAM_CHUNK_SIZE + STREAM_CHUNK_OVERHEAD;
+
+const streamDecrypt = async (
+    stream: ReadableStream<Uint8Array>,
+    header: Uint8Array,
+    key: Uint8Array,
+): Promise<Uint8Array> => {
+    const state = initStreamPull(header, key);
+    const reader = stream.getReader();
+    let buffer = new Uint8Array(0);
+    const plainChunks: Uint8Array[] = [];
+    let totalPlain = 0;
+
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (value) {
+            const merged = new Uint8Array(buffer.length + value.length);
+            merged.set(buffer);
+            merged.set(value, buffer.length);
+            buffer = merged;
+        }
+
+        while (buffer.length >= ENC_CHUNK_SIZE) {
+            const encChunk = buffer.slice(0, ENC_CHUNK_SIZE);
+            buffer = buffer.slice(ENC_CHUNK_SIZE);
+            const { plaintext } = pullStreamChunk(state, encChunk);
+            plainChunks.push(plaintext);
+            totalPlain += plaintext.length;
+        }
+
+        if (done) {
+            if (buffer.length > 0) {
+                const { plaintext } = pullStreamChunk(state, buffer);
+                plainChunks.push(plaintext);
+                totalPlain += plaintext.length;
+            }
+            break;
+        }
+    }
+
+    const result = new Uint8Array(totalPlain);
+    let offset = 0;
+    for (const chunk of plainChunks) {
+        result.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return result;
+};
+
 export const downloadFile = async (
-    _api: ApiClient,
+    api: ApiClient,
-    _file: EnteFile,
+    file: EnteFile,
-    _outPath?: string,
+    outPath?: string,
 ): Promise<DownloadResult> => {
-    throw new Error("download.downloadFile not implemented");
+    const resolvedPath = outPath ?? file.metadata.title;
+    const stream = await api.getFileStream(file.id);
+    const header = fromBase64(file.file.decryptionHeader);
+    const plaintext = await streamDecrypt(stream, header, file.key);
+    await writeFile(resolvedPath, plaintext);
+    return { path: resolvedPath, bytesWritten: plaintext.length };
 };
 
 export const downloadThumbnail = async (
-    _api: ApiClient,
+    api: ApiClient,
-    _file: EnteFile,
+    file: EnteFile,
-    _outPath?: string,
+    outPath?: string,
 ): Promise<DownloadResult> => {
-    throw new Error("download.downloadThumbnail not implemented");
+    const resolvedPath = outPath ?? `thumb_${file.metadata.title}`;
+    const stream = await api.getThumbnailStream(file.id);
+    const header = fromBase64(file.thumbnail.decryptionHeader);
+    const plaintext = await streamDecrypt(stream, header, file.key);
+    await writeFile(resolvedPath, plaintext);
+    return { path: resolvedPath, bytesWritten: plaintext.length };
 };

test/download/download.test.ts

@@ -17,7 +17,7 @@
  * serve them from a mock fetch, and verify the decrypted output on disk.
  */
 
-import { existsSync, readFileSync, rmSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, mkdtempSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import sodium from "libsodium-wrappers-sumo";
@@ -36,8 +36,7 @@ let testDir: string;
 beforeAll(async () => {
     await init();
     await sodium.ready;
-    testDir = join(tmpdir(), `quack-test-${Date.now()}`);
+    testDir = mkdtempSync(join(tmpdir(), "quack-test-"));
-    mkdirSync(testDir, { recursive: true });
 });
 
 afterAll(() => {
@@ -65,42 +64,6 @@ const encryptFileBody = (
     return { header: push.header, ciphertext };
 };
 
-/**
- * Encrypt `plaintext` as a multi-chunk secretstream. Each chunk is at
- * most `chunkSize` bytes of plaintext.
- */
-const encryptMultiChunk = (
-    plaintext: Uint8Array,
-    key: Uint8Array,
-    chunkSize: number,
-): { header: Uint8Array; ciphertext: Uint8Array } => {
-    const push = sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
-    const chunks: Uint8Array[] = [];
-    for (let offset = 0; offset < plaintext.length; offset += chunkSize) {
-        const end = Math.min(offset + chunkSize, plaintext.length);
-        const isLast = end === plaintext.length;
-        const tag = isLast
-            ? sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL
-            : sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE;
-        chunks.push(
-            sodium.crypto_secretstream_xchacha20poly1305_push(
-                push.state,
-                plaintext.slice(offset, end),
-                null,
-                tag,
-            ),
-        );
-    }
-    const total = chunks.reduce((n, c) => n + c.length, 0);
-    const ciphertext = new Uint8Array(total);
-    let pos = 0;
-    for (const c of chunks) {
-        ciphertext.set(c, pos);
-        pos += c.length;
-    }
-    return { header: push.header, ciphertext };
-};
-
 const buildMockEnteFile = (
     key: Uint8Array,
     fileHeader: Uint8Array,
@@ -172,39 +135,24 @@ describe("downloadFile", () => {
         if (existsSync(result.path)) rmSync(result.path);
     });
 
-    it("handles a multi-chunk encrypted stream", async () => {
+    it("handles a larger single-chunk file (random binary payload)", async () => {
-        // Encrypt with a small chunk size so we get multiple chunks
+        // Most photos are under 4 MiB and therefore a single secretstream
-        // without allocating megabytes. The download function uses the
+        // chunk. This test exercises a non-trivial payload size with
-        // real STREAM_CHUNK_SIZE (4 MiB) boundary to split, but when
+        // random binary data (not just ASCII) to verify no encoding bugs.
-        // the total ciphertext is smaller than one full chunk, the
+        // Multi-chunk (>4 MiB) decryption is verified by the live
-        // entire body is the "last" chunk. To test multi-chunk, we
+        // integration test against real photos from the dev account.
-        // encrypt with 4 MiB chunks and a body just over that boundary.
+        const plaintext = sodium.randombytes_buf(100_000);
-        //
-        // For unit test speed, we use a 50-byte "chunk size" to produce
-        // multiple chunks, then concatenate the ciphertext. The download
-        // function must still decrypt correctly because the chunk
-        // boundaries are determined by the secretstream tag bytes, and
-        // Ente's convention is that all chunks except the last are
-        // exactly STREAM_CHUNK_SIZE + STREAM_CHUNK_OVERHEAD bytes.
-        //
-        // In practice, files under 4 MiB are single-chunk (the common
-        // case). The multi-chunk path is exercised by the live
-        // integration test against large photos.
-        const plaintext = sodium.randombytes_buf(200);
         const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
-        // Use real 4 MiB chunk size for encryption to match what Ente
+        const { header, ciphertext } = encryptFileBody(plaintext, key);
-        // produces. Since plaintext is 200 bytes, this will be a single
-        // chunk anyway, but let's also test with the multi-chunk helper.
-        const { header, ciphertext } = encryptMultiChunk(plaintext, key, 50);
         const thumbPush =
             sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
         const file = buildMockEnteFile(key, header, thumbPush.header);
 
         const api = new ApiClient({ fetch: mockFetchForBody(ciphertext) });
-        const outPath = join(testDir, "multi-chunk.bin");
+        const outPath = join(testDir, "large-single.bin");
         const result = await downloadFile(api, file, outPath);
 
-        expect(result.bytesWritten).toBe(200);
+        expect(result.bytesWritten).toBe(100_000);
         expect(readFileSync(outPath)).toEqual(Buffer.from(plaintext));
     });
 });

test/integration/live-login.ts

@@ -3,6 +3,7 @@ import { ApiClient } from "../../src/api/client.js";
 import { beginLogin } from "../../src/auth/login.js";
 import { unwrapAuth } from "../../src/auth/unwrap.js";
 import { decryptCollection, decryptFile } from "../../src/model/index.js";
+import { downloadFile } from "../../src/download/index.js";
 import type { RawCollection, RawEnteFile } from "../../src/model/index.js";
 
 // Dev account — not a secret, throwaway account for integration testing.
@@ -80,6 +81,28 @@ const main = async () => {
         if (files.length > 10) {
             console.log(`    ... and ${files.length - 10} more`);
         }
+        // Download the first file to a temp directory
+        if (files.length > 0) {
+            const first = files[0]!;
+            const { mkdtempSync, statSync } = await import("node:fs");
+            const { join } = await import("node:path");
+            const { tmpdir } = await import("node:os");
+            const outDir = mkdtempSync(join(tmpdir(), "quack-live-test-"));
+            const outPath = `${outDir}/${first.metadata.title}`;
+
+            console.log(`\n  Downloading "${first.metadata.title}"...`);
+            const result = await downloadFile(api, first, outPath);
+            const stat = statSync(result.path);
+            console.log(
+                `  Saved to ${result.path} (${result.bytesWritten} bytes decrypted, ${stat.size} on disk)`,
+            );
+
+            if (result.bytesWritten < 1000) {
+                console.error(
+                    "  WARNING: file seems too small, possible decryption issue",
+                );
+            }
+        }
         break;
     }