Sanitize file names taken from server metadata (closes #9)

A file title or album name decrypted from server data could name a path
outside the chosen directory (`../../.ssh/authorized_keys`). One module,
src/filename.ts, now makes such names safe for `quak get`/`get-thumb`
without `--out`, downloadFile/downloadThumbnail without outPath, and the
backup and metadata backup trees. Originals-cache extensions are limited to
letters and digits. A user-supplied path is still used as is. decryptFile
reads a missing or non-string title as "" and rejects metadata that is not
a JSON object.

Model: opus-5-5

src/backup.ts

@@ -40,8 +40,9 @@ import {
     symlinkSync,
     writeFileSync,
 } from "node:fs";
-import { basename, dirname, extname, join, relative } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 
+import { safeExtension, sanitizeFileName } from "./filename.js";
 import type { Collection, EnteFile } from "./model/types.js";
 
 export type ProgressCallback = (message: string) => void;
@@ -108,16 +109,11 @@ interface FailureEntry {
 
 const LEDGER_VERSION = 1;
 
-const sanitizePath = (name: string): string =>
-    name.replace(/[/\\:*?"<>|]/g, "_").replace(/^\.+/, "_");
-
 // The originals/ filename for a file: `<id><ext>`, the extension taken from the
 // title (or `.bin`). Matches the content cache's own naming so a present check
 // lines up with what a fetch would write.
-const originalName = (file: EnteFile): string => {
-    const ext = extname(file.metadata.title || "") || ".bin";
-    return `${file.id}${ext}`;
-};
+const originalName = (file: EnteFile): string =>
+    `${file.id}${safeExtension(file.metadata.title)}`;
 
 // A regular file with content is treated as complete. A zero-byte file is not:
 // it is the shape an aborted write leaves and must be re-fetched.
@@ -370,7 +366,7 @@ export const runBackup = async (
 
     // Then the per-collection symlink trees and JSON.
     for (const c of collections) {
-        const colDirName = sanitizePath(c.name || `collection-${c.id}`);
+        const colDirName = sanitizeFileName(c.name, `collection-${c.id}`);
         const colDir = join(collectionsDir, colDirName);
         mkdirSync(colDir, { recursive: true });
 
@@ -381,8 +377,9 @@ export const runBackup = async (
             if (!includeOriginals) continue;
             const orig = join(originalsDir, originalName(file));
             if (!isPresent(orig)) continue;
-            const linkName = sanitizePath(
-                file.metadata.title || `file-${file.id}`,
+            const linkName = sanitizeFileName(
+                file.metadata.title,
+                `file-${file.id}`,
             );
             const linkPath = join(colDir, linkName);
             try {

src/cli-output.ts

@@ -9,6 +9,7 @@
 // `metadata.title`, and issue #52 requires that output stay byte-identical, so
 // the commands shape their output from the raw `EnteFile` through here.
 
+import { sanitizeFileName } from "./filename.js";
 import type { EnteFile, FileType, Microseconds } from "./model/types.js";
 
 // One row of `quak files --json`.
@@ -32,9 +33,11 @@ export const fileListRow = (file: EnteFile): FileListRow => ({
 export const fileListLine = (file: EnteFile): string =>
     `${file.id}\t${file.metadata.fileType}\t${file.metadata.title}`;
 
-// Default output path for `quak get` when `--out` is not given.
-export const originalName = (file: EnteFile): string => file.metadata.title;
+// Default output path for `quak get` when `--out` is not given. The title comes
+// from the server, so it is sanitized; `--out` is the user's and is used as is.
+export const originalName = (file: EnteFile): string =>
+    sanitizeFileName(file.metadata.title, `file-${file.id}`);
 
 // Default output path for `quak get-thumb` when `--out` is not given.
 export const thumbnailName = (file: EnteFile): string =>
-    `thumb_${file.metadata.title}`;
+    `thumb_${originalName(file)}`;

src/download/index.ts

@@ -11,6 +11,7 @@ import {
     streamTagFinal,
 } from "../crypto/index.js";
 import { TruncatedStreamError } from "../errors.js";
+import { sanitizeFileName } from "../filename.js";
 import { withRetry } from "../retry.js";
 import type { ApiClient } from "../api/client.js";
 import type { EnteFile } from "../model/types.js";
@@ -286,7 +287,10 @@ export const downloadFile = async (
     outPath?: string,
     onProgress?: ProgressCallback,
 ): Promise<DownloadResult> => {
-    const resolvedPath = outPath ?? file.metadata.title;
+    // `outPath` is the caller's and is used as is; the title is the server's
+    // and is sanitized so it can only name a file in the current directory.
+    const resolvedPath =
+        outPath ?? sanitizeFileName(file.metadata.title, `file-${file.id}`);
     const header = fromBase64(file.file.decryptionHeader);
     const bytesWritten = await fetchAndDecrypt(
         api,
@@ -305,7 +309,9 @@ export const downloadThumbnail = async (
     outPath?: string,
     onProgress?: ProgressCallback,
 ): Promise<DownloadResult> => {
-    const resolvedPath = outPath ?? `thumb_${file.metadata.title}`;
+    const resolvedPath =
+        outPath ??
+        `thumb_${sanitizeFileName(file.metadata.title, `file-${file.id}`)}`;
     const header = fromBase64(file.thumbnail.decryptionHeader);
     const bytesWritten = await fetchAndDecrypt(
         api,

src/filename.ts

@@ -0,0 +1,37 @@
+// File names built from server-supplied metadata.
+//
+// A file's title and a collection's name are decrypted from data the server
+// hands us, and quak does not trust the server. Any name taken from them and
+// used on disk goes through here, so it can only ever name one file inside the
+// directory the caller chose: never a path, never `..`, never hidden, never a
+// Windows device name.
+//
+// A path the user typed (`--out`, `outPath`) is not passed through here: the
+// caller is trusted, the server is not.
+
+import { extname } from "node:path";
+
+// Path separators, characters Windows forbids in file names, and control
+// characters (NUL included).
+// eslint-disable-next-line no-control-regex
+const UNSAFE_CHARACTERS = /[/\\:*?"<>|\x00-\x1f\x7f]/g;
+
+// Names Windows reserves for devices, with or without an extension.
+const RESERVED_DEVICE_NAME = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\.|$)/i;
+
+// `name` made safe to use as a single file name. Each unsafe character becomes
+// `_`, a leading run of dots becomes one `_`, and a device name gets a leading
+// `_`. A name with none of these comes back unchanged. An empty name becomes
+// `fallback`, which the caller derives from the record's ID.
+export const sanitizeFileName = (name: string, fallback: string): string => {
+    if (name === "") return fallback;
+    const cleaned = name.replace(UNSAFE_CHARACTERS, "_").replace(/^\.+/, "_");
+    return RESERVED_DEVICE_NAME.test(cleaned) ? `_${cleaned}` : cleaned;
+};
+
+// The extension of `title` (".jpg"), or ".bin" when it has none or it holds
+// anything but letters and digits.
+export const safeExtension = (title: string): string => {
+    const ext = extname(title);
+    return /^\.[A-Za-z0-9]+$/.test(ext) ? ext : ".bin";
+};

src/library/content.ts

@@ -40,6 +40,7 @@ import {
     downloadThumbnail,
     type ProgressCallback,
 } from "../download/index.js";
+import { safeExtension } from "../filename.js";
 import type { EnteFile } from "../model/types.js";
 import type { Priority, RequestPools } from "./pools.js";
 
@@ -209,10 +210,8 @@ class AbortDrop extends Error {
     }
 }
 
-const originalName = (file: EnteFile): string => {
-    const ext = extname(file.metadata.title || "") || ".bin";
-    return `${file.id}${ext}`;
-};
+const originalName = (file: EnteFile): string =>
+    `${file.id}${safeExtension(file.metadata.title)}`;
 
 // The fileID a cache filename encodes, or undefined when the name is not one
 // the cache writes (`<digits><ext>`).

src/metadata-backup.ts

@@ -4,6 +4,7 @@ import * as jpeg from "jpeg-js";
 import exifReader from "exif-reader";
 import type { Client } from "./client.js";
 import type { Library, Photo } from "./library/index.js";
+import { sanitizeFileName } from "./filename.js";
 import { fetchMLData } from "./mldata-fetch.js";
 import type { EnteFile } from "./model/types.js";
 
@@ -14,9 +15,6 @@ export interface MetadataBackupOptions {
     onProgress?: ProgressCallback;
 }
 
-const sanitizePath = (name: string): string =>
-    name.replace(/[/\\:*?"<>|]/g, "_").replace(/^\.+/, "_");
-
 // 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.
@@ -151,7 +149,7 @@ export const runMetadataBackup = async (
         const col = lib.getCollection(album.collectionID);
         if (!col) continue;
 
-        const dirName = `${col.id}-${sanitizePath(col.name || "unnamed")}`;
+        const dirName = `${col.id}-${sanitizeFileName(col.name, "unnamed")}`;
         const colDir = join(outDir, "collections", dirName);
         mkdirSync(colDir, { recursive: true });
 

src/model/decrypt.ts

@@ -98,9 +98,18 @@ export const decryptFile = (
         key,
     );
     const metadataJSON = JSON.parse(new TextDecoder().decode(metadataBytes));
+    if (
+        typeof metadataJSON !== "object" ||
+        metadataJSON === null ||
+        Array.isArray(metadataJSON)
+    ) {
+        throw new Error(`file ${raw.id}: metadata is not a JSON object`);
+    }
 
     const metadata: FileMetadata = {
-        title: metadataJSON.title ?? "",
+        // The server controls this JSON: a title that is missing or not a
+        // string becomes "", never an arbitrary value.
+        title: typeof metadataJSON.title === "string" ? metadataJSON.title : "",
         fileType: parseFileType(metadataJSON.fileType ?? -1),
         creationTime: metadataJSON.creationTime ?? 0,
         modificationTime: metadataJSON.modificationTime ?? 0,