Refresh vendored REPO_POLICIES.md from prompts repo

/collections/v2 is a sync API: deleted collections remain in the
response forever with isDeleted: true, and their /collections/v2/diff
endpoint returns HTTP 404. A long-lived account accumulates hundreds
of tombstones, so any caller that iterates listCollections() output
(backup, backup-metadata) dies on the first one.

.gitea/workflows/check.yml

@@ -6,4 +6,4 @@ jobs:
         steps:
             # actions/checkout v4.2.2, 2026-02-22
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-            - run: docker build .
+            - run: script/cibuild

.gitignore

@@ -30,6 +30,9 @@ coverage/
 *.pem
 *.key
 
+# Compiled binary (built by make build-bin)
+bin/quak
+
 # quak runtime data (in case anyone runs the CLI from inside the repo)
 .quak/
 

Dockerfile

@@ -1,11 +1,10 @@
 # node 22-alpine, 2026-02-22
 FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
 
-RUN apk add --no-cache make
-
 WORKDIR /app
+COPY script/ script/
 COPY package.json yarn.lock ./
-RUN yarn install --frozen-lockfile
+RUN script/bootstrap
 COPY . .
 
 RUN make check

Makefile

@@ -1,31 +1,39 @@
-.PHONY: test lint fmt fmt-check check build dev clean docker hooks
-
-# Use `timeout` (GNU coreutils) when available so `make test` is hard-capped.
-# On macOS without coreutils this is empty and the cap is skipped.
-TIMEOUT := $(shell command -v timeout 2>/dev/null || command -v gtimeout 2>/dev/null)
+.PHONY: bootstrap setup test lint fmt fmt-check check build build-bin install dev clean docker hooks
 
 YARN := yarn run
 
+bootstrap:
+	@script/bootstrap
+
+setup:
+	@script/setup
+
 test:
-	@$(TIMEOUT) $(if $(TIMEOUT),30s,) $(YARN) vitest run --reporter=dot || \
-		{ echo "--- Rerunning with verbose for details ---"; \
-		  $(YARN) vitest run --reporter=verbose; exit 1; }
+	@script/test
 
 lint:
-	@$(YARN) eslint .
-	@$(YARN) prettier --check .
+	@script/lint
 
 fmt:
-	@$(YARN) prettier --write .
+	@script/fmt
 
 fmt-check:
-	@$(YARN) prettier --check .
+	@script/fmt-check
 
-check: test lint fmt-check
+check:
+	@script/check
 
 build:
 	@$(YARN) tsc
 
+build-bin:
+	nix-shell -p bun --run "bun build bin/quak.ts --compile --outfile bin/quak"
+
+install: build-bin
+	mkdir -p ~/bin
+	cp bin/quak ~/bin/quak
+	chmod +x ~/bin/quak
+
 dev:
 	@$(YARN) tsc --watch
 
@@ -33,13 +41,7 @@ clean:
 	@rm -rf dist coverage .vitest-cache *.tsbuildinfo
 
 docker:
-	docker build -t quak .
+	@script/docker
 
 hooks:
-	@printf '#!/bin/sh\nset -e\nmake lint\nmake fmt-check\n' > .git/hooks/pre-commit
-	@chmod +x .git/hooks/pre-commit
-	@echo "Installed pre-commit hook (runs make lint && make fmt-check)."
-	@echo "Note: tests are deliberately not in the pre-commit hook so the"
-	@echo "TDD red-phase commit (failing tests, no implementation yet)"
-	@echo "can land. CI runs make check via docker build, which catches"
-	@echo "any branch that ships red."
+	@script/install-precommit

README.md

@@ -5,6 +5,15 @@ quak is a WTFPL-licensed TypeScript client library and CLI by
 encrypted photo hosting service. It logs in, enumerates collections and files,
 and downloads individual images while decrypting them on the way to disk.
 
+quak also includes a resilient backup command that downloads every file in the
+account into a deduplicated local directory tree, skipping files that already
+exist on disk and continuing past individual download failures instead of
+crashing. It decrypts and persists all three metadata layers (basic, private
+magic, public magic) per file, including camera info, GPS coordinates, captions,
+and any face/keyword labels the Ente clients have added. A helper subcommand can
+detect and regenerate missing thumbnails, encrypting and uploading them back to
+the server.
+
 ## Getting Started
 
 ```bash
@@ -14,7 +23,6 @@ yarn install
 yarn build
 
 # Log in (prompts for email, password, and OTP/TOTP if required).
-# Stores an encrypted session under $XDG_CONFIG_HOME/quak/.
 yarn quak login
 
 # List the user's collections (albums).
@@ -23,8 +31,11 @@ yarn quak collections
 # List files in a collection.
 yarn quak files --collection 12345
 
-# Download and decrypt a single file to ./out/.
-yarn quak get 67890 --out ./out/
+# Download and decrypt a single file.
+yarn quak get 67890 --out ./photo.jpg
+
+# Back up every file in the account.
+yarn quak backup ./my-backup
 ```
 
 For library use:
@@ -32,14 +43,63 @@ For library use:
 ```ts
 import { Client } from "quak";
 
-const client = await Client.fromSavedSession();
+const client = await Client.login({
+    email: "you@example.com",
+    password: "your-password",
+});
+
 for (const c of await client.listCollections()) {
     console.log(c.id, c.name);
+    const files = await client.listFiles(c.id, c.key);
+    for (const f of files) {
+        console.log(`  ${f.metadata.title} [${f.metadata.fileType}]`);
+    }
 }
-const file = await client.getFile(67890);
-await client.downloadFile(file, "./out/");
+
+// Download a file
+const files = await client.listFiles(collectionID, collectionKey);
+await client.downloadFile(files[0], "./photo.jpg");
+
+// Serialize session for later (consumer handles persistence)
+const snapshot = client.toJSON();
+// ... later:
+const restored = Client.fromJSON(snapshot);
 ```
 
