Add quak helper list-missing-thumbnails and fix-missing-thumbnails

list-missing-thumbnails: iterates all files across all collections,
fetches each thumbnail from the CDN, reports any that are missing or
empty. Deduplicates by file ID across collections.

fix-missing-thumbnails: for each missing thumbnail, downloads the
original file, generates a 720px JPEG thumbnail via sharp, encrypts
it with secretstream push (encryptBlob), uploads to a presigned URL,
and registers the new thumbnail via PUT /files/thumbnail.

New crypto: encryptBlob (secretstream push, single chunk TAG_FINAL).
New ApiClient methods: getUploadURL, putFile, putJSON, updateThumbnail.
New Client method: getApiClient() for modules that need raw API access.

Deps: sharp 0.34.5 (image processing), @types/sharp 0.32.0.

src/api/client.ts

@@ -162,6 +162,52 @@ export class ApiClient {
         return resp.body;
     }
 
+    async getUploadURL(
+        contentLength: number,
+        contentMD5: string,
+    ): Promise<{ objectKey: string; url: string }> {
+        return this.postJSON("/files/upload-url", {
+            contentLength,
+            contentMD5,
+        });
+    }
+
+    async putFile(presignedURL: string, data: Uint8Array): Promise<void> {
+        const resp = await this._fetch(presignedURL, {
+            method: "PUT",
+            headers: {
+                "Content-Type": "application/octet-stream",
+                "Content-Length": String(data.length),
+            },
+            body: data,
+        });
+        if (!resp.ok) {
+            throw new Error(`PUT to presigned URL failed: HTTP ${resp.status}`);
+        }
+    }
+
+    async putJSON<T>(path: string, body: unknown): Promise<T> {
+        const url = `${this.apiOrigin}${path}`;
+        const resp = await this._fetch(url, {
+            method: "PUT",
+            headers: this.headers({ "Content-Type": "application/json" }),
+            body: JSON.stringify(body),
+        });
+        await this.throwIfError(resp);
+        return (await resp.json()) as T;
+    }
+
+    async updateThumbnail(
+        fileID: number,
+        objectKey: string,
+        decryptionHeader: string,
+    ): Promise<void> {
+        await this.putJSON("/files/thumbnail", {
+            fileID,
+            thumbnail: { objectKey, decryptionHeader },
+        });
+    }
+
     async getThumbnailStream(
         fileID: number,
     ): Promise<ReadableStream<Uint8Array>> {

src/client.ts

@@ -119,6 +119,11 @@ export class Client {
         );
     }
 
+    getApiClient(): ApiClient {
+        this.assertLoggedIn();
+        return this.api;
+    }
+
     private assertLoggedIn(): void {
         if (this.loggedOut) throw new Error("Client has been logged out");
     }

src/crypto/index.ts

