Carry file size, thumbnail size, and deletion flag through decryptFile (closes #37)

Foundation unit for the cache/API design. Three fields arrived on the wire
but decryptFile dropped them:

- Live files now set `file.size` from `info.fileSize` and `thumbnail.size`
  from `info.thumbSize`, left `undefined` when the server omits `info`.
- A deleted file is returned as a new `EnteFileTombstone` (`id`,
  `collectionID`, `updationTime`, `isDeleted: true`) with no decryption,
  since the server no longer holds ciphertext for it.

decryptFile now returns `EnteFile | EnteFileTombstone`. Rather than making
EnteFile's structural fields optional — which would force `?.`/guards across
every consumer under strict tsc and break the build — a tombstone is a
distinct minimal type, and `EnteFile.isDeleted?: false` is the discriminant
(a live file is never deleted). This keeps all existing consumers untouched;
they still receive fully-populated `EnteFile` values.

client.ts is the only direct caller: it now routes every row through
decryptFile and drops results whose `isDeleted` is set. listFiles still
returns live files only, so its observable behaviour is unchanged.

Model: opus-4-8

TODO.md

@@ -21,10 +21,9 @@ Update the README API reference section to match the current implementation.
 - 2026-09-22: Carried file size, thumbnail size, and the deletion flag through
   `decryptFile` (issue 37, foundation for the cache/API design). Live files now
   populate `file.size`/`thumbnail.size` from the server's `info` (left
-  `undefined` when the server omits it), and `isDeleted` is carried from the
-  diff row onto `EnteFile`. No caller change: `listFiles` still filters deleted
-  rows before decrypting. Surfacing a tombstone through decryption belongs to
-  the enumeration unit (issue 38).
+  `undefined` when the server omits it), and a deleted file returns an
+  `EnteFileTombstone` — `id`, `collectionID`, `updationTime`, `isDeleted` —
+  instead of decrypting ciphertext the server no longer holds.
 - 2026-08-10: Made `lint-once.test.ts` enforce what its header claims. It walked
   `make check` only, so it never read `Dockerfile` — the image CI builds through
   `script/cibuild` — and a second `prettier --check .` could be added there with

src/client.ts