+## Entrypoints
+
+This repository adheres to the
+[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+standard: normalized scripts in `script/` are the entrypoints for the
+development workflow, and the Makefile targets are thin shims that call them.
+The scripts are POSIX sh (not bash) so they run in minimal containers such as
+alpine. We provide:
+
+- `script/bootstrap` — install all dependencies (node/yarn if missing, then
+  `yarn install --frozen-lockfile`)
+- `script/setup` — set up the repo for development after a fresh clone: runs
+  `script/bootstrap`, then `script/install-precommit`
+- `script/projectname` — output the project name (our own extension); used by
+  `script/docker` for the image tag
+- `script/test` — run the test suite (vitest, hard-capped at 30s where `timeout`
+  is available, verbose rerun on failure)
+- `script/lint` — run eslint and a prettier check
+- `script/fmt` — format all files with prettier (writes)
+- `script/fmt-check` — check formatting (read-only)
+- `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own
+  extension)
+- `script/docker` — build the Docker image, tagged via `script/projectname`
+  (byte-identical across repos)
+- `script/cibuild` — cd to the repo root and `docker build .` (what CI runs; the
+  image build runs `make check`)
+- `script/precommit` — run by the git pre-commit hook (our own extension); runs
+  `script/lint` and `script/fmt-check` but deliberately not the tests, so the
+  TDD red-phase commit can land
+- `script/install-precommit` — installs the git pre-commit hook (our own
+  extension); `make hooks` shims to it
+
+`make hooks` installs the pre-commit hook that runs `script/precommit`.
+
 ## Rationale
 
 Ente is one of very few photo services with a credible end-to-end encryption
@@ -48,11 +108,13 @@ CLI) work, but they are slow, buggy, and difficult to script against. The
 Flutter app fails to sync reliably. The web app is heavy. The desktop app is the
 web app inside a slow Electron wrapper. The Go CLI is the closest thing to a
 usable tool, but it is awkward to integrate from anything that is not a shell.
+The Go CLI's backup mode crashes entirely when a single file download fails,
+which makes it useless as an actual backup tool.
 
-quak is the first step in fixing that. This repo ships a small, correct,
-well-tested implementation of Ente's cryptographic protocol and its read-only
-API surface, plus a CLI that proves the library is enough to do real work
-without a UI.
+quak fixes these problems. This repo ships a correct, well-tested implementation
+of Ente's cryptographic protocol and API surface, plus a CLI that proves the
+library is enough to do real work without a UI. The backup command is resilient
+by design: per-file errors are logged and the run continues.
 
 The longer-term goal of this project is a simple desktop client for Ente, built
 on this library in Electron (or a comparable runtime), with two priorities above
@@ -60,11 +122,6 @@ everything else: correctness and stability. Performance and simplicity follow
 from those. Features will be added only after the protocol layer is correct, the
 local cache is reliable, and the UI is responsive on a five-year-old laptop.
 
-This first release is deliberately scoped to read operations: log in, walk the
-account, decrypt and save files. Upload, sharing, deletion, and bidirectional
-sync are out of scope. Adding them later is straightforward; doing them right
-requires the protocol layer to be correct first.
-
 ## Development workflow
 
 All work on quak is test-driven. No exceptions.
@@ -90,11 +147,11 @@ All work on quak is test-driven. No exceptions.
    test-then-implementation sequence into reviewable commits, but the final
    history must still show tests landing before (or with) the matching
    implementation.
-8. The pre-commit hook installed by `make hooks` runs
-   `make lint && make fmt-check`, not the full `make check`. This is deliberate
-   so the TDD red-phase commit (failing tests, no implementation yet) can land.
-   The full `make check` runs as part of `docker build .`, which is what CI
-   executes, so a red branch still cannot reach `main`.
+8. The pre-commit hook installed by `make hooks` runs `script/precommit`, which
+   runs the lint and format checks but not the full `make check`. This is
+   deliberate so the TDD red-phase commit (failing tests, no implementation yet)
+   can land. The full `make check` runs as part of `docker build .`, which is
+   what CI executes, so a red branch still cannot reach `main`.
 
 ## Design
 
@@ -107,14 +164,16 @@ the CLI is for humans.
 quak/
     src/
         crypto/         libsodium primitives (boxes, secretstreams, KDF, SRP)
-        api/            HTTP client + typed endpoint wrappers
+        api/            HTTP client (ApiClient class)
         auth/           login flow (SRP + email OTP + TOTP), key unwrap
-        model/          decrypted Collection, File, Metadata types
-        session/        on-disk session persistence (token + master key)
+        model/          decrypted Collection, File, Metadata types + decrypt fns
+        download/       streaming file/thumbnail download + decryption
+        backup.ts       resilient full-account backup with dedup
+        thumbnails.ts   detect + regenerate missing thumbnails
         client.ts       high-level Client class assembled from the above
         index.ts        public library exports
     bin/
-        quak.ts        CLI entrypoint (commander.js)
+        quak.ts         CLI entrypoint (commander.js)
     test/               unit + integration tests (vitest)
     Makefile
     Dockerfile
@@ -150,9 +209,13 @@ The key hierarchy, derived during login, is:
 Per-collection keys are decrypted with `crypto_secretbox_open_easy` using the
 master key (for owned collections). Per-file keys are decrypted with
 `crypto_secretbox_open_easy` using the collection key. File metadata is a
-secretbox under the file key. File content is a chunked
-`crypto_secretstream_xchacha20poly1305` stream under the file key, with a 4 MiB
-plaintext chunk size and a 17-byte authentication overhead per chunk.
+secretstream blob (single chunk, TAG_FINAL) under the file key. File content is
+a chunked `crypto_secretstream_xchacha20poly1305` stream under the file key,
+with a 4 MiB plaintext chunk size and a 17-byte authentication overhead per
+chunk. Thumbnails use the same secretstream blob format as metadata.
+
+For upload (thumbnail repair), `encryptBlob` performs the push side: a single
+secretstream chunk with TAG_FINAL, returning the header and ciphertext.
 
 ### HTTP API
 
@@ -163,8 +226,8 @@ Production endpoints:
 - Thumbnail CDN: `https://thumbnails.ente.io/?fileID=<id>`
 
 A custom API endpoint is configurable for self-hosted servers via the
-`ENTE_API_ENDPOINT` environment variable. When set, file downloads route through
-`<endpoint>/files/download/<id>` instead of the dedicated CDN host.
+constructor option `apiOrigin`. When set, file downloads route through
+`<apiOrigin>/files/download/<id>` instead of the dedicated CDN host.
 
 Required request headers on every authenticated call:
 
@@ -184,514 +247,100 @@ Endpoints used:
 - `GET /collections/v2/diff?collectionID=<id>&sinceTime=<usec>`: list files in a
   collection; paginate while `hasMore` is true.
 - `GET https://files.ente.io/?fileID=<id>`: download encrypted file bytes.
+- `POST /files/upload-url`: mint a presigned upload URL (for thumbnail repair).
+- `PUT /files/thumbnail`: register an uploaded thumbnail's object key.
 
-### Session persistence
+### Session handling
 
-After login, quak writes an encrypted session blob to
-`$XDG_CONFIG_HOME/quak/session.json` (default `~/.config/quak/session.json`)
-containing the auth token, the user's master key, the user's secret key, and the
-user's email. The session file is itself encrypted with a key derived from a
-per-machine random value stored in the OS keychain when available, falling back
-to a key file at mode `0600` in the same config directory. The master key and
-secret key are never written to disk in cleartext.
+The `Client` class holds the auth token, master key, secret key, and public key
+in memory. There is no on-disk session store in the library; the consumer
+decides how to persist sessions.
+
+`client.toJSON()` returns a `ClientSnapshot` (a plain serializable object with
+base64-encoded keys) that the consumer can write to disk, a database, or
+whatever else fits their use case. `Client.fromJSON(snapshot)` restores a
+working client from that snapshot without re-authenticating.
+
+The CLI stores the snapshot at the platform-appropriate data directory via
+`env-paths`: `~/Library/Application Support/quak/session.json` on macOS,
+`$XDG_DATA_HOME/quak/session.json` on Linux. The file is written with mode
+`0600`. The key material is stored in cleartext in the JSON; treat this file as
+you would treat the password itself.
 
 ### CLI surface
 
-- `quak login`: interactive login, writes session.
-- `quak logout`: deletes the session.
-- `quak whoami`: prints the logged-in email.
-- `quak collections`: list collections (id, name, type, file count).
-- `quak files --collection <id>`: list files in a collection (id, name, type,
-  creation time, size).
-- `quak get <fileID> --out <dir>`: download and decrypt a file.
-- `quak get-thumb <fileID> --out <dir>`: download and decrypt a thumbnail.
-
-All commands accept `--json` for machine-readable output.
-
-## API reference
-
-The complete public surface of the library, expressed as TypeScript
-declarations. Every exported name is listed here. Anything not listed is
-internal.
-
-### Type aliases
-
-```ts
-// src/model/types.ts
-export type Bytes = Uint8Array;
-export type Base64 = string; // standard base64 unless noted
-export type Base64URL = string; // URL-safe base64
-export type Microseconds = number; // unix epoch microseconds (int64-ish)
+```
+quak login                                      interactive or QUAK_EMAIL/QUAK_PASSWORD
+quak whoami                                     print logged-in account as JSON
+quak logout                                     delete saved session
+quak collections [--json]                       list all collections
+quak files --collection <id> [--json]           list files in a collection
+quak get <fileID> [--out path] [--collection]   download and decrypt a file
+quak get-thumb <fileID> [--out] [--collection]  download and decrypt a thumbnail
+quak backup <dir> [--json]                      full incremental backup
+quak helper list-missing-thumbnails [--json]    find files with missing thumbnails
+quak helper fix-missing-thumbnails [--file ids] generate + upload missing thumbnails
 ```
 
-### Crypto module
+`get` and `get-thumb` search all collections for the file ID when `--collection`
+is not specified. All listing and backup commands support `--json` for
+machine-readable output.
 
-```ts
-// src/crypto/index.ts
+### Backup layout
 
-// Lazily initializes libsodium. Safe to call repeatedly; the first call
-// performs the init, subsequent calls are no-ops.
-export function init(): Promise<void>;
+`quak backup <dir>` produces:
 
-// Argon2id over a UTF-8 password and a 16-byte salt, producing a 32-byte
-// key. memLimit is in bytes, opsLimit is the iteration count, both as
-// returned by the server in SRP / key attributes.
-export function deriveKEK(
-    password: string,
-    salt: Bytes,
-    opsLimit: number,
-    memLimit: number,
-): Promise<Bytes>;
-
-// crypto_kdf_derive_from_key with subkey id 1 and context "loginctx",
-// returning the first 16 bytes. Used as the SRP password.
-export function deriveLoginSubkey(kek: Bytes): Bytes;
-
-// crypto_secretbox_open_easy. Returns plaintext or throws on auth failure.
-export function decryptBox(ciphertext: Bytes, nonce: Bytes, key: Bytes): Bytes;
-
-// crypto_box_seal_open. Used to recover the auth token after login.
-export function decryptSealed(
-    ciphertext: Bytes,
-    publicKey: Bytes,
-    secretKey: Bytes,
-): Bytes;
-
-// crypto_secretstream_xchacha20poly1305_init_pull. Returned state is opaque
-// and threaded through pullStreamChunk.
-export function initStreamPull(header: Bytes, key: Bytes): StreamPullState;
-
-// crypto_secretstream_xchacha20poly1305_pull. Tag values follow libsodium's
-// constants: 0=MESSAGE, 1=PUSH, 2=REKEY, 3=FINAL.
-export function pullStreamChunk(
-    state: StreamPullState,
-    ciphertext: Bytes,
-): { plaintext: Bytes; tag: number };
-
-// Convenience helpers. fromBase64 accepts both standard and URL-safe.
-export function fromBase64(s: Base64 | Base64URL): Bytes;
-export function toBase64(b: Bytes): Base64;
-export function toBase64URL(b: Bytes): Base64URL;
-
-// Plaintext chunk size used by Ente for file content streams.
-export const STREAM_CHUNK_SIZE: number; // 4 * 1024 * 1024
-
-// Encrypted-chunk overhead: secretstream auth tag (16) + tag byte (1).
-export const STREAM_CHUNK_OVERHEAD: number; // 17
-
-export interface StreamPullState {
-    /* opaque */
-}
+```
+<dir>/
+    originals/
+        <fileID>.<ext>          actual file content (one per unique file)
+        <fileID>.json           all decrypted metadata for that file
+    collections/
+        <name>/
+            <title> -> ../../originals/<fileID>.<ext>   (symlink)
+        <name>.json             collection metadata + file list
 ```
 
-### Auth module
-
-```ts
-// src/auth/types.ts
-
-export interface KDFParams {
-    kekSalt: Base64;
-    memLimit: number;
-    opsLimit: number;
-}
-
-export interface KeyAttributes {
-    kekSalt: Base64;
-    encryptedKey: Base64;
-    keyDecryptionNonce: Base64;
-    publicKey: Base64;
-    encryptedSecretKey: Base64;
-    secretKeyDecryptionNonce: Base64;
-    memLimit: number;
-    opsLimit: number;
-    masterKeyEncryptedWithRecoveryKey?: Base64;
-    masterKeyDecryptionNonce?: Base64;
-    recoveryKeyEncryptedWithMasterKey?: Base64;
-    recoveryKeyDecryptionNonce?: Base64;
-}
-
-export interface SRPAttributes {
-    srpUserID: string;
-    srpSalt: Base64;
-    memLimit: number;
-    opsLimit: number;
-    kekSalt: Base64;
-    isEmailMFAEnabled: boolean;
-}
-
-export interface AuthorizationResponse {
-    id: number; // user ID
-    keyAttributes?: KeyAttributes;
-    encryptedToken?: Base64URL; // sealed-box-encrypted to user's pubkey
-    twoFactorSessionID?: string;
-    passkeySessionID?: string;
-}
-
-export type LoginChallenge =
-    | { kind: "complete"; response: AuthorizationResponse }
-    | { kind: "totp"; sessionID: string }
-    | { kind: "passkey"; sessionID: string }
-    | { kind: "emailOTP" };
-```
-
-```ts
-// src/auth/index.ts
-
-// Begin login. Returns a challenge that tells the caller what to do next:
-// supply a TOTP code, supply an email OTP, follow a passkey URL, or stop
-// because login is already complete.
-export function beginLogin(
-    api: ApiClient,
-    email: string,
-    password: string,
-): Promise<LoginChallenge>;
-
-// Submit a TOTP code from an authenticator app. Returns the final
-// AuthorizationResponse on success.
-export function submitTOTP(
-    api: ApiClient,
-    sessionID: string,
-    code: string,
-): Promise<AuthorizationResponse>;
-
-// Request and submit an email-delivered one-time code. Two calls, because
-// the first triggers email delivery and the second verifies it.
-export function requestEmailOTP(api: ApiClient, email: string): Promise<void>;
-export function submitEmailOTP(
-    api: ApiClient,
-    email: string,
-    code: string,
-): Promise<AuthorizationResponse>;
-
-// Given an AuthorizationResponse and the user's password, decrypt the master
-// key, secret key, and auth token. Throws on bad password or tampered data.
-export function unwrapAuth(
-    response: AuthorizationResponse,
-    password: string,
-): Promise<{
-    masterKey: Bytes;
-    secretKey: Bytes;
-    publicKey: Bytes;
-    token: string; // base64 URL-safe; goes into X-Auth-Token
-}>;
-```
-
-### Model module
-
-```ts
-// src/model/index.ts
-
-export type CollectionType =
-    | "album"
-    | "folder"
-    | "favorites"
-    | "uncategorized"
-    | "unknown";
-
-export interface Collection {
-    id: number;
-    ownerID: number;
-    key: Bytes; // decrypted
-    name: string; // decrypted
-    type: CollectionType;
-    updationTime: Microseconds;
-    isShared: boolean; // true if owner != current user
-}
-
-export type FileType = "image" | "video" | "livePhoto" | "unknown";
-
-export interface FileMetadata {
-    title: string;
-    fileType: FileType;
-    creationTime: Microseconds;
-    modificationTime: Microseconds;
-    latitude?: number;
-    longitude?: number;
-    hash?: string; // base64 of file SHA256
-}
-
-export interface FileBlob {
-    decryptionHeader: Base64;
-    size?: number; // size of the encrypted body, if known from server
-}
-
-export interface EnteFile {
-    id: number;
-    collectionID: number;
-    ownerID: number;
-    key: Bytes; // decrypted file key
-    metadata: FileMetadata;
-    file: FileBlob;
-    thumbnail: FileBlob;
-    updationTime: Microseconds;
-}
-```
-
-### HTTP client
-
-```ts
-// src/api/client.ts
-
-export interface ApiClientOptions {
-    apiOrigin?: string; // default https://api.ente.io
-    filesOrigin?: string; // default https://files.ente.io
-    thumbsOrigin?: string; // default https://thumbnails.ente.io
-    authToken?: string;
-    fetch?: typeof fetch; // injectable for tests
-    userAgent?: string; // default "quak/<version>"
-}
-
-export class ApiError extends Error {
-    readonly status: number;
-    readonly code?: string;
-    readonly requestID?: string;
-    readonly body?: unknown;
-}
-
-export class ApiClient {
-    constructor(opts?: ApiClientOptions);
-    setAuthToken(token: string): void;
-    clearAuthToken(): void;
-
-    getJSON<T>(
-        path: string,
-        query?: Record<string, string | number | undefined>,
-    ): Promise<T>;
-    postJSON<T>(path: string, body: unknown): Promise<T>;
-
-    // Streaming download from the file CDN. Caller is responsible for
-    // consuming the stream.
-    getFileStream(fileID: number): Promise<ReadableStream<Uint8Array>>;
-    getThumbnailStream(fileID: number): Promise<ReadableStream<Uint8Array>>;
-}
-```
-
-### Session
-
-```ts
-// src/session/index.ts
-
-export interface Session {
-    email: string;
-    userID: number;
-    token: string; // base64 URL-safe
-    masterKey: Bytes; // 32 bytes, never serialized in cleartext
-    secretKey: Bytes; // 32 bytes, never serialized in cleartext
-    publicKey: Bytes; // 32 bytes
-}
-
-export interface SessionStoreOptions {
-    path?: string; // default $XDG_CONFIG_HOME/quak/session.json
-    keychainService?: string; // default "berlin.sneak.quak"
-}
-
-export class SessionStore {
-    constructor(opts?: SessionStoreOptions);
-    load(): Promise<Session | null>;
-    save(s: Session): Promise<void>;
-    clear(): Promise<void>;
-}
-```
-
-### Client
-
-```ts
-// src/client.ts
-
-export interface LoginPrompt {
-    password: () => Promise<string>;
-    emailOTP?: () => Promise<string>; // called when account uses email OTP
-    totp?: () => Promise<string>; // called when TOTP is required
-}
-
-export interface ClientOptions extends ApiClientOptions {
-    sessionStore?: SessionStore;
-}
-
-export interface DownloadResult {
-    path: string;
-    bytesWritten: number;
-}
-
-export class Client {
-    // Static constructors. Both end with a Client that has a populated
-    // session and a ready ApiClient.
-    static login(
-        email: string,
-        prompt: LoginPrompt,
-        opts?: ClientOptions,
-    ): Promise<Client>;
-    static fromSavedSession(opts?: ClientOptions): Promise<Client>;
-
-    readonly api: ApiClient;
-    readonly session: Readonly<Session>;
-
-    // Account.
-    whoami(): { email: string; userID: number };
-    saveSession(): Promise<void>;
-    logout(): Promise<void>; // clears session on disk and in memory
-
-    // Collections.
-    listCollections(opts?: { sinceTime?: Microseconds }): Promise<Collection[]>;
-    getCollection(id: number): Promise<Collection>;
-
-    // Files.
-    listFiles(
-        collectionID: number,
-        opts?: { sinceTime?: Microseconds },
-    ): Promise<EnteFile[]>;
-    getFile(fileID: number): Promise<EnteFile>;
-
-    // Downloads. If outPath is omitted, a path is constructed from the
-    // decrypted metadata title in the current working directory. If outPath
-    // is a directory, the filename is taken from the metadata title. If
-    // outPath is a file path, that file is written.
-    downloadFile(
-        file: EnteFile | number,
-        outPath?: string,
-    ): Promise<DownloadResult>;
-    downloadThumbnail(
-        file: EnteFile | number,
-        outPath?: string,
-    ): Promise<DownloadResult>;
-}
-```
-
-### Public exports (`src/index.ts`)
-
-```ts
-export { Client } from "./client";
-export { ApiClient, ApiError } from "./api/client";
-export { SessionStore } from "./session";
-export * from "./model";
-export type {
-    Session,
-    LoginPrompt,
-    ClientOptions,
-    DownloadResult,
-} from "./client";
-```
+Each file is downloaded exactly once regardless of how many collections it
+appears in. On subsequent runs, existing originals are skipped. If a download
+fails, the error is logged and the backup continues with the next file. The exit
+code is non-zero if any files failed.
 
 ## TODO
 
-Phase 1: scaffolding
-
-- [x] `git init`, write README
-- [x] Create `initial-scaffolding` feature branch
-- [x] Add `LICENSE` (WTFPL), `REPO_POLICIES.md`, `.gitignore`, `.editorconfig`,
-      `.prettierrc`, `.prettierignore`, `.dockerignore`
-- [x] Add `Makefile` with `test`, `lint`, `fmt`, `fmt-check`, `check`, `docker`,
-      `hooks`, plus `build`, `dev`, `clean`
-- [x] Add `Dockerfile` running `make check` against pinned node image
-- [x] Add `.gitea/workflows/check.yml` running `docker build .`
-- [x] Add `package.json`, `tsconfig.json`, pinned dev versions of `typescript`,
-      `prettier`, `eslint`, `typescript-eslint`, `vitest`, `@types/node` (the
-      runtime deps `libsodium-wrappers-sumo`, `secure-remote-password`,
-      `commander`, etc. land with their respective implementation phases)
-- [x] Smoke test: `make check` and `make docker` both pass
-
-Phase 2: crypto primitives
-
-- [x] Wrap libsodium init as an awaitable singleton
-- [x] `deriveKEK(password, kekSalt, memLimit, opsLimit)` (Argon2id)
-- [x] `deriveLoginSubkey(kek)` (KDF with subkey id 1, context `loginctx`, 16
-      bytes)
-- [x] `decryptBox(ciphertext, nonce, key)` for secretbox
-- [x] `decryptSealed(ciphertext, publicKey, secretKey)` for sealed box
-- [x] `initStreamPull` and `pullStreamChunk` for chunked secretstream (4 MiB
-      plaintext chunks, 17-byte overhead)
-- [x] Round-trip tests against vectors generated by libsodium directly
-- [x] Base64 helpers (`fromBase64`, `toBase64`, `toBase64URL`) accepting all
-      four sodium variants on input
-
-Phase 3: SRP + auth
-
-- [x] SRP-6a client using `fast-srp-hap` with the 4096-bit group (matching the
-      upstream Ente web client)
-- [x] `beginLogin(api, email, password)` returning a `LoginChallenge`
-- [x] `requestEmailOTP` and `submitEmailOTP` for accounts without SRP
-- [x] `submitTOTP(api, sessionID, code)`
-- [x] `unwrapAuth(response, password)` returning master key, secret key, public
-      key, and decrypted token (URL-safe-no-padding base64)
-- [x] `src/auth/types.ts` with `KeyAttributes`, `SRPAttributes`,
-      `AuthorizationResponse`, and `LoginChallenge`
-- [x] Tests with mock SRP server performing real 4096-bit math end-to-end
-
-Phase 4: HTTP client + endpoints
-
-- [x] `ApiClient` that attaches `X-Auth-Token` and `X-Client-Package`
-- [x] `ApiError` that surfaces the server's error code and request id
-- [x] `getJSON` / `postJSON` with query-param and JSON-body handling
-- [x] `getFileStream` / `getThumbnailStream` with self-hosted routing
-- [ ] Typed wrappers for the endpoints listed above
 - [ ] Retry policy: no retry on 4xx, exponential backoff on 5xx and network
       errors
-
-Phase 5: collections and files
-
-- [x] `decryptCollection(raw, masterKey)` with key + name decryption, type
-      mapping, isShared flag
-- [x] `decryptFile(raw, collectionKey)` with key + metadata decryption
-      (secretstream blob, not secretbox), fileType mapping, header passthrough
-- [x] `decryptBlob(ciphertext, header, key)` convenience for single-chunk
-      secretstream decryption (used by file metadata and magic metadata)
-- [x] Model types: `Collection`, `EnteFile`, `FileMetadata`, `RawCollection`,
-      `RawEnteFile`
-- [x] Live-tested against real Ente API (collection names + file metadata)
-- [ ] Higher-level `listCollections()` / `listFiles()` with pagination
-
-Phase 6: download
-
-- [x] `downloadFile(api, file, outPath?)` streams encrypted body, buffers to 4
-      MiB chunk boundary, decrypts via secretstream pull, writes to disk. Falls
-      back to `metadata.title` when outPath is omitted.
-- [x] `downloadThumbnail(api, file, outPath?)` same for thumbnails
-- [x] Live integration test: logs in, decrypts collections and files, downloads
-      a real JPEG from the dev account and verifies it on disk
-
-Phase 7: Client class
-
-- [x] `Client.login({ email, password, totp?, emailOTP? })` performs the full
-      SRP handshake, key unwrap, returns a ready Client
-- [x] `Client.fromJSON(snapshot)` restores from a serialized snapshot
-- [x] `client.toJSON()` produces a `ClientSnapshot` the consumer can persist
-- [x] `client.whoami()`, `client.logout()`
-- [x] `client.listCollections()` with decryption
-- [x] `client.listFiles(collectionID, collectionKey)` with pagination
-- [x] `client.downloadFile(file, outPath?)` and `client.downloadThumbnail()`
-- [x] Literate test/client/usage.test.ts tutorial covering the entire API
-
-Phase 8: CLI
-
-- [x] `quak login` (interactive TTY prompts or QUAK_EMAIL/QUAK_PASSWORD env vars
-      for non-interactive use)
-- [x] `quak whoami`, `quak logout`
-- [x] `quak collections` and `quak files --collection <id>`
-- [x] `quak get <fileID>` and `quak get-thumb <fileID>` with --out and
-      --collection options; searches all collections when --collection omitted
-- [x] `quak backup <dir>` with originals/ dedup, collections/ symlinks,
-      per-collection and per-file JSON metadata, incremental skip, per-file
-      error resilience, --json flag
-- [x] `--json` output on every listing/backup command
-- [x] Progress output to stderr for backup
-- [x] Session persistence via env-paths (~/Library/Application Support/quak/ on
-      macOS, XDG_DATA_HOME/quak/ on Linux)
-
-Phase 9: docs and 1.0
-
-- [ ] Update README Getting Started and Design sections to match current state
-- [ ] All TODO items above checked
+- [ ] Update the API reference section below to match the current implementation
 - [ ] `make docker` green
 - [ ] Tag `v1.0.0`
 
-Phase 10 and beyond: desktop client (separate repo)
+Future (desktop client, separate repo):
 
-- [ ] Spike Electron app skeleton consuming this library
+- [ ] Electron app skeleton consuming this library
 - [ ] Local cache (SQLite) keyed on `(collectionID, fileID, updationTime)`
 - [ ] Background sync worker that streams new files into the cache
-- [ ] Read-only gallery UI: thumbnails, full-image view, basic search
-- [ ] Add upload, delete, and share back into the library before the desktop UI
-      exposes them
+- [ ] Gallery UI: thumbnails, full-image view, basic search
+- [ ] Upload, delete, and share operations in the library
+
+## API reference
+
+The API reference section below is from an earlier draft and does not fully
+reflect the current implementation. The authoritative API documentation is in
+the test files, particularly `test/client/usage.test.ts` which is a literate
+tutorial walking through every operation. Run `yarn test` to verify the examples
+are correct.
+
+The key types and their actual signatures can be found in:
+
+- `src/client.ts`: `Client`, `LoginOptions`, `ClientSnapshot`
+- `src/api/client.ts`: `ApiClient`, `ApiClientOptions`, `ApiError`
+- `src/auth/types.ts`: `KeyAttributes`, `SRPAttributes`,
+  `AuthorizationResponse`, `LoginChallenge`
+- `src/model/types.ts`: `Collection`, `EnteFile`, `FileMetadata`, `FileBlob`,
+  `RawCollection`, `RawEnteFile`, `RawMagicMetadata`
+- `src/download/index.ts`: `DownloadResult`
+- `src/backup.ts`: `BackupResult`, `BackupError`
+- `src/thumbnails.ts`: `MissingThumbnailInfo`, `ThumbnailFixResult`
 
 ## Source attribution
 
@@ -702,6 +351,38 @@ is rewritten in TypeScript in this repository. Protocol fidelity is verified
 against the upstream implementations in `web/packages/base/`,
 `mobile/apps/photos/lib/`, and `cli/`.
 
+## For LLMs
+
+If you are an LLM agent working on this repository, read and follow these
+documents:
+
+- **`REPO_POLICIES.md`** in the repo root. It is copied from
+  <https://git.eeqj.de/sneak/prompts> and covers repository structure, tooling,
+  Makefile targets, Dockerfile conventions, dependency pinning, and commit
+  hygiene. All external dependencies must be pinned by cryptographic hash in
+  `yarn.lock`. Never `git add -A`. Never force-push to main.
+
+- **The "Development workflow" section above.** All changes go on feature
+  branches. Tests are written first and committed in a failing state before the
+  implementation. Tests are the canonical API documentation and must be
+  commented thoroughly. `main` is always green.
+
+- **Required checks before every commit:** `make lint` (eslint + prettier check)
+  and `make fmt-check` must pass. The pre-commit hook enforces this.
+  `make check` (which also runs tests) must pass before merging to `main`.
+
+- **Formatting:** prettier with 4-space indents and `proseWrap: always` for
+  markdown. Use `make fmt` to format. Use `yarn` not `npm`.
+
+- **Testing:** vitest. Tests go in `test/` mirroring the `src/` structure.
+  `make test` must complete in under 20 seconds. Use `mkdtempSync` for temporary
+  directories, never manual timestamp paths.
+
+- **Code style:** `const` for everything, `let` if reassignment is needed, never
+  `var`. Avoid unnecessary comments. No hand-rolled crypto. The
+  `LLM_PROSE_TELLS.md` document in the prompts repo applies to any prose written
+  in this repository (README, comments, commit messages).
+
 ## License
 
 WTFPL. See [LICENSE](LICENSE).

REPO_POLICIES.md

@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-03-18
+last_modified: 2026-07-06
 ---
 
 This document covers repository structure, tooling, and workflow standards. Code
@@ -34,10 +34,46 @@ style conventions are in separate documents:
   every file before committing. There are zero exceptions to this rule.
 
 - Every repo with software must have a root `Makefile` with these targets:
-  `make test`, `make lint`, `make fmt` (writes), `make fmt-check` (read-only),
-  `make check` (prereqs: `test`, `lint`, `fmt-check`), `make docker`, and
-  `make hooks` (installs pre-commit hook). A model Makefile is at
-  `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
+  `make bootstrap`, `make setup`, `make test`, `make lint`, `make fmt` (writes),
+  `make fmt-check` (read-only), `make check` (runs `test`, `lint`, `fmt-check`),
+  `make docker`, and `make hooks` (installs pre-commit hook). A model Makefile
+  is at `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
+
+- Repos follow the
+  [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+  pattern: the implementation of each Makefile target lives in an executable
+  script in `script/` (`script/bootstrap`, `script/setup`, `script/test`,
+  `script/lint`, `script/fmt`, `script/fmt-check`, `script/check`,
+  `script/docker`), and the Makefile targets are thin shims that call them. The
+  scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run in
+  minimal containers (e.g. alpine images have no bash); locate the repo root
+  with `$(cd "$(dirname "$0")/.." && pwd -P)` and `cd` there before acting. From
+  the standard's canonical set we use `bootstrap`, `setup` (make the repo ready
+  for development after a fresh clone: runs `bootstrap`, then
+  `install-precommit`, plus any repo-specific initialization), `test`, and
+  `cibuild`. `script/bootstrap` installs all dependencies idempotently and
+  assumes nothing is present: base tools come from nix, apt, brew, or apk
+  (detected in that order; apt runs noninteractive). For node it uses the
+  installed node if present; otherwise it installs a PINNED node version via
+  nvm, first installing nvm itself if missing — from a hash-verified GitHub
+  release archive (never `curl | sh`), with bash installed as an explicit
+  prerequisite since nvm requires bash. yarn is then pinned via
+  `corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
+  always exact versions. `script/cibuild` runs the CI build: it changes to the
+  repo root and runs `docker build .`; the Gitea workflow calls it. Four further
+  scripts are our own extensions to the standard: `script/check` runs
+  `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
+  what the git pre-commit hook runs, and it calls `script/check`;
+  `script/install-precommit` installs the git pre-commit hook (the `make hooks`
+  target shims to it); and `script/projectname` (literally that filename) simply
+  outputs the project's name. Scripts that need the name call
+  `script/projectname` — e.g. `script/docker` assembles its image tag from it —
+  so those scripts stay byte-identical across all repos. Repo-type-specific
+  pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
+  `script/precommit`, not in the hook itself. Model scripts are at
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
+  must document the provided scripts in an **Entrypoints** section (see the
+  README requirements below).
 
 - Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
   instead of invoking the underlying tools directly. The Makefile is the single
@@ -57,7 +93,11 @@ style conventions are in separate documents:
   as a build step so the build fails if the branch is not green. For non-server
   repos, the Dockerfile should bring up a development environment and run
   `make check`. For server repos, `make check` should run as an early build
-  stage before the final image is assembled.
+  stage before the final image is assembled. Dockerfiles install development
+  prerequisites by running `script/bootstrap` rather than duplicating installs
+  inline; COPY `script/` and the dependency manifests (`package.json` +
+  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
+  layer stays cached until dependencies change.
 
 - **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
   repos use a multistage build where linting runs in an independent stage based
@@ -127,8 +167,9 @@ style conventions are in separate documents:
       artifacts or heavier dependencies.
 
 - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
-  runs `docker build .` on push. Since the Dockerfile already runs `make check`,
-  a successful build implies all checks pass.
+  runs `script/cibuild` (which runs `docker build .`) on push. Since the
+  Dockerfile already runs `make check`, a successful build implies all checks
+  pass.
 
 - Use platform-standard formatters: `black` for Python, `prettier` for
   JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
@@ -136,9 +177,11 @@ style conventions are in separate documents:
   Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown,
   HTML, CSS) should also have `.prettierrc` and `.prettierignore`.
 
-- Pre-commit hook: `make check` if local testing is possible, otherwise
-  `make lint && make fmt-check`. The Makefile should provide a `make hooks`
-  target to install the pre-commit hook.
+- Pre-commit hook: runs `script/precommit`, which calls `script/check`. If local
+  testing is not possible in the repo, `script/precommit` may skip `script/test`
+  and run only `script/lint` and `script/fmt-check`. The hook is installed by
+  `script/install-precommit`; the Makefile must provide a `make hooks` target
+  that shims to it.
 
 - All repos with software must have tests that run via the platform-standard
   test framework (`go test`, `pytest`, `jest`/`vitest`, etc.). If no meaningful
@@ -297,6 +340,10 @@ style conventions are in separate documents:
       "µPaaS is an MIT-licensed Go web application by @sneak that receives
       git-frontend webhooks and deploys applications via Docker in realtime."
     - **Getting Started**: Copy-pasteable install/usage code block.
+    - **Entrypoints**: Opens by stating that the repo adheres to the
+      [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+      standard (with that link), then documents each provided `script/`
+      entrypoint and its purpose.
     - **Rationale**: Why does this exist?
     - **Design**: How is the program structured?
     - **TODO**: Update meticulously, even between commits. When planning, put
@@ -351,6 +398,9 @@ style conventions are in separate documents:
     - `README.md`, `.git`, `.gitignore`, `.editorconfig`
     - `LICENSE`, `REPO_POLICIES.md` (copy from the `prompts` repo)
     - `Makefile`
+    - `script/` entrypoints (`bootstrap`, `setup`, `projectname`, `test`,
+      `lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
+      `install-precommit`)
     - `Dockerfile`, `.dockerignore`
     - `.gitea/workflows/check.yml`
     - Go: `go.mod`, `go.sum`, `.golangci.yml`

TODO.md

@@ -0,0 +1,54 @@
+# Workflow
+
+- branch (from `main`)
+- do the work in Next Step
+- move Next Step to the top of Completed Steps
+- move the top item of Future Steps into Next Step
+- commit (`TODO.md` changes in the same commit as the work)
+- merge to `main` if the branch is not protected, otherwise open a PR
+- push
+
+# Status
+
+pre-1.0
+
+# Next Step
+
+Implement the download retry policy from the README TODO: no retry on 4xx,
+exponential backoff on 5xx and network errors. Apply it to file and thumbnail
+downloads, cover it with mock-server tests, and update the README TODO checkbox.
+
+# Completed Steps
+
+- 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints, Makefile
+  shims, README Entrypoints section
+- 2026-06-10: Decrypted collections shared by other users (sealed-box keys);
+  listCollections drops deleted-collection tombstones.
+- 2026-06-10: Login hardening: dual-2FA empty-string fields handled, TOTP
+  preferred when a passkey is also enrolled, interactive input via
+  @inquirer/prompts.
+- 2026-06-10: Replaced sharp with pure JS (jpeg-js + exif-reader); added
+  single-binary bun build and make install.
+- 2026-06-09: Added backup-metadata command (ML data always included, --exif
+  opt-in); rewrote README to match the implementation; added thumbnail helper
+  tests.
+- 2026-05-13: Full CLI surface: login, backup with dedup symlink layout,
+  collections, files, get, get-thumb, thumbnail repair helpers.
+- 2026-05-13: Client OO API with literate usage tests; file download and
+  decryption; all three metadata layers decrypted and persisted; renamed quack
+  to quak.
+- 2026-05-11: SRP login flow (email OTP + TOTP) and ApiClient.
+
+# Future Steps
+
+- Retry policy: no retry on 4xx, exponential backoff on 5xx and network errors
+  (the Next Step).
+- Update the README API reference section to match the current implementation.
+- Make `make docker` green.
+- Tag v1.0.0.
+- Future desktop client, separate repo:
+    - Electron app skeleton consuming this library.
+    - Local SQLite cache keyed on (collectionID, fileID, updationTime).
+    - Background sync worker streaming new files into the cache.
+    - Gallery UI: thumbnails, full-image view, basic search.
+    - Upload, delete, and share operations in the library.

bin/quak.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-import { createInterface } from "node:readline/promises";
-import { stdin, stdout, stderr } from "node:process";
+import { input, password as passwordPrompt } from "@inquirer/prompts";
+import { stdout, stderr } from "node:process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { Command } from "commander";
@@ -9,6 +9,7 @@ import envPaths from "env-paths";
 import { Client, type ClientSnapshot } from "../src/client.js";
 import { init } from "../src/crypto/index.js";
 import { runBackup } from "../src/backup.js";
+import { runMetadataBackup } from "../src/metadata-backup.js";
 import {
     listMissingThumbnails,
     fixMissingThumbnails,
@@ -44,46 +45,10 @@ const requireSession = (): Client => {
     return Client.fromJSON(snapshot);
 };
 
-const prompt = async (message: string): Promise<string> => {
-    const rl = createInterface({ input: stdin, output: stderr });
-    const answer = await rl.question(message);
-    rl.close();
-    return answer;
-};
+const prompt = async (message: string): Promise<string> => input({ message });
 
-const promptPassword = async (message: string): Promise<string> => {
-    if (!stdin.isTTY) {
-        return prompt(message);
-    }
-    stderr.write(message);
-    stdin.setRawMode(true);
-    stdin.resume();
-    const chars: string[] = [];
-    return new Promise((resolve) => {
-        const onData = (buf: Buffer) => {
-            for (const byte of buf) {
-                if (byte === 3) {
-                    stdin.setRawMode(false);
-                    process.exit(130);
-                }
-                if (byte === 13 || byte === 10) {
-                    stdin.setRawMode(false);
-                    stdin.removeListener("data", onData);
-                    stdin.pause();
-                    stderr.write("\n");
-                    resolve(chars.join(""));
-                    return;
-                }
-                if (byte === 127 || byte === 8) {
-                    chars.pop();
-                } else {
-                    chars.push(String.fromCharCode(byte));
-                }
-            }
-        };
-        stdin.on("data", onData);
-    });
-};
+const promptSecret = async (message: string): Promise<string> =>
+    passwordPrompt({ message, mask: true });
 
 const program = new Command();
 
@@ -97,18 +62,9 @@ program
     .description("Log in to an Ente account and save the session")
     .action(async () => {
         await init();
-        const email =
-            process.env.QUAK_EMAIL ??
-            (stdin.isTTY ? await prompt("Email: ") : null);
+        const email = process.env.QUAK_EMAIL ?? (await prompt("Email"));
         const password =
-            process.env.QUAK_PASSWORD ??
-            (stdin.isTTY ? await promptPassword("Password: ") : null);
-        if (!email || !password) {
-            stderr.write(
-                "Set QUAK_EMAIL and QUAK_PASSWORD env vars for non-interactive use.\n",
-            );
-            process.exit(1);
-        }
+            process.env.QUAK_PASSWORD ?? (await promptSecret("Password"));
 
         stderr.write("Authenticating...\n");
         try {
@@ -333,6 +289,26 @@ program
         },
     );
 
+program
+    .command("backup-metadata")
+    .description(
+        "Dump all decrypted account metadata to a directory of JSON files",
+    )
+    .argument("<dir>", "Output directory")
+    .option(
+        "--exif",
+        "Download each file and extract full EXIF/IPTC/XMP metadata (slow)",
+    )
+    .option("--all", "Alias for --exif")
+    .action(async (dir: string, opts: { exif?: boolean; all?: boolean }) => {
+        await init();
+        const client = requireSession();
+        await runMetadataBackup(client, dir, {
+            exif: opts.exif || opts.all,
+            onProgress: (msg) => stderr.write(msg + "\n"),
+        });
+    });
+
 program
     .command("backup")
     .description(
@@ -456,4 +432,5 @@ helper
         process.exit(results.some((r) => !r.success) ? 1 : 0);
     });
 
+await init();
 program.parse();

package.json

@@ -31,7 +31,6 @@
         "@eslint/js": "9.38.0",
         "@types/libsodium-wrappers-sumo": "0.8.2",
         "@types/node": "22.18.13",
-        "@types/sharp": "0.32.0",
         "eslint": "9.38.0",
         "prettier": "3.8.1",
         "typescript": "5.9.3",
@@ -39,10 +38,12 @@
         "vitest": "2.1.9"
     },
     "dependencies": {
+        "@inquirer/prompts": "8.5.2",
         "commander": "14.0.3",
         "env-paths": "4.0.0",
+        "exif-reader": "2.0.3",
         "fast-srp-hap": "2.0.4",
-        "libsodium-wrappers-sumo": "0.8.4",
-        "sharp": "0.34.5"
+        "jpeg-js": "0.4.4",
+        "libsodium-wrappers-sumo": "0.8.4"
     }
 }

script/bootstrap

@@ -0,0 +1,136 @@
+#!/bin/sh
+# script/bootstrap: install all dependencies needed to build and develop
+# this repo. Idempotent: every install is guarded by a check so already
+# installed tools are skipped. Base tooling comes from nix, apt, brew,
+# or apk (detected in that order); assumes nothing is present. Node is
+# used directly if installed; otherwise it is installed at a pinned
+# version via nvm (installing nvm itself first, from a hash-verified
+# release archive, never curl | sh).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# Pinned versions, 2026-07-06
+NODE_VERSION="22.17.0"
+NVM_VERSION="0.40.3"
+# sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
+NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
+YARN_VERSION="1.22.22"
+
+PKGMGR=""
+SUDO=""
+
+detect_pkgmgr() {
+    [ -n "$PKGMGR" ] && return 0
+    if command -v nix-env >/dev/null 2>&1; then
+        PKGMGR="nix"
+    elif command -v apt-get >/dev/null 2>&1; then
+        PKGMGR="apt"
+    elif command -v brew >/dev/null 2>&1; then
+        PKGMGR="brew"
+    elif command -v apk >/dev/null 2>&1; then
+        PKGMGR="apk"
+    else
+        echo "bootstrap: no supported package manager (nix, apt, brew, apk)" >&2
+        exit 1
+    fi
+    if [ "$PKGMGR" = "apt" ]; then
+        export DEBIAN_FRONTEND=noninteractive
+        if [ "$(id -u)" != "0" ]; then
+            SUDO="sudo"
+        fi
+    fi
+}
+
+# pkg_install <nix-attr> <apt-pkg> <brew-formula> <apk-pkg>
+pkg_install() {
+    detect_pkgmgr
+    case "$PKGMGR" in
+        nix) nix-env -iA "nixpkgs.$1" ;;
+        apt) $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2" ;;
+        brew) brew install "$3" ;;
+        apk) apk add --no-cache "$4" ;;
+    esac
+}
+
+missing() {
+    ! command -v "$1" >/dev/null 2>&1
+}
+
+# verify_sha256 <file> <expected-hash>
+verify_sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        actual="$(sha256sum "$1" | cut -d' ' -f1)"
+    else
+        actual="$(shasum -a 256 "$1" | cut -d' ' -f1)"
+    fi
+    if [ "$actual" != "$2" ]; then
+        echo "bootstrap: sha256 mismatch for $1" >&2
+        echo "  expected: $2" >&2
+        echo "  actual:   $actual" >&2
+        exit 1
+    fi
+}
+
+# nvm is a bash script; run a command in a bash with nvm loaded
+nvm_sh() {
+    bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
+}
+
+ensure_nvm() {
+    [ -s "$HOME/.nvm/nvm.sh" ] && return 0
+    # nvm prerequisites; nvm itself requires bash
+    if missing bash; then pkg_install bash bash bash bash; fi
+    if missing curl; then pkg_install curl curl curl curl; fi
+    if missing git; then pkg_install git git git git; fi
+    tmp="$(mktemp -d)"
+    curl -fsSL -o "$tmp/nvm.tar.gz" \
+        "https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz"
+    verify_sha256 "$tmp/nvm.tar.gz" "$NVM_SHA256"
+    mkdir -p "$HOME/.nvm"
+    tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1
+    rm -rf "$tmp"
+}
+
+ensure_node() {
+    if ! missing node; then return 0; fi
+    ensure_nvm
+    nvm_sh "nvm install $NODE_VERSION"
+}
+
+ensure_yarn() {
+    if ! missing yarn; then return 0; fi
+    if ! missing corepack; then
+        corepack enable
+        corepack prepare "yarn@$YARN_VERSION" --activate
+    elif [ -s "$HOME/.nvm/nvm.sh" ]; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && corepack enable && \
+            corepack prepare yarn@$YARN_VERSION --activate"
+    else
+        npm install -g "yarn@$YARN_VERSION"
+    fi
+}
+
+install_js_deps() {
+    if missing yarn && [ -s "$HOME/.nvm/nvm.sh" ]; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \
+            yarn install --frozen-lockfile"
+    else
+        yarn install --frozen-lockfile
+    fi
+}
+
+main() {
+    cd "$ROOT"
+
+    if missing make; then pkg_install gnumake make make make; fi
+    if missing git; then pkg_install git git git git; fi
+
+    ensure_node
+    ensure_yarn
+    install_js_deps
+
+    echo "bootstrap complete"
+}
+
+main "$@"

script/check

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/check: run all checks (test, lint, fmt-check). Our own
+# extension to scripts-to-rule-them-all. Must not modify any files.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/test"
+    "$SCRIPT_DIR/lint"
+    "$SCRIPT_DIR/fmt-check"
+}
+
+main "$@"

script/cibuild

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/cibuild: run the CI build. The Dockerfile runs script/check, so
+# a successful build implies all checks pass.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    docker build .
+}
+
+main "$@"

script/docker

@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/docker: build the Docker image tagged with the project name.
+# Identical in all repos; the tag comes from script/projectname.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    docker build -t "$("$SCRIPT_DIR/projectname")" .
+}
+
+main "$@"

script/fmt

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/fmt: format all files (writes).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    yarn run prettier --write .
+}
+
+main "$@"

script/fmt-check

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/fmt-check: check formatting (read-only).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    yarn run prettier --check .
+}
+
+main "$@"

script/install-precommit

@@ -0,0 +1,16 @@
+#!/bin/sh
+# script/install-precommit: install the git pre-commit hook that runs
+# script/precommit. Our own extension to scripts-to-rule-them-all.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    hook=".git/hooks/pre-commit"
+    printf '#!/bin/sh\nset -e\nscript/precommit\n' > .git/hooks/pre-commit
+    chmod +x .git/hooks/pre-commit
+    echo "pre-commit hook installed: runs script/precommit"
+}
+
+main "$@"

script/lint

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/lint: run the linter (eslint plus a prettier check).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    yarn run eslint .
+    yarn run prettier --check .
+}
+
+main "$@"

script/precommit

@@ -0,0 +1,18 @@
+#!/bin/sh
+# script/precommit: run by the git pre-commit hook; fails the commit if
+# checks fail. Our own extension to scripts-to-rule-them-all.
+#
+# Runs lint and fmt-check but deliberately NOT the tests, so the TDD
+# red-phase commit (failing tests, no implementation yet) can land. CI
+# runs make check via docker build, which catches any branch that
+# ships red.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/lint"
+    "$SCRIPT_DIR/fmt-check"
+}
+
+main "$@"

script/projectname

@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/projectname: output the name of this project. Our own
+# extension to scripts-to-rule-them-all. Other scripts that need the
+# name (e.g. script/docker) call this, so they can stay identical
+# across all repos.
+set -eu
+
+main() {
+    echo "quack"
+}
+
+main "$@"

script/setup

@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/setup: set up the repo for development after a fresh clone:
+# installs dependencies and the git pre-commit hook.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/bootstrap"
+    "$SCRIPT_DIR/install-precommit"
+}
+
+main "$@"

script/test

@@ -0,0 +1,25 @@
+#!/bin/sh
+# script/test: run the test suite. Uses `timeout` (GNU coreutils) when
+# available so the run is hard-capped at 30s; on macOS without
+# coreutils the cap is skipped.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+rerun_verbose() {
+    echo "--- Rerunning with verbose for details ---"
+    yarn run vitest run --reporter=verbose
+    exit 1
+}
+
+main() {
+    cd "$ROOT"
+    TIMEOUT="$(command -v timeout 2>/dev/null || command -v gtimeout 2>/dev/null || true)"
+    if [ -n "$TIMEOUT" ]; then
+        "$TIMEOUT" 30s yarn run vitest run --reporter=dot || rerun_verbose
+    else
+        yarn run vitest run --reporter=dot || rerun_verbose
+    fi
+}
+
+main "$@"

src/auth/login.ts

@@ -73,8 +73,18 @@ const srpHandshake = async (
 
     srpClient.checkM2(Buffer.from(verifyResponse.srpM2, "base64"));
 
-    if (verifyResponse.twoFactorSessionID) {
-        return { kind: "totp", sessionID: verifyResponse.twoFactorSessionID };
+    // twoFactorSessionIDV2 is set (instead of twoFactorSessionID) when the
+    // account has BOTH passkeys and TOTP. Prefer TOTP: a CLI cannot perform
+    // a WebAuthn ceremony, and the user has a TOTP secret enrolled.
+    //
+    // The server marshals these fields without `omitempty`, so unset fields
+    // arrive as "" rather than being absent. Use || (not ??) so empty
+    // strings are treated as not-set.
+    const totpSessionID =
+        verifyResponse.twoFactorSessionID ||
+        verifyResponse.twoFactorSessionIDV2;
+    if (totpSessionID) {
+        return { kind: "totp", sessionID: totpSessionID };
     }
     if (verifyResponse.passkeySessionID) {
         return {

src/auth/types.ts

@@ -34,13 +34,18 @@ export interface SRPAttributes {
 // The body of a successful login response. Exactly one of the following
 // situations applies, and the caller dispatches on the populated fields:
 //   - both keyAttributes and encryptedToken present: login is complete
-//   - twoFactorSessionID present: caller must submit a TOTP code
-//   - passkeySessionID present: caller must complete a passkey ceremony
+//   - twoFactorSessionID present: caller must submit a TOTP code (TOTP-only
+//     account)
+//   - passkeySessionID + twoFactorSessionIDV2 present: account has both
+//     passkeys and TOTP; the V2 field is set instead of twoFactorSessionID
+//     so that older clients keep using the passkey flow
+//   - only passkeySessionID present: caller must complete a passkey ceremony
 export interface AuthorizationResponse {
     id: number;
     keyAttributes?: KeyAttributes;
     encryptedToken?: Base64;
     twoFactorSessionID?: string;
+    twoFactorSessionIDV2?: string;
     passkeySessionID?: string;
 }
 

src/client.ts

@@ -155,9 +155,21 @@ export class Client {
         const { collections } = await this.api.getJSON<{
             collections: RawCollection[];
         }>("/collections/v2", { sinceTime: 0 });
-        return collections.map((raw) =>
-            decryptCollection(raw, this.masterKey, this.userID),
-        );
+        // The sync API keeps returning deleted collections as tombstones
+        // (isDeleted: true); their diff endpoint 404s, so drop them.
+        return collections
+            .filter((raw) => !raw.isDeleted)
+            .map((raw) =>
+                decryptCollection(
+                    raw,
+                    {
+                        masterKey: this.masterKey,
+                        publicKey: this.publicKey,
+                        secretKey: this.secretKey,
+                    },
+                    this.userID,
+                ),
+            );
     }
 
     async listFiles(

src/index.ts

@@ -24,6 +24,7 @@ export type {
     FileBlob,
     FileMetadata,
     FileType,
+    KeyMaterial,
     Microseconds,
     RawCollection,
     RawEnteFile,

src/metadata-backup.ts

@@ -0,0 +1,270 @@
+import { gunzipSync } from "node:zlib";
+import {
+    mkdirSync,
+    mkdtempSync,
+    readFileSync,
+    rmSync,
+    writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import * as jpeg from "jpeg-js";
+import exifReader from "exif-reader";
+import type { Client } from "./client.js";
+import { decryptBlob, fromBase64 } from "./crypto/index.js";
+import type { EnteFile } from "./model/types.js";
+
+export type ProgressCallback = (message: string) => void;
+
+export interface MetadataBackupOptions {
+    exif?: boolean;
+    onProgress?: ProgressCallback;
+}
+
+const sanitizePath = (name: string): string =>
+    name.replace(/[/\\:*?"<>|]/g, "_").replace(/^\.+/, "_");
+
+interface RawRemoteFileData {
+    fileID: number;
+    encryptedData: string;
+    decryptionHeader: string;
+    updatedAt?: number;
+}
+
+const fetchMLDataForFiles = async (
+    client: Client,
+    fileIDs: number[],
+    fileKeys: Map<number, Uint8Array>,
+): Promise<Map<number, Record<string, unknown>>> => {
+    const api = client.getApiClient();
+    const result = new Map<number, Record<string, unknown>>();
+    const batchSize = 200;
+
+    for (let i = 0; i < fileIDs.length; i += batchSize) {
+        const batch = fileIDs.slice(i, i + batchSize);
+        const { data } = await api.postJSON<{ data: RawRemoteFileData[] }>(
+            "/files/data/fetch",
+            { type: "mldata", fileIDs: batch },
+        );
+
+        for (const entry of data ?? []) {
+            const key = fileKeys.get(entry.fileID);
+            if (!key) continue;
+            try {
+                const decrypted = decryptBlob(
+                    fromBase64(entry.encryptedData),
+                    fromBase64(entry.decryptionHeader),
+                    key,
+                );
+                const jsonStr = gunzipSync(Buffer.from(decrypted)).toString(
+                    "utf-8",
+                );
+                result.set(entry.fileID, JSON.parse(jsonStr));
+            } catch {
+                // Corrupted ML data for this file; skip it
+            }
+        }
+    }
+    return result;
+};
+
+// Extract the raw EXIF APP1 segment from JPEG bytes. Returns the EXIF
+// data buffer (starting after the APP1 length field, at the "Exif\0\0"
+// header) or undefined if no APP1 marker is found.
+const extractExifFromJpeg = (buf: Uint8Array): Buffer | undefined => {
+    if (buf[0] !== 0xff || buf[1] !== 0xd8) return undefined;
+    let offset = 2;
+    while (offset < buf.length - 1) {
+        if (buf[offset] !== 0xff) return undefined;
+        const marker = buf[offset + 1]!;
+        if (marker === 0xda) break; // start of scan, no more markers
+        if (offset + 3 >= buf.length) break;
+        const len = (buf[offset + 2]! << 8) | buf[offset + 3]!;
+        if (marker === 0xe1) {
+            // APP1 — check for "Exif\0\0" header
+            if (
+                buf[offset + 4] === 0x45 &&
+                buf[offset + 5] === 0x78 &&
+                buf[offset + 6] === 0x69 &&
+                buf[offset + 7] === 0x66
+            ) {
+                return Buffer.from(
+                    buf.buffer,
+                    buf.byteOffset + offset + 4,
+                    len - 2,
+                );
+            }
+        }
+        offset += 2 + len;
+    }
+    return undefined;
+};
+
+const extractImageMetadata = (
+    fileBytes: Uint8Array,
+): Record<string, unknown> | undefined => {
+    try {
+        const result: Record<string, unknown> = {};
+
+        // Try to get dimensions from JPEG decode
+        try {
+            const decoded = jpeg.decode(fileBytes, {
+                useTArray: true,
+                formatAsRGBA: false,
+            });
+            result.format = "jpeg";
+            result.width = decoded.width;
+            result.height = decoded.height;
+        } catch {
+            // Not a JPEG or corrupt; still try EXIF extraction
+        }
+
+        const exifBuf = extractExifFromJpeg(fileBytes);
+        if (exifBuf) {
+            try {
+                result.exif = exifReader(exifBuf);
+            } catch {
+                result.exifRaw = exifBuf.toString("base64");
+            }
+        }
+
+        // Extract XMP (look for "http://ns.adobe.com/xap" in the bytes)
+        const xmpStart = Buffer.from(fileBytes).indexOf("<?xpacket begin");
+        if (xmpStart !== -1) {
+            const xmpEnd = Buffer.from(fileBytes).indexOf(
+                "<?xpacket end",
+                xmpStart,
+            );
+            if (xmpEnd !== -1) {
+                const end = Buffer.from(fileBytes).indexOf("?>", xmpEnd);
+                result.xmp = Buffer.from(fileBytes)
+                    .subarray(xmpStart, end !== -1 ? end + 2 : xmpEnd + 50)
+                    .toString("utf-8");
+            }
+        }
+
+        return Object.keys(result).length > 0 ? result : undefined;
+    } catch {
+        return undefined;
+    }
+};
+
+const extractExif = async (
+    client: Client,
+    file: EnteFile,
+): Promise<Record<string, unknown> | undefined> => {
+    const tmpDir = mkdtempSync(join(tmpdir(), "quak-exif-"));
+    try {
+        const origPath = join(tmpDir, "original");
+        await client.downloadFile(file, origPath);
+        const fileBytes = new Uint8Array(readFileSync(origPath));
+        return extractImageMetadata(fileBytes);
+    } catch {
+        return undefined;
+    } finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+};
+
+export const runMetadataBackup = async (
+    client: Client,
+    outDir: string,
+    opts?: MetadataBackupOptions,
+): Promise<void> => {
+    const log = opts?.onProgress ?? (() => {});
+    const wantExif = opts?.exif ?? false;
+
+    mkdirSync(outDir, { recursive: true });
+    mkdirSync(join(outDir, "collections"), { recursive: true });
+
+    const { email, userID } = client.whoami();
+    writeFileSync(
+        join(outDir, "account.json"),
+        JSON.stringify({ email, userID }, null, 2),
+    );
+
+    log("Fetching collections...");
+    const collections = await client.listCollections();
+
+    const allFiles: { file: EnteFile; colDirName: string }[] = [];
+    const fileKeys = new Map<number, Uint8Array>();
+    const seenFileIDs = new Set<number>();
+
+    for (const col of collections) {
+        const dirName = `${col.id}-${sanitizePath(col.name || "unnamed")}`;
+        const colDir = join(outDir, "collections", dirName);
+        mkdirSync(colDir, { recursive: true });
+
+        const collectionMeta: Record<string, unknown> = {
+            id: col.id,
+            name: col.name,
+            type: col.type,
+            ownerID: col.ownerID,
+            isShared: col.isShared,
+            updationTime: col.updationTime,
+        };
+        if (col.magicMetadata) collectionMeta.magicMetadata = col.magicMetadata;
+        if (col.pubMagicMetadata)
+            collectionMeta.pubMagicMetadata = col.pubMagicMetadata;
+        if (col.sharedMagicMetadata)
+            collectionMeta.sharedMagicMetadata = col.sharedMagicMetadata;
+
+        writeFileSync(
+            join(colDir, "_collection.json"),
+            JSON.stringify(collectionMeta, null, 2),
+        );
+
+        log(`[${col.name}] Fetching files...`);
+        const files = await client.listFiles(col.id, col.key);
+        log(`[${col.name}] ${files.length} file(s)`);
+
+        for (const file of files) {
+            allFiles.push({ file, colDirName: dirName });
+            if (!seenFileIDs.has(file.id)) {
+                fileKeys.set(file.id, file.key);
+                seenFileIDs.add(file.id);
+            }
+        }
+    }
+
+    log("Fetching ML data (face detections, CLIP embeddings)...");
+    const mlDataMap = await fetchMLDataForFiles(
+        client,
+        [...fileKeys.keys()],
+        fileKeys,
+    );
+    log(`Got ML data for ${mlDataMap.size} file(s)`);
+
+    const writtenFileIDs = new Set<number>();
+    for (const { file, colDirName } of allFiles) {
+        const colDir = join(outDir, "collections", colDirName);
+
+        const fileMeta: Record<string, unknown> = {
+            id: file.id,
+            collectionID: file.collectionID,
+            ownerID: file.ownerID,
+            metadata: file.metadata,
+            updationTime: file.updationTime,
+        };
+        if (file.magicMetadata) fileMeta.magicMetadata = file.magicMetadata;
+        if (file.pubMagicMetadata)
+            fileMeta.pubMagicMetadata = file.pubMagicMetadata;
+
+        const ml = mlDataMap.get(file.id);
+        if (ml) fileMeta.mlData = ml;
+
+        if (wantExif && !writtenFileIDs.has(file.id)) {
+            log(`[${file.metadata.title}] Extracting EXIF...`);
+            const exifData = await extractExif(client, file);
+            if (exifData) fileMeta.imageMetadata = exifData;
+        }
+        writtenFileIDs.add(file.id);
+
+        writeFileSync(
+            join(colDir, `${file.id}.json`),
+            JSON.stringify(fileMeta, null, 2),
+        );
+    }
+
+    log("Metadata backup complete.");
+};

src/model/decrypt.ts

@@ -1,10 +1,16 @@
-import { decryptBlob, decryptBox, fromBase64 } from "../crypto/index.js";
+import {
+    decryptBlob,
+    decryptBox,
+    decryptSealed,
+    fromBase64,
+} from "../crypto/index.js";
 import type {
     Collection,
     CollectionType,
     EnteFile,
     FileMetadata,
     FileType,
+    KeyMaterial,
     RawCollection,
     RawEnteFile,
     RawMagicMetadata,
@@ -30,14 +36,25 @@ const parseFileType = (n: number): FileType => FILE_TYPE_MAP[n] ?? "unknown";
 
 export const decryptCollection = (
     raw: RawCollection,
-    masterKey: Uint8Array,
+    keys: KeyMaterial,
     currentUserID?: number,
 ): Collection => {
-    const key = decryptBox(
-        fromBase64(raw.encryptedKey),
-        fromBase64(raw.keyDecryptionNonce),
-        masterKey,
-    );
+    // Owned collections carry their key as a secretbox under our master
+    // key, with the nonce in keyDecryptionNonce. Collections shared with
+    // us carry it as an anonymous sealed box to our public key and have
+    // no keyDecryptionNonce at all (sealed boxes embed an ephemeral
+    // public key instead).
+    const key = raw.keyDecryptionNonce
+        ? decryptBox(
+              fromBase64(raw.encryptedKey),
+              fromBase64(raw.keyDecryptionNonce),
+              keys.masterKey,
+          )
+        : decryptSealed(
+              fromBase64(raw.encryptedKey),
+              keys.publicKey,
+              keys.secretKey,
+          );
 
     let name = "";
     if (raw.encryptedName && raw.nameDecryptionNonce) {
@@ -57,6 +74,9 @@ export const decryptCollection = (
         type: parseCollectionType(raw.type),
         updationTime: raw.updationTime,
         isShared: currentUserID !== undefined && raw.owner.id !== currentUserID,
+        magicMetadata: decryptMagicMetadata(raw.magicMetadata, key),
+        pubMagicMetadata: decryptMagicMetadata(raw.pubMagicMetadata, key),
+        sharedMagicMetadata: decryptMagicMetadata(raw.sharedMagicMetadata, key),
     };
 };
 

src/model/index.ts

@@ -6,6 +6,7 @@ export type {
     FileBlob,
     FileMetadata,
     FileType,
+    KeyMaterial,
     Microseconds,
     RawCollection,
     RawEnteFile,

src/model/types.ts

@@ -15,6 +15,9 @@ export interface Collection {
     type: CollectionType;
     updationTime: Microseconds;
     isShared: boolean;
+    magicMetadata?: Record<string, unknown>;
+    pubMagicMetadata?: Record<string, unknown>;
+    sharedMagicMetadata?: Record<string, unknown>;
 }
 
 export type FileType = "image" | "video" | "livePhoto" | "unknown";
@@ -47,18 +50,33 @@ export interface EnteFile {
     updationTime: Microseconds;
 }
 
+// The key material a logged-in client holds, everything needed to decrypt
+// any collection: the master key (secretbox for owned collection keys) and
+// the X25519 keypair (sealed box for collection keys shared with us).
+export interface KeyMaterial {
+    masterKey: Uint8Array;
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+
 // Raw shapes as they arrive from the Ente API, before decryption.
 
 export interface RawCollection {
     id: number;
     owner: { id: number };
     encryptedKey: string;
-    keyDecryptionNonce: string;
+    // Absent for collections shared with us: their encryptedKey is a
+    // sealed box to our public key, which embeds an ephemeral public key
+    // instead of using a nonce.
+    keyDecryptionNonce?: string;
     encryptedName?: string;
     nameDecryptionNonce?: string;
     type: string;
     updationTime: number;
     isDeleted?: boolean;
+    magicMetadata?: RawMagicMetadata;
+    pubMagicMetadata?: RawMagicMetadata;
+    sharedMagicMetadata?: RawMagicMetadata;
 }
 
 export interface RawMagicMetadata {

src/thumbnails.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
-import sharp from "sharp";
+import { readFileSync } from "node:fs";
+import * as jpeg from "jpeg-js";
 import type { Client } from "./client.js";
 import { encryptBlob, toBase64 } from "./crypto/index.js";
 import { downloadFile } from "./download/index.js";
@@ -74,16 +75,71 @@ export const listMissingThumbnails = async (
     return missing;
 };
 
-const generateThumbnail = async (originalPath: string): Promise<Uint8Array> => {
-    const result = await sharp(originalPath)
-        .rotate()
-        .resize(THUMB_MAX_DIMENSION, THUMB_MAX_DIMENSION, {
-            fit: "inside",
-            withoutEnlargement: true,
-        })
-        .jpeg({ quality: THUMB_JPEG_QUALITY })
-        .toBuffer();
-    return new Uint8Array(result);
+// Bilinear resize of RGBA pixel buffer
+const resizeRGBA = (
+    src: Uint8Array,
+    srcW: number,
+    srcH: number,
+    dstW: number,
+    dstH: number,
+): Uint8Array => {
+    const dst = new Uint8Array(dstW * dstH * 4);
+    const xRatio = srcW / dstW;
+    const yRatio = srcH / dstH;
+    for (let y = 0; y < dstH; y++) {
+        const srcY = y * yRatio;
+        const y0 = Math.floor(srcY);
+        const y1 = Math.min(y0 + 1, srcH - 1);
+        const fy = srcY - y0;
+        for (let x = 0; x < dstW; x++) {
+            const srcX = x * xRatio;
+            const x0 = Math.floor(srcX);
+            const x1 = Math.min(x0 + 1, srcW - 1);
+            const fx = srcX - x0;
+            const i00 = (y0 * srcW + x0) * 4;
+            const i10 = (y0 * srcW + x1) * 4;
+            const i01 = (y1 * srcW + x0) * 4;
+            const i11 = (y1 * srcW + x1) * 4;
+            const di = (y * dstW + x) * 4;
+            for (let c = 0; c < 4; c++) {
+                dst[di + c] = Math.round(
+                    src[i00 + c]! * (1 - fx) * (1 - fy) +
+                        src[i10 + c]! * fx * (1 - fy) +
+                        src[i01 + c]! * (1 - fx) * fy +
+                        src[i11 + c]! * fx * fy,
+                );
+            }
+        }
+    }
+    return dst;
+};
+
+const generateThumbnail = (fileBytes: Uint8Array): Uint8Array => {
+    const decoded = jpeg.decode(fileBytes, {
+        useTArray: true,
+        formatAsRGBA: true,
+    });
+    const { width: srcW, height: srcH } = decoded;
+    const scale = Math.min(
+        THUMB_MAX_DIMENSION / srcW,
+        THUMB_MAX_DIMENSION / srcH,
+        1,
+    );
+    const dstW = Math.round(srcW * scale);
+    const dstH = Math.round(srcH * scale);
+
+    let pixels: Uint8Array;
+    if (scale < 1) {
+        pixels = resizeRGBA(decoded.data, srcW, srcH, dstW, dstH);
+    } else {
+        pixels = decoded.data;
+    }
+
+    const encoded = jpeg.encode(
+        { data: pixels, width: dstW, height: dstH },
+        THUMB_JPEG_QUALITY,
+    );
+    return new Uint8Array(encoded.data);
 };
 
 export const fixMissingThumbnails = async (
@@ -139,7 +195,8 @@ export const fixMissingThumbnails = async (
             log(
                 `[${collectionName}] Generating thumbnail for ${file.metadata.title}...`,
             );
-            const thumbJpeg = await generateThumbnail(origPath);
+            const fileBytes = readFileSync(origPath);
+            const thumbJpeg = generateThumbnail(new Uint8Array(fileBytes));
 
             log(
                 `[${collectionName}] Encrypting and uploading thumbnail (${thumbJpeg.length} bytes)...`,

test/api/upload.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Tests for the upload-related ApiClient methods added for thumbnail
+ * repair: `putJSON`, `putFile`, `getUploadURL`, and `updateThumbnail`.
+ *
+ * `putFile` sends a raw PUT to a presigned S3 URL. It must NOT send
+ * quak's auth headers (X-Auth-Token, X-Client-Package) because the
+ * presigned URL carries its own S3 auth in the query string. Sending
+ * extra headers can cause S3 to reject the request.
+ *
+ * `putJSON` is like `postJSON` but sends PUT. Used by `updateThumbnail`
+ * to register the uploaded thumbnail's object key with the Ente API.
+ */
+
+import { describe, expect, it } from "vitest";
+import { ApiClient } from "../../src/api/client.js";
+
+const jsonResponse = (
+    body: unknown,
+    status = 200,
+    headers: Record<string, string> = {},
+): Response =>
+    new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json", ...headers },
+    });
+
+const recordingFetch = (
+    ...responses: Response[]
+): {
+    fetch: typeof globalThis.fetch;
+    calls: { url: string; init: RequestInit | undefined }[];
+} => {
+    const calls: { url: string; init: RequestInit | undefined }[] = [];
+    let i = 0;
+    const fake = async (
+        input: RequestInfo | URL,
+        init?: RequestInit,
+    ): Promise<Response> => {
+        const url =
+            typeof input === "string"
+                ? input
+                : input instanceof URL
+                  ? input.href
+                  : input.url;
+        calls.push({ url, init });
+        if (i >= responses.length) {
+            throw new Error(`recordingFetch: no response for call #${i}`);
+        }
+        return responses[i++]!;
+    };
+    return { fetch: fake as typeof globalThis.fetch, calls };
+};
+
+describe("ApiClient.putJSON", () => {
+    it("sends a PUT request with JSON body and auth headers", async () => {
+        const { fetch, calls } = recordingFetch(jsonResponse({ ok: true }));
+        const client = new ApiClient({ fetch, authToken: "tok" });
+
+        await client.putJSON("/files/thumbnail", {
+            fileID: 42,
+            thumbnail: { objectKey: "k", decryptionHeader: "h" },
+        });
+
+        expect(calls[0]!.init?.method).toBe("PUT");
+        const headers = new Headers(calls[0]!.init?.headers as HeadersInit);
+        expect(headers.get("Content-Type")).toBe("application/json");
+        expect(headers.get("X-Auth-Token")).toBe("tok");
+        expect(headers.get("X-Client-Package")).toBe("berlin.sneak.quak");
+        const body = JSON.parse(calls[0]!.init?.body as string);
+        expect(body.fileID).toBe(42);
+        expect(body.thumbnail.objectKey).toBe("k");
+    });
+});
+
+describe("ApiClient.putFile", () => {
+    it("PUTs raw bytes to the presigned URL without auth headers", async () => {
+        const { fetch, calls } = recordingFetch(
+            new Response(null, { status: 200 }),
+        );
+        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);
+
+        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");
+        // Must NOT leak auth headers to S3
+        expect(headers.has("X-Auth-Token")).toBe(false);
+        expect(headers.has("X-Client-Package")).toBe(false);
+    });
+
+    it("throws on non-2xx response from presigned URL", async () => {
+        const { fetch } = recordingFetch(
+            new Response("Forbidden", { status: 403 }),
+        );
+        const client = new ApiClient({ fetch });
+
+        await expect(
+            client.putFile("https://s3.example.com/bad", new Uint8Array(10)),
+        ).rejects.toThrow(/403/);
+    });
+});
+
+describe("ApiClient.getUploadURL", () => {
+    it("POSTs to /files/upload-url with contentLength and contentMD5", async () => {
+        const { fetch, calls } = recordingFetch(
+            jsonResponse({ objectKey: "user/thumb123", url: "https://s3/put" }),
+        );
+        const client = new ApiClient({ fetch, authToken: "tok" });
+
+        const result = await client.getUploadURL(5000, "abc123==");
+
+        expect(calls[0]!.url).toBe("https://api.ente.io/files/upload-url");
+        const body = JSON.parse(calls[0]!.init?.body as string);
+        expect(body.contentLength).toBe(5000);
+        expect(body.contentMD5).toBe("abc123==");
+        expect(result.objectKey).toBe("user/thumb123");
+        expect(result.url).toBe("https://s3/put");
+    });
+});
+
+describe("ApiClient.updateThumbnail", () => {
+    it("PUTs to /files/thumbnail with fileID, objectKey, and decryptionHeader", async () => {
+        const { fetch, calls } = recordingFetch(jsonResponse({}));
+        const client = new ApiClient({ fetch, authToken: "tok" });
+
+        await client.updateThumbnail(42, "user/obj", "headerBase64==");
+
+        expect(calls[0]!.url).toBe("https://api.ente.io/files/thumbnail");
+        expect(calls[0]!.init?.method).toBe("PUT");
+        const body = JSON.parse(calls[0]!.init?.body as string);
+        expect(body.fileID).toBe(42);
+        expect(body.thumbnail.objectKey).toBe("user/obj");
+        expect(body.thumbnail.decryptionHeader).toBe("headerBase64==");
+    });
+});

