make build-bin: on macOS, build with bun's pinned release build (closes #251)

nixpkgs points its macOS bun at an ICU in the nix store, and bun build
--compile copied that reference into bin/quak, so nix-collect-garbage could
break the cron backup. script/build-bin now downloads bun 1.3.13's release
archive on macOS too, Intel (baseline) or Apple silicon, checks its SHA-256,
and compiles with it. Those builds load only /usr/lib libraries. nix-shell is
no longer used; any system without a bun release build stops with an error.
The hash check falls back to shasum where sha256sum is missing.

Model: opus-5-5

README.md

@@ -31,7 +31,8 @@ again on the next run. Every download is decrypted on its way to disk.
 
 ## Getting Started
 
-The commands below need `git`, Node 22 or later and `yarn`.
+The commands below need `git`, `yarn` and Node 22.13 or later. Node 23 needs
+23.5 or later.
 
 ```bash
 git clone https://git.eeqj.de/sneak/quak.git
@@ -69,11 +70,29 @@ The library keeps a local copy of the account's album and file lists, the cache.
 It brings the cache up to date with the server in rounds called refreshes.
 
 quak is not published to a package registry: `package.json` marks it `private`,
-and `dist/` is not committed. Clone and build it as above, then add the clone to
+and `dist/` is not committed. Clone and build it as above, then link the clone
-your own program's `package.json` by its path, for example
+into your own program:
-`yarn add file:../quak`. The package's `main`, `types` and `exports` fields
+
-point into `dist/`, so the clone must be built first. The package is an ES
+```bash
-module only, so a CommonJS program cannot `require` it.
+# In the quak clone:
+yarn link
+
+# In your program's directory:
+yarn link quak
+```
+
+`yarn link` also installs the `quak` command in yarn's global bin directory, and
+`yarn unlink` in the clone removes the link and the command.
+
+A linked quak uses the dependencies that `yarn install` put in the clone, at the
+versions in quak's `yarn.lock`. Avoid `yarn add file:../quak`: it resolves
+quak's dependencies again, and their newer releases can need a newer Node.
+`yarn link quak` does not add quak to your `package.json`, so run it again in
+each new checkout of your program.
+
+The package's `main`, `types` and `exports` fields point into `dist/`, so the
+clone must be built first. The package is an ES module only, so a CommonJS
+program cannot `require` it.
 
 ```ts
 import { Client, Library } from "quak";
@@ -137,10 +156,13 @@ requests. The "Library reference" below covers both.
 `quak backup` never prompts, so cron can run it. `make install` builds quak as
 one binary and copies it to `~/bin/quak`. It uses bun, a JavaScript runtime, to
 bundle the built `dist/` into one executable. Besides what Getting Started
