diff --git a/src/crypto/stream.ts b/src/crypto/stream.ts index cb48818..d2bde06 100644 --- a/src/crypto/stream.ts +++ b/src/crypto/stream.ts @@ -12,11 +12,20 @@ export const STREAM_CHUNK_OVERHEAD = 17; // marks the last chunk of a stream. Exported so callers (the download layer) // can detect truncation without importing sodium themselves. // -// This is a function rather than a constant because libsodium attaches its -// constants to the module object only once `sodium.ready` has resolved, which -// is long after this module is evaluated — a module-level read would bind -// `undefined`. Reading it at call time returns the library's own value, so -// there is no second copy of a protocol constant to keep in sync. +// This is a function rather than a constant, and that is load-bearing: +// libsodium attaches its constants to the module object inside +// `ready.then(...)`, which resolves long after this module is evaluated. A +// module-level read would bind `undefined`, every downstream comparison +// against it would then be false, and every valid download would be rejected +// as truncated. Reading at call time returns the library's own value, so +// there is also no second copy of a protocol constant to keep in sync. +// +// Under vitest sodium is already initialised in the worker before this module +// is evaluated, so an eager read would pick up a real value there and the +// ordinary tests could not tell the difference. The regression guard is +// "streamTagFinal() reads the constant at call time, not at import time" in +// test/crypto/stream.test.ts, which reproduces the plain-Node ESM ordering +// against a stand-in sodium module; it goes red if this becomes eager. export const streamTagFinal = (): number => sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL; diff --git a/test/crypto/stream.test.ts b/test/crypto/stream.test.ts index f4b2707..331317f 100644 --- a/test/crypto/stream.test.ts +++ b/test/crypto/stream.test.ts @@ -18,6 +18,9 @@ * - The chunk-size constants match Ente's expectations, and the * re-exported `streamTagFinal()` matches the tag a real final chunk * carries. + * - `streamTagFinal()` reads libsodium's constant at call time rather than + * at import time, which it must, because the constant does not exist yet + * when this library's modules are evaluated. * - The pull state can decrypt a multi-chunk stream produced by * sodium.crypto_secretstream_xchacha20poly1305_push, in order. * - The tag byte is propagated to the caller. @@ -25,7 +28,7 @@ */ import sodium from "libsodium-wrappers-sumo"; -import { beforeAll, describe, expect, it } from "vitest"; +import { beforeAll, describe, expect, it, vi } from "vitest"; import { init, initStreamPull, @@ -60,9 +63,9 @@ describe("crypto stream constants", () => { * evaluated. Reading the value at call time yields libsodium's number; * reading it at module scope would yield `undefined`, and every * truncation check downstream would then compare against `undefined` and - * reject good downloads. This test pins the behaviour end to end — it - * compares against the tag observed on a real final chunk pulled back off - * the wire format, so it fails if the accessor is ever made eager. + * reject good downloads. The eagerness itself is guarded by the next test; + * this one pins the value, comparing it against the tag observed on a real + * final chunk pulled back off the wire format. */ it("streamTagFinal() is the tag carried by a real final chunk", async () => { await init(); @@ -81,6 +84,52 @@ describe("crypto stream constants", () => { const state = initStreamPull(push.header, key); expect(pullStreamChunk(state, ciphertext).tag).toBe(streamTagFinal()); }); + + /** + * The regression guard for the eagerness property described above. + * + * Under vitest, sodium is already initialised in the worker process by + * the time any source module is evaluated, so an eager module-level read + * would happen to pick up a real value and no ordinary test could tell + * the difference. This test recreates the ordering that a plain Node ESM + * consumer sees: a stand-in sodium module whose `TAG_FINAL` property does + * not exist yet when `src/crypto/stream.ts` is evaluated and only appears + * afterwards, exactly as libsodium attaches its constants inside + * `ready.then(...)`. + * + * A call-time read observes the value that appeared after evaluation; a + * module-level read binds `undefined` and this test fails. The stand-in + * uses a sentinel rather than the real tag number so that a read which + * somehow reached the real libsodium would fail too. + */ + it("streamTagFinal() reads the constant at call time, not at import time", async () => { + const SENTINEL = 42; + const late: { tagFinal: number | undefined } = { tagFinal: undefined }; + + vi.resetModules(); + vi.doMock("libsodium-wrappers-sumo", () => ({ + default: { + ready: Promise.resolve(), + get crypto_secretstream_xchacha20poly1305_TAG_FINAL() { + return late.tagFinal; + }, + }, + })); + + try { + // Evaluated while the constant is still absent, as it is before + // `sodium.ready` resolves. + const fresh = await import("../../src/crypto/stream.js"); + expect(late.tagFinal).toBeUndefined(); + + // libsodium attaches its constants; a lazy accessor sees them. + late.tagFinal = SENTINEL; + expect(fresh.streamTagFinal()).toBe(SENTINEL); + } finally { + vi.doUnmock("libsodium-wrappers-sumo"); + vi.resetModules(); + } + }); }); describe("crypto.initStreamPull / pullStreamChunk", () => {