@@ -9,6 +9,7 @@ export { deriveKEK, deriveLoginSubkey } from "./kdf.js";
 export { decryptBox, decryptSealed } from "./box.js";
 export {
     decryptBlob,
+    encryptBlob,
     initStreamPull,
     pullStreamChunk,
     STREAM_CHUNK_OVERHEAD,

src/crypto/stream.ts

@@ -8,6 +8,23 @@ export const STREAM_CHUNK_SIZE = 4 * 1024 * 1024;
 // 16 bytes of Poly1305 tag plus 1 byte of secretstream tag.
 export const STREAM_CHUNK_OVERHEAD = 17;
 
+// Encrypt a small blob as a single secretstream chunk with TAG_FINAL.
+// Returns the header and ciphertext. Used for encrypting thumbnails
+// and metadata before upload.
+export const encryptBlob = (
+    plaintext: Uint8Array,
+    key: Uint8Array,
+): { header: Uint8Array; ciphertext: Uint8Array } => {
+    const push = sodium.crypto_secretstream_xchacha20poly1305_init_push(key);
+    const ciphertext = sodium.crypto_secretstream_xchacha20poly1305_push(
+        push.state,
+        plaintext,
+        null,
+        sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL,
+    );
+    return { header: push.header, ciphertext };
+};
+
 // Opaque handle to libsodium's secretstream pull state. Threaded through
 // successive pullStreamChunk calls.
 export type StreamPullState = sodium.StateAddress;

src/thumbnails.ts

@@ -0,0 +1,183 @@
+import { createHash } from "node:crypto";
+import sharp from "sharp";
+import type { Client } from "./client.js";
+import { encryptBlob, toBase64 } from "./crypto/index.js";
+import { downloadFile } from "./download/index.js";
+import type { EnteFile } from "./model/types.js";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const THUMB_MAX_DIMENSION = 720;
+const THUMB_JPEG_QUALITY = 50;
+
+export interface MissingThumbnailInfo {
+    fileID: number;
+    title: string;
+    collection: string;
+    reason: string;
+}
+
+export interface ThumbnailFixResult {
+    fileID: number;
+    title: string;
+    collection: string;
+    success: boolean;
+    error?: string;
+}
+
+export type ProgressCallback = (message: string) => void;
+
+export const listMissingThumbnails = async (
+    client: Client,
+    onProgress?: ProgressCallback,
+): Promise<MissingThumbnailInfo[]> => {
+    const log = onProgress ?? (() => {});
+    const missing: MissingThumbnailInfo[] = [];
+    const seen = new Set<number>();
+
+    const collections = await client.listCollections();
+    for (const col of collections) {
+        log(`[${col.name}] Checking thumbnails...`);
+        const files = await client.listFiles(col.id, col.key);
+        for (const file of files) {
+            if (seen.has(file.id)) continue;
+            seen.add(file.id);
+            try {
+                const api = client.getApiClient();
+                const stream = await api.getThumbnailStream(file.id);
+                const reader = stream.getReader();
+                let totalBytes = 0;
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (value) totalBytes += value.length;
+                    if (done) break;
+                }
+                if (totalBytes === 0) {
+                    missing.push({
+                        fileID: file.id,
+                        title: file.metadata.title,
+                        collection: col.name,
+                        reason: "empty thumbnail (0 bytes)",
+                    });
+                }
+            } catch {
+                missing.push({
+                    fileID: file.id,
+                    title: file.metadata.title,
+                    collection: col.name,
+                    reason: "thumbnail fetch failed",
+                });
+            }
+        }
+    }
+    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);
+};
+
+export const fixMissingThumbnails = async (
+    client: Client,
+    fileIDs: number[],
+    onProgress?: ProgressCallback,
+): Promise<ThumbnailFixResult[]> => {
+    const log = onProgress ?? (() => {});
+    const results: ThumbnailFixResult[] = [];
+    const api = client.getApiClient();
+
+    const collections = await client.listCollections();
+    const fileMap = new Map<
+        number,
+        { file: EnteFile; collectionName: string }
+    >();
+
+    for (const col of collections) {
+        const files = await client.listFiles(col.id, col.key);
+        for (const file of files) {
+            if (fileIDs.includes(file.id) && !fileMap.has(file.id)) {
+                fileMap.set(file.id, {
+                    file,
+                    collectionName: col.name,
+                });
+            }
+        }
+    }
+
+    for (const fileID of fileIDs) {
+        const entry = fileMap.get(fileID);
+        if (!entry) {
+            results.push({
+                fileID,
+                title: "unknown",
+                collection: "unknown",
+                success: false,
+                error: "file not found in any collection",
+            });
+            continue;
+        }
+
+        const { file, collectionName } = entry;
+        const tmpDir = mkdtempSync(join(tmpdir(), "quak-thumb-"));
+
+        try {
+            log(
+                `[${collectionName}] Downloading ${file.metadata.title} for thumbnail generation...`,
+            );
+            const origPath = join(tmpDir, "original");
+            await downloadFile(api, file, origPath);
+
+            log(
+                `[${collectionName}] Generating thumbnail for ${file.metadata.title}...`,
+            );
+            const thumbJpeg = await generateThumbnail(origPath);
+
+            log(
+                `[${collectionName}] Encrypting and uploading thumbnail (${thumbJpeg.length} bytes)...`,
+            );
+            const { header, ciphertext } = encryptBlob(thumbJpeg, file.key);
+
+            const md5 = createHash("md5").update(ciphertext).digest("base64");
+            const { objectKey, url } = await api.getUploadURL(
+                ciphertext.length,
+                md5,
+            );
+            await api.putFile(url, ciphertext);
+            await api.updateThumbnail(file.id, objectKey, toBase64(header));
+
+            log(
+                `[${collectionName}] Thumbnail uploaded for ${file.metadata.title}`,
+            );
+            results.push({
+                fileID,
+                title: file.metadata.title,
+                collection: collectionName,
+                success: true,
+            });
+        } catch (err) {
+            log(
+                `[${collectionName}] FAILED ${file.metadata.title}: ${err instanceof Error ? err.message : err}`,
+            );
+            results.push({
+                fileID,
+                title: file.metadata.title,
+                collection: collectionName,
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        } finally {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+    }
+
+    return results;
+};