-needs, `make install` needs `make`. On Linux it downloads bun from GitHub with
+needs, `make install` needs `make`. It downloads bun from GitHub with `curl` and
-`curl` and unpacks it with `unzip`. It checks the download against a SHA-256
+unpacks it with `unzip`. It checks the download against a SHA-256 hash in the
-hash in the repo. On macOS it runs bun through `nix-shell -p bun`, so it needs
+repo. `make install` works on Linux and macOS, on x86-64 and arm64.
-[nix](https://nixos.org/download).
+
+On Linux systems that use the musl C library, such as Alpine, `make install`
+downloads bun's musl build. On Alpine, both that bun and `~/bin/quak` need the
+`libstdc++` and `libgcc` packages.
 
 Log in once with `~/bin/quak`, as the user the cron job will run as:
 
@@ -673,6 +695,9 @@ but letters and digits, or when it is longer than 16 characters.
 When the date or the time zone changes, the next run stores the original at its
 new path and leaves the old copy where it is.
 
+A file deleted in Ente keeps its original at its save path, and the JSON beside
+it. The next run removes its symlinks from the collection directories.
+
 The library gives the same path as `photo.savePath` and writes it with
 `photo.download()` (see "A photo's content").
 
@@ -1911,10 +1936,9 @@ These apply to people and to coding agents alike.
     - container images by digest;
     - the nvm archive `script/bootstrap` downloads, and the Python packages
       `bin/clip-keyword-vectors` installs, by SHA-256 hash;
-    - bun, which `script/build-bin` downloads on Linux, by SHA-256 hash;
+    - the bun builds `script/build-bin` downloads, by SHA-256 hash;
     - Node and yarn, when `script/bootstrap` installs them, by version.
 - Not pinned:
-    - bun on macOS, which `script/build-bin` takes from `nix-shell -p bun`;
     - `make` and `git`, which `script/bootstrap` installs from the system
       package manager when they are missing, as every `Dockerfile` stage does;
     - `bash` and `curl`, which `script/bootstrap` installs the same way when it

package.json

@@ -12,7 +12,7 @@
     "private": true,
     "type": "module",
     "engines": {
-        "node": ">=22"
+        "node": "^22.13.0 || >=23.5.0"
     },
     "main": "./dist/src/index.js",
     "types": "./dist/src/index.d.ts",

script/build-bin

@@ -3,21 +3,28 @@
 # executable, bin/quak, which reports the version script/build stamped. Our own
 # extension to scripts-to-rule-them-all.
 #
-# bun compiles the binary from a copy of its own executable. On Linux, nix's
+# bun compiles the binary from a copy of its own executable, so the binary
-# bun loads through a C library in the nix store, and so does a binary compiled
+# loads the same libraries as the bun that built it. nix's bun loads libraries
-# from it. nix-collect-garbage can delete that library, and the binary then no
+# from the nix store: on Linux its C library, on macOS its ICU. A binary
-# longer starts. On Linux this script therefore compiles with bun's own release
+# compiled from it loads them too. nix-collect-garbage can delete them, and the
-# build, which loads through the system's C library. It downloads that build
+# binary then no longer starts. This script therefore compiles with bun's own
-# and checks it against the hash below before running it.
+# release build, which loads only the system's libraries. It downloads that
+# build and checks it against the hash below before running it.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 # bun 1.3.13, 2026-11-11, and the SHA-256 of each release archive below. The
-# x86-64 archive is the baseline build, which also runs on CPUs without AVX2.
+# x86-64 archives are the baseline builds, which also run on CPUs without AVX2.
+# The musl archives are for Linux systems that use the musl C library, such as
+# Alpine.
 BUN_VERSION="1.3.13"
 BUN_LINUX_X64_BASELINE_SHA256="9d8a24292a7068090205daac0a5a223f5f69736f5287e37bf88d3b4031edc750"
+BUN_LINUX_X64_MUSL_BASELINE_SHA256="88ca7c7ad235b498f549eea2f770f434e9f0f5e9ba95168a2d3a1f235184c394"
 BUN_LINUX_AARCH64_SHA256="70bae41b3908b0a120e1e58c5c8af30e74afae3b8d11b0d3fdd8e787ddfb4b22"
+BUN_LINUX_AARCH64_MUSL_SHA256="5385e978107ce4934298d8d6afe9bfbb898683f6cc23e6753a0da60bc60c5b81"
+BUN_DARWIN_X64_BASELINE_SHA256="a98ba6a480f22fda9b343626b906a4e26aa53618bf85d2bc5928ecf2ba45f0ed"
+BUN_DARWIN_AARCH64_SHA256="5467e3f65dba526b9fea98f0cce04efafc0c63e169733ec27b876a3ad32da190"
 
 # compile_with_downloaded_bun <archive-name> <sha256>
 compile_with_downloaded_bun() {
@@ -25,7 +32,12 @@ compile_with_downloaded_bun() {
     trap 'rm -rf "$tmp"' EXIT
     curl -fsSL -o "$tmp/$1.zip" \
         "https://github.com/oven-sh/bun/releases/download/bun-v$BUN_VERSION/$1.zip"
-    echo "$2  $tmp/$1.zip" | sha256sum -c -
+    # macOS always has shasum, but not every macOS has sha256sum.
+    if command -v sha256sum >/dev/null 2>&1; then
+        echo "$2  $tmp/$1.zip" | sha256sum -c -
+    else
+        echo "$2  $tmp/$1.zip" | shasum -a 256 -c -
+    fi
     unzip -q "$tmp/$1.zip" -d "$tmp"
     "$tmp/$1/bun" build dist/bin/quak.js --compile --outfile bin/quak
 }
@@ -33,22 +45,39 @@ compile_with_downloaded_bun() {
 main() {
     cd "$ROOT"
     "$ROOT/script/build"
-    case "$(uname -s)-$(uname -m)" in
+    platform="$(uname -s)-$(uname -m)"
+    # musl's ldd begins its version output with "musl libc"; glibc's does not.
+    if ldd --version 2>&1 | grep -q '^musl libc'; then
+        platform="$platform-musl"
+    fi
+    case "$platform" in
         Linux-x86_64)
             compile_with_downloaded_bun bun-linux-x64-baseline \
                 "$BUN_LINUX_X64_BASELINE_SHA256"
             ;;
+        Linux-x86_64-musl)
+            compile_with_downloaded_bun bun-linux-x64-musl-baseline \
+                "$BUN_LINUX_X64_MUSL_BASELINE_SHA256"
+            ;;
         Linux-aarch64)
             compile_with_downloaded_bun bun-linux-aarch64 \
                 "$BUN_LINUX_AARCH64_SHA256"
             ;;
-        Linux-*)
+        Linux-aarch64-musl)
-            echo "build-bin: bun has no release build for Linux on $(uname -m)" >&2
+            compile_with_downloaded_bun bun-linux-aarch64-musl \
-            exit 1
+                "$BUN_LINUX_AARCH64_MUSL_SHA256"
+            ;;
+        Darwin-x86_64)
+            compile_with_downloaded_bun bun-darwin-x64-baseline \
+                "$BUN_DARWIN_X64_BASELINE_SHA256"
+            ;;
+        Darwin-arm64)
+            compile_with_downloaded_bun bun-darwin-aarch64 \
+                "$BUN_DARWIN_AARCH64_SHA256"
             ;;
         *)
