sneak
8a200be8a7
All checks were successful
check / check (push) Successful in 22s
Rework against review findings on the branch. Test runtime (B1): the suite's cost was never the 4 MiB fixture, it was filling that fixture from the CSPRNG. sodium.randombytes_buf goes through the wasm wrapper a byte at a time and takes ~20s for 4 MiB, against ~108ms to encrypt the same buffer. Fixture content is not load-bearing anywhere in the file — only length and tag are — so payloads now come from a seeded LCG instead, which also makes them deterministic and reproducible as the README asks. A seeded generator rather than a constant fill, so a downloader that reordered or repeated chunks would still be caught. make test goes from over the 30s cap in script/test (it was failing outright, then rerunning verbose) back to 8.96s, against 10.02s on main. Atomic write coverage (B2): every failure the suite injected originated in streamDecrypt, which runs before anything is written, so no test observed a temp file existing or being cleaned up and the catch block in writeAtomic was dead code. rename is now intercepted in the test file, which adds two cases per entry point: one asserting the staged file exists at rename time and is a sibling of the destination, and one failing the rename itself so the cleanup path runs with a temp file genuinely on disk. Deleting writeAtomic in favour of a plain writeFile now turns the suite red. TAG_FINAL (M1): STREAM_TAG_FINAL was a hardcoded 3 plus a test to detect drift. The premise was right — libsodium attaches its constants inside ready.then(...), so an eager module-level read binds undefined — but a lazy read works, and decryptBlob was doing exactly that before. Replaced with streamTagFinal(), which reads the library's own value at call time. The drift test is repurposed to pin the accessor against the tag observed on a real final chunk, which fails if it is ever made eager again. Partial trailing chunk (M2): a transfer that stopped mid-chunk surfaced as "authentication failed", which reads as corruption and sends the user after the wrong problem. A final chunk that arrived in full always authenticates, so trailing bytes that do not are reported as the truncation they almost always are, with the authentication failure kept as the error's cause. Poly1305 cannot separate a partial chunk from a corrupt one, so the message names both possibilities; a corrupt whole chunk mid-stream is still reported as an authentication failure, and both are now tested. The pre-existing test that wrote its output to the process working directory, i.e. the repo root, now writes into the test's temp directory.
758 lines
32 KiB
TypeScript
758 lines
32 KiB
TypeScript
/**
|
|
* Tests for `downloadFile` and `downloadThumbnail`.
|
|
*
|
|
* These functions combine the ApiClient's streaming download with the
|
|
* secretstream pull decryption to recover the plaintext file content and
|
|
* write it to disk.
|
|
*
|
|
* The encrypted body returned by the CDN is a concatenation of
|
|
* secretstream ciphertext chunks. Each chunk is at most
|
|
* `STREAM_CHUNK_SIZE + STREAM_CHUNK_OVERHEAD` bytes (4 MiB + 17 bytes).
|
|
* The download function buffers incoming network data, splits it on the
|
|
* chunk boundary, and feeds each piece to `pullStreamChunk`.
|
|
*
|
|
* Two contracts are load-bearing for anyone using this library as a backup
|
|
* tool, and both are documented by the tests below:
|
|
*
|
|
* 1. **Truncation is an error, never a short file.** Only the final chunk of
|
|
* a secretstream carries `TAG_FINAL`. A download cut short by a dropped
|
|
* connection still decrypts cleanly up to the last whole chunk, so without
|
|
* an explicit `TAG_FINAL` check a truncated body is indistinguishable from
|
|
* a complete one. `streamDecrypt` therefore refuses to return unless the
|
|
* stream ended on `TAG_FINAL`, and the error says the stream was truncated.
|
|
* A transfer that stopped part-way through a chunk is reported the same
|
|
* way, since a final chunk that arrived in full always authenticates.
|
|
*
|
|
* 2. **The destination path is written atomically.** Plaintext goes to a
|
|
* temporary sibling file first and is `rename`d into place only after the
|
|
* whole stream has decrypted and verified. A caller that sees no exception
|
|
* can rely on the destination containing the complete, authenticated file;
|
|
* a caller that sees an exception can rely on the destination being
|
|
* untouched — whatever was there before is still there, byte for byte, and
|
|
* no partial file has appeared. This matters because `runBackup` skips any
|
|
* existing non-empty file, so a partial write would be treated as complete
|
|
* forever after. The staging file and the rename are observed directly (see
|
|
* the `rename` hook below), not inferred from an empty directory.
|
|
*
|
|
* These tests build synthetic encrypted files using sodium's push API,
|
|
* serve them from a mock fetch, and verify the decrypted output on disk.
|
|
*/
|
|
|
|
import {
|
|
existsSync,
|
|
readdirSync,
|
|
readFileSync,
|
|
rmSync,
|
|
mkdtempSync,
|
|
writeFileSync,
|
|
} from "node:fs";
|
|
import { dirname, join } from "node:path";
|
|
import { tmpdir } from "node:os";
|
|
import { createHash } from "node:crypto";
|
|
import sodium from "libsodium-wrappers-sumo";
|
|
import {
|
|
beforeAll,
|
|
beforeEach,
|
|
afterAll,
|
|
describe,
|
|
expect,
|
|
it,
|
|
vi,
|
|
} from "vitest";
|
|
import { init, toBase64, STREAM_CHUNK_SIZE } from "../../src/crypto/index.js";
|
|
import { ApiClient } from "../../src/api/client.js";
|
|
import { downloadFile, downloadThumbnail } from "../../src/download/index.js";
|
|
import type { EnteFile, FileMetadata } from "../../src/model/types.js";
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Test helpers
|
|
// ---------------------------------------------------------------------------
|
|
|
|
/**
|
|
* `rename` is intercepted so that the tests can observe — and fail — the
|
|
* final step of the atomic write.
|
|
*
|
|
* Every other failure in this file is injected inside `streamDecrypt`, which
|
|
* runs before anything is written to disk. Those tests therefore cannot tell
|
|
* an atomic write from a plain `writeFile`: under both, nothing was ever
|
|
* created, so an empty directory proves nothing about cleanup. This hook is
|
|
* what closes that gap. It records each rename the downloader performs,
|
|
* including whether the source existed at that moment (i.e. that the staged
|
|
* temp file really was written), and can be told to fail the rename so the
|
|
* cleanup path runs with a temp file genuinely on disk.
|
|
*
|
|
* `vi.hoisted` is required: `vi.mock` factories are hoisted above the imports,
|
|
* so a plain module-level `const` would still be in its temporal dead zone by
|
|
* the time the factory runs.
|
|
*/
|
|
const renameHook = vi.hoisted(() => ({
|
|
calls: [] as { from: string; to: string; sourceExisted: boolean }[],
|
|
failWith: null as Error | null,
|
|
}));
|
|
|
|
vi.mock("node:fs/promises", async (importOriginal) => {
|
|
const actual = await importOriginal<typeof import("node:fs/promises")>();
|
|
const { existsSync: sourceExists } = await import("node:fs");
|
|
return {
|
|
...actual,
|
|
rename: async (from: string, to: string): Promise<void> => {
|
|
renameHook.calls.push({
|
|
from,
|
|
to,
|
|
sourceExisted: sourceExists(from),
|
|
});
|
|
if (renameHook.failWith !== null) {
|
|
throw renameHook.failWith;
|
|
}
|
|
await actual.rename(from, to);
|
|
},
|
|
};
|
|
});
|
|
|
|
beforeEach(() => {
|
|
renameHook.calls.length = 0;
|
|
renameHook.failWith = null;
|
|
});
|
|
|
|
let testDir: string;
|
|
|
|
beforeAll(async () => {
|
|
await init();
|
|
await sodium.ready;
|
|
testDir = mkdtempSync(join(tmpdir(), "quak-test-"));
|
|
});
|
|
|
|
afterAll(() => {
|
|
if (testDir && existsSync(testDir)) {
|
|
rmSync(testDir, { recursive: true, force: true });
|
|
}
|
|
});
|
|
|
|
/**
|
|
* Deterministic stand-in for random test payloads.
|
|
*
|
|
* Fixture *content* is never load-bearing here — the assertions turn on
|
|
* length, framing, and the secretstream tag — but it must not be a constant
|
|
* fill either, or a downloader that reordered or repeated chunks would still
|
|
* produce the expected bytes. A seeded linear congruential generator gives
|
|
* both: byte patterns that differ across every offset and seed, reproducible
|
|
* on any machine, which is what the README asks of fixtures.
|
|
*
|
|
* It is also the difference between a fast suite and a broken one.
|
|
* `sodium.randombytes_buf` goes through the wasm wrapper a byte at a time and
|
|
* costs roughly 20 seconds for the 4 MiB chunk below — about two hundred
|
|
* times what it costs to encrypt the same buffer, and on its own enough to
|
|
* push `make test` past the 30-second cap in `script/test`. This loop fills
|
|
* 4 MiB in a few milliseconds.
|
|
*/
|
|
const patternBytes = (length: number, seed: number): Uint8Array => {
|
|
const out = new Uint8Array(length);
|
|
let x = seed >>> 0;
|
|
for (let i = 0; i < length; i++) {
|
|
// Numerical Recipes' LCG constants; the high byte is used because
|
|
// the low bits of an LCG have short periods.
|
|
x = (Math.imul(x, 1664525) + 1013904223) >>> 0;
|
|
out[i] = (x >>> 24) & 0xff;
|
|
}
|
|
return out;
|
|
};
|
|
|
|
/**
|
|
* Encrypt `plaintext` as a secretstream file body (single chunk with
|
|
* TAG_FINAL). Returns the key, header, and ciphertext that the mock CDN
|
|
* will serve.
|
|
*/
|
|
const encryptFileBody = (
|
|
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_FINAL,
|
|
);
|
|
return { header: push.header, ciphertext };
|
|
};
|
|
|
|
/**
|
|
* Encrypt a body that spans more than one secretstream chunk, the way the
|
|
* server does for files larger than the 4 MiB plaintext chunk size.
|
|
*
|
|
* Framing matters here: the downloader splits the byte stream on fixed
|
|
* `STREAM_CHUNK_SIZE + STREAM_CHUNK_OVERHEAD` boundaries, so every chunk
|
|
* except the last must carry exactly `STREAM_CHUNK_SIZE` plaintext bytes.
|
|
* Only the last chunk is tagged `TAG_FINAL`; the leading ones are
|
|
* `TAG_MESSAGE`.
|
|
*
|
|
* Returns the header, the concatenated body, the plaintext it decrypts to,
|
|
* and `finalChunkOffset` — the byte offset at which the `TAG_FINAL` chunk
|
|
* begins, so a test can slice it off to simulate a connection that dropped
|
|
* before the end of the file.
|
|
*/
|
|
const encryptMultiChunkBody = (
|
|
key: Uint8Array,
|
|
leadingChunks: number,
|
|
finalChunkPlainSize: number,
|
|
): {
|
|
header: Uint8Array;
|
|
body: Uint8Array;
|
|
plaintext: Uint8Array;
|
|
finalChunkOffset: number;
|
|
} => {
|
|
const push = sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
|
|
const cipherParts: Uint8Array[] = [];
|
|
const plainParts: Uint8Array[] = [];
|
|
|
|
for (let i = 0; i < leadingChunks; i++) {
|
|
const plain = patternBytes(STREAM_CHUNK_SIZE, i + 1);
|
|
plainParts.push(plain);
|
|
cipherParts.push(
|
|
sodium.crypto_secretstream_xchacha20poly1305_push(
|
|
push.state,
|
|
plain,
|
|
null,
|
|
sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE,
|
|
),
|
|
);
|
|
}
|
|
|
|
const finalPlain = patternBytes(finalChunkPlainSize, leadingChunks + 1);
|
|
plainParts.push(finalPlain);
|
|
const finalCipher = sodium.crypto_secretstream_xchacha20poly1305_push(
|
|
push.state,
|
|
finalPlain,
|
|
null,
|
|
sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL,
|
|
);
|
|
|
|
const finalChunkOffset = cipherParts.reduce((n, c) => n + c.length, 0);
|
|
cipherParts.push(finalCipher);
|
|
|
|
return {
|
|
header: push.header,
|
|
body: concat(cipherParts),
|
|
plaintext: concat(plainParts),
|
|
finalChunkOffset,
|
|
};
|
|
};
|
|
|
|
const concat = (parts: Uint8Array[]): Uint8Array => {
|
|
const total = parts.reduce((n, p) => n + p.length, 0);
|
|
const out = new Uint8Array(total);
|
|
let offset = 0;
|
|
for (const p of parts) {
|
|
out.set(p, offset);
|
|
offset += p.length;
|
|
}
|
|
return out;
|
|
};
|
|
|
|
const buildMockEnteFile = (
|
|
key: Uint8Array,
|
|
fileHeader: Uint8Array,
|
|
thumbHeader: Uint8Array,
|
|
): EnteFile => ({
|
|
id: 999,
|
|
collectionID: 1,
|
|
ownerID: 1,
|
|
key,
|
|
metadata: {
|
|
title: "test-photo.jpg",
|
|
fileType: "image",
|
|
creationTime: 0,
|
|
modificationTime: 0,
|
|
} as FileMetadata,
|
|
file: { decryptionHeader: toBase64(fileHeader) },
|
|
thumbnail: { decryptionHeader: toBase64(thumbHeader) },
|
|
updationTime: 0,
|
|
});
|
|
|
|
const mockFetchForBody = (body: Uint8Array) => {
|
|
const fake = async (): Promise<Response> =>
|
|
new Response(body, { status: 200 });
|
|
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: one full 4 MiB
|
|
* `TAG_MESSAGE` chunk followed by a small `TAG_FINAL` chunk. It is built once
|
|
* and shared because encrypting 4 MiB costs about 100ms. Its plaintext is
|
|
* generated rather than drawn from the CSPRNG, which is what keeps that
|
|
* encryption the whole cost of the fixture.
|
|
*/
|
|
let multiChunk: ReturnType<typeof encryptMultiChunkBody>;
|
|
let multiChunkKey: Uint8Array;
|
|
|
|
beforeAll(() => {
|
|
multiChunkKey = sodium.crypto_secretstream_xchacha20poly1305_keygen();
|
|
multiChunk = encryptMultiChunkBody(multiChunkKey, 1, 1024);
|
|
});
|
|
|
|
/**
|
|
* Build an EnteFile plus ApiClient whose file *and* thumbnail streams both
|
|
* serve `body` under `header`. The download path under test is otherwise
|
|
* identical for the two, so every truncation/atomicity case below runs
|
|
* against both entry points from a single fixture.
|
|
*/
|
|
const fixtureFor = (
|
|
key: Uint8Array,
|
|
header: Uint8Array,
|
|
body: Uint8Array,
|
|
): { api: ApiClient; file: EnteFile } => ({
|
|
api: new ApiClient({ fetch: mockFetchForBody(body) }),
|
|
file: buildMockEnteFile(key, header, header),
|
|
});
|
|
|
|
// The two entry points share `streamDecrypt` and the atomic-write wrapper,
|
|
// so the contract tests are written once and run against both.
|
|
const entryPoints = [
|
|
{ name: "downloadFile", download: downloadFile },
|
|
{ name: "downloadThumbnail", download: downloadThumbnail },
|
|
];
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Tests
|
|
// ---------------------------------------------------------------------------
|
|
|
|
describe("downloadFile", () => {
|
|
it("downloads, decrypts, and writes a single-chunk file", async () => {
|
|
const plaintext = new TextEncoder().encode(
|
|
"Hello from quak! This is a test photo payload.",
|
|
);
|
|
const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
|
|
const { header, ciphertext } = encryptFileBody(plaintext, key);
|
|
|
|
// Separate header for thumbnail (not used in this test path but
|
|
// needed to construct the EnteFile)
|
|
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, "single-chunk.jpg");
|
|
|
|
const result = await downloadFile(api, file, outPath);
|
|
|
|
// The whole DownloadResult shape is asserted, not just its fields:
|
|
// callers depend on `path` being the destination they asked for
|
|
// (never the temporary file used along the way) and on
|
|
// `bytesWritten` being the plaintext length.
|
|
expect(result).toEqual({
|
|
path: outPath,
|
|
bytesWritten: plaintext.length,
|
|
});
|
|
expect(readFileSync(outPath)).toEqual(Buffer.from(plaintext));
|
|
});
|
|
|
|
it("uses metadata.title as filename when outPath is omitted", async () => {
|
|
// With no `outPath`, the destination is `metadata.title`, used
|
|
// verbatim as a path. The title here is therefore given inside the
|
|
// test's temporary directory: a bare relative name would resolve
|
|
// against the process working directory, i.e. the repo root, and
|
|
// `make check` must not create files in the repo — a failure between
|
|
// the write and any cleanup would leave one behind.
|
|
const plaintext = new Uint8Array([1, 2, 3]);
|
|
const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
|
|
const { header, ciphertext } = encryptFileBody(plaintext, key);
|
|
const thumbPush =
|
|
sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
|
|
const file = buildMockEnteFile(key, header, thumbPush.header);
|
|
const titlePath = join(testDir, "fallback-name.png");
|
|
file.metadata.title = titlePath;
|
|
|
|
const api = new ApiClient({ fetch: mockFetchForBody(ciphertext) });
|
|
const result = await downloadFile(api, file);
|
|
|
|
expect(result.path).toBe(titlePath);
|
|
expect(readFileSync(result.path)).toEqual(Buffer.from(plaintext));
|
|
});
|
|
|
|
it("handles a larger single-chunk file (random binary payload)", async () => {
|
|
// Most photos are under 4 MiB and therefore a single secretstream
|
|
// chunk. This test exercises a non-trivial payload size with
|
|
// arbitrary binary data (not just ASCII) to verify no encoding bugs.
|
|
const plaintext = patternBytes(100_000, 11);
|
|
const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
|
|
const { header, ciphertext } = encryptFileBody(plaintext, key);
|
|
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, "large-single.bin");
|
|
const result = await downloadFile(api, file, outPath);
|
|
|
|
expect(result.bytesWritten).toBe(100_000);
|
|
expectSameBytes(readFileSync(outPath), plaintext);
|
|
});
|
|
|
|
it("decrypts a body that spans several secretstream chunks", async () => {
|
|
// Files over 4 MiB arrive as several ciphertext chunks concatenated
|
|
// into one HTTP body. The downloader has to re-split them on the
|
|
// exact chunk boundary; getting that wrong corrupts every large
|
|
// photo in an account. This is also the positive control for the
|
|
// truncation tests below: it proves the multi-chunk fixture itself
|
|
// decrypts cleanly when nothing has been removed from it.
|
|
const { api, file } = fixtureFor(
|
|
multiChunkKey,
|
|
multiChunk.header,
|
|
multiChunk.body,
|
|
);
|
|
const outPath = join(testDir, "multi-chunk.bin");
|
|
|
|
const result = await downloadFile(api, file, outPath);
|
|
|
|
expect(result.bytesWritten).toBe(multiChunk.plaintext.length);
|
|
expectSameBytes(readFileSync(outPath), multiChunk.plaintext);
|
|
});
|
|
});
|
|
|
|
describe("downloadThumbnail", () => {
|
|
it("downloads and decrypts the thumbnail stream", async () => {
|
|
const plaintext = new Uint8Array([0xff, 0xd8, 0xff, 0xe0]); // JPEG SOI
|
|
const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
|
|
|
|
const filePush =
|
|
sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
|
|
const { header: thumbHeader, ciphertext: thumbCipher } =
|
|
encryptFileBody(plaintext, key);
|
|
|
|
const file = buildMockEnteFile(key, filePush.header, thumbHeader);
|
|
const api = new ApiClient({ fetch: mockFetchForBody(thumbCipher) });
|
|
const outPath = join(testDir, "thumb.jpg");
|
|
|
|
const result = await downloadThumbnail(api, file, outPath);
|
|
|
|
expect(result).toEqual({ path: outPath, bytesWritten: 4 });
|
|
expect(readFileSync(outPath)).toEqual(Buffer.from(plaintext));
|
|
});
|
|
});
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Truncation detection and atomic writes
|
|
//
|
|
// Everything below is the failure contract. It is deliberately written once
|
|
// per entry point via `entryPoints`, because `downloadFile` and
|
|
// `downloadThumbnail` must behave identically here: a corrupt thumbnail is
|
|
// just as unacceptable as a corrupt original, and `runBackup` trusts both.
|
|
// ---------------------------------------------------------------------------
|
|
|
|
describe.each(entryPoints)(
|
|
"$name truncation handling",
|
|
({ name, download }) => {
|
|
/** A fresh, empty directory so leftover-file assertions are meaningful. */
|
|
const freshDir = (): string => {
|
|
const dir = mkdtempSync(join(testDir, `${name}-`));
|
|
return dir;
|
|
};
|
|
|
|
it("rejects a body whose final TAG_FINAL chunk never arrived", async () => {
|
|
// Simulate a connection that dropped after the first 4 MiB chunk.
|
|
// Every byte that did arrive decrypts and authenticates perfectly —
|
|
// that is precisely the danger. The only signal that the file is
|
|
// incomplete is the absence of a chunk tagged TAG_FINAL, so the
|
|
// downloader must treat "stream ended on TAG_MESSAGE" as a hard
|
|
// error rather than returning a short file.
|
|
const truncatedBody = multiChunk.body.slice(
|
|
0,
|
|
multiChunk.finalChunkOffset,
|
|
);
|
|
const { api, file } = fixtureFor(
|
|
multiChunkKey,
|
|
multiChunk.header,
|
|
truncatedBody,
|
|
);
|
|
const outPath = join(freshDir(), "truncated.bin");
|
|
|
|
await expect(download(api, file, outPath)).rejects.toThrow(
|
|
/truncated/i,
|
|
);
|
|
});
|
|
|
|
it("rejects a body whose final chunk arrived only in part", async () => {
|
|
// The likelier shape of a dropped connection: the transfer stops
|
|
// in the middle of a chunk rather than neatly between two. The
|
|
// bytes that arrived are a prefix of a complete chunk, so Poly1305
|
|
// rejects them — which is, cryptographically, indistinguishable
|
|
// from corruption of a whole chunk.
|
|
//
|
|
// It is still reported as truncation, because that is what it
|
|
// almost always is and because this library's entire reason for
|
|
// checking TAG_FINAL is to make a short transfer visible. Calling
|
|
// a short transfer "authentication failed" would send a user
|
|
// hunting for a corrupt file when their network is at fault. The
|
|
// underlying authentication failure is kept as the error's
|
|
// `cause`, so the real diagnosis is never lost.
|
|
const shortBody = multiChunk.body.slice(
|
|
0,
|
|
multiChunk.body.length - 8,
|
|
);
|
|
const { api, file } = fixtureFor(
|
|
multiChunkKey,
|
|
multiChunk.header,
|
|
shortBody,
|
|
);
|
|
const dir = freshDir();
|
|
const outPath = join(dir, "partial-final.bin");
|
|
|
|
const err = await download(api, file, outPath).catch(
|
|
(e: unknown) => e,
|
|
);
|
|
|
|
expect(err).toBeInstanceOf(Error);
|
|
expect((err as Error).message).toMatch(/truncated/i);
|
|
expect((err as Error).cause).toBeInstanceOf(Error);
|
|
expect(((err as Error).cause as Error).message).toMatch(
|
|
/authentication failed/i,
|
|
);
|
|
|
|
// And, as with every other failure, the destination is untouched
|
|
// and no staged temp file survives.
|
|
expect(existsSync(outPath)).toBe(false);
|
|
expect(readdirSync(dir)).toEqual([]);
|
|
});
|
|
|
|
it("rejects an empty body instead of writing a zero-byte file", async () => {
|
|
// Ente always emits at least one chunk, even for empty content:
|
|
// `encryptBlob` shows that a zero-length plaintext still produces a
|
|
// TAG_FINAL chunk. A body with no chunks at all therefore means the
|
|
// transfer failed, not that the file is empty. Writing a zero-byte
|
|
// file here would be the worst outcome, because `runBackup` would
|
|
// then see a file it considers present and never retry it.
|
|
const { api, file } = fixtureFor(
|
|
multiChunkKey,
|
|
multiChunk.header,
|
|
new Uint8Array(0),
|
|
);
|
|
const outPath = join(freshDir(), "empty.bin");
|
|
|
|
await expect(download(api, file, outPath)).rejects.toThrow(
|
|
/truncated/i,
|
|
);
|
|
});
|
|
|
|
it("leaves no file at the destination after a truncated download", async () => {
|
|
// 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.
|
|
//
|
|
// 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(
|
|
patternBytes(256, 21),
|
|
key,
|
|
);
|
|
const { api, file } = fixtureFor(key, header, ciphertext);
|
|
const dir = freshDir();
|
|
const outPath = join(dir, "absent.bin");
|
|
|
|
await expect(download(api, file, outPath)).rejects.toThrow(
|
|
/truncated/i,
|
|
);
|
|
|
|
expect(existsSync(outPath)).toBe(false);
|
|
// And no temporary scratch file is left behind either: the download
|
|
// stages plaintext in a sibling temp file, which must be removed on
|
|
// the failure path so repeated failures cannot fill the disk.
|
|
expect(readdirSync(dir)).toEqual([]);
|
|
});
|
|
|
|
it("reports a corrupt whole chunk as an authentication failure, not truncation", async () => {
|
|
// The counterpart to the partial-final-chunk case above, and the
|
|
// reason the two are distinguishable at all. A byte is flipped
|
|
// inside the first chunk of a multi-chunk body: that chunk arrives
|
|
// complete — the stream goes on past it — so its failure cannot be
|
|
// a short transfer. It is corruption, and the caller is told so,
|
|
// with `pullStreamChunk`'s error propagated unchanged because it is
|
|
// the real diagnosis.
|
|
//
|
|
// The same on-disk guarantee holds for this failure mode as for
|
|
// every other: nothing at the destination, nothing left over.
|
|
const corrupted = Uint8Array.from(multiChunk.body);
|
|
corrupted[10] ^= 0xff;
|
|
|
|
const { api, file } = fixtureFor(
|
|
multiChunkKey,
|
|
multiChunk.header,
|
|
corrupted,
|
|
);
|
|
const dir = freshDir();
|
|
const outPath = join(dir, "corrupt.bin");
|
|
|
|
await expect(download(api, file, outPath)).rejects.toThrow(
|
|
/authentication failed/i,
|
|
);
|
|
|
|
expect(existsSync(outPath)).toBe(false);
|
|
expect(readdirSync(dir)).toEqual([]);
|
|
});
|
|
|
|
it("does not clobber an existing file when the download fails", async () => {
|
|
// The repair case. A user re-running a backup over a directory that
|
|
// already holds good originals must never end up worse off: a failed
|
|
// download leaves the previous contents exactly as they were, so the
|
|
// old good copy survives until a complete new one is available to
|
|
// replace it in a single rename.
|
|
const existing = new TextEncoder().encode(
|
|
"previously downloaded, known-good contents",
|
|
);
|
|
const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
|
|
const { header, ciphertext } = encryptNonFinalBody(
|
|
patternBytes(256, 22),
|
|
key,
|
|
);
|
|
const { api, file } = fixtureFor(key, header, ciphertext);
|
|
const dir = freshDir();
|
|
const outPath = join(dir, "existing.bin");
|
|
writeFileSync(outPath, existing);
|
|
|
|
await expect(download(api, file, outPath)).rejects.toThrow(
|
|
/truncated/i,
|
|
);
|
|
|
|
expect(readFileSync(outPath)).toEqual(Buffer.from(existing));
|
|
expect(readdirSync(dir)).toEqual(["existing.bin"]);
|
|
});
|
|
|
|
it("replaces an existing file when the download succeeds", async () => {
|
|
// The mirror image of the previous test: a complete download does
|
|
// overwrite whatever was at the destination, atomically, via rename.
|
|
const existing = new TextEncoder().encode("stale contents");
|
|
const plaintext = patternBytes(512, 23);
|
|
const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
|
|
const { header, ciphertext } = encryptFileBody(plaintext, key);
|
|
|
|
const { api, file } = fixtureFor(key, header, ciphertext);
|
|
const dir = freshDir();
|
|
const outPath = join(dir, "replaced.bin");
|
|
writeFileSync(outPath, existing);
|
|
|
|
const result = await download(api, file, outPath);
|
|
|
|
expect(result).toEqual({ path: outPath, bytesWritten: 512 });
|
|
expect(readFileSync(outPath)).toEqual(Buffer.from(plaintext));
|
|
// The temp file is gone once the rename has happened, so a
|
|
// successful download leaves exactly one file behind.
|
|
expect(readdirSync(dir)).toEqual(["replaced.bin"]);
|
|
});
|
|
|
|
it("stages the plaintext in a sibling temp file and renames it into place", async () => {
|
|
// The atomic write, observed directly rather than inferred from an
|
|
// empty directory. Every other failure in this file is injected
|
|
// inside `streamDecrypt`, which runs before anything is written —
|
|
// so under those tests a plain `writeFile` to the destination would
|
|
// look identical. This one watches the rename itself.
|
|
//
|
|
// Two properties are load-bearing. The staging file must exist on
|
|
// disk when the rename happens: that is what makes the destination
|
|
// appear complete or not at all, instead of filling up as bytes
|
|
// land. And it must be a sibling of the destination, because
|
|
// `rename` is only atomic within one filesystem — staging in
|
|
// `/tmp` and renaming across a mount point would silently become a
|
|
// copy, reintroducing the partial-file window this exists to close.
|
|
const plaintext = patternBytes(512, 31);
|
|
const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
|
|
const { header, ciphertext } = encryptFileBody(plaintext, key);
|
|
const { api, file } = fixtureFor(key, header, ciphertext);
|
|
const dir = freshDir();
|
|
const outPath = join(dir, "staged.bin");
|
|
|
|
await download(api, file, outPath);
|
|
|
|
expect(renameHook.calls).toHaveLength(1);
|
|
const staged = renameHook.calls[0]!;
|
|
expect(staged.to).toBe(outPath);
|
|
expect(staged.from).not.toBe(outPath);
|
|
expect(dirname(staged.from)).toBe(dir);
|
|
expect(staged.sourceExisted).toBe(true);
|
|
|
|
// Afterwards the temp file is gone and only the destination is
|
|
// left, holding the complete plaintext.
|
|
expect(existsSync(staged.from)).toBe(false);
|
|
expect(readFileSync(outPath)).toEqual(Buffer.from(plaintext));
|
|
expect(readdirSync(dir)).toEqual(["staged.bin"]);
|
|
});
|
|
|
|
it("removes the staged temp file when the rename itself fails", async () => {
|
|
// The cleanup path. It can only run when something fails at or
|
|
// after the write, which no amount of bad network data can
|
|
// produce: by the time anything is written the whole stream has
|
|
// already decrypted and verified. Failing the rename is what
|
|
// reaches it — a real possibility on a full disk, a read-only
|
|
// mount, or a destination that has become a directory.
|
|
//
|
|
// This is the only case in which the temp file is on disk at the
|
|
// moment of failure, so it is the only one that can show it is
|
|
// actually removed rather than merely never created. It also pins
|
|
// that the caller sees the original failure: a cleanup that threw
|
|
// over the top of it would hide why the download failed.
|
|
const existing = new TextEncoder().encode("known-good contents");
|
|
const plaintext = patternBytes(512, 32);
|
|
const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
|
|
const { header, ciphertext } = encryptFileBody(plaintext, key);
|
|
const { api, file } = fixtureFor(key, header, ciphertext);
|
|
const dir = freshDir();
|
|
const outPath = join(dir, "rename-fails.bin");
|
|
writeFileSync(outPath, existing);
|
|
|
|
renameHook.failWith = new Error("simulated rename failure");
|
|
|
|
await expect(download(api, file, outPath)).rejects.toThrow(
|
|
"simulated rename failure",
|
|
);
|
|
|
|
expect(renameHook.calls).toHaveLength(1);
|
|
const staged = renameHook.calls[0]!;
|
|
expect(staged.sourceExisted).toBe(true);
|
|
expect(existsSync(staged.from)).toBe(false);
|
|
|
|
// The previous contents are still there, untouched, and the
|
|
// directory holds nothing else.
|
|
expect(readFileSync(outPath)).toEqual(Buffer.from(existing));
|
|
expect(readdirSync(dir)).toEqual(["rename-fails.bin"]);
|
|
});
|
|
},
|
|
);
|