test/auth/login.test.ts

@@ -145,7 +145,7 @@ const buildServerFixture = async (password: string) => {
  */
 const buildMockFetch = (
     fixture: Awaited<ReturnType<typeof buildServerFixture>>,
-    opts?: { requireTOTP?: boolean },
+    opts?: { requireTOTP?: boolean; requirePasskeyAndTOTP?: boolean },
 ) => {
     let srpServer: SrpServer;
     const sessionID = "test-session-id";
@@ -200,11 +200,47 @@ const buildMockFetch = (
             srpServer.checkM1(Buffer.from(body.srpM1, "base64"));
             const M2 = srpServer.computeM2();
 
+            // IMPORTANT: the museum server's EmailAuthorizationResponse
+            // (server/ente/user.go) declares passkeySessionID, accountsUrl,
+            // twoFactorSessionID, and twoFactorSessionIDV2 WITHOUT the
+            // `omitempty` JSON tag. Go therefore always serializes them,
+            // sending "" (empty string, NOT null/absent) for any that do
+            // not apply. These mocks must reproduce that faithfully: a
+            // client that distinguishes fields with `??` instead of `||`
+            // passes against an omitting mock but breaks against the real
+            // server.
+
             if (opts?.requireTOTP) {
                 return new Response(
                     JSON.stringify({
+                        id: 42,
                         srpM2: M2.toString("base64"),
+                        passkeySessionID: "",
+                        accountsUrl: "",
                         twoFactorSessionID: "totp-session-999",
+                        twoFactorSessionIDV2: "",
+                    }),
+                    {
+                        status: 200,
+                        headers: { "content-type": "application/json" },
+                    },
+                );
+            }
+
+            if (opts?.requirePasskeyAndTOTP) {
+                // When the account has BOTH passkeys and TOTP enabled, the
+                // server sets passkeySessionID + twoFactorSessionIDV2 (not
+                // twoFactorSessionID -- that's deliberate, so old clients
+                // that only know the V1 field keep using the passkey flow).
+                // The V1 field is still present on the wire as "".
+                return new Response(
+                    JSON.stringify({
+                        id: 42,
+                        srpM2: M2.toString("base64"),
+                        passkeySessionID: "passkey-session-123",
+                        accountsUrl: "https://accounts.ente.io",
+                        twoFactorSessionID: "",
+                        twoFactorSessionIDV2: "totp-session-v2-456",
                     }),
                     {
                         status: 200,
@@ -219,6 +255,10 @@ const buildMockFetch = (
                     id: 42,
                     keyAttributes: fixture.keyAttributes,
                     encryptedToken: fixture.encryptedToken,
+                    passkeySessionID: "",
+                    accountsUrl: "",
+                    twoFactorSessionID: "",
+                    twoFactorSessionIDV2: "",
                 }),
                 {
                     status: 200,
@@ -305,6 +345,26 @@ describe("beginLogin via SRP", () => {
         }
     });
 
+    it("prefers TOTP over passkey when the account has both", async () => {
+        // Accounts with both passkeys and TOTP get passkeySessionID +
+        // twoFactorSessionIDV2 in the verify-session response. A CLI
+        // cannot perform a WebAuthn ceremony, so quak must take the TOTP
+        // path using the V2 session ID. Returning { kind: "passkey" } here
+        // would make such accounts unusable from the CLI even though they
+        // have a perfectly good TOTP secret enrolled.
+        const fixture = await buildServerFixture(TEST_PASSWORD);
+        const api = new ApiClient({
+            fetch: buildMockFetch(fixture, { requirePasskeyAndTOTP: true }),
+        });
+
+        const challenge = await beginLogin(api, TEST_EMAIL, TEST_PASSWORD);
+
+        expect(challenge.kind).toBe("totp");
+        if (challenge.kind === "totp") {
+            expect(challenge.sessionID).toBe("totp-session-v2-456");
+        }
+    });
+
     it("rejects a wrong password (SRP M1 verification fails)", async () => {
         const fixture = await buildServerFixture(TEST_PASSWORD);
         const api = new ApiClient({ fetch: buildMockFetch(fixture) });

test/cli/metadata-backup.test.ts

@@ -0,0 +1,623 @@
+/**
+ * Tests for `quak backup-metadata <dir>`.
+ *
+ * This command dumps all decrypted account metadata into a directory
+ * tree of plain JSON files, without downloading any file content. It
+ * is fast (no multi-megabyte downloads) and produces a complete
+ * plaintext record of every collection name, file title, creation
+ * date, GPS coordinate, camera model, caption, face label, and any
+ * other metadata the Ente clients have attached.
+ *
+ * Layout:
+ *
+ *     <dir>/
+ *         account.json                { email, userID }
+ *         collections/
+ *             <id>-<sanitized-name>/
+ *                 _collection.json    { id, name, type, magicMetadata?, ... }
+ *                 <fileID>.json       { id, metadata, magicMetadata?, pubMagicMetadata? }
+ *
+ * The test builds a mock server with two collections, each with files
+ * that have different combinations of metadata layers, and verifies
+ * the output tree is correct and complete.
+ */
+
+import { gzipSync } from "node:zlib";
+import {
+    existsSync,
+    mkdtempSync,
+    readFileSync,
+    readdirSync,
+    rmSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import sodium from "libsodium-wrappers-sumo";
+import { SRP, SrpServer } from "fast-srp-hap";
+import { beforeAll, afterAll, describe, expect, it } from "vitest";
+import {
+    init,
+    toBase64,
+    deriveKEK,
+    deriveLoginSubkey,
+    encryptBlob,
+} from "../../src/crypto/index.js";
+import * as jpegJs from "jpeg-js";
+import { Client } from "../../src/client.js";
+import { runMetadataBackup } from "../../src/metadata-backup.js";
+import type { KeyAttributes } from "../../src/auth/types.js";
+
+const TEST_EMAIL = "metabackup@example.com";
+const TEST_PASSWORD = "metapass";
+const TEST_OPS = 2;
+const TEST_MEM = 64 * 1024 * 1024;
+
+interface MetaMockState {
+    verifier: Buffer;
+    srpAttributes: Record<string, unknown>;
+    keyAttributes: KeyAttributes;
+    encryptedToken: string;
+    collections: Record<string, unknown>[];
+    filesByCollection: Record<number, Record<string, unknown>[]>;
+    // For ML data and EXIF tests
+    encryptedMLData: Record<
+        number,
+        { encryptedData: string; decryptionHeader: string }
+    >;
+    fileCiphertexts: Record<number, Uint8Array>;
+}
+
+let mock: MetaMockState;
+let testDir: string;
+
+const encryptSecretbox = (plaintext: Uint8Array, key: Uint8Array) => {
+    const nonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
+    const ciphertext = sodium.crypto_secretbox_easy(plaintext, nonce, key);
+    return { ciphertext, nonce };
+};
+
+const encryptStreamBlob = (plaintext: Uint8Array, key: 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 { ciphertext, header: push.header };
+};
+
+const buildMetaMock = async (): Promise<MetaMockState> => {
+    const kekSalt = sodium.randombytes_buf(sodium.crypto_pwhash_SALTBYTES);
+    const kek = await deriveKEK(TEST_PASSWORD, kekSalt, TEST_OPS, TEST_MEM);
+    const loginSubKeyBytes = deriveLoginSubkey(kek);
+    const srpUserID = "meta-srp";
+    const srpSalt = sodium.randombytes_buf(16);
+    const verifier = SRP.computeVerifier(
+        SRP.params["4096"],
+        Buffer.from(srpSalt),
+        Buffer.from(srpUserID),
+        Buffer.from(loginSubKeyBytes),
+    );
+
+    const masterKey = sodium.randombytes_buf(32);
+    const { ciphertext: encMK, nonce: mkNonce } = encryptSecretbox(
+        masterKey,
+        kek,
+    );
+    const kp = sodium.crypto_box_keypair();
+    const { ciphertext: encSK, nonce: skNonce } = encryptSecretbox(
+        kp.privateKey,
+        masterKey,
+    );
+    const tokenBytes = sodium.randombytes_buf(32);
+    const encToken = sodium.crypto_box_seal(tokenBytes, kp.publicKey);
+
+    const keyAttributes: KeyAttributes = {
+        kekSalt: toBase64(kekSalt),
+        encryptedKey: toBase64(encMK),
+        keyDecryptionNonce: toBase64(mkNonce),
+        publicKey: toBase64(kp.publicKey),
+        encryptedSecretKey: toBase64(encSK),
+        secretKeyDecryptionNonce: toBase64(skNonce),
+        memLimit: TEST_MEM,
+        opsLimit: TEST_OPS,
+    };
+
+    // Collection 1: "Vacation" with collection-level pubMagicMetadata
+    const ck1 = sodium.crypto_secretbox_keygen();
+    const { ciphertext: encCK1, nonce: ck1N } = encryptSecretbox(
+        ck1,
+        masterKey,
+    );
+    const { ciphertext: encCN1, nonce: cn1N } = encryptSecretbox(
+        new TextEncoder().encode("Vacation"),
+        ck1,
+    );
+    const collPubMagic = JSON.stringify({ coverID: 999, sortBy: "date" });
+    const { ciphertext: encCollPM, header: collPMHeader } = encryptStreamBlob(
+        new TextEncoder().encode(collPubMagic),
+        ck1,
+    );
+
+    const rawColl1 = {
+        id: 10,
+        owner: { id: 42 },
+        encryptedKey: toBase64(encCK1),
+        keyDecryptionNonce: toBase64(ck1N),
+        encryptedName: toBase64(encCN1),
+        nameDecryptionNonce: toBase64(cn1N),
+        type: "album",
+        updationTime: 1700000000000000,
+        pubMagicMetadata: {
+            version: 1,
+            count: 1,
+            data: toBase64(encCollPM),
+            header: toBase64(collPMHeader),
+        },
+    };
+
+    // Collection 2: "Work" with no magic metadata
+    const ck2 = sodium.crypto_secretbox_keygen();
+    const { ciphertext: encCK2, nonce: ck2N } = encryptSecretbox(
+        ck2,
+        masterKey,
+    );
+    const { ciphertext: encCN2, nonce: cn2N } = encryptSecretbox(
+        new TextEncoder().encode("Work"),
+        ck2,
+    );
+    const rawColl2 = {
+        id: 20,
+        owner: { id: 42 },
+        encryptedKey: toBase64(encCK2),
+        keyDecryptionNonce: toBase64(ck2N),
+        encryptedName: toBase64(encCN2),
+        nameDecryptionNonce: toBase64(cn2N),
+        type: "folder",
+        updationTime: 1700000000000000,
+    };
+
+    // File 100 in coll 10: has metadata + pubMagicMetadata
+    const fk1 = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+    const { ciphertext: encFK1, nonce: fk1N } = encryptSecretbox(fk1, ck1);
+    const meta1 = JSON.stringify({
+        title: "beach.jpg",
+        fileType: 0,
+        creationTime: 1700000000000000,
+        modificationTime: 1700000000000000,
+        latitude: 35.6762,
+        longitude: 139.6503,
+    });
+    const { ciphertext: encMeta1, header: meta1Header } = encryptStreamBlob(
+        new TextEncoder().encode(meta1),
+        fk1,
+    );
+    const pubMagic1 = JSON.stringify({
+        w: 3000,
+        h: 2000,
+        cameraMake: "SONY",
+        cameraModel: "DSC-RX1RM3",
+    });
+    const { ciphertext: encPM1, header: pm1Header } = encryptStreamBlob(
+        new TextEncoder().encode(pubMagic1),
+        fk1,
+    );
+
+    const rawFile1 = {
+        id: 100,
+        collectionID: 10,
+        ownerID: 42,
+        encryptedKey: toBase64(encFK1),
+        keyDecryptionNonce: toBase64(fk1N),
+        metadata: {
+            encryptedData: toBase64(encMeta1),
+            decryptionHeader: toBase64(meta1Header),
+        },
+        pubMagicMetadata: {
+            version: 1,
+            count: 1,
+            data: toBase64(encPM1),
+            header: toBase64(pm1Header),
+        },
+        file: { decryptionHeader: toBase64(sodium.randombytes_buf(24)) },
+        thumbnail: { decryptionHeader: toBase64(sodium.randombytes_buf(24)) },
+        updationTime: 1700000000000000,
+    };
+
+    // File 200 in coll 20: metadata only, no magic metadata
+    const fk2 = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+    const { ciphertext: encFK2, nonce: fk2N } = encryptSecretbox(fk2, ck2);
+    const meta2 = JSON.stringify({
+        title: "diagram.png",
+        fileType: 0,
+        creationTime: 1710000000000000,
+        modificationTime: 1710000000000000,
+    });
+    const { ciphertext: encMeta2, header: meta2Header } = encryptStreamBlob(
+        new TextEncoder().encode(meta2),
+        fk2,
+    );
+
+    const rawFile2 = {
+        id: 200,
+        collectionID: 20,
+        ownerID: 42,
+        encryptedKey: toBase64(encFK2),
+        keyDecryptionNonce: toBase64(fk2N),
+        metadata: {
+            encryptedData: toBase64(encMeta2),
+            decryptionHeader: toBase64(meta2Header),
+        },
+        file: { decryptionHeader: toBase64(sodium.randombytes_buf(24)) },
+        thumbnail: { decryptionHeader: toBase64(sodium.randombytes_buf(24)) },
+        updationTime: 1710000000000000,
+    };
+
+    // Encrypt ML data for file 100 (gzipped JSON, encrypted with file key)
+    const mlPayload = JSON.stringify({
+        face: {
+            version: 1,
+            client: "test",
+            width: 3000,
+            height: 2000,
+            faces: [
+                {
+                    faceID: "face-abc",
+                    detection: {
+                        box: { x: 0.1, y: 0.2, width: 0.3, height: 0.4 },
+                        landmarks: [
+                            { x: 0.15, y: 0.25 },
+                            { x: 0.25, y: 0.25 },
+                        ],
+                    },
+                    score: 0.98,
+                    blur: 12.5,
+                    embedding: [0.1, 0.2, 0.3],
+                },
+            ],
+        },
+        clip: {
+            version: 1,
+            client: "test",
+            embedding: [0.5, 0.6, 0.7],
+        },
+    });
+    const gzipped = gzipSync(Buffer.from(mlPayload));
+    const { header: mlHeader, ciphertext: mlCiphertext } = encryptBlob(
+        new Uint8Array(gzipped),
+        fk1,
+    );
+
+    // Generate a real JPEG for EXIF extraction tests
+    const jw = 100;
+    const jh = 80;
+    const jpixels = new Uint8Array(jw * jh * 4);
+    for (let i = 0; i < jpixels.length; i += 4) {
+        jpixels[i] = 255;
+        jpixels[i + 1] = 0;
+        jpixels[i + 2] = 0;
+        jpixels[i + 3] = 255;
+    }
+    const tinyJpeg = jpegJs.encode(
+        { data: jpixels, width: jw, height: jh },
+        80,
+    ).data;
+    const filePush1 =
+        sodium.crypto_secretstream_xchacha20poly1305_init_push(fk1);
+    const encFileBody1 = sodium.crypto_secretstream_xchacha20poly1305_push(
+        filePush1.state,
+        new Uint8Array(tinyJpeg),
+        null,
+        sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL,
+    );
+    // Patch rawFile1's file.decryptionHeader to match the push header
+    rawFile1.file.decryptionHeader = toBase64(filePush1.header);
+
+    return {
+        verifier,
+        srpAttributes: {
+            srpUserID,
+            srpSalt: toBase64(srpSalt),
+            memLimit: TEST_MEM,
+            opsLimit: TEST_OPS,
+            kekSalt: toBase64(kekSalt),
+            isEmailMFAEnabled: false,
+        },
+        keyAttributes,
+        encryptedToken: toBase64(encToken),
+        collections: [rawColl1, rawColl2],
+        filesByCollection: { 10: [rawFile1], 20: [rawFile2] },
+        encryptedMLData: {
+            100: {
+                encryptedData: toBase64(mlCiphertext),
+                decryptionHeader: toBase64(mlHeader),
+            },
+        },
+        fileCiphertexts: { 100: encFileBody1 },
+    };
+};
+
+const buildMetaFetch = (m: MetaMockState) => {
+    let srpServer: SrpServer;
+    return (async (
+        input: RequestInfo | URL,
+        init?: RequestInit,
+    ): Promise<Response> => {
+        const url =
+            typeof input === "string"
+                ? input
+                : input instanceof URL
+                  ? input.href
+                  : input.url;
+        const path = new URL(url).pathname;
+        const json = (body: unknown) =>
+            new Response(JSON.stringify(body), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+
+        if (path === "/users/srp/attributes")
+            return json({ attributes: m.srpAttributes });
+        if (path === "/users/srp/create-session") {
+            const body = JSON.parse(init?.body as string);
+            const serverKey = await SRP.genKey();
+            srpServer = new SrpServer(
+                SRP.params["4096"],
+                m.verifier,
+                serverKey,
+            );
+            const B = srpServer.computeB();
+            srpServer.setA(Buffer.from(body.srpA, "base64"));
+            return json({ sessionID: "s1", srpB: B.toString("base64") });
+        }
+        if (path === "/users/srp/verify-session") {
+            const body = JSON.parse(init?.body as string);
+            srpServer.checkM1(Buffer.from(body.srpM1, "base64"));
+            return json({
+                srpM2: srpServer.computeM2().toString("base64"),
+                id: 42,
+                keyAttributes: m.keyAttributes,
+                encryptedToken: m.encryptedToken,
+            });
+        }
+        if (path === "/collections/v2")
+            return json({ collections: m.collections });
+        if (path === "/collections/v2/diff") {
+            const collID = Number(
+                new URL(url).searchParams.get("collectionID"),
+            );
+            return json({
+                diff: m.filesByCollection[collID] ?? [],
+                hasMore: false,
+            });
+        }
+        if (path === "/files/data/fetch") {
+            const body = JSON.parse(init?.body as string);
+            const data = (body.fileIDs as number[])
+                .filter((id: number) => m.encryptedMLData[id])
+                .map((id: number) => ({
+                    fileID: id,
+                    ...m.encryptedMLData[id],
+                    updatedAt: 1700000000000000,
+                }));
+            return json({ data });
+        }
+        if (
+            url.includes("files.ente.io") ||
+            path.startsWith("/files/download/")
+        ) {
+            const parsed = new URL(url);
+            const fileID = Number(
+                parsed.searchParams.get("fileID") ?? path.split("/").pop(),
+            );
+            const ct = m.fileCiphertexts[fileID];
+            if (ct) return new Response(ct, { status: 200 });
+            return new Response("not found", { status: 404 });
+        }
+        return new Response("not found", { status: 404 });
+    }) as typeof globalThis.fetch;
+};
+
+beforeAll(async () => {
+    await init();
+    await sodium.ready;
+    mock = await buildMetaMock();
+    testDir = mkdtempSync(join(tmpdir(), "quak-meta-backup-test-"));
+});
+
+afterAll(() => {
+    if (testDir && existsSync(testDir))
+        rmSync(testDir, { recursive: true, force: true });
+});
+
+describe("quak backup-metadata", () => {
+    it("writes account.json with email and userID", async () => {
+        const outDir = join(testDir, "full");
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildMetaFetch(mock) },
+        });
+
+        await runMetadataBackup(client, outDir);
+
+        const account = JSON.parse(
+            readFileSync(join(outDir, "account.json"), "utf-8"),
+        );
+        expect(account.email).toBe(TEST_EMAIL);
+        expect(account.userID).toBe(42);
+    });
+
+    it("creates per-collection directories with _collection.json", async () => {
+        const outDir = join(testDir, "collections");
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildMetaFetch(mock) },
+        });
+
+        await runMetadataBackup(client, outDir);
+
+        const collDirs = readdirSync(join(outDir, "collections"));
+        expect(collDirs.length).toBe(2);
+
+        // Find the Vacation collection dir (prefixed with ID)
+        const vacDir = collDirs.find((d) => d.includes("Vacation"))!;
+        expect(vacDir).toBeDefined();
+        const collMeta = JSON.parse(
+            readFileSync(
+                join(outDir, "collections", vacDir, "_collection.json"),
+                "utf-8",
+            ),
+        );
+        expect(collMeta.id).toBe(10);
+        expect(collMeta.name).toBe("Vacation");
+        expect(collMeta.type).toBe("album");
+    });
+
+    it("decrypts collection-level pubMagicMetadata", async () => {
+        const outDir = join(testDir, "coll-magic");
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildMetaFetch(mock) },
+        });
+
+        await runMetadataBackup(client, outDir);
+
+        const collDirs = readdirSync(join(outDir, "collections"));
+        const vacDir = collDirs.find((d) => d.includes("Vacation"))!;
+        const collMeta = JSON.parse(
+            readFileSync(
+                join(outDir, "collections", vacDir, "_collection.json"),
+                "utf-8",
+            ),
+        );
+        expect(collMeta.pubMagicMetadata).toBeDefined();
+        expect(collMeta.pubMagicMetadata.coverID).toBe(999);
+        expect(collMeta.pubMagicMetadata.sortBy).toBe("date");
+    });
+
+    it("writes per-file JSON with all three metadata layers", async () => {
+        const outDir = join(testDir, "file-meta");
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildMetaFetch(mock) },
+        });
+
+        await runMetadataBackup(client, outDir);
+
+        const collDirs = readdirSync(join(outDir, "collections"));
+        const vacDir = collDirs.find((d) => d.includes("Vacation"))!;
+        const fileMeta = JSON.parse(
+            readFileSync(
+                join(outDir, "collections", vacDir, "100.json"),
+                "utf-8",
+            ),
+        );
+        expect(fileMeta.id).toBe(100);
+        expect(fileMeta.metadata.title).toBe("beach.jpg");
+        expect(fileMeta.metadata.latitude).toBeCloseTo(35.6762);
+        expect(fileMeta.pubMagicMetadata.cameraMake).toBe("SONY");
+        expect(fileMeta.pubMagicMetadata.w).toBe(3000);
+    });
+
+    it("handles files with no magic metadata gracefully", async () => {
+        const outDir = join(testDir, "no-magic");
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildMetaFetch(mock) },
+        });
+
+        await runMetadataBackup(client, outDir);
+
+        const collDirs = readdirSync(join(outDir, "collections"));
+        const workDir = collDirs.find((d) => d.includes("Work"))!;
+        const fileMeta = JSON.parse(
+            readFileSync(
+                join(outDir, "collections", workDir, "200.json"),
+                "utf-8",
+            ),
+        );
+        expect(fileMeta.id).toBe(200);
+        expect(fileMeta.metadata.title).toBe("diagram.png");
+        expect(fileMeta.pubMagicMetadata).toBeUndefined();
+        expect(fileMeta.magicMetadata).toBeUndefined();
+    });
+
+    it("is incremental: second run does not fail", async () => {
+        const outDir = join(testDir, "incremental");
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildMetaFetch(mock) },
+        });
+
+        await runMetadataBackup(client, outDir);
+        await runMetadataBackup(client, outDir);
+
+        const account = JSON.parse(
+            readFileSync(join(outDir, "account.json"), "utf-8"),
+        );
+        expect(account.email).toBe(TEST_EMAIL);
+    });
+
+    it("fetches and decrypts ML data by default", async () => {
+        const outDir = join(testDir, "ml-data");
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildMetaFetch(mock) },
+        });
+
+        await runMetadataBackup(client, outDir);
+
+        const collDirs = readdirSync(join(outDir, "collections"));
+        const vacDir = collDirs.find((d) => d.includes("Vacation"))!;
+        const fileMeta = JSON.parse(
+            readFileSync(
+                join(outDir, "collections", vacDir, "100.json"),
+                "utf-8",
+            ),
+        );
+
+        // ML data should be present and decrypted
+        expect(fileMeta.mlData).toBeDefined();
+        expect(fileMeta.mlData.face).toBeDefined();
+        expect(fileMeta.mlData.face.faces.length).toBe(1);
+        expect(fileMeta.mlData.face.faces[0].faceID).toBe("face-abc");
+        expect(fileMeta.mlData.face.faces[0].score).toBeCloseTo(0.98);
+        expect(fileMeta.mlData.face.faces[0].detection.box.x).toBeCloseTo(0.1);
+        expect(fileMeta.mlData.clip).toBeDefined();
+        expect(fileMeta.mlData.clip.embedding).toEqual([0.5, 0.6, 0.7]);
+    });
+
+    it("extracts EXIF from downloaded files when --exif is set", async () => {
+        const outDir = join(testDir, "exif-data");
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildMetaFetch(mock) },
+        });
+
+        await runMetadataBackup(client, outDir, { exif: true });
+
+        const collDirs = readdirSync(join(outDir, "collections"));
+        const vacDir = collDirs.find((d) => d.includes("Vacation"))!;
+        const fileMeta = JSON.parse(
+            readFileSync(
+                join(outDir, "collections", vacDir, "100.json"),
+                "utf-8",
+            ),
+        );
+
+        // imageMetadata from JPEG parsing should be present
+        expect(fileMeta.imageMetadata).toBeDefined();
+        expect(fileMeta.imageMetadata.format).toBe("jpeg");
+        expect(fileMeta.imageMetadata.width).toBe(100);
+        expect(fileMeta.imageMetadata.height).toBe(80);
+    });
+});

