quak login --server: log in to a self-hosted Ente server (closes #243)

`quak login` takes the server's API address from `--server` or
`QUAK_SERVER`, refusing anything that is not an http or https URL. The
client's snapshot now keeps a non-default `apiOrigin`, so the session
file names the server and every later command uses it. A snapshot's
`apiOrigin` wins over the one in `fromJSON`'s `apiOptions`, since the
token belongs to that server.

Model: opus-5-5

README.md

@@ -156,10 +156,9 @@ 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
@@ -230,7 +229,7 @@ below belong to quak itself, and go before or after the command's name.
 ### The commands
 
 ```
-quak login
+quak login [--server <url>]
 quak whoami
 quak logout
 quak collections [--json]
@@ -247,13 +246,26 @@ Every command but `login` and `logout` needs a saved session. Every command but
 `login`, `whoami` and `logout` opens the library. How each one gets current data
 from the server is described under "How a command gets current data".
 
-#### `quak login`
+#### `quak login [--server <url>]`
 
 Logs in to an account and saves the session. It reads the email from
 `QUAK_EMAIL` and the password from `QUAK_PASSWORD`. For each one that is not
 set, it asks on the terminal. The password shows as `*` characters while it is
 typed.
 
+quak logs in to Ente's hosted service unless you name a self-hosted Ente server.
+Name it with `--server`, or with `QUAK_SERVER` when `--server` is not given.
+Give the address of the server's API, for example
+`quak login --server https://ente.example.com`. The address is an http or https
+URL. It may include a path, but no query or fragment. quak refuses any other
+address before it asks for anything. It logs
+`Invalid server address "<url>": it must be an http or https URL with no query or fragment`,
+and the exit status is 1.
+
+The session file keeps the server's address. Every later command, cron runs
+included, uses that server without further setting. To change server, log in
+again.
+
 When the account has a second factor, quak asks for the code. It asks
 `TOTP code: ` for a time-based code from an authenticator app. An account whose
 only second factor is a passkey cannot log in with quak. When the account has
@@ -598,9 +610,11 @@ Linux that is `$XDG_DATA_HOME/quak/session.json`, or
 mode `0600`, in a directory it creates with mode `0700`.
 
 The file holds the account's email, its user ID, the session token and the
-account's three keys, in base64 and unencrypted. Treat it as you would treat the
+account's three keys, in base64 and unencrypted. After a login to a self-hosted
-password. A missing file means "not logged in". A file that cannot be read back
+server, it also holds the server's address as `apiOrigin`. Treat it as you would
-is reported as corrupt, with the reason. Run `quak logout`, then `quak login`.
+treat the password. A missing file means "not logged in". A file that cannot be
+read back is reported as corrupt, with the reason. Run `quak logout`, then
+`quak login`.
 
 A command that needs a session exits 3 when the file is missing or corrupt. It
 also exits 3 when the server no longer accepts the session, and prints
@@ -1478,6 +1492,11 @@ write wherever it likes. `Client.fromJSON(snapshot, apiOptions?)` restores a
 working client from that snapshot without logging in again. It checks every
 field and each key's length first, and throws an error naming the bad field.
 
+A client whose `apiOptions` named an `apiOrigin` puts it in its snapshot. The
+restored client then uses that server, even when the `apiOptions` given to
+`Client.fromJSON` name another. A snapshot without `apiOrigin` uses the
+`apiOrigin` of those `apiOptions`, or the default server.
+
 `Client.fromJSON` works only once libsodium, the cryptography library quak uses,
 is loaded. `Client.login` loads it, and `Client.fromJSON` does not. A program
 that restores a session in a new process first runs `await sodium.ready`, with
@@ -1937,11 +1956,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's glibc and musl builds, which `script/build-bin` downloads on Linux,
+    - the bun builds `script/build-bin` downloads, by SHA-256 hash;
-      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

bin/quak.ts

@@ -74,7 +74,11 @@ const context = (): CliContext => ({
     sessionDir: paths.data,
     cacheDir: program.opts<ProgramOptions>().cacheDir,
     loadSession: (path) => loadSession(path, logRequests(log())),
-    login: (opts) => Client.login({ ...opts, apiOptions: logRequests(log()) }),
+    login: (opts) =>
+        Client.login({
+            ...opts,
+            apiOptions: { ...opts.apiOptions, ...logRequests(log()) },
+        }),
     prompt: (message) => input({ message }),
     promptSecret: (message) => password({ message, mask: true }),
 });
@@ -85,7 +89,12 @@ const run = (command: Promise<number>): Promise<void> =>
 program
     .command("login")
     .description("Log in to an Ente account and save the session")
-    .action(() => run(loginCommand(context())));
+    .option(
+        "--server <url>",
+        "Address of a self-hosted Ente server's API, saved with the session " +
+            "(default: QUAK_SERVER, then Ente's hosted service)",
+    )
+    .action((opts: { server?: string }) => run(loginCommand(context(), opts)));
 
 program
     .command("whoami")

script/build-bin

@@ -3,12 +3,13 @@
 # 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)"
@@ -22,6 +23,8 @@ BUN_LINUX_X64_BASELINE_SHA256="9d8a24292a7068090205daac0a5a223f5f69736f5287e37bf
 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() {
@@ -29,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
 }
@@ -59,13 +67,17 @@ main() {
             compile_with_downloaded_bun bun-linux-aarch64-musl \
                 "$BUN_LINUX_AARCH64_MUSL_SHA256"
             ;;
-        Linux-*)
+        Darwin-x86_64)
-            echo "build-bin: bun has no release build for Linux on $(uname -m)" >&2
+            compile_with_downloaded_bun bun-darwin-x64-baseline \
-            exit 1
+                "$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/cli-commands.ts