@@ -186,8 +186,11 @@ export class Client {
             }>("/collections/v2/diff", { collectionID, sinceTime });
 
             for (const raw of diff) {
-                if (!raw.isDeleted) {
-                    allFiles.push(decryptFile(raw, collectionKey));
+                // decryptFile returns a tombstone for a deleted file; the
+                // diff keeps returning those, so drop them from the listing.
+                const file = decryptFile(raw, collectionKey);
+                if (!file.isDeleted) {
+                    allFiles.push(file);
                 }
                 if (raw.updationTime > sinceTime) {
                     sinceTime = raw.updationTime;

src/index.ts

@@ -39,6 +39,7 @@ export type {
     Collection,
     CollectionType,
     EnteFile,
+    EnteFileTombstone,
     FileBlob,
     FileMetadata,
     FileType,

src/model/decrypt.ts

@@ -8,6 +8,7 @@ import type {
     Collection,
     CollectionType,
     EnteFile,
+    EnteFileTombstone,
     FileMetadata,
     FileType,
     KeyMaterial,
@@ -83,7 +84,18 @@ export const decryptCollection = (
 export const decryptFile = (
     raw: RawEnteFile,
     collectionKey: Uint8Array,
-): EnteFile => {
+): EnteFile | EnteFileTombstone => {
+    // A deleted file has no ciphertext to decrypt; return the identity and
+    // the flag, and touch none of the encrypted fields.
+    if (raw.isDeleted) {
+        return {
+            id: raw.id,
+            collectionID: raw.collectionID,
+            updationTime: raw.updationTime,
+            isDeleted: true,
+        };
+    }
+
     const key = decryptBox(
         fromBase64(raw.encryptedKey),
         fromBase64(raw.keyDecryptionNonce),
@@ -129,7 +141,6 @@ export const decryptFile = (
             size: raw.info?.thumbSize,
         },
         updationTime: raw.updationTime,
-        isDeleted: raw.isDeleted,
     };
 };
 

src/model/index.ts

@@ -3,6 +3,7 @@ export type {
     Collection,
     CollectionType,
     EnteFile,
+    EnteFileTombstone,
     FileBlob,
     FileMetadata,
     FileType,

src/model/types.ts

@@ -48,9 +48,18 @@ export interface EnteFile {
     file: FileBlob;
     thumbnail: FileBlob;
     updationTime: Microseconds;
-    // Set from the diff row's flag. Live files decode with it absent/false;
-    // deleted rows are filtered out before decryptFile, so it is not set here.
-    isDeleted?: boolean;
+    isDeleted?: false;
+}
+
+// A deleted file as the sync diff reports it. The server keeps returning the
+// row so clients can drop it, but it carries no ciphertext to decrypt, so a
+// tombstone is only an identity plus the flag. isDeleted discriminates it
+// from EnteFile, so callers narrow on that field before reaching for content.
+export interface EnteFileTombstone {
+    id: number;
+    collectionID: number;
+    updationTime: Microseconds;
+    isDeleted: true;
 }
 
 // The key material a logged-in client holds, everything needed to decrypt

test/model/decrypt.test.ts

@@ -196,6 +196,24 @@ const buildRawFile = (
     };
 };
 
+// A deleted file as the sync diff returns it: isDeleted is set and the
+// encrypted payload fields are empty, because the server no longer holds
+// the content to encrypt. Attempting to decrypt these would throw, which
+// is exactly what the tombstone path must avoid. Do not "fix" this fixture
+// by giving it real ciphertext: its emptiness is what the wire sends.
+const buildTombstoneRawFile = (): RawEnteFile => ({
+    id: 201,
+    collectionID: 100,
+    ownerID: 1,
+    encryptedKey: "",
+    keyDecryptionNonce: "",
+    metadata: { encryptedData: "", decryptionHeader: "" },
+    file: { decryptionHeader: "" },
+    thumbnail: { decryptionHeader: "" },
+    updationTime: 1700000000000001,
+    isDeleted: true,
+});
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
@@ -375,6 +393,7 @@ describe("model.decryptFile", () => {
         });
 
         const file = decryptFile(raw, collectionKey);
+        if (file.isDeleted) throw new Error("expected a live file");
 
         expect(file.file.size).toBe(4096);
         expect(file.thumbnail.size).toBe(512);
@@ -389,21 +408,28 @@ describe("model.decryptFile", () => {
         expect(raw.info).toBeUndefined();
 
         const file = decryptFile(raw, collectionKey);
+        if (file.isDeleted) throw new Error("expected a live file");
 
         expect(file.file.size).toBeUndefined();
         expect(file.thumbnail.size).toBeUndefined();
     });
 
-    it("carries the deletion flag from the diff row", () => {
-        // The diff marks a deleted row with isDeleted; decryptFile copies it
-        // onto the file so a caller can tell a deleted row from a live one.
+    it("returns a minimal record for a tombstone without decrypting", () => {
+        // A deleted file arrives with isDeleted set and no usable ciphertext.
+        // decryptFile must skip decryption entirely and return just the
+        // identity plus the flag — decrypting the empty payload would throw.
         const masterKey = sodium.crypto_secretbox_keygen();
         const { collectionKey } = buildRawCollection(masterKey);
-        const raw = buildRawFile(collectionKey);
-        raw.isDeleted = true;
+        const raw = buildTombstoneRawFile();
 
         const file = decryptFile(raw, collectionKey);
 
         expect(file.isDeleted).toBe(true);
+        expect(file.id).toBe(201);
+        expect(file.collectionID).toBe(100);
+        expect(file.updationTime).toBe(1700000000000001);
+        // No decrypted content is carried for a tombstone.
+        expect("metadata" in file).toBe(false);
+        expect("key" in file).toBe(false);
     });
 });