test/client/usage.test.ts

@@ -91,6 +91,7 @@ interface ServerState {
     thumbHeader: Uint8Array;
     thumbCiphertext: Uint8Array;
     collectionKey: Uint8Array;
+    sharedCollectionKey: Uint8Array;
 }
 
 let server: ServerState;
@@ -211,6 +212,69 @@ const buildServer = async (): Promise<ServerState> => {
         updationTime: 1700000000000000,
     };
 
+    // A collection another user shared WITH us. The sharer does not have
+    // our master key, only our public key, so the real server delivers the
+    // collection key as an anonymous sealed box (crypto_box_seal) to our
+    // public key and the response carries NO keyDecryptionNonce. Every
+    // account with an incoming shared album has one of these in its
+    // /collections/v2 response, so the mock must include one too.
+    const sharedCollectionKey = sodium.crypto_secretbox_keygen();
+    const sealedSharedKey = sodium.crypto_box_seal(
+        sharedCollectionKey,
+        kp.publicKey,
+    );
+    const sharedNameNonce = sodium.randombytes_buf(
+        sodium.crypto_secretbox_NONCEBYTES,
+    );
+    const encSharedName = sodium.crypto_secretbox_easy(
+        new TextEncoder().encode("Friend's Wedding"),
+        sharedNameNonce,
+        sharedCollectionKey,
+    );
+    const rawSharedCollection = {
+        id: 2,
+        owner: { id: 99 },
+        encryptedKey: toBase64(sealedSharedKey),
+        encryptedName: toBase64(encSharedName),
+        nameDecryptionNonce: toBase64(sharedNameNonce),
+        type: "album",
+        updationTime: 1700000000000000,
+    };
+
+    // A DELETED collection. /collections/v2 is a sync API: deleted
+    // collections stay in the response forever as tombstones with
+    // isDeleted: true (a long-lived real account accumulates hundreds).
+    // Their keys still decrypt, but /collections/v2/diff returns
+    // HTTP 404 for them, so they must never surface from
+    // listCollections(); a client that naively iterates them dies on
+    // the first deleted album.
+    const deletedKey = sodium.crypto_secretbox_keygen();
+    const dkNonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
+    const encDeletedKey = sodium.crypto_secretbox_easy(
+        deletedKey,
+        dkNonce,
+        masterKey,
+    );
+    const deletedNameNonce = sodium.randombytes_buf(
+        sodium.crypto_secretbox_NONCEBYTES,
+    );
+    const encDeletedName = sodium.crypto_secretbox_easy(
+        new TextEncoder().encode("Old Album"),
+        deletedNameNonce,
+        deletedKey,
+    );
+    const rawDeletedCollection = {
+        id: 3,
+        owner: { id: 42 },
+        encryptedKey: toBase64(encDeletedKey),
+        keyDecryptionNonce: toBase64(dkNonce),
+        encryptedName: toBase64(encDeletedName),
+        nameDecryptionNonce: toBase64(deletedNameNonce),
+        type: "album",
+        updationTime: 1700000000000000,
+        isDeleted: true,
+    };
+
     const rawFile = {
         id: 100,
         collectionID: 1,
@@ -230,6 +294,10 @@ const buildServer = async (): Promise<ServerState> => {
     // can return them. This is ugly plumbing; in a real program you
     // never see any of it.
     (globalThis as Record<string, unknown>).__mockRawCollection = rawCollection;
+    (globalThis as Record<string, unknown>).__mockRawSharedCollection =
+        rawSharedCollection;
+    (globalThis as Record<string, unknown>).__mockRawDeletedCollection =
+        rawDeletedCollection;
     (globalThis as Record<string, unknown>).__mockRawFile = rawFile;
 
     return {
@@ -253,6 +321,7 @@ const buildServer = async (): Promise<ServerState> => {
         thumbHeader: thumbPush.header,
         thumbCiphertext,
         collectionKey,
+        sharedCollectionKey,
     };
 };
 
@@ -303,9 +372,14 @@ const buildMockFetch = (s: ServerState) => {
             });
         }
         if (path === "/collections/v2") {
-            const raw = (globalThis as Record<string, unknown>)
-                .__mockRawCollection;
-            return json({ collections: [raw] });
+            const g = globalThis as Record<string, unknown>;
+            return json({
+                collections: [
+                    g.__mockRawCollection,
+                    g.__mockRawSharedCollection,
+                    g.__mockRawDeletedCollection,
+                ],
+            });
         }
         if (path === "/collections/v2/diff") {
             const raw = (globalThis as Record<string, unknown>).__mockRawFile;
@@ -412,6 +486,10 @@ describe("quak Client usage guide", () => {
      * encryption key. `listCollections()` fetches them from the server,
      * decrypts the keys and names, and returns typed objects.
      *
+     * This works transparently for both kinds of collection: ones you
+     * own (key encrypted with your master key) and ones shared with you
+     * (key sealed to your public key, flagged with `isShared: true`).
+     *
      * ```ts
      * const collections = await client.listCollections();
      * for (const c of collections) {
@@ -419,7 +497,7 @@ describe("quak Client usage guide", () => {
      * }
      * ```
      */
-    it("3. list and decrypt collections", async () => {
+    it("3. list and decrypt collections, owned and shared", async () => {
         const client = await Client.login({
             email: TEST_EMAIL,
             password: TEST_PASSWORD,
@@ -428,12 +506,25 @@ describe("quak Client usage guide", () => {
 
         const collections = await client.listCollections();
 
-        expect(collections.length).toBe(1);
-        expect(collections[0]!.name).toBe("Vacation");
-        expect(collections[0]!.type).toBe("album");
-        expect(collections[0]!.id).toBe(1);
+        // The mock server also returns a deleted collection (id 3).
+        // Deleted collections are tombstones in the sync protocol: their
+        // file diff endpoint 404s, so listCollections must drop them.
+        expect(collections.length).toBe(2);
+        expect(collections.find((c) => c.id === 3)).toBeUndefined();
+
+        const owned = collections.find((c) => c.id === 1)!;
+        expect(owned.name).toBe("Vacation");
+        expect(owned.type).toBe("album");
+        expect(owned.isShared).toBe(false);
         // The decrypted collection key is available for advanced use.
-        expect(collections[0]!.key.length).toBe(32);
+        expect(owned.key.length).toBe(32);
+
+        const shared = collections.find((c) => c.id === 2)!;
+        expect(shared.name).toBe("Friend's Wedding");
+        expect(shared.isShared).toBe(true);
+        // The key was unsealed with our keypair; the decrypted name above
+        // already proves it round-trips, but check it exactly too.
+        expect(shared.key).toEqual(server.sharedCollectionKey);
     });
 
     /**

test/crypto/encrypt-blob.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Tests for `crypto.encryptBlob`.
+ *
+ * `encryptBlob` is the push-side counterpart to `decryptBlob`. It
+ * encrypts a small payload as a single secretstream chunk with
+ * TAG_FINAL and returns the header + ciphertext. Used for encrypting
+ * thumbnails before upload to the Ente server.
+ *
+ * The critical invariant is that `decryptBlob(encryptBlob(...))` is the
+ * identity function. If either side drifts, uploaded thumbnails become
+ * unreadable.
+ */
+
+import sodium from "libsodium-wrappers-sumo";
+import { beforeAll, describe, expect, it } from "vitest";
+import {
+    decryptBlob,
+    encryptBlob,
+    init,
+    STREAM_CHUNK_OVERHEAD,
+} from "../../src/crypto/index.js";
+
+describe("crypto.encryptBlob", () => {
+    beforeAll(async () => {
+        await init();
+        await sodium.ready;
+    });
+
+    it("round-trips with decryptBlob for arbitrary data", () => {
+        const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+        const plaintext = sodium.randombytes_buf(500);
+        const { header, ciphertext } = encryptBlob(plaintext, key);
+        const recovered = decryptBlob(ciphertext, header, key);
+        expect(recovered).toEqual(plaintext);
+    });
+
+    it("round-trips a zero-length payload", () => {
+        const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+        const { header, ciphertext } = encryptBlob(new Uint8Array(0), key);
+        const recovered = decryptBlob(ciphertext, header, key);
+        expect(recovered.length).toBe(0);
+    });
+
+    it("ciphertext is exactly STREAM_CHUNK_OVERHEAD longer than plaintext", () => {
+        const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+        const plaintext = sodium.randombytes_buf(1234);
+        const { ciphertext } = encryptBlob(plaintext, key);
+        expect(ciphertext.length).toBe(
+            plaintext.length + STREAM_CHUNK_OVERHEAD,
+        );
+    });
+
+    it("header is 24 bytes (secretstream XChaCha20 header size)", () => {
+        const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+        const { header } = encryptBlob(new Uint8Array([1, 2, 3]), key);
+        expect(header.length).toBe(
+            sodium.crypto_secretstream_xchacha20poly1305_HEADERBYTES,
+        );
+    });
+
+    it("produces different ciphertext for different keys", () => {
+        const k1 = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+        const k2 = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+        const plaintext = new Uint8Array([1, 2, 3, 4, 5]);
+        const enc1 = encryptBlob(plaintext, k1);
+        const enc2 = encryptBlob(plaintext, k2);
+        expect(enc1.ciphertext).not.toEqual(enc2.ciphertext);
+    });
+
+    it("produces different ciphertext on each call (random nonce in header)", () => {
+        const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+        const plaintext = new Uint8Array([9, 9, 9]);
+        const a = encryptBlob(plaintext, key);
+        const b = encryptBlob(plaintext, key);
+        expect(a.header).not.toEqual(b.header);
+        expect(a.ciphertext).not.toEqual(b.ciphertext);
+    });
+
+    it("decryptBlob rejects ciphertext encrypted with a different key", () => {
+        const k1 = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+        const k2 = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+        const { header, ciphertext } = encryptBlob(
+            new Uint8Array([1, 2, 3]),
+            k1,
+        );
+        expect(() => decryptBlob(ciphertext, header, k2)).toThrow();
+    });
+
+    it("decryptBlob rejects tampered ciphertext from encryptBlob", () => {
+        const key = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+        const { header, ciphertext } = encryptBlob(
+            sodium.randombytes_buf(100),
+            key,
+        );
+        ciphertext[ciphertext.length - 1] =
+            ciphertext[ciphertext.length - 1]! ^ 0x01;
+        expect(() => decryptBlob(ciphertext, header, key)).toThrow();
+    });
+});

test/integration/live-login.ts

@@ -25,7 +25,10 @@ const main = async () => {
         process.exit(1);
     }
 
-    const { masterKey, token } = await unwrapAuth(challenge.response, PASSWORD);
+    const { masterKey, secretKey, publicKey, token } = await unwrapAuth(
+        challenge.response,
+        PASSWORD,
+    );
     api.setAuthToken(token);
     console.log("Logged in, user ID:", challenge.response.id);
 
@@ -37,7 +40,7 @@ const main = async () => {
 
     const userID = challenge.response.id;
     const collections = rawCollections.map((raw) =>
-        decryptCollection(raw, masterKey, userID),
+        decryptCollection(raw, { masterKey, publicKey, secretKey }, userID),
     );
 
     console.log(`${collections.length} collection(s):`);

test/model/decrypt.test.ts

@@ -7,12 +7,27 @@
  *
  * ## Collection decryption
  *
- *   The server stores each collection's encryption key sealed under the
- *   owner's master key (secretbox). The collection's name is then sealed
- *   under that collection key (also secretbox). `decryptCollection`:
+ *   How a collection's key is encrypted depends on who owns it:
  *
- *     1. decryptBox(encryptedKey, keyDecryptionNonce, masterKey) -> collectionKey
- *     2. decryptBox(encryptedName, nameDecryptionNonce, collectionKey) -> name (UTF-8)
+ *   OWNED collections (owner == current user): the collection key is a
+ *   secretbox under the owner's master key, and `keyDecryptionNonce`
+ *   carries the nonce.
+ *
+ *   SHARED collections (owned by someone else, shared with us): the owner
+ *   does not have our master key, so the server instead carries the
+ *   collection key as an anonymous SEALED BOX (crypto_box_seal) to our
+ *   X25519 public key, and `keyDecryptionNonce` is ABSENT from the wire
+ *   (sealed boxes embed an ephemeral public key instead of a nonce).
+ *
+ *   `decryptCollection` therefore takes the full key material (master key
+ *   plus keypair) and dispatches on the presence of `keyDecryptionNonce`:
+ *
+ *     1a. nonce present: decryptBox(encryptedKey, keyDecryptionNonce,
+ *         masterKey) -> collectionKey
+ *     1b. nonce absent: decryptSealed(encryptedKey, publicKey, secretKey)
+ *         -> collectionKey
+ *     2. decryptBox(encryptedName, nameDecryptionNonce, collectionKey)
+ *        -> name (UTF-8)
  *     3. Maps the string `type` field to a CollectionType union member
  *     4. Returns a Collection with decrypted key, name, and type
  *
@@ -38,12 +53,28 @@ import sodium from "libsodium-wrappers-sumo";
 import { beforeAll, describe, expect, it } from "vitest";
 import { init, toBase64 } from "../../src/crypto/index.js";
 import { decryptCollection, decryptFile } from "../../src/model/index.js";
-import type { RawCollection, RawEnteFile } from "../../src/model/index.js";
+import type {
+    KeyMaterial,
+    RawCollection,
+    RawEnteFile,
+} from "../../src/model/index.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+// The full set of key material a logged-in client holds: the master key
+// (decrypts owned collection keys) and the X25519 keypair (unseals shared
+// collection keys and the auth token).
+const buildKeys = (): KeyMaterial => {
+    const kp = sodium.crypto_box_keypair();
+    return {
+        masterKey: sodium.crypto_secretbox_keygen(),
+        publicKey: kp.publicKey,
+        secretKey: kp.privateKey,
+    };
+};
+
 const secretboxEncrypt = (
     plaintext: Uint8Array,
     key: Uint8Array,
@@ -80,6 +111,38 @@ const buildRawCollection = (
     return { raw, collectionKey };
 };
 
+// A collection shared with us by another user. The wire format differs
+// from owned collections in two ways, both verified against the live
+// api.ente.io: `encryptedKey` is an anonymous sealed box to OUR public
+// key (80 bytes for a 32-byte key, vs 48 for a secretbox), and
+// `keyDecryptionNonce` is entirely ABSENT from the JSON.
+const buildSharedRawCollection = (
+    recipientPublicKey: Uint8Array,
+    opts?: { name?: string; ownerID?: number },
+): { raw: RawCollection; collectionKey: Uint8Array } => {
+    const collectionKey = sodium.crypto_secretbox_keygen();
+    const sealedKey = sodium.crypto_box_seal(collectionKey, recipientPublicKey);
+    const name = opts?.name ?? "Shared Album";
+    const { ciphertext: encName, nonce: nameNonce } = secretboxEncrypt(
+        new TextEncoder().encode(name),
+        collectionKey,
+    );
+    const raw: RawCollection = {
+        id: 101,
+        owner: { id: opts?.ownerID ?? 99 },
+        encryptedKey: toBase64(sealedKey),
+        // NOTE: no keyDecryptionNonce. Do not "fix" this fixture by adding
+        // one: its absence is exactly what the real server sends, and an
+        // unfaithful fixture here previously masked a crash on every
+        // account with an incoming shared album.
+        encryptedName: toBase64(encName),
+        nameDecryptionNonce: toBase64(nameNonce),
+        type: "album",
+        updationTime: 1700000000000000,
+    };
+    return { raw, collectionKey };
+};
+
 const buildRawFile = (
     collectionKey: Uint8Array,
     opts?: { title?: string; fileType?: number; creationTime?: number },
@@ -137,13 +200,13 @@ describe("model.decryptCollection", () => {
         await sodium.ready;
     });
 
-    it("decrypts the collection key and name from a raw server response", () => {
-        const masterKey = sodium.crypto_secretbox_keygen();
-        const { raw, collectionKey } = buildRawCollection(masterKey, {
+    it("decrypts an owned collection key and name from a raw server response", () => {
+        const keys = buildKeys();
+        const { raw, collectionKey } = buildRawCollection(keys.masterKey, {
             name: "Summer Photos",
         });
 
-        const col = decryptCollection(raw, masterKey, 1);
+        const col = decryptCollection(raw, keys, 1);
 
         expect(col.id).toBe(100);
         expect(col.key).toEqual(collectionKey);
@@ -154,49 +217,73 @@ describe("model.decryptCollection", () => {
         expect(col.isShared).toBe(false);
     });
 
-    it("sets isShared when owner != current user", () => {
-        const masterKey = sodium.crypto_secretbox_keygen();
-        const { raw } = buildRawCollection(masterKey, { ownerID: 99 });
+    it("decrypts a shared collection via sealed box when keyDecryptionNonce is absent", () => {
+        // A collection shared TO us is not encrypted with our master key:
+        // the sharer only knows our public key, so the collection key
+        // arrives as crypto_box_seal(collectionKey, ourPublicKey) and the
+        // response has NO keyDecryptionNonce. decryptCollection must
+        // recover the key with the keypair, then decrypt the name with it
+        // as usual. Accounts with any incoming shared album hit this path
+        // on every listCollections call.
+        const keys = buildKeys();
+        const { raw, collectionKey } = buildSharedRawCollection(
+            keys.publicKey,
+            { name: "Friend's Wedding", ownerID: 99 },
+        );
 
-        const col = decryptCollection(raw, masterKey, 1);
+        const col = decryptCollection(raw, keys, 1);
+
+        expect(col.key).toEqual(collectionKey);
+        expect(col.name).toBe("Friend's Wedding");
+        expect(col.ownerID).toBe(99);
         expect(col.isShared).toBe(true);
     });
 
     it("maps known type strings to CollectionType", () => {
-        const masterKey = sodium.crypto_secretbox_keygen();
+        const keys = buildKeys();
         for (const type of ["album", "folder", "favorites", "uncategorized"]) {
-            const { raw } = buildRawCollection(masterKey, { type });
-            const col = decryptCollection(raw, masterKey, 1);
+            const { raw } = buildRawCollection(keys.masterKey, { type });
+            const col = decryptCollection(raw, keys, 1);
             expect(col.type).toBe(type);
         }
     });
 
     it("maps unrecognised type strings to 'unknown'", () => {
-        const masterKey = sodium.crypto_secretbox_keygen();
-        const { raw } = buildRawCollection(masterKey, {
+        const keys = buildKeys();
+        const { raw } = buildRawCollection(keys.masterKey, {
             type: "someFutureType",
         });
-        const col = decryptCollection(raw, masterKey, 1);
+        const col = decryptCollection(raw, keys, 1);
         expect(col.type).toBe("unknown");
     });
 
     it("handles a collection with no encrypted name gracefully", () => {
         // Some special collections (e.g. uncategorized) may have no name.
-        const masterKey = sodium.crypto_secretbox_keygen();
-        const { raw } = buildRawCollection(masterKey);
+        const keys = buildKeys();
+        const { raw } = buildRawCollection(keys.masterKey);
         delete raw.encryptedName;
         delete raw.nameDecryptionNonce;
 
-        const col = decryptCollection(raw, masterKey, 1);
+        const col = decryptCollection(raw, keys, 1);
         expect(col.name).toBe("");
     });
 
-    it("throws when the master key is wrong", () => {
-        const masterKey = sodium.crypto_secretbox_keygen();
-        const wrongKey = sodium.crypto_secretbox_keygen();
-        const { raw } = buildRawCollection(masterKey);
+    it("throws when the master key is wrong for an owned collection", () => {
+        const keys = buildKeys();
+        const { raw } = buildRawCollection(keys.masterKey);
 
-        expect(() => decryptCollection(raw, wrongKey, 1)).toThrow();
+        // buildKeys() generates fresh random key material, so this is a
+        // client holding the wrong master key.
+        expect(() => decryptCollection(raw, buildKeys(), 1)).toThrow();
+    });
+
+    it("throws when the keypair is wrong for a shared collection", () => {
+        const keys = buildKeys();
+        const { raw } = buildSharedRawCollection(keys.publicKey);
+
+        // A different keypair must not be able to unseal the key.
+        const wrongKeys = buildKeys();
+        expect(() => decryptCollection(raw, wrongKeys, 1)).toThrow();
     });
 });
 

test/thumbnails/thumbnails.test.ts

@@ -0,0 +1,510 @@
+/**
+ * Tests for `listMissingThumbnails` and `fixMissingThumbnails`.
+ *
+ * These use a mock Ente server that serves encrypted collections, files,
+ * and thumbnails. The mock server has deliberate gaps: some files have
+ * working thumbnails, others return 404 or empty bodies. The tests
+ * verify that the detection and repair logic handles each case correctly.
+ *
+ * `fixMissingThumbnails` is the most complex function in quak: it
+ * downloads the original file, generates a JPEG thumbnail with jpeg-js,
+ * encrypts it with secretstream push, gets a presigned upload URL,
+ * uploads to S3, and registers the new thumbnail with the API. The
+ * test verifies each step actually happened and the uploaded data is
+ * a valid encrypted blob that decrypts to a JPEG.
+ */
+
+import sodium from "libsodium-wrappers-sumo";
+import * as jpegJs from "jpeg-js";
+import { beforeAll, describe, expect, it } from "vitest";
+import {
+    init,
+    toBase64,
+    decryptBlob,
+    fromBase64,
+    deriveKEK,
+    deriveLoginSubkey,
+} from "../../src/crypto/index.js";
+import { SRP, SrpServer } from "fast-srp-hap";
+import { Client } from "../../src/client.js";
+import {
+    listMissingThumbnails,
+    fixMissingThumbnails,
+} from "../../src/thumbnails.js";
+import type { KeyAttributes } from "../../src/auth/types.js";
+
+// ---------------------------------------------------------------------------
+// Mock server with controllable thumbnail behavior
+// ---------------------------------------------------------------------------
+
+const TEST_EMAIL = "thumb@example.com";
+const TEST_PASSWORD = "thumbpass";
+const TEST_OPS = 2;
+const TEST_MEM = 64 * 1024 * 1024;
+
+interface ThumbMockState {
+    verifier: Buffer;
+    srpAttributes: Record<string, unknown>;
+    keyAttributes: KeyAttributes;
+    encryptedToken: string;
+    collections: Record<string, unknown>[];
+    filesByCollection: Record<number, Record<string, unknown>[]>;
+    fileCiphertexts: Record<number, Uint8Array>;
+    fileKeys: Record<number, Uint8Array>;
+    thumbnailBehavior: Record<number, "ok" | "empty" | "404">;
+    // Captures from fix operations
+    uploadedThumbnails: {
+        fileID: number;
+        objectKey: string;
+        decryptionHeader: string;
+        ciphertext: Uint8Array;
+    }[];
+}
+
+let mock: ThumbMockState;
+
+const buildThumbMock = async (): Promise<ThumbMockState> => {
+    const kekSalt = sodium.randombytes_buf(sodium.crypto_pwhash_SALTBYTES);
+    const kek = await deriveKEK(TEST_PASSWORD, kekSalt, TEST_OPS, TEST_MEM);
+    const loginSubKeyBytes = deriveLoginSubkey(kek);
+
+    const srpUserID = "thumb-srp";
+    const srpSalt = sodium.randombytes_buf(16);
+    const verifier = SRP.computeVerifier(
+        SRP.params["4096"],
+        Buffer.from(srpSalt),
+        Buffer.from(srpUserID),
+        Buffer.from(loginSubKeyBytes),
+    );
+
+    const masterKey = sodium.randombytes_buf(32);
+    const keyNonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
+    const encryptedKey = sodium.crypto_secretbox_easy(masterKey, keyNonce, kek);
+    const kp = sodium.crypto_box_keypair();
+    const skNonce = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
+    const encSK = sodium.crypto_secretbox_easy(
+        kp.privateKey,
+        skNonce,
+        masterKey,
+    );
+    const tokenBytes = sodium.randombytes_buf(32);
+    const encToken = sodium.crypto_box_seal(tokenBytes, kp.publicKey);
+
+    const keyAttributes: KeyAttributes = {
+        kekSalt: toBase64(kekSalt),
+        encryptedKey: toBase64(encryptedKey),
+        keyDecryptionNonce: toBase64(keyNonce),
+        publicKey: toBase64(kp.publicKey),
+        encryptedSecretKey: toBase64(encSK),
+        secretKeyDecryptionNonce: toBase64(skNonce),
+        memLimit: TEST_MEM,
+        opsLimit: TEST_OPS,
+    };
+
+    // One collection with 3 files: ok thumbnail, empty thumbnail, 404 thumbnail
+    const collKey = sodium.crypto_secretbox_keygen();
+    const ckN = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
+    const encCK = sodium.crypto_secretbox_easy(collKey, ckN, masterKey);
+    const nameB = new TextEncoder().encode("Photos");
+    const cnN = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
+    const encCN = sodium.crypto_secretbox_easy(nameB, cnN, collKey);
+
+    const rawCollection = {
+        id: 1,
+        owner: { id: 42 },
+        encryptedKey: toBase64(encCK),
+        keyDecryptionNonce: toBase64(ckN),
+        encryptedName: toBase64(encCN),
+        nameDecryptionNonce: toBase64(cnN),
+        type: "album",
+        updationTime: 1700000000000000,
+    };
+
+    // Generate a real tiny JPEG via jpeg-js
+    const w = 100;
+    const h = 80;
+    const pixels = new Uint8Array(w * h * 4);
+    for (let i = 0; i < pixels.length; i += 4) {
+        pixels[i] = 255; // R
+        pixels[i + 1] = 0; // G
+        pixels[i + 2] = 0; // B
+        pixels[i + 3] = 255; // A
+    }
+    const tinyJpeg = jpegJs.encode(
+        { data: pixels, width: w, height: h },
+        80,
+    ).data;
+
+    const fileKeys: Record<number, Uint8Array> = {};
+    const fileCiphertexts: Record<number, Uint8Array> = {};
+    const rawFiles: Record<string, unknown>[] = [];
+
+    for (const fileID of [100, 101, 102]) {
+        const fk = sodium.crypto_secretstream_xchacha20poly1305_keygen();
+        fileKeys[fileID] = fk;
+        const fkN = sodium.randombytes_buf(sodium.crypto_secretbox_NONCEBYTES);
+        const encFK = sodium.crypto_secretbox_easy(fk, fkN, collKey);
+
+        const meta = JSON.stringify({
+            title: `file-${fileID}.jpg`,
+            fileType: 0,
+            creationTime: 1700000000000000,
+            modificationTime: 1700000000000000,
+        });
+        const metaPush =
+            sodium.crypto_secretstream_xchacha20poly1305_init_push(fk);
+        const encMeta = sodium.crypto_secretstream_xchacha20poly1305_push(
+            metaPush.state,
+            new TextEncoder().encode(meta),
+            null,
+            sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL,
+        );
+
+        // Encrypt the tiny JPEG as the file body
+        const filePush =
+            sodium.crypto_secretstream_xchacha20poly1305_init_push(fk);
+        const encFile = sodium.crypto_secretstream_xchacha20poly1305_push(
+            filePush.state,
+            new Uint8Array(tinyJpeg),
+            null,
+            sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL,
+        );
+        fileCiphertexts[fileID] = encFile;
+
+        rawFiles.push({
+            id: fileID,
+            collectionID: 1,
+            ownerID: 42,
+            encryptedKey: toBase64(encFK),
+            keyDecryptionNonce: toBase64(fkN),
+            metadata: {
+                encryptedData: toBase64(encMeta),
+                decryptionHeader: toBase64(metaPush.header),
+            },
+            file: { decryptionHeader: toBase64(filePush.header) },
+            thumbnail: {
+                decryptionHeader: toBase64(sodium.randombytes_buf(24)),
+            },
+            updationTime: 1700000000000000,
+        });
+    }
+
+    return {
+        verifier,
+        srpAttributes: {
+            srpUserID,
+            srpSalt: toBase64(srpSalt),
+            memLimit: TEST_MEM,
+            opsLimit: TEST_OPS,
+            kekSalt: toBase64(kekSalt),
+            isEmailMFAEnabled: false,
+        },
+        keyAttributes,
+        encryptedToken: toBase64(encToken),
+        collections: [rawCollection],
+        filesByCollection: { 1: rawFiles },
+        fileCiphertexts,
+        fileKeys,
+        thumbnailBehavior: {
+            100: "ok",
+            101: "empty",
+            102: "404",
+        },
+        uploadedThumbnails: [],
+    };
+};
+
+const buildThumbFetch = (m: ThumbMockState) => {
+    let srpServer: SrpServer;
+
+    return (async (
+        input: RequestInfo | URL,
+        init?: RequestInit,
+    ): Promise<Response> => {
+        const url =
+            typeof input === "string"
+                ? input
+                : input instanceof URL
+                  ? input.href
+                  : input.url;
+        const parsed = new URL(url);
+        const path = parsed.pathname;
+        const json = (body: unknown) =>
+            new Response(JSON.stringify(body), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+
+        // SRP auth flow
+        if (path === "/users/srp/attributes")
+            return json({ attributes: m.srpAttributes });
+        if (path === "/users/srp/create-session") {
+            const body = JSON.parse(init?.body as string);
+            const serverKey = await SRP.genKey();
+            srpServer = new SrpServer(
+                SRP.params["4096"],
+                m.verifier,
+                serverKey,
+            );
+            const B = srpServer.computeB();
+            srpServer.setA(Buffer.from(body.srpA, "base64"));
+            return json({ sessionID: "s1", srpB: B.toString("base64") });
+        }
+        if (path === "/users/srp/verify-session") {
+            const body = JSON.parse(init?.body as string);
+            srpServer.checkM1(Buffer.from(body.srpM1, "base64"));
+            return json({
+                srpM2: srpServer.computeM2().toString("base64"),
+                id: 42,
+                keyAttributes: m.keyAttributes,
+                encryptedToken: m.encryptedToken,
+            });
+        }
+
+        // Collections & files
+        if (path === "/collections/v2")
+            return json({ collections: m.collections });
+        if (path === "/collections/v2/diff") {
+            const collID = Number(parsed.searchParams.get("collectionID"));
+            return json({
+                diff: m.filesByCollection[collID] ?? [],
+                hasMore: false,
+            });
+        }
+
+        // File download (for fix: download original to generate thumb)
+        if (
+            url.includes("files.ente.io") ||
+            path.startsWith("/files/download/")
+        ) {
+            const fileID = Number(
+                parsed.searchParams.get("fileID") ?? path.split("/").pop(),
+            );
+            const ct = m.fileCiphertexts[fileID];
+            if (ct) return new Response(ct, { status: 200 });
+            return new Response("not found", { status: 404 });
+        }
+
+        // Thumbnail download (for list: check if thumbnail exists)
+        if (
+            url.includes("thumbnails.ente.io") ||
+            path.startsWith("/files/preview/")
+        ) {
+            const fileID = Number(
+                parsed.searchParams.get("fileID") ?? path.split("/").pop(),
+            );
+            const behavior = m.thumbnailBehavior[fileID];
+            if (behavior === "ok") {
+                return new Response(new Uint8Array([0xff, 0xd8, 0xff]), {
+                    status: 200,
+                });
+            }
+            if (behavior === "empty") {
+                return new Response(new Uint8Array(0), { status: 200 });
+            }
+            return new Response("not found", { status: 404 });
+        }
+
+        // Upload URL minting
+        if (path === "/files/upload-url") {
+            return json({
+                objectKey: `42/thumb-${Date.now()}`,
+                url: "https://s3.mock.test/presigned-put",
+            });
+        }
+
+        // Presigned PUT (S3 upload)
+        if (url.startsWith("https://s3.mock.test/")) {
+            const body = init?.body;
+            // Store the uploaded bytes for later inspection
+            if (body instanceof Uint8Array) {
+                (m as Record<string, unknown>)._lastUploadedCiphertext = body;
+            } else if (body instanceof ArrayBuffer) {
+                (m as Record<string, unknown>)._lastUploadedCiphertext =
+                    new Uint8Array(body);
+            }
+            return new Response(null, { status: 200 });
+        }
+
+        // Update thumbnail metadata
+        if (path === "/files/thumbnail" && init?.method === "PUT") {
+            const reqBody = JSON.parse(init?.body as string);
+            m.uploadedThumbnails.push({
+                fileID: reqBody.fileID,
+                objectKey: reqBody.thumbnail.objectKey,
+                decryptionHeader: reqBody.thumbnail.decryptionHeader,
+                ciphertext:
+                    ((m as Record<string, unknown>)
+                        ._lastUploadedCiphertext as Uint8Array) ??
+                    new Uint8Array(0),
+            });
+            return json({});
+        }
+
+        return new Response("not found", { status: 404 });
+    }) as typeof globalThis.fetch;
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+beforeAll(async () => {
+    await init();
+    await sodium.ready;
+    mock = await buildThumbMock();
+});
+
+describe("listMissingThumbnails", () => {
+    it("identifies files with empty and 404 thumbnails, ignores working ones", async () => {
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildThumbFetch(mock) },
+        });
+
+        const missing = await listMissingThumbnails(client);
+
+        // File 100 has a working thumbnail → not reported
+        // File 101 has an empty thumbnail → reported
+        // File 102 has a 404 thumbnail → reported
+        expect(missing.length).toBe(2);
+        const ids = missing.map((m) => m.fileID).sort();
+        expect(ids).toEqual([101, 102]);
+
+        const emptyEntry = missing.find((m) => m.fileID === 101)!;
+        expect(emptyEntry.reason).toContain("empty");
+        expect(emptyEntry.title).toBe("file-101.jpg");
+        expect(emptyEntry.collection).toBe("Photos");
+
+        const notFoundEntry = missing.find((m) => m.fileID === 102)!;
+        expect(notFoundEntry.reason).toContain("fetch failed");
+    });
+
+    it("deduplicates files seen in multiple collections", async () => {
+        // Add the same files to a second collection in the mock
+        const mockWithDupes = await buildThumbMock();
+        const dupeCollection = {
+            ...mockWithDupes.collections[0]!,
+            id: 2,
+        };
+        mockWithDupes.collections.push(
+            dupeCollection as Record<string, unknown>,
+        );
+        mockWithDupes.filesByCollection[2] =
+            mockWithDupes.filesByCollection[1]!;
+
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildThumbFetch(mockWithDupes) },
+        });
+
+        const missing = await listMissingThumbnails(client);
+
+        // Should still be 2, not 4 (each file checked only once)
+        expect(missing.length).toBe(2);
+    });
+});
+
+describe("fixMissingThumbnails", () => {
+    it("downloads original, generates thumbnail, encrypts, uploads, and registers", async () => {
+        const fixMock = await buildThumbMock();
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildThumbFetch(fixMock) },
+        });
+
+        const results = await fixMissingThumbnails(client, [101]);
+
+        expect(results.length).toBe(1);
+        expect(results[0]!.success).toBe(true);
+        expect(results[0]!.fileID).toBe(101);
+        expect(results[0]!.title).toBe("file-101.jpg");
+        expect(results[0]!.collection).toBe("Photos");
+
+        // Verify the uploaded thumbnail was registered
+        expect(fixMock.uploadedThumbnails.length).toBe(1);
+        const upload = fixMock.uploadedThumbnails[0]!;
+        expect(upload.fileID).toBe(101);
+        expect(upload.objectKey).toContain("42/");
+        expect(upload.decryptionHeader.length).toBeGreaterThan(0);
+
+        // Verify the uploaded ciphertext can be decrypted back to a JPEG
+        const fileKey = fixMock.fileKeys[101]!;
+        const decrypted = decryptBlob(
+            upload.ciphertext,
+            fromBase64(upload.decryptionHeader),
+            fileKey,
+        );
+        // JPEG magic bytes: FF D8 FF
+        expect(decrypted[0]).toBe(0xff);
+        expect(decrypted[1]).toBe(0xd8);
+        expect(decrypted[2]).toBe(0xff);
+        // Verify jpeg-js produced a reasonably sized thumbnail
+        expect(decrypted.length).toBeGreaterThan(100);
+        expect(decrypted.length).toBeLessThan(50000);
+    });
+
+    it("reports failure for nonexistent file IDs without crashing", async () => {
+        const fixMock = await buildThumbMock();
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildThumbFetch(fixMock) },
+        });
+
+        const results = await fixMissingThumbnails(client, [999]);
+
+        expect(results.length).toBe(1);
+        expect(results[0]!.success).toBe(false);
+        expect(results[0]!.fileID).toBe(999);
+        expect(results[0]!.error).toContain("not found");
+    });
+
+    it("continues after one file fails and reports mixed results", async () => {
+        const fixMock = await buildThumbMock();
+        // Make file 102 fail by removing its ciphertext so download fails
+        delete fixMock.fileCiphertexts[102];
+
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildThumbFetch(fixMock) },
+        });
+
+        const results = await fixMissingThumbnails(client, [101, 102]);
+
+        expect(results.length).toBe(2);
+        const success = results.find((r) => r.fileID === 101)!;
+        const failure = results.find((r) => r.fileID === 102)!;
+        expect(success.success).toBe(true);
+        expect(failure.success).toBe(false);
+    });
+});
+
+describe("Client.getApiClient", () => {
+    it("returns the ApiClient when logged in", async () => {
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildThumbFetch(mock) },
+        });
+
+        const api = client.getApiClient();
+        expect(api).toBeDefined();
+        expect(typeof api.getJSON).toBe("function");
+    });
+
+    it("throws after logout", async () => {
+        const client = await Client.login({
+            email: TEST_EMAIL,
+            password: TEST_PASSWORD,
+            apiOptions: { fetch: buildThumbFetch(mock) },
+        });
+        client.logout();
+
+        expect(() => client.getApiClient()).toThrow(/logged out/);
+    });
+});

yarn.lock

@@ -2,13 +2,6 @@
 # yarn lockfile v1
 
 
-"@emnapi/runtime@^1.7.0":
-  version "1.10.0"
-  resolved "https://registry.yarnpkg.com/@emnapi/runtime/-/runtime-1.10.0.tgz#4b260c0d3534204e98c6110b8db1a987d26ec87c"
-  integrity sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==
-  dependencies:
-    tslib "^2.4.0"
-
 "@esbuild/aix-ppc64@0.21.5":
   version "0.21.5"
   resolved "https://registry.yarnpkg.com/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz#c7184a326533fcdf1b8ee0733e21c713b975575f"
@@ -230,152 +223,144 @@
   resolved "https://registry.yarnpkg.com/@humanwhocodes/retry/-/retry-0.4.3.tgz#c2b9d2e374ee62c586d3adbea87199b1d7a7a6ba"
   integrity sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==
 
-"@img/colour@^1.0.0":
-  version "1.1.0"
-  resolved "https://registry.yarnpkg.com/@img/colour/-/colour-1.1.0.tgz#b0c2c2fa661adf75effd6b4964497cd80010bb9d"
-  integrity sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==
+"@inquirer/ansi@^2.0.7":
+  version "2.0.7"
+  resolved "https://registry.yarnpkg.com/@inquirer/ansi/-/ansi-2.0.7.tgz#86de22810cac3ed406ec10f8d66016815b8226b4"
+  integrity sha512-3eTuUO1vH2cZm2ZKHeQxnOqlTi9EfZDGgIe3BL3I4u+rJHocr9Fz86M4fjYABPvFnQG/gGK551HqDiIcETwU6Q==
 
-"@img/sharp-darwin-arm64@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.5.tgz#6e0732dcade126b6670af7aa17060b926835ea86"
-  integrity sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==
-  optionalDependencies:
-    "@img/sharp-libvips-darwin-arm64" "1.2.4"
-
-"@img/sharp-darwin-x64@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.5.tgz#19bc1dd6eba6d5a96283498b9c9f401180ee9c7b"
-  integrity sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==
-  optionalDependencies:
-    "@img/sharp-libvips-darwin-x64" "1.2.4"
-
-"@img/sharp-libvips-darwin-arm64@1.2.4":
-  version "1.2.4"
-  resolved "https://registry.yarnpkg.com/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.2.4.tgz#2894c0cb87d42276c3889942e8e2db517a492c43"
-  integrity sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==
-
-"@img/sharp-libvips-darwin-x64@1.2.4":
-  version "1.2.4"
-  resolved "https://registry.yarnpkg.com/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.4.tgz#e63681f4539a94af9cd17246ed8881734386f8cc"
-  integrity sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==
-
-"@img/sharp-libvips-linux-arm64@1.2.4":
-  version "1.2.4"
-  resolved "https://registry.yarnpkg.com/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.4.tgz#b1b288b36864b3bce545ad91fa6dadcf1a4ad318"
-  integrity sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==
-
-"@img/sharp-libvips-linux-arm@1.2.4":
-  version "1.2.4"
-  resolved "https://registry.yarnpkg.com/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.4.tgz#b9260dd1ebe6f9e3bdbcbdcac9d2ac125f35852d"
-  integrity sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==
-
-"@img/sharp-libvips-linux-ppc64@1.2.4":
-  version "1.2.4"
-  resolved "https://registry.yarnpkg.com/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.4.tgz#4b83ecf2a829057222b38848c7b022e7b4d07aa7"
-  integrity sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==
-
-"@img/sharp-libvips-linux-riscv64@1.2.4":
-  version "1.2.4"
-  resolved "https://registry.yarnpkg.com/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.2.4.tgz#880b4678009e5a2080af192332b00b0aaf8a48de"
-  integrity sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==
-
-"@img/sharp-libvips-linux-s390x@1.2.4":
-  version "1.2.4"
-  resolved "https://registry.yarnpkg.com/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.2.4.tgz#74f343c8e10fad821b38f75ced30488939dc59ec"
-  integrity sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==
-
-"@img/sharp-libvips-linux-x64@1.2.4":
-  version "1.2.4"
-  resolved "https://registry.yarnpkg.com/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.4.tgz#df4183e8bd8410f7d61b66859a35edeab0a531ce"
-  integrity sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==
-
-"@img/sharp-libvips-linuxmusl-arm64@1.2.4":
-  version "1.2.4"
-  resolved "https://registry.yarnpkg.com/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.4.tgz#c8d6b48211df67137541007ee8d1b7b1f8ca8e06"
-  integrity sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==
-
-"@img/sharp-libvips-linuxmusl-x64@1.2.4":
-  version "1.2.4"
-  resolved "https://registry.yarnpkg.com/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.4.tgz#be11c75bee5b080cbee31a153a8779448f919f75"
-  integrity sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==
-
-"@img/sharp-linux-arm64@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.5.tgz#7aa7764ef9c001f15e610546d42fce56911790cc"
-  integrity sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==
-  optionalDependencies:
-    "@img/sharp-libvips-linux-arm64" "1.2.4"
-
-"@img/sharp-linux-arm@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.5.tgz#5fb0c3695dd12522d39c3ff7a6bc816461780a0d"
-  integrity sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==
-  optionalDependencies:
-    "@img/sharp-libvips-linux-arm" "1.2.4"
-
-"@img/sharp-linux-ppc64@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.34.5.tgz#9c213a81520a20caf66978f3d4c07456ff2e0813"
-  integrity sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==
-  optionalDependencies:
-    "@img/sharp-libvips-linux-ppc64" "1.2.4"
-
-"@img/sharp-linux-riscv64@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.34.5.tgz#cdd28182774eadbe04f62675a16aabbccb833f60"
-  integrity sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==
-  optionalDependencies:
-    "@img/sharp-libvips-linux-riscv64" "1.2.4"
-
-"@img/sharp-linux-s390x@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.5.tgz#93eac601b9f329bb27917e0e19098c722d630df7"
-  integrity sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==
-  optionalDependencies:
-    "@img/sharp-libvips-linux-s390x" "1.2.4"
-
-"@img/sharp-linux-x64@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.5.tgz#55abc7cd754ffca5002b6c2b719abdfc846819a8"
-  integrity sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==
-  optionalDependencies:
-    "@img/sharp-libvips-linux-x64" "1.2.4"
-
-"@img/sharp-linuxmusl-arm64@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.5.tgz#d6515ee971bb62f73001a4829b9d865a11b77086"
-  integrity sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==
-  optionalDependencies:
-    "@img/sharp-libvips-linuxmusl-arm64" "1.2.4"
-
-"@img/sharp-linuxmusl-x64@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.5.tgz#d97978aec7c5212f999714f2f5b736457e12ee9f"
-  integrity sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==
-  optionalDependencies:
-    "@img/sharp-libvips-linuxmusl-x64" "1.2.4"
-
-"@img/sharp-wasm32@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-wasm32/-/sharp-wasm32-0.34.5.tgz#2f15803aa626f8c59dd7c9d0bbc766f1ab52cfa0"
-  integrity sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==
+"@inquirer/checkbox@^5.2.1":
+  version "5.2.1"
+  resolved "https://registry.yarnpkg.com/@inquirer/checkbox/-/checkbox-5.2.1.tgz#7f148b3153a776cee202015b10f9a985068d188d"
+  integrity sha512-b6xmA/VlTe0ZgDQHDui+Nav470u7u49nRd8/iuhOcQPO9Ch7lGuogydhi2VOmNlZ+zXcM8IcPuNSwQcdJaF/kw==
   dependencies:
-    "@emnapi/runtime" "^1.7.0"
+    "@inquirer/ansi" "^2.0.7"
+    "@inquirer/core" "^11.2.1"
+    "@inquirer/figures" "^2.0.7"
+    "@inquirer/type" "^4.0.7"
 
-"@img/sharp-win32-arm64@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.5.tgz#3706e9e3ac35fddfc1c87f94e849f1b75307ce0a"
-  integrity sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==
+"@inquirer/confirm@^6.1.1":
+  version "6.1.1"
+  resolved "https://registry.yarnpkg.com/@inquirer/confirm/-/confirm-6.1.1.tgz#9c6a7d79c6132b2af57fdb75747f056204e55356"
+  integrity sha512-eb8DBZcz/2qHWQda4rk2JiQk5h9QV/cVHi1yjt0f69WFZMRFn0sJTye3EAP8icut8UDMjQPsaH5KbcOogefrFQ==
+  dependencies:
+    "@inquirer/core" "^11.2.1"
+    "@inquirer/type" "^4.0.7"
 
-"@img/sharp-win32-ia32@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.5.tgz#0b71166599b049e032f085fb9263e02f4e4788de"
-  integrity sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==
+"@inquirer/core@^11.2.1":
+  version "11.2.1"
+  resolved "https://registry.yarnpkg.com/@inquirer/core/-/core-11.2.1.tgz#54ccd8f7d47852140b6066cbd77d63b2c2b168fd"
+  integrity sha512-Qd6GJT1yVyrZZCfN8W2qKF5ApmqryXRhRKCuip8h01x2w/esJQ2XIYc6f9abMIHgKQdBfFTSOdbHRLAhuM09UA==
+  dependencies:
+    "@inquirer/ansi" "^2.0.7"
+    "@inquirer/figures" "^2.0.7"
+    "@inquirer/type" "^4.0.7"
+    cli-width "^4.1.0"
+    fast-wrap-ansi "^0.2.0"
+    mute-stream "^3.0.0"
+    signal-exit "^4.1.0"
 
-"@img/sharp-win32-x64@0.34.5":
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.5.tgz#a81ffb00e69267cd0a1d626eaedb8a8430b2b2f8"
-  integrity sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==
+"@inquirer/editor@^5.2.2":
+  version "5.2.2"
+  resolved "https://registry.yarnpkg.com/@inquirer/editor/-/editor-5.2.2.tgz#7c73e2fc0e7bd4c40cfd38a180ae5bbd24d32b90"
+  integrity sha512-ZRVd/oD+sYsUd5zVm0NflqEzlqfYCyHNsqkHl2oWXEUHs12tCbcSFi+wVFEvD8+LGRaMUsVrE7qeo6lSG/S1Vg==
+  dependencies:
+    "@inquirer/core" "^11.2.1"
+    "@inquirer/external-editor" "^3.0.3"
+    "@inquirer/type" "^4.0.7"
+
+"@inquirer/expand@^5.1.1":
+  version "5.1.1"
+  resolved "https://registry.yarnpkg.com/@inquirer/expand/-/expand-5.1.1.tgz#e2afeac247d97dd64ee18aa81e902bdd1fe0ea70"
+  integrity sha512-YmQpenjbFSHAK3sOd44puHh3V1KXXr+JiNpUztoSQ4drLh2rTVzTap/YtlAVu/5xavifIlBfNEzJ/neZJ1a/1g==
+  dependencies:
+    "@inquirer/core" "^11.2.1"
+    "@inquirer/type" "^4.0.7"
+
+"@inquirer/external-editor@^3.0.3":
+  version "3.0.3"
+  resolved "https://registry.yarnpkg.com/@inquirer/external-editor/-/external-editor-3.0.3.tgz#d79e772542cf8d340642e9dabd3a1ea7f5a30104"
+  integrity sha512-6thf5I8q7lZwzGLAxPaaGEREEkZ3nyePPDQ1oyobblxmEE8mqTLguScP7pDjUTAibiyb4hfXl+qjUEJ+di/aNA==
+  dependencies:
+    chardet "^2.1.1"
+    iconv-lite "^0.7.2"
+
+"@inquirer/figures@^2.0.7":
+  version "2.0.7"
+  resolved "https://registry.yarnpkg.com/@inquirer/figures/-/figures-2.0.7.tgz#f5cc5843732a81304d06a0db4b53cc7dbda15541"
+  integrity sha512-aJ8TBPOGB6f/2qziPfElISTCEd5XOYTFckA2SGjhNmiKzfK/u4ot3v0DUzGVdUnKjN10EqnnEPck36BkyfLnJw==
+
+"@inquirer/input@^5.1.2":
+  version "5.1.2"
+  resolved "https://registry.yarnpkg.com/@inquirer/input/-/input-5.1.2.tgz#9305cb170dfc3a5323e5eac885a945e7cddd5c4b"
+  integrity sha512-9K/DDBSQpOyZSkt6sOVP9Vo0TR7atX2kuILsUu0x3wVcVbe97lJwIJKMLdMw25tDYuXl/qp6erT0Xs1rfmcfZg==
+  dependencies:
+    "@inquirer/core" "^11.2.1"
+    "@inquirer/type" "^4.0.7"
+
+"@inquirer/number@^4.1.1":
+  version "4.1.1"
+  resolved "https://registry.yarnpkg.com/@inquirer/number/-/number-4.1.1.tgz#b133668d8e0e099b4133abb915221501e0ff75d7"
+  integrity sha512-XF4IXAbPnGPgw0wsbC/i2tPcyfdZgDpUlhsqU0SfT4IRIGWha6Xm9VRgN5yYxJq+jnyXlfXI/nQ3ulfk0iEICA==
+  dependencies:
+    "@inquirer/core" "^11.2.1"
+    "@inquirer/type" "^4.0.7"
+
+"@inquirer/password@^5.1.1":
+  version "5.1.1"
+  resolved "https://registry.yarnpkg.com/@inquirer/password/-/password-5.1.1.tgz#f21efb614da9c905095262f51781fd2a721fceac"
+  integrity sha512-3XBfF7DAsp5qeDsvN5Rd1HmbNokVvEQoUM0QLrRcybC9nX96w3Pbmu7qUsb3IT3J3jBvs2+mTXaKHOUsgHMLzg==
+  dependencies:
+    "@inquirer/ansi" "^2.0.7"
+    "@inquirer/core" "^11.2.1"
+    "@inquirer/type" "^4.0.7"
+
+"@inquirer/prompts@8.5.2":
+  version "8.5.2"
+  resolved "https://registry.yarnpkg.com/@inquirer/prompts/-/prompts-8.5.2.tgz#09c0132ada2bbba94c91d341115e1e41cb3f1525"
+  integrity sha512-IYR/3C/paEVVQYQvdDlFZVjRCJVYHHON0XXMH91KO9GSxs0TdKYWlUdvfQl2EfAHDxUaN3IBffkE/BDTh5nJ6g==
+  dependencies:
+    "@inquirer/checkbox" "^5.2.1"
+    "@inquirer/confirm" "^6.1.1"
+    "@inquirer/editor" "^5.2.2"
+    "@inquirer/expand" "^5.1.1"
+    "@inquirer/input" "^5.1.2"
+    "@inquirer/number" "^4.1.1"
+    "@inquirer/password" "^5.1.1"
+    "@inquirer/rawlist" "^5.3.1"
+    "@inquirer/search" "^4.2.1"
+    "@inquirer/select" "^5.2.1"
+
+"@inquirer/rawlist@^5.3.1":
+  version "5.3.1"
+  resolved "https://registry.yarnpkg.com/@inquirer/rawlist/-/rawlist-5.3.1.tgz#66f6b8e6aa82d47399c433b8262128e7c1a4f9ce"
+  integrity sha512-QqdTqQddL3qPX/PPrjobpsO25NZ4dWXgTLenrR445L2ptLEYE6Z+PD5c5CNDJNx4ugRgELAIpSIJxZaO2jJ2Og==
+  dependencies:
+    "@inquirer/core" "^11.2.1"
+    "@inquirer/type" "^4.0.7"
+
+"@inquirer/search@^4.2.1":
+  version "4.2.1"
+  resolved "https://registry.yarnpkg.com/@inquirer/search/-/search-4.2.1.tgz#c8f4b78ab3f866fdf0503fac0cd08c4a6661c11e"
+  integrity sha512-xJj8QWKRSrfKoBIITLZK61dD3zwo0Rz11fgDImku30/Oe81zMdIdGgrLY2h6RkJ+KZ/GhNYIRMKnH/62qBTA5g==
+  dependencies:
+    "@inquirer/core" "^11.2.1"
+    "@inquirer/figures" "^2.0.7"
+    "@inquirer/type" "^4.0.7"
+
+"@inquirer/select@^5.2.1":
+  version "5.2.1"
+  resolved "https://registry.yarnpkg.com/@inquirer/select/-/select-5.2.1.tgz#3a05e76e58d9e1bb095e912c3e7093aa04cd4604"
+  integrity sha512-FlDndEUww8m7BfukO2nJa25vhD+H5jxxCv4oGioKqzyWz3nPHhhw4LKdYRSlXuAx7DsdWia7iyaBPKKS95Evfw==
+  dependencies:
+    "@inquirer/ansi" "^2.0.7"
+    "@inquirer/core" "^11.2.1"
+    "@inquirer/figures" "^2.0.7"
+    "@inquirer/type" "^4.0.7"
+
+"@inquirer/type@^4.0.7":
+  version "4.0.7"
+  resolved "https://registry.yarnpkg.com/@inquirer/type/-/type-4.0.7.tgz#9c6f0d857fe6ad549a3a932343b64e76acb34b10"
+  integrity sha512-t28inv14nMQ1PhKpsJPY+kEs/c00qzeCOS2gTNRyTjG5d6qsVA2fItxW4hkvGZ5lvanGLdtCzVIx5dwdRpN1+g==
 
 "@jridgewell/sourcemap-codec@^1.5.5":
   version "1.5.5"
@@ -557,13 +542,6 @@
   dependencies:
     undici-types "~6.21.0"
 
-"@types/sharp@^0.32.0":
-  version "0.32.0"
-  resolved "https://registry.yarnpkg.com/@types/sharp/-/sharp-0.32.0.tgz#fc3ac6df6b456319bae807c3d24efdc6631cdd6f"
-  integrity sha512-OOi3kL+FZDnPhVzsfD37J88FNeZh6gQsGcLc95NbeURRGvmSjeXiDcyWzF2o3yh/gQAUn2uhh/e+CPCa5nwAxw==
-  dependencies:
-    sharp "*"
-
 "@typescript-eslint/eslint-plugin@8.46.2":
   version "8.46.2"
   resolved "https://registry.yarnpkg.com/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.46.2.tgz#dc4ab93ee3d7e6c8e38820a0d6c7c93c7183e2dc"
@@ -824,11 +802,21 @@ chalk@^4.0.0:
     ansi-styles "^4.1.0"
     supports-color "^7.1.0"
 
+chardet@^2.1.1:
+  version "2.1.1"
+  resolved "https://registry.yarnpkg.com/chardet/-/chardet-2.1.1.tgz#5c75593704a642f71ee53717df234031e65373c8"
+  integrity sha512-PsezH1rqdV9VvyNhxxOW32/d75r01NY7TQCmOqomRo15ZSOKbpTFVsfjghxo6JloQUCGnH4k1LGu0R4yCLlWQQ==
+
 check-error@^2.1.1:
   version "2.1.3"
   resolved "https://registry.yarnpkg.com/check-error/-/check-error-2.1.3.tgz#2427361117b70cca8dc89680ead32b157019caf5"
   integrity sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA==
 
+cli-width@^4.1.0:
+  version "4.1.0"
+  resolved "https://registry.yarnpkg.com/cli-width/-/cli-width-4.1.0.tgz#42daac41d3c254ef38ad8ac037672130173691c5"
+  integrity sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ==
+
 color-convert@^2.0.1:
   version "2.0.1"
   resolved "https://registry.yarnpkg.com/color-convert/-/color-convert-2.0.1.tgz#72d3a68d598c9bdb3af2ad1e84f21d896abd4de3"
@@ -877,11 +865,6 @@ deep-is@^0.1.3:
   resolved "https://registry.yarnpkg.com/deep-is/-/deep-is-0.1.4.tgz#a6f2dce612fadd2ef1f519b73551f17e85199831"
   integrity sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==
 
-detect-libc@^2.1.2:
-  version "2.1.2"
-  resolved "https://registry.yarnpkg.com/detect-libc/-/detect-libc-2.1.2.tgz#689c5dcdc1900ef5583a4cb9f6d7b473742074ad"
-  integrity sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==
-
 env-paths@4.0.0:
   version "4.0.0"
   resolved "https://registry.yarnpkg.com/env-paths/-/env-paths-4.0.0.tgz#d0bb1f84a81d2542581bf7b7e8085d0683b39097"
@@ -1026,6 +1009,11 @@ esutils@^2.0.2:
   resolved "https://registry.yarnpkg.com/esutils/-/esutils-2.0.3.tgz#74d2eb4de0b8da1293711910d50775b9b710ef64"
   integrity sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==
 
+exif-reader@2.0.3:
+  version "2.0.3"
+  resolved "https://registry.yarnpkg.com/exif-reader/-/exif-reader-2.0.3.tgz#259997735080bc6bb959c37b32c60f004ec4391d"
+  integrity sha512-zFbQvguwT9JkqyYhR7pjE1Yn8SagwaGLNRU0Oh14xFa1paSf5Gzxn4gxgk0XhnudI0UIqU+HgnBX93+nva592A==
+
 expect-type@^1.1.0:
   version "1.3.0"
   resolved "https://registry.yarnpkg.com/expect-type/-/expect-type-1.3.0.tgz#0d58ed361877a31bbc4dd6cf71bbfef7faf6bd68"
@@ -1062,6 +1050,25 @@ fast-srp-hap@2.0.4:
   resolved "https://registry.yarnpkg.com/fast-srp-hap/-/fast-srp-hap-2.0.4.tgz#9db296e21a5143951310f99e5a74290106467811"
   integrity sha512-lHRYYaaIbMrhZtsdGTwPN82UbqD9Bv8QfOlKs+Dz6YRnByZifOh93EYmf2iEWFtkOEIqR2IK8cFD0UN5wLIWBQ==
 
+fast-string-truncated-width@^3.0.2:
+  version "3.0.3"
+  resolved "https://registry.yarnpkg.com/fast-string-truncated-width/-/fast-string-truncated-width-3.0.3.tgz#23afe0da67d752ca0727538f1e6967759728ce49"
+  integrity sha512-0jjjIEL6+0jag3l2XWWizO64/aZVtpiGE3t0Zgqxv0DPuxiMjvB3M24fCyhZUO4KomJQPj3LTSUnDP3GpdwC0g==
+
+fast-string-width@^3.0.2:
+  version "3.0.2"
+  resolved "https://registry.yarnpkg.com/fast-string-width/-/fast-string-width-3.0.2.tgz#16dbabb491ce5585b5ecb675b65c165d71688eeb"
+  integrity sha512-gX8LrtNEI5hq8DVUfRQMbr5lpaS4nMIWV+7XEbXk2b8kiQIizgnlr12B4dA3ZEx3308ze0O4Q1R+cHts8kyUJg==
+  dependencies:
+    fast-string-truncated-width "^3.0.2"
+
+fast-wrap-ansi@^0.2.0:
+  version "0.2.2"
+  resolved "https://registry.yarnpkg.com/fast-wrap-ansi/-/fast-wrap-ansi-0.2.2.tgz#95e952a0145bce3f59ad56e179f84c48d4072935"
+  integrity sha512-7F2Fl+TjRSenLqlU3UjSH0iyqopqoZIu7eZVpEirP2g1GtWa2G/ecEmBdgz31+Mxr+ELclgg6sokpSFIQiZ02Q==
+  dependencies:
+    fast-string-width "^3.0.2"
+
 fastq@^1.6.0:
   version "1.20.1"
   resolved "https://registry.yarnpkg.com/fastq/-/fastq-1.20.1.tgz#ca750a10dc925bc8b18839fd203e3ef4b3ced675"
@@ -1138,6 +1145,13 @@ has-flag@^4.0.0:
   resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-4.0.0.tgz#944771fd9c81c81265c4d6941860da06bb59479b"
   integrity sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==
 
+iconv-lite@^0.7.2:
+  version "0.7.2"
+  resolved "https://registry.yarnpkg.com/iconv-lite/-/iconv-lite-0.7.2.tgz#d0bdeac3f12b4835b7359c2ad89c422a4d1cc72e"
+  integrity sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==
+  dependencies:
+    safer-buffer ">= 2.1.2 < 3.0.0"
+
 ignore@^5.2.0:
   version "5.3.2"
   resolved "https://registry.yarnpkg.com/ignore/-/ignore-5.3.2.tgz#3cd40e729f3643fd87cb04e50bf0eb722bc596f5"
@@ -1188,6 +1202,11 @@ isexe@^2.0.0:
   resolved "https://registry.yarnpkg.com/isexe/-/isexe-2.0.0.tgz#e8fbf374dc556ff8947a10dcb0572d633f2cfa10"
   integrity sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==
 
+jpeg-js@0.4.4:
+  version "0.4.4"
+  resolved "https://registry.yarnpkg.com/jpeg-js/-/jpeg-js-0.4.4.tgz#a9f1c6f1f9f0fa80cdb3484ed9635054d28936aa"
+  integrity sha512-WZzeDOEtTOBK4Mdsar0IqEU5sMr3vSV2RqkAIzUEV2BHnUfKGyswWFPFwK5EeDo93K3FohSHbLAjj0s1Wzd+dg==
+
 js-yaml@^4.1.1:
   version "4.1.1"
   resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-4.1.1.tgz#854c292467705b699476e1a2decc0c8a3458806b"
@@ -1293,6 +1312,11 @@ ms@^2.1.3:
   resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.3.tgz#574c8138ce1d2b5861f0b44579dbadd60c6615b2"
   integrity sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==
 
+mute-stream@^3.0.0:
+  version "3.0.0"
+  resolved "https://registry.yarnpkg.com/mute-stream/-/mute-stream-3.0.0.tgz#cd8014dd2acb72e1e91bb67c74f0019e620ba2d1"
+  integrity sha512-dkEJPVvun4FryqBmZ5KhDo0K9iDXAwn08tMLDinNdRBNPcYEDiWYysLcc6k3mjTMlbP9KyylvRpd4wFtwrT9rw==
+
 nanoid@^3.3.11:
   version "3.3.12"
   resolved "https://registry.yarnpkg.com/nanoid/-/nanoid-3.3.12.tgz#ab3d912e217a6d0a514f00a72a16543a28982c05"
@@ -1446,45 +1470,16 @@ run-parallel@^1.1.9:
   dependencies:
     queue-microtask "^1.2.2"
 
-semver@^7.6.0, semver@^7.7.3:
+"safer-buffer@>= 2.1.2 < 3.0.0":
+  version "2.1.2"
+  resolved "https://registry.yarnpkg.com/safer-buffer/-/safer-buffer-2.1.2.tgz#44fa161b0187b9549dd84bb91802f9bd8385cd6a"
+  integrity sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==
+
+semver@^7.6.0:
   version "7.8.0"
   resolved "https://registry.yarnpkg.com/semver/-/semver-7.8.0.tgz#ed0661039fcbcda2ce71f01fa6adbefaa77040df"
   integrity sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==
 
-sharp@*, sharp@^0.34.5:
-  version "0.34.5"
-  resolved "https://registry.yarnpkg.com/sharp/-/sharp-0.34.5.tgz#b6f148e4b8c61f1797bde11a9d1cfebbae2c57b0"
-  integrity sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==
-  dependencies:
-    "@img/colour" "^1.0.0"
-    detect-libc "^2.1.2"
-    semver "^7.7.3"
-  optionalDependencies:
-    "@img/sharp-darwin-arm64" "0.34.5"
-    "@img/sharp-darwin-x64" "0.34.5"
-    "@img/sharp-libvips-darwin-arm64" "1.2.4"
-    "@img/sharp-libvips-darwin-x64" "1.2.4"
-    "@img/sharp-libvips-linux-arm" "1.2.4"
-    "@img/sharp-libvips-linux-arm64" "1.2.4"
-    "@img/sharp-libvips-linux-ppc64" "1.2.4"
-    "@img/sharp-libvips-linux-riscv64" "1.2.4"
-    "@img/sharp-libvips-linux-s390x" "1.2.4"
-    "@img/sharp-libvips-linux-x64" "1.2.4"
-    "@img/sharp-libvips-linuxmusl-arm64" "1.2.4"
-    "@img/sharp-libvips-linuxmusl-x64" "1.2.4"
-    "@img/sharp-linux-arm" "0.34.5"
-    "@img/sharp-linux-arm64" "0.34.5"
-    "@img/sharp-linux-ppc64" "0.34.5"
-    "@img/sharp-linux-riscv64" "0.34.5"
-    "@img/sharp-linux-s390x" "0.34.5"
-    "@img/sharp-linux-x64" "0.34.5"
-    "@img/sharp-linuxmusl-arm64" "0.34.5"
-    "@img/sharp-linuxmusl-x64" "0.34.5"
-    "@img/sharp-wasm32" "0.34.5"
-    "@img/sharp-win32-arm64" "0.34.5"
-    "@img/sharp-win32-ia32" "0.34.5"
-    "@img/sharp-win32-x64" "0.34.5"
-
 shebang-command@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/shebang-command/-/shebang-command-2.0.0.tgz#ccd0af4f8835fbdc265b82461aaf0c36663f34ea"
@@ -1502,6 +1497,11 @@ siginfo@^2.0.0:
   resolved "https://registry.yarnpkg.com/siginfo/-/siginfo-2.0.0.tgz#32e76c70b79724e3bb567cb9d543eb858ccfaf30"
   integrity sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==
 
+signal-exit@^4.1.0:
+  version "4.1.0"
+  resolved "https://registry.yarnpkg.com/signal-exit/-/signal-exit-4.1.0.tgz#952188c1cbd546070e2dd20d0f41c0ae0530cb04"
+  integrity sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==
+
 source-map-js@^1.2.1:
   version "1.2.1"
   resolved "https://registry.yarnpkg.com/source-map-js/-/source-map-js-1.2.1.tgz#1ce5650fddd87abc099eda37dcff024c2667ae46"
@@ -1566,11 +1566,6 @@ ts-api-utils@^2.1.0:
   resolved "https://registry.yarnpkg.com/ts-api-utils/-/ts-api-utils-2.5.0.tgz#4acd4a155e22734990a5ed1fe9e97f113bcb37c1"
   integrity sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==
 
-tslib@^2.4.0:
-  version "2.8.1"
-  resolved "https://registry.yarnpkg.com/tslib/-/tslib-2.8.1.tgz#612efe4ed235d567e8aba5f2a5fab70280ade83f"
-  integrity sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==
-
 type-check@^0.4.0, type-check@~0.4.0:
   version "0.4.0"
   resolved "https://registry.yarnpkg.com/type-check/-/type-check-0.4.0.tgz#07b8203bfa7056c0657050e3ccd2c37730bab8f1"