-            nix-shell -p bun --run \
+            echo "build-bin: bun has no release build for $(uname -s) on $(uname -m)" >&2
-                "bun build dist/bin/quak.js --compile --outfile bin/quak"
+            exit 1
             ;;
     esac
 }

src/api/client.ts

@@ -354,7 +354,13 @@ export class ApiClient {
         });
     }
 
-    async putFile(presignedURL: string, data: Uint8Array): Promise<void> {
+    // `contentMD5` is the value given to `getUploadURL`. The server signs it
+    // into the URL, and storage refuses a PUT without that `Content-MD5`.
+    async putFile(
+        presignedURL: string,
+        data: Uint8Array,
+        contentMD5: string,
+    ): Promise<void> {
         // Idempotent despite being a write: a presigned PUT stores one whole
         // object at one key in one request, so replaying it either overwrites
         // the same bytes or lands them for the first time. There is no partial
@@ -370,6 +376,7 @@ export class ApiClient {
                     headers: {
                         "Content-Type": "application/octet-stream",
                         "Content-Length": String(data.length),
+                        "Content-MD5": contentMD5,
                     },
                     body: data,
                     signal: AbortSignal.timeout(this.requestTimeoutMs),

src/thumbnails.ts

@@ -325,7 +325,7 @@ export const fixMissingThumbnails = async (
                 ciphertext.length,
                 md5,
             );
-            await api.putFile(url, ciphertext);
+            await api.putFile(url, ciphertext, md5);
             await api.updateThumbnail(file.id, objectKey, toBase64(header));
 
             log(`[${collectionName}] Thumbnail uploaded for ${title}`);

test/api/client.test.ts

@@ -780,7 +780,7 @@ describe("ApiClient timeouts", () => {
 
         await client.getJSON("/a");
         await client.postJSON("/b", {});
-        await client.putFile("https://s3.example/x", new Uint8Array([1]));
+        await client.putFile("https://s3.example/x", new Uint8Array([1]), "m");
         await client.putJSON("/c", {});
 
         for (const call of calls) {
@@ -825,7 +825,8 @@ describe("ApiClient timeouts", () => {
             [
                 "putFile",
                 () => new Response(null, { status: 200 }),
-                (c) => c.putFile("https://s3.example/x", new Uint8Array([1])),
+                (c) =>
+                    c.putFile("https://s3.example/x", new Uint8Array([1]), "m"),
             ],
             [
                 "getFileStream",
@@ -1049,7 +1050,7 @@ describe("ApiClient error typing", () => {
         const client = new ApiClient({ fetch, retry: noWait });
 
         const err: unknown = await client
-            .putFile("https://s3.example/obj", new Uint8Array([1, 2]))
+            .putFile("https://s3.example/obj", new Uint8Array([1, 2]), "m")
             .catch((e: unknown) => e);
 
         expect(err).toBeInstanceOf(ApiError);
@@ -1067,7 +1068,11 @@ describe("ApiClient error typing", () => {
         );
         const client = new ApiClient({ fetch, retry: noWait });
 
-        await client.putFile("https://s3.example/obj", new Uint8Array([1, 2]));
+        await client.putFile(
+            "https://s3.example/obj",
+            new Uint8Array([1, 2]),
+            "m",
+        );
         expect(calls).toHaveLength(2);
     });
 
@@ -1277,6 +1282,7 @@ describe("ApiClient onRequest", () => {
         await client.putFile(
             "https://s3.example/obj?X-Amz-Signature=abc",
             new Uint8Array([1, 2]),
+            "m",
         );
 
         expect(requests).toEqual([

test/api/upload.test.ts

@@ -80,13 +80,20 @@ describe("ApiClient.putFile", () => {
         const client = new ApiClient({ fetch, authToken: "secret-tok" });
         const data = new Uint8Array([1, 2, 3, 4, 5]);
 
-        await client.putFile("https://s3.example.com/presigned?sig=abc", data);
+        await client.putFile(
+            "https://s3.example.com/presigned?sig=abc",
+            data,
+            "md5base64==",
+        );
 
         expect(calls[0]!.url).toBe("https://s3.example.com/presigned?sig=abc");
         expect(calls[0]!.init?.method).toBe("PUT");
         const headers = new Headers(calls[0]!.init?.headers as HeadersInit);
         expect(headers.get("Content-Type")).toBe("application/octet-stream");
         expect(headers.get("Content-Length")).toBe("5");
+        // The server signs the MD5 into the URL; storage refuses the PUT
+        // without it.
+        expect(headers.get("Content-MD5")).toBe("md5base64==");
         // Must NOT leak auth headers to S3
         expect(headers.has("X-Auth-Token")).toBe(false);
         expect(headers.has("X-Client-Package")).toBe(false);
@@ -99,7 +106,11 @@ describe("ApiClient.putFile", () => {
         const client = new ApiClient({ fetch });
 
         await expect(
-            client.putFile("https://s3.example.com/bad", new Uint8Array(10)),
+            client.putFile(
+                "https://s3.example.com/bad",
+                new Uint8Array(10),
+                "md5base64==",
+            ),
         ).rejects.toThrow(/403/);
     });
 });

test/packaging/build-bin.test.ts

@@ -0,0 +1,241 @@
+// `script/build-bin` compiles `bin/quak`, the single binary that the README's
+// cron setup runs. bun compiles it from a copy of its own executable, so the
+// binary loads the same libraries as the bun that built it. nix's bun loads
+// libraries from the nix store, which garbage collection can delete: on Linux
+// its C library, on macOS its ICU. The script therefore downloads bun's own
+// release build, which loads only the system's libraries.
+//
+// What the script promises, and why each test matters:
+//
+// - Each system, machine and C library that bun publishes a build for gets its
+//   own archive: Linux on x86-64 or arm64, with glibc or with musl, as on
+//   Alpine, and macOS on Intel or Apple silicon. A bun built for another
+//   system, machine or C library does not start, and `make install` fails.
+// - The archive's SHA-256 must match the one in the script before anything in
+//   the archive runs. Without that check, a tampered download would build the
+//   binary that cron runs.
+// - Any other system or machine stops with an error, and never falls back to
+//   nix's bun. Building with nix's bun would bring back the dependency on the
+//   nix store.
+//
+// Each test copies the script into a fresh directory, which the script then
+// treats as the checkout, and runs it there. Stubs first on PATH stand in for
+// `uname`, `ldd`, `curl`, `unzip`, `nix-shell` and `shasum`, so no test
+// downloads anything or runs a real bun.
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { execFileSync, spawnSync } from "node:child_process";
+import {
+    chmodSync,
+    copyFileSync,
+    existsSync,
+    mkdirSync,
+    mkdtempSync,
+    readFileSync,
+    rmSync,
+    symlinkSync,
+    writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = fileURLToPath(new URL("../../", import.meta.url));
+
+// The stubs, keyed by the command each replaces. `uname` and `ldd` describe the
+// system that runBuildBin passes in the environment. `curl`, `unzip`,
+// `nix-shell` and `shasum` write the arguments they were given, one per line,
+// to a file named after the command in $STUB_LOG_DIR, which also shows that
+// they ran.
+const stubs: Record<string, string> = {
+    uname: `
+        case "$1" in
+            -s) echo "$STUB_UNAME_S" ;;
+            -m) echo "$STUB_UNAME_M" ;;
+        esac`,
+    // The script looks only at the start of the line: "musl libc" or not.
+    ldd: `
+        if [ "$STUB_LIBC" = musl ]; then
+            echo "musl libc (x86_64)"
+        else
+            echo "ldd (GNU libc) 2.36"
+        fi`,
+    // Writes a file that is not the archive to the path after -o.
+    curl: `
+        printf '%s\\n' "$@" > "$STUB_LOG_DIR/curl"
+        while [ $# -gt 1 ]; do
+            if [ "$1" = -o ]; then echo "not the archive" > "$2"; fi
+            shift
+        done`,
+    // Unpacks a stub bun where the real archive puts bun: in a directory named
+    // after the archive, inside the directory after -d. That bun writes
+    // bin/quak, as a real compile would.
+    unzip: `
+        printf '%s\\n' "$@" > "$STUB_LOG_DIR/unzip"
+        for arg in "$@"; do
+            case "$arg" in *.zip) archive="$arg" ;; esac
+            if [ "$previous" = -d ]; then directory="$arg"; fi
+            previous="$arg"
+        done
+        bun="$directory/$(basename "$archive" .zip)/bun"
+        mkdir -p "$(dirname "$bun")"
+        echo '#!/bin/sh' > "$bun"
+        echo 'mkdir -p bin && echo binary > bin/quak' >> "$bun"
+        chmod +x "$bun"`,
+    "nix-shell": `
+        printf '%s\\n' "$@" > "$STUB_LOG_DIR/nix-shell"`,
+    // The script checks the hash with `shasum` where there is no `sha256sum`.
+    // The stub fails, as `shasum` does when the hash does not match.
+    shasum: `
+        printf '%s\\n' "$@" > "$STUB_LOG_DIR/shasum"
+        exit 1`,
+};
+
+let checkout = "";
+
+const writeScript = (path: string, body: string): void => {
+    writeFileSync(path, `#!/bin/sh\n${body}\n`);
+    chmodSync(path, 0o755);
+};
+
+// A checkout holding the script, a stub script/build that does nothing, the
+// stubs, and the directory they log to.
+beforeEach(() => {
+    checkout = mkdtempSync(join(tmpdir(), "quak-build-bin-"));
+    mkdirSync(join(checkout, "script"));
+    copyFileSync(
+        join(repoRoot, "script/build-bin"),
+        join(checkout, "script/build-bin"),
+    );
+    chmodSync(join(checkout, "script/build-bin"), 0o755);
+    writeScript(join(checkout, "script/build"), "exit 0");
+    mkdirSync(join(checkout, "stubs"));
+    for (const [command, body] of Object.entries(stubs)) {
+        writeScript(join(checkout, "stubs", command), body);
+    }
+    mkdirSync(join(checkout, "log"));
+});
+
+afterEach(() => {
+    rmSync(checkout, { recursive: true, force: true });
+});
+
+// Runs the script with nothing in its environment but the stubs' settings and a
+// PATH. Unless the caller passes one, the PATH finds the stubs first and then
+// the host's commands.
+const runBuildBin = (
+    system: string,
+    machine: string,
+    {
+        libc = "glibc",
+        path = `${join(checkout, "stubs")}:${process.env.PATH}`,
+    } = {},
+) =>
+    spawnSync(join(checkout, "script/build-bin"), {
+        cwd: checkout,
+        encoding: "utf-8",
+        env: {
+            PATH: path,
+            STUB_UNAME_S: system,
+            STUB_UNAME_M: machine,
+            STUB_LIBC: libc,
+            STUB_LOG_DIR: join(checkout, "log"),
+        },
+    });
+
+// The real commands that the script and the stubs run.
+const hostCommands = [
+    "basename",
+    "chmod",
+    "dirname",
+    "grep",
+    "mkdir",
+    "mktemp",
+    "rm",
+];
+
+// A Mac has no `ldd`, and not every Mac has `sha256sum`. This makes a PATH that
+// finds neither: the stubs other than `ldd`, then links to hostCommands.
+const makeMacPath = (): string => {
+    rmSync(join(checkout, "stubs", "ldd"));
+    mkdirSync(join(checkout, "host-commands"));
+    for (const command of hostCommands) {
+        const target = execFileSync("sh", ["-c", `command -v ${command}`], {
+            encoding: "utf-8",
+        }).trim();
+        symlinkSync(target, join(checkout, "host-commands", command));
+    }
+    return `${join(checkout, "stubs")}:${join(checkout, "host-commands")}`;
+};
+
+const ran = (command: string): boolean =>
+    existsSync(join(checkout, "log", command));
+
+const argumentsOf = (command: string): string[] =>
+    readFileSync(join(checkout, "log", command), "utf-8")
+        .trimEnd()
+        .split("\n");
+
+describe("script/build-bin", () => {
+    // The stub curl writes a file that is not the archive, so the hash check
+    // must stop the script before unzip runs. A script without the check would
+    // run unzip, and the stub bun it unpacks would write bin/quak. On Linux the
+    // check must use `sha256sum`, since a stock Alpine has no `shasum`.
+    it.each([
+        ["Linux", "x86_64", "glibc", "bun-linux-x64-baseline.zip"],
+        ["Linux", "x86_64", "musl", "bun-linux-x64-musl-baseline.zip"],
+        ["Linux", "aarch64", "glibc", "bun-linux-aarch64.zip"],
+        ["Linux", "aarch64", "musl", "bun-linux-aarch64-musl.zip"],
+    ])(
+        "on %s %s with %s, downloads %s and stops when its hash does not match",
+        (system, machine, libc, archive) => {
+            const result = runBuildBin(system, machine, { libc });
+            expect(argumentsOf("curl")).toContain(
+                "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/" +
+                    archive,
+            );
+            expect(ran("shasum")).toBe(false);
+            expect(result.status).not.toBe(0);
+            expect(ran("unzip")).toBe(false);
+            expect(ran("nix-shell")).toBe(false);
+            expect(existsSync(join(checkout, "bin/quak"))).toBe(false);
+        },
+    );
+
+    // On the PATH from makeMacPath the script finds no `sha256sum` and checks
+    // the hash with the stub `shasum`. That stub fails, so the script must stop
+    // before unzip runs.
+    // On Apple silicon `uname -m` says arm64, where bun's archive says aarch64.
+    it.each([
+        ["Darwin", "x86_64", "bun-darwin-x64-baseline.zip"],
+        ["Darwin", "arm64", "bun-darwin-aarch64.zip"],
+    ])(
+        "on %s %s, downloads %s and stops when shasum rejects its hash",
+        (system, machine, archive) => {
+            const result = runBuildBin(system, machine, {
+                path: makeMacPath(),
+            });
+            expect(argumentsOf("curl")).toContain(
+                "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/" +
+                    archive,
+            );
+            expect(argumentsOf("shasum")).toEqual(["-a", "256", "-c", "-"]);
+            expect(result.status).not.toBe(0);
+            expect(ran("unzip")).toBe(false);
+            expect(ran("nix-shell")).toBe(false);
+            expect(existsSync(join(checkout, "bin/quak"))).toBe(false);
+        },
+    );
+
+    it.each([
+        ["Linux", "riscv64"],
+        ["FreeBSD", "amd64"],
+    ])(
+        "stops on %s %s, which bun publishes no build for",
+        (system, machine) => {
+            const result = runBuildBin(system, machine);
+            expect(result.status).not.toBe(0);
+            expect(ran("curl")).toBe(false);
+            expect(ran("nix-shell")).toBe(false);
+        },
+    );
+});

test/thumbnails/thumbnails.test.ts

@@ -273,6 +273,7 @@ const buildThumbMock = async (opts?: {
 
 const buildThumbFetch = (m: ThumbMockState) => {
     let srpServer: SrpServer;
+    let signedMD5: string | undefined;
 
     return (async (
         input: RequestInfo | URL,
@@ -365,8 +366,9 @@ const buildThumbFetch = (m: ThumbMockState) => {
             return new Response("not found", { status: 404 });
         }
 
-        // Upload URL minting
+        // Upload URL minting. The real server signs the MD5 into the URL.
         if (path === "/files/upload-url") {
+            signedMD5 = JSON.parse(init?.body as string).contentMD5;
             return json({
                 objectKey: `42/thumb-${Date.now()}`,
                 url: "https://s3.mock.test/presigned-put",
@@ -375,6 +377,11 @@ const buildThumbFetch = (m: ThumbMockState) => {
 
         // Presigned PUT (S3 upload)
         if (url.startsWith("https://s3.mock.test/")) {
+            // Storage refuses a PUT that lacks the signed `Content-MD5`.
+            const headers = new Headers(init?.headers);
+            if (headers.get("Content-MD5") !== signedMD5) {
+                return new Response("AccessDenied", { status: 400 });
+            }
             const body = init?.body;
             // Store the uploaded bytes for later inspection
             if (body instanceof Uint8Array) {