Verify secretstream TAG_FINAL and write downloads atomically (closes #1)

streamDecrypt discarded the secretstream tag, so a download cut short
by a dropped connection decrypted cleanly up to the last whole chunk
and was returned as a success. downloadFile and downloadThumbnail then
wrote straight to the destination, and runBackup skips any existing
non-empty file, so a truncated original was treated as complete on
every subsequent run and never repaired.

streamDecrypt now tracks the tag of each chunk it pulls and throws if
the stream ended on anything other than TAG_FINAL, or if the body
carried no chunks at all — Ente always emits at least one chunk, as
encryptBlob shows by producing a TAG_FINAL chunk even for zero-length
plaintext, so an empty body is a failed transfer rather than an empty
file. Both error messages say the stream was truncated.

Plaintext is now staged in a temporary sibling file (same directory,
so the rename cannot cross a filesystem boundary; random UUID suffix,
so concurrent downloads cannot collide) and renamed into place only
after the whole stream has decrypted and verified. On any error the
temporary file is removed and the original error is rethrown
unchanged, so a cleanup failure never masks the real diagnosis. A
failed download therefore leaves the destination exactly as it was.

Public signatures and the DownloadResult shape are unchanged.

The download layer keeps its no-direct-sodium-import shape: TAG_FINAL
is re-exported from src/crypto as STREAM_TAG_FINAL, which decryptBlob
now uses too. Also moves the pullStreamChunk doc comment off
decryptBlob, where it had been sitting.

Retry and backoff remain out of scope; they stay the Next Step in
TODO.md and are tracked separately.

test/download/download.test.ts

@@ -45,6 +45,7 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
 import sodium from "libsodium-wrappers-sumo";
 import { beforeAll, afterAll, describe, expect, it } from "vitest";
 import { init, toBase64, STREAM_CHUNK_SIZE } from "../../src/crypto/index.js";
@@ -188,6 +189,42 @@ const mockFetchForBody = (body: Uint8Array) => {
     return fake as typeof globalThis.fetch;
 };
 
+/**
+ * Encrypt a body consisting of one chunk that is *not* tagged TAG_FINAL.
+ *
+ * This is the cheap way to present a stream that ended without its final
+ * chunk: the downloader pulls it, authenticates it, and finds the stream
+ * over on a TAG_MESSAGE chunk — the same terminal condition as a large file
+ * whose last chunk was lost, without paying for a 4 MiB fixture. The
+ * multi-chunk fixture above covers the realistic wire shape; this one is
+ * used where the test is really about what happens on disk afterwards.
+ */
+const encryptNonFinalBody = (
+    plaintext: Uint8Array,
+    key: Uint8Array,
+): { header: Uint8Array; ciphertext: Uint8Array } => {
+    const push = sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
+    const ciphertext = sodium.crypto_secretstream_xchacha20poly1305_push(
+        push.state,
+        plaintext,
+        null,
+        sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE,
+    );
+    return { header: push.header, ciphertext };
+};
+
+/**
+ * Compare file contents by digest rather than with `toEqual`. Vitest's deep
+ * equality walks multi-megabyte buffers byte by byte, which costs seconds on
+ * the 4 MiB fixtures; a digest comparison is exact and effectively free.
+ */
+const expectSameBytes = (actual: Uint8Array, expected: Uint8Array): void => {
+    expect(actual.length).toBe(expected.length);
+    expect(createHash("sha256").update(actual).digest("hex")).toBe(
+        createHash("sha256").update(expected).digest("hex"),
+    );
+};
+
 /**
  * A multi-chunk fixture shared by the truncation tests. Building it costs a
  * few MiB of encryption, so it is built once: one full 4 MiB `TAG_MESSAGE`
@@ -291,7 +328,7 @@ describe("downloadFile", () => {
         const result = await downloadFile(api, file, outPath);
 
         expect(result.bytesWritten).toBe(100_000);
-        expect(readFileSync(outPath)).toEqual(Buffer.from(plaintext));
+        expectSameBytes(readFileSync(outPath), plaintext);
     });
 
     it("decrypts a body that spans several secretstream chunks", async () => {
@@ -311,9 +348,7 @@ describe("downloadFile", () => {
         const result = await downloadFile(api, file, outPath);
 
         expect(result.bytesWritten).toBe(multiChunk.plaintext.length);
-        expect(readFileSync(outPath)).toEqual(
-            Buffer.from(multiChunk.plaintext),
-        );
+        expectSameBytes(readFileSync(outPath), multiChunk.plaintext);
     });
 });
 
@@ -402,15 +437,18 @@ describe.each(entryPoints)(
             // The caller's contract: if the promise rejects, the destination
             // path does not exist. Nothing downstream should ever have to guess
             // whether a leftover file is complete.
-            const truncatedBody = multiChunk.body.slice(
-                0,
-                multiChunk.finalChunkOffset,
-            );
-            const { api, file } = fixtureFor(
-                multiChunkKey,
-                multiChunk.header,
-                truncatedBody,
+            //
+            // The body here is a single chunk that was never tagged TAG_FINAL,
+            // which puts the downloader in exactly the terminal state a lost
+            // last chunk produces, without the cost of a 4 MiB fixture. What
+            // this test is really about is the state of the filesystem after
+            // the rejection.
+            const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+            const { header, ciphertext } = encryptNonFinalBody(
+                sodium.randombytes_buf(256),
+                key,
             );
+            const { api, file } = fixtureFor(key, header, ciphertext);
             const dir = freshDir();
             const outPath = join(dir, "absent.bin");
 
@@ -458,15 +496,12 @@ describe.each(entryPoints)(
             const existing = new TextEncoder().encode(
                 "previously downloaded, known-good contents",
             );
-            const truncatedBody = multiChunk.body.slice(
-                0,
-                multiChunk.finalChunkOffset,
-            );
-            const { api, file } = fixtureFor(
-                multiChunkKey,
-                multiChunk.header,
-                truncatedBody,
+            const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+            const { header, ciphertext } = encryptNonFinalBody(
+                sodium.randombytes_buf(256),
+                key,
             );
+            const { api, file } = fixtureFor(key, header, ciphertext);
             const dir = freshDir();
             const outPath = join(dir, "existing.bin");
             writeFileSync(outPath, existing);