@@ -155,8 +155,31 @@ const openReadLibrary = (ctx: CliContext, client: Client): Promise<Library> =>
         onProgress: logRefresh(ctx.log),
     });
 
-export const loginCommand = async (ctx: CliContext): Promise<number> => {
+// Logs in to the server `--server` or `QUAK_SERVER` names, the flag first, or
+// to Ente's hosted service when neither is set. The saved session keeps the
+// server, so every later command uses it.
+// Whether `text` can be an Ente server's address: an http or https URL, which
+// may have a path, and no query or fragment, which request URLs could not
+// carry.
+const isServerAddress = (text: string): boolean =>
+    URL.canParse(text) &&
+    ["http:", "https:"].includes(new URL(text).protocol) &&
+    !/[?#]/.test(text);
+
+export const loginCommand = async (
+    ctx: CliContext,
+    opts: { server?: string },
+): Promise<number> => {
     await init();
+    const server = opts.server ?? process.env.QUAK_SERVER;
+    if (server !== undefined && !isServerAddress(server)) {
+        ctx.log(
+            "fatal",
+            `Invalid server address "${server}": it must be an http or ` +
+                `https URL with no query or fragment`,
+        );
+        return 1;
+    }
     const email = process.env.QUAK_EMAIL ?? (await ctx.prompt("Email"));
     const password =
         process.env.QUAK_PASSWORD ?? (await ctx.promptSecret("Password"));
@@ -168,6 +191,8 @@ export const loginCommand = async (ctx: CliContext): Promise<number> => {
             password,
             totp: async () => ctx.prompt("TOTP code: "),
             emailOTP: async () => ctx.prompt("Email verification code: "),
+            apiOptions:
+                server === undefined ? undefined : { apiOrigin: server },
         });
 
         saveSession(ctx.sessionDir, client.toJSON());

src/client.ts

@@ -40,6 +40,9 @@ export interface ClientSnapshot {
     masterKey: string;
     secretKey: string;
     publicKey: string;
+    // The `apiOrigin` the client was given, so a restored client talks to
+    // the server that issued its token. Absent means the default server.
+    apiOrigin?: string;
 }
 
 // The result of a resumable enumeration. Live decrypted records and deleted
@@ -73,6 +76,7 @@ export class Client {
     private readonly masterKey: Uint8Array;
     private readonly secretKey: Uint8Array;
     private readonly publicKey: Uint8Array;
+    private readonly apiOrigin: string | undefined;
     private loggedOut = false;
 
     private constructor(
@@ -82,6 +86,7 @@ export class Client {
         masterKey: Uint8Array,
         secretKey: Uint8Array,
         publicKey: Uint8Array,
+        apiOrigin: string | undefined,
     ) {
         this.api = api;
         this.email = email;
@@ -89,6 +94,7 @@ export class Client {
         this.masterKey = masterKey;
         this.secretKey = secretKey;
         this.publicKey = publicKey;
+        this.apiOrigin = apiOrigin;
     }
 
     static async login(opts: LoginOptions): Promise<Client> {
@@ -130,12 +136,15 @@ export class Client {
             unwrapped.masterKey,
             unwrapped.secretKey,
             unwrapped.publicKey,
+            opts.apiOptions?.apiOrigin,
         );
     }
 
     // Restore a client from a `toJSON()` snapshot. The snapshot usually comes
     // straight from `JSON.parse` of a file on disk, so every field is checked
-    // before use; a bad one throws an error naming it. Needs `init()` first.
+    // before use; a bad one throws an error naming it. The snapshot's
+    // `apiOrigin`, when it has one, is used instead of `apiOptions.apiOrigin`.
+    // Needs `init()` first.
     static fromJSON(snapshot: unknown, apiOptions?: ApiClientOptions): Client {
         const invalid = (field: string, problem: string): Error =>
             new Error(`Invalid session data: ${field} ${problem}`);
@@ -152,6 +161,14 @@ export class Client {
         if (!Number.isInteger(s.userID)) {
             throw invalid("userID", "must be an integer");
         }
+        if (
+            s.apiOrigin !== undefined &&
+            (typeof s.apiOrigin !== "string" || s.apiOrigin === "")
+        ) {
+            throw invalid("apiOrigin", "must be a non-empty string");
+        }
+        const apiOrigin =
+            (s.apiOrigin as string | undefined) ?? apiOptions?.apiOrigin;
         const key = (field: string): Uint8Array => {
             const value = s[field];
             if (typeof value !== "string") {
@@ -175,6 +192,7 @@ export class Client {
 
         const api = new ApiClient({
             ...apiOptions,
+            apiOrigin,
             authToken: s.token as string,
         });
         return new Client(
@@ -184,6 +202,7 @@ export class Client {
             key("masterKey"),
             key("secretKey"),
             key("publicKey"),
+            apiOrigin,
         );
     }
 
@@ -222,6 +241,9 @@ export class Client {
             masterKey: toBase64(this.masterKey),
             secretKey: toBase64(this.secretKey),
             publicKey: toBase64(this.publicKey),
+            ...(this.apiOrigin === undefined
+                ? {}
+                : { apiOrigin: this.apiOrigin }),
         };
     }
 

test/cli/bin.test.ts

@@ -2,8 +2,9 @@
  * Tests for the retry options `bin/quak.ts` loads the saved session with
  * (`quak backup` gets the unattended ones, every other command the default),
  * each with the callbacks that log its requests and retries, for `quak files`
- * taking its collection ID as an optional argument, and for `quak get` and
+ * taking its collection ID as an optional argument, for `quak get` and
- * `quak get-thumb` refusing `--collection`.
+ * `quak get-thumb` refusing `--collection`, and for `quak login` taking
+ * `--server`.
  *
  * Each test runs `bin/quak.ts`, as the smoke test does, with its session loader
  * replaced by one that records the options it is given and reports no session,
@@ -117,3 +118,13 @@ describe("bin/quak.ts get and get-thumb", () => {
         },
     );
 });
+
+// The command refuses an address that is not a URL before it asks for anything
+// or sends any request.
+describe("bin/quak.ts login", () => {
+    it("hands --server to the command", async () => {
+        expect(await quak("login", "--server", "ente.example.com")).toMatch(
+            /^Invalid server address "ente\.example\.com"/,
+        );
+    });
+});

test/cli/commands.test.ts

@@ -328,6 +328,7 @@ describe("login", () => {
         prompts = [];
         vi.stubEnv("QUAK_EMAIL", "cli@example.com");
         vi.stubEnv("QUAK_PASSWORD", "hunter2");
+        vi.stubEnv("QUAK_SERVER", undefined);
     });
 
     afterEach(() => {
@@ -340,12 +341,14 @@ describe("login", () => {
             calls.push(opts);
             return loggedIn;
         });
-        expect(await loginCommand(ctx)).toBe(0);
+        expect(await loginCommand(ctx, {})).toBe(0);
 
         expect(prompts).toEqual([]);
         expect(calls).toHaveLength(1);
         expect(calls[0]!.email).toBe("cli@example.com");
         expect(calls[0]!.password).toBe("hunter2");
+        // No server named: the client uses Ente's hosted service.
+        expect(calls[0]!.apiOptions).toBeUndefined();
         const path = join(ctx.sessionDir, "session.json");
         expect(stderr.text).toBe(
             "Authenticating...\n" +
@@ -356,7 +359,7 @@ describe("login", () => {
 
     it("saves the session with mode 0600 in a directory with mode 0700", async () => {
         const ctx = loginContext(async () => loggedIn);
-        expect(await loginCommand(ctx)).toBe(0);
+        expect(await loginCommand(ctx, {})).toBe(0);
 
         expect(statSync(ctx.sessionDir).mode & 0o777).toBe(0o700);
         const path = join(ctx.sessionDir, "session.json");
@@ -370,7 +373,7 @@ describe("login", () => {
             code = await opts.totp!();
             return loggedIn;
         });
-        expect(await loginCommand(ctx)).toBe(0);
+        expect(await loginCommand(ctx, {})).toBe(0);
 
         expect(prompts).toEqual(["TOTP code: "]);
         expect(code).toBe("123456");
@@ -380,13 +383,68 @@ describe("login", () => {
         const ctx = loginContext(async () => {
             throw new Error("HTTP 401 from server");
         });
-        expect(await loginCommand(ctx)).toBe(1);
+        expect(await loginCommand(ctx, {})).toBe(1);
 
         expect(stderr.text).toBe(
             "Authenticating...\nLogin failed: HTTP 401 from server\n",
         );
         expect(existsSync(join(ctx.sessionDir, "session.json"))).toBe(false);
     });
+
+    it("logs in to the server --server names, ahead of QUAK_SERVER", async () => {
+        vi.stubEnv("QUAK_SERVER", "https://other.example.com");
+        const calls: LoginOptions[] = [];
+        const ctx = loginContext(async (opts) => {
+            calls.push(opts);
+            return loggedIn;
+        });
+        expect(
+            await loginCommand(ctx, { server: "https://ente.example.com" }),
+        ).toBe(0);
+
+        expect(calls[0]!.apiOptions).toEqual({
+            apiOrigin: "https://ente.example.com",
+        });
+    });
+
+    it("logs in to the server QUAK_SERVER names without --server", async () => {
+        vi.stubEnv("QUAK_SERVER", "http://192.0.2.1:8080/ente");
+        const calls: LoginOptions[] = [];
+        const ctx = loginContext(async (opts) => {
+            calls.push(opts);
+            return loggedIn;
+        });
+        expect(await loginCommand(ctx, {})).toBe(0);
+
+        expect(calls[0]!.apiOptions).toEqual({
+            apiOrigin: "http://192.0.2.1:8080/ente",
+        });
+    });
+
+    it.each([
+        "",
+        "ente.example.com",
+        "ftp://ente.example.com",
+        "https://ente.example.com/?region=eu",
+        "https://ente.example.com/#top",
+    ])(
+        "refuses the server address %j before asking for anything",
+        async (server) => {
+            const ctx = loginContext(async () => {
+                throw new Error("login must not be called");
+            });
+            expect(await loginCommand(ctx, { server })).toBe(1);
+
+            expect(prompts).toEqual([]);
+            expect(stderr.text).toBe(
+                `Invalid server address "${server}": it must be an http or ` +
+                    `https URL with no query or fragment\n`,
+            );
+            expect(existsSync(join(ctx.sessionDir, "session.json"))).toBe(
+                false,
+            );
+        },
+    );
 });
 
 // These use a real client read from the session file, over a fake API that
@@ -1851,6 +1909,47 @@ describe("an account with many albums", () => {
         expect(existsSync(join(root, "cache", "metadata.json"))).toBe(false);
     });
 
+    // A self-hosted server serves downloads under its own address, at
+    // `/files/download/<id>`, so no request goes to Ente's hosted service.
+    it("login --server saves the server, and a later get sends every request to it", async () => {
+        vi.stubEnv("QUAK_EMAIL", "many@example.com");
+        vi.stubEnv("QUAK_PASSWORD", PASSWORD);
+        vi.stubEnv("QUAK_SERVER", undefined);
+        const hosts = new Set<string>();
+        const fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+            hosts.add(
+                new URL(input instanceof Request ? input.url : input).host,
+            );
+            return server(input, init);
+        }) as typeof globalThis.fetch;
+        const ctx: CliContext = {
+            ...context(),
+            login: (opts) =>
+                Client.login({
+                    ...opts,
+                    apiOptions: { ...opts.apiOptions, fetch },
+                }),
+            loadSession: (path) => loadSession(path, { fetch }),
+        };
+        const out = join(root, "photo.jpg");
+        try {
+            const opts = { server: "https://ente.example.com" };
+            expect(await loginCommand(ctx, opts)).toBe(0);
+            requests.length = 0;
+            expect(await getCommand(ctx, "200", { out })).toBe(0);
+        } finally {
+            vi.unstubAllEnvs();
+        }
+
+        const path = join(ctx.sessionDir, "session.json");
+        expect(JSON.parse(readFileSync(path, "utf-8")).apiOrigin).toBe(
+            "https://ente.example.com",
+        );
+        expect(readFileSync(out, "utf-8")).toBe("photo-2.jpg");
+        expect(requests.at(-1)).toBe("/files/download/200");
+        expect([...hosts]).toEqual(["ente.example.com"]);
+    });
+
     // `files` first fills the cache, so `get` waits for a refresh. No album has
     // changed since, so the refresh asks for no album's files.
     it("get on a cache that holds the account asks for no unchanged album's files, also for a photo in no album", async () => {

test/client/session.test.ts

@@ -47,6 +47,20 @@ describe("Client.toJSON", () => {
         expect(Client.fromJSON(snapshot).toJSON()).toEqual(snapshot);
     });
 
+    it("round-trips a snapshot that names a server", () => {
+        const snapshot = {
+            ...validSnapshot(),
+            apiOrigin: "https://ente.example.com",
+        };
+        expect(Client.fromJSON(snapshot).toJSON()).toEqual(snapshot);
+    });
+
+    it("names the server apiOptions gave fromJSON", () => {
+        const apiOrigin = "https://ente.example.com";
+        const client = Client.fromJSON(validSnapshot(), { apiOrigin });
+        expect(client.toJSON().apiOrigin).toBe(apiOrigin);
+    });
+
     it("throws instead of emitting a snapshot without a token", () => {
         const client = Client.fromJSON(validSnapshot());
         client.getApiClient().clearAuthToken();
@@ -77,6 +91,8 @@ describe("Client.fromJSON", () => {
         ["publicKey", undefined],
         ["publicKey", "not base64!"],
         ["publicKey", shortKey],
+        ["apiOrigin", 7],
+        ["apiOrigin", ""],
     ])("rejects %s = %j, naming the field", (field, value) => {
         const snapshot: Record<string, unknown> = { ...validSnapshot() };
         snapshot[field] = value;
@@ -85,6 +101,30 @@ describe("Client.fromJSON", () => {
         );
     });
 
+    // The token belongs to the snapshot's server, so that server wins over
+    // the one in `apiOptions`.
+    it("sends requests to the snapshot's server", async () => {
+        const urls: string[] = [];
+        const client = Client.fromJSON(
+            { ...validSnapshot(), apiOrigin: "https://ente.example.com/" },
+            {
+                apiOrigin: "https://other.example.com",
+                fetch: async (input) => {
+                    urls.push(String(input));
+                    return new Response(JSON.stringify({ collections: [] }), {
+                        status: 200,
+                        headers: { "content-type": "application/json" },
+                    });
+                },
+            },
+        );
+
+        await client.listCollections();
+        expect(urls).toEqual([
+            "https://ente.example.com/collections/v2?sinceTime=0",
+        ]);
+    });
+
     it.each([null, "a string", 42])("rejects a non-object %j", (value) => {
         expect(() => Client.fromJSON(value)).toThrow(
             /^Invalid session data: not a JSON object/,

test/packaging/build-bin.test.ts

@@ -1,30 +1,29 @@
 // `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 through the same C library as the bun that built it. nix's bun
+// binary loads the same libraries as the bun that built it. nix's bun loads
-// loads through a C library in the nix store, which garbage collection can
+// libraries from the nix store, which garbage collection can delete: on Linux
-// delete. On Linux the script therefore downloads bun's own release build,
+// its C library, on macOS its ICU. The script therefore downloads bun's own
-// which loads through the system's C library.
+// release build, which loads only the system's libraries.
 //
 // What the script promises, and why each test matters:
 //
-// - On Linux, each machine and C library that bun publishes a build for gets
+// - Each system, machine and C library that bun publishes a build for gets its
-//   its own archive: x86-64 or arm64, with glibc or with musl, as on Alpine. A
+//   own archive: Linux on x86-64 or arm64, with glibc or with musl, as on
-//   bun built for another machine or C library does not start, and
+//   Alpine, and macOS on Intel or Apple silicon. A bun built for another
-//   `make install` fails.
+//   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.
-// - Linux on any other machine stops with an error. Building there with nix's
+// - Any other system or machine stops with an error, and never falls back to
-//   bun would bring back the dependency on the nix store.
+//   nix's bun. Building with nix's bun would bring back the dependency on the
-// - Other systems, such as macOS, compile with nix's bun as before, and
+//   nix store.
-//   download nothing.
 //
 // 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` and `nix-shell`, so no test downloads
+// `uname`, `ldd`, `curl`, `unzip`, `nix-shell` and `shasum`, so no test
-// anything or runs a real bun.
+// downloads anything or runs a real bun.
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { spawnSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import {
     chmodSync,
     copyFileSync,
@@ -33,6 +32,7 @@ import {
     mkdtempSync,
     readFileSync,
     rmSync,
+    symlinkSync,
     writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
@@ -42,9 +42,10 @@ 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` and
+// system that runBuildBin passes in the environment. `curl`, `unzip`,
-// `nix-shell` write the arguments they were given, one per line, to a file
+// `nix-shell` and `shasum` write the arguments they were given, one per line,
-// named after the command in $STUB_LOG_DIR, which also shows that they ran.
+// 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
@@ -82,6 +83,11 @@ const stubs: Record<string, string> = {
         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 = "";
@@ -114,13 +120,21 @@ afterEach(() => {
 });
 
 // Runs the script with nothing in its environment but the stubs' settings and a
-// PATH that finds the stubs first.
+// PATH. Unless the caller passes one, the PATH finds the stubs first and then
-const runBuildBin = (system: string, machine: string, libc = "glibc") =>
+// 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: `${join(checkout, "stubs")}:${process.env.PATH}`,
+            PATH: path,
             STUB_UNAME_S: system,
             STUB_UNAME_M: machine,
             STUB_LIBC: libc,
@@ -128,6 +142,31 @@ const runBuildBin = (system: string, machine: string, libc = "glibc") =>
         },
     });
 
+// 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));
 
@@ -139,42 +178,64 @@ const argumentsOf = (command: string): string[] =>
 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.
+    // 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([
-        ["x86_64", "glibc", "bun-linux-x64-baseline.zip"],
+        ["Linux", "x86_64", "glibc", "bun-linux-x64-baseline.zip"],
-        ["x86_64", "musl", "bun-linux-x64-musl-baseline.zip"],
+        ["Linux", "x86_64", "musl", "bun-linux-x64-musl-baseline.zip"],
-        ["aarch64", "glibc", "bun-linux-aarch64.zip"],
+        ["Linux", "aarch64", "glibc", "bun-linux-aarch64.zip"],
-        ["aarch64", "musl", "bun-linux-aarch64-musl.zip"],
+        ["Linux", "aarch64", "musl", "bun-linux-aarch64-musl.zip"],
     ])(
-        "on Linux %s with %s, downloads %s and stops when its hash does not match",
+        "on %s %s with %s, downloads %s and stops when its hash does not match",
-        (machine, libc, archive) => {
+        (system, machine, libc, archive) => {
-            const result = runBuildBin("Linux", machine, libc);
+            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);
         },
     );
 
-    it("stops on a Linux machine that bun publishes no build for", () => {
+    // On the PATH from makeMacPath the script finds no `sha256sum` and checks
-        const result = runBuildBin("Linux", "riscv64");
+    // the hash with the stub `shasum`. That stub fails, so the script must stop
-        expect(result.status).not.toBe(0);
+    // before unzip runs.
-        expect(ran("curl")).toBe(false);
+    // On Apple silicon `uname -m` says arm64, where bun's archive says aarch64.
-        expect(ran("nix-shell")).toBe(false);
+    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("compiles with nix's bun on macOS", () => {
+    it.each([
-        const result = runBuildBin("Darwin", "arm64");
+        ["Linux", "riscv64"],
-        expect(result.status).toBe(0);
+        ["FreeBSD", "amd64"],
-        expect(ran("curl")).toBe(false);
+    ])(
-        expect(argumentsOf("nix-shell")).toEqual([
+        "stops on %s %s, which bun publishes no build for",
-            "-p",
+        (system, machine) => {
-            "bun",
+            const result = runBuildBin(system, machine);
-            "--run",
+            expect(result.status).not.toBe(0);
-            "bun build dist/bin/quak.js --compile --outfile bin/quak",
+            expect(ran("curl")).toBe(false);
-        ]);
+            expect(ran("nix-shell")).toBe(false);
-    });
+        },
+    );
 });