@telecrypt-io/storage 0.5.28 → 0.5.30

package/dist/core/operations.js

@@ -10,12 +10,12 @@
  * config (persistent crypto store, session credentials, etc.) is
  * platform-specific and stays with the caller.
  */
-import { withMatrixMutationAbort, withTreeMutation, } from "../TeleCryptIOStorage.js";
+import { readFileEventMetadata, withMatrixMutationAbort, withTreeMutation, } from "../TeleCryptIOStorage.js";
 import { EventType, MatrixError, RoomCreateTypeField, RoomType, UNSTABLE_MSC3089_BRANCH, UNSTABLE_MSC3088_ENABLED, UNSTABLE_MSC3088_PURPOSE, UNSTABLE_MSC3089_TREE_SUBTYPE, } from "matrix-js-sdk";
 import { ClientPrefix } from "matrix-js-sdk/lib/http-api/prefix.js";
 import { Method } from "matrix-js-sdk/lib/http-api/method.js";
-import { FileTooLargeError, MutationPartialError, MutationOutcomeUnknownError, NonEmptyTreeError, RoomCreationAmbiguousError, RoomCleanupIncompleteError, StorageError, UndecryptableFileError, } from "./errors.js";
-import { waitForCondition } from "./poll.js";
+import { FileTooLargeError, MutationPartialError, MutationOutcomeUnknownError, NonEmptyTreeError, RoomCreationAmbiguousError, RoomCleanupIncompleteError, StorageError, } from "./errors.js";
+import { ConditionTimeoutError, waitForCondition } from "./poll.js";
 import { validateMatrixEventId } from "./constants.js";
 import { validateName } from "./validation.js";
 import { getDeletedTreeIds, isFileDeleted, isTreeDeleted, markFileDeleted, markTreeDeleted, } from "../deletion-markers.js";
@@ -27,14 +27,12 @@ import { getDeletedTreeIds, isFileDeleted, isTreeDeleted, markFileDeleted, markT
  * server-advised backoff. Mirrors the harness library suite's
  * `withRateLimitRetry`; must not mask non-rate-limit failures.
  */
-const RATE_LIMIT_RETRIES = 6;
 const RATE_LIMIT_DEFAULT_DELAY_MS = 15_000;
-const RATE_LIMIT_MAX_DELAY_MS = 30_000;
-const RATE_LIMIT_MAX_TOTAL_DELAY_MS = 90_000;
+// JavaScript timers cannot represent a longer delay reliably. The operation's
+// own deadline remains the authority that stops retrying.
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 const MAX_DELETION_ROOMS = 4096;
 const MAX_DELETION_DEPTH = 128;
-const MAX_FILE_VERSION_CHAIN = 128;
-const MAX_LIST_ITEMS = 10000;
 const DEFAULT_MUTATION_TIMEOUT_MS = 5 * 60_000;
 const MAX_MUTATION_TIMEOUT_MS = 15 * 60_000;
 function createOperationDeadline(options) {
@@ -79,24 +77,17 @@ async function raceOperationDeadline(deadline, pending, kind) {
     finally {
         if (onAbort)
             deadline.signal.removeEventListener("abort", onAbort);
-        void pending.catch(() => undefined);
     }
 }
 async function withOperationDeadline(options, operation, kind = "read") {
     const deadline = createOperationDeadline(options);
-    let pending;
     try {
         ensureOperationActive(deadline.signal);
-        pending = Promise.resolve().then(() => operation(deadline.signal));
+        const pending = Promise.resolve().then(() => operation(deadline.signal));
         return await raceOperationDeadline(deadline, pending, kind);
     }
     finally {
         deadline.close();
-        // A caller-facing deadline must not wait for a broken provider, but the
-        // late result remains observed so an ignored AbortSignal cannot create an
-        // unhandled rejection.
-        if (pending)
-            void pending.catch(() => undefined);
     }
 }
 function isRateLimited(error) {
@@ -107,16 +98,28 @@ function isRateLimited(error) {
     const isRateLimitError = error.isRateLimitError;
     return typeof isRateLimitError === "function" && isRateLimitError.call(error) === true;
 }
+function requiresMutationReconciliation(error) {
+    return (error instanceof MutationOutcomeUnknownError ||
+        error instanceof RoomCreationAmbiguousError ||
+        error instanceof RoomCleanupIncompleteError ||
+        (error instanceof Error &&
+            error.cleanupIncomplete === true));
+}
 async function withRateLimitRetry(operation, signal) {
-    let totalDelay = 0;
-    for (let attempt = 0;; attempt++) {
+    for (;;) {
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
         try {
             return await operation();
         }
         catch (error) {
-            if (!isRateLimited(error) || attempt >= RATE_LIMIT_RETRIES)
+            // A mutation that may have committed, or whose compensating cleanup is
+            // incomplete, must be reconciled by its owner before any retry. A
+            // server rate-limit response does not make repeating room creation safe.
+            if (requiresMutationReconciliation(error)) {
+                throw error;
+            }
+            if (!isRateLimited(error))
                 throw error;
             // The server's retry_after_ms only covers one token; tree operations
             // need several (kick + leave + forget). Wait at least 15s so the
@@ -131,12 +134,7 @@ async function withRateLimitRetry(operation, signal) {
                     }
                 }
             }
-            retryAfter = Math.min(retryAfter, RATE_LIMIT_MAX_DELAY_MS);
-            const remaining = RATE_LIMIT_MAX_TOTAL_DELAY_MS - totalDelay;
-            if (remaining <= 0)
-                throw error;
-            retryAfter = Math.min(retryAfter, remaining);
-            totalDelay += retryAfter;
+            retryAfter = Math.min(retryAfter, MAX_TIMER_DELAY_MS);
             await new Promise((resolve, reject) => {
                 let timer;
                 const onAbort = () => {
@@ -169,10 +167,12 @@ async function resolveTree(storage, treeId, signal) {
             signal,
         });
     }
-    catch {
+    catch (error) {
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
-        throw new StorageError("storage space not found");
+        if (error instanceof ConditionTimeoutError)
+            throw new StorageError("storage space not found");
+        throw new StorageError("storage space lookup failed", { cause: error });
     }
 }
 function isMarkedTreeDeleted(storage, treeId) {
@@ -197,42 +197,13 @@ async function resolveFile(storage, tree, fileId, signal) {
     try {
         return await waitForCondition(() => (isMarkedFileDeleted(storage, tree.id, fileId) ? null : tree.getFile(fileId)), { timeoutMs: 15000, signal });
     }
-    catch {
+    catch (error) {
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
-        throw new StorageError("file not found");
-    }
-}
-function snapshotTreeSpaces(root, tooLargeMessage = "storage tree is too large") {
-    const spaces = [];
-    const seen = new Set();
-    const pending = [{ tree: root, depth: 0 }];
-    while (pending.length > 0) {
-        const next = pending.pop();
-        if (!next)
-            continue;
-        const { tree, depth } = next;
-        if (seen.has(tree.id))
-            continue;
-        if (depth > MAX_DELETION_DEPTH || spaces.length >= MAX_DELETION_ROOMS) {
-            throw new StorageError(tooLargeMessage);
-        }
-        seen.add(tree.id);
-        spaces.push(tree);
-        let children;
-        try {
-            children = tree.getDirectories();
-        }
-        catch {
-            throw new StorageError("could not enumerate storage space descendants safely");
-        }
-        if (children.length > MAX_DELETION_ROOMS) {
-            throw new StorageError(tooLargeMessage);
-        }
-        for (const child of children)
-            pending.push({ tree: child, depth: depth + 1 });
+        if (error instanceof ConditionTimeoutError)
+            throw new StorageError("file not found");
+        throw new StorageError("file lookup failed", { cause: error });
     }
-    return spaces;
 }
 /**
  * Deleting a tree is deliberately a one-room operation.  File versions are
@@ -250,8 +221,8 @@ function assertTreeEmptyForDeletion(storage, tree, spaces) {
             .filter((file) => !isMarkedFileDeleted(storage, tree.id, file.id) &&
             !isConfirmedDeletedFile(storage.getClient(), tree.id, file));
     }
-    catch {
-        throw new StorageError("could not enumerate storage files safely");
+    catch (error) {
+        throw new StorageError("could not enumerate storage files safely", { cause: error });
     }
     if (files.length > 0)
         throw new NonEmptyTreeError(tree.id);
@@ -316,6 +287,62 @@ function isActiveRelationEvent(event) {
         !Array.isArray(content) &&
         Object.keys(content).length > 0);
 }
+function activeTreeDirectories(client, tree) {
+    const childEvents = readRelationEvents(client, tree.id, EventType.SpaceChild);
+    if (childEvents === null)
+        throw new StorageError("delete graph is unsafe");
+    const activeChildIds = new Set();
+    for (const event of childEvents) {
+        if (!isActiveRelationEvent(event))
+            continue;
+        const childId = relationStateKey(event);
+        if (!childId)
+            throw new StorageError("delete graph is unsafe");
+        activeChildIds.add(childId);
+    }
+    const knownChildren = new Map(tree.getDirectories().map((child) => [child.id, child]));
+    return [...activeChildIds].map((childId) => {
+        const child = knownChildren.get(childId);
+        if (!child)
+            throw new StorageError("delete graph is unsafe");
+        return child;
+    });
+}
+function snapshotTreeSpaces(root, tooLargeMessage = "storage tree is too large", activeRelationClient) {
+    const spaces = [];
+    const seen = new Set();
+    const pending = [{ tree: root, depth: 0 }];
+    while (pending.length > 0) {
+        const next = pending.pop();
+        if (!next)
+            continue;
+        const { tree, depth } = next;
+        if (seen.has(tree.id))
+            continue;
+        if (depth > MAX_DELETION_DEPTH || spaces.length >= MAX_DELETION_ROOMS) {
+            throw new StorageError(tooLargeMessage);
+        }
+        seen.add(tree.id);
+        spaces.push(tree);
+        let children;
+        try {
+            children = activeRelationClient
+                ? activeTreeDirectories(activeRelationClient, tree)
+                : tree.getDirectories();
+        }
+        catch (error) {
+            if (error instanceof StorageError)
+                throw error;
+            throw new StorageError("could not enumerate storage space descendants safely", { cause: error });
+        }
+        if (children.length > MAX_DELETION_ROOMS) {
+            throw new StorageError(tooLargeMessage);
+        }
+        for (const child of children)
+            pending.push({ tree: child, depth: depth + 1 });
+    }
+    return spaces;
+}
 /**
  * A deleted MSC3089 branch is represented by an authoritative empty state
  * event. Inactive branches with metadata are historical versions, and a
@@ -356,13 +383,7 @@ function validateDeletionGraph(client, root, ids, deletedRooms) {
         const tree = client.unstableGetFileTreeSpace(id);
         if (!tree)
             throw new StorageError("delete graph is unsafe");
-        let directories;
-        try {
-            directories = tree.getDirectories();
-        }
-        catch {
-            throw new StorageError("delete graph is unsafe");
-        }
+        const directories = activeTreeDirectories(client, tree);
         for (const child of directories)
             addEdge(id, child.id);
         const childEvents = readRelationEvents(client, id, EventType.SpaceChild);
@@ -455,8 +476,10 @@ async function unlinkExternalParents(storage, rootId, externalParents, signal) {
         try {
             await relinkExternalParents(storage, rootId, externalParents, new AbortController().signal);
         }
-        catch {
-            throw new StorageError("delete graph unlink cleanup is incomplete");
+        catch (cleanupError) {
+            throw new StorageError("delete graph unlink cleanup is incomplete", {
+                cause: new AggregateError([error, cleanupError], "delete graph unlink and relink both failed", { cause: error }),
+            });
         }
         throw error;
     }
@@ -554,7 +577,7 @@ async function deleteRoomDeterministically(storage, roomId, signal) {
         if (error instanceof MutationOutcomeUnknownError || error instanceof MutationPartialError)
             throw error;
         if (completedRoomIds.length > 0) {
-            throw new MutationPartialError("delete", completedRoomIds, "room cleanup stopped");
+            throw new MutationPartialError("delete", completedRoomIds, "room cleanup stopped", { cause: error });
         }
         throw error;
     }
@@ -565,14 +588,7 @@ async function deleteRoomDeterministically(storage, roomId, signal) {
  * may otherwise leave a stale invite visible until the next sync.
  */
 function removeRoomFromLocalStore(client, roomId) {
-    try {
-        client.store?.removeRoom(roomId);
-    }
-    catch {
-        // Server-side leave/forget already completed; a store implementation that
-        // cannot evict synchronously must not turn authoritative cleanup into a
-        // false failure.
-    }
+    client.store?.removeRoom(roomId);
 }
 function isActiveMembership(membership) {
     return membership === "join" || membership === "invite";
@@ -582,12 +598,11 @@ function isRevocableMembership(membership) {
 }
 function safePartialDetail(error) {
     // Provider/Matrix errors can contain response bodies, URLs, or credentials.
-    // StorageError messages are authored by this package and are already
-    // bounded; retain those local policy details so callers still get useful
-    // owner/self-target diagnostics.
+    // StorageError messages are authored by this package; retain those local
+    // policy details so callers still get useful owner/self-target diagnostics.
     if (!(error instanceof StorageError) || error instanceof MutationOutcomeUnknownError)
         return undefined;
-    return error.message.length <= 256 ? error.message : undefined;
+    return error.message;
 }
 function toArrayBuffer(bytes) {
     return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
@@ -599,16 +614,12 @@ export async function createVault(storage, name, options) {
             tree = await withRateLimitRetry(() => storage.createTree(name, signal), signal);
         }
         catch (error) {
-            if (error instanceof RoomCleanupIncompleteError ||
-                error instanceof RoomCreationAmbiguousError ||
-                error instanceof MutationOutcomeUnknownError ||
-                (error instanceof Error &&
-                    error.cleanupIncomplete === true)) {
+            if (requiresMutationReconciliation(error)) {
                 throw error;
             }
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("create vault failed");
+            throw new StorageError("create vault failed", { cause: error });
         }
         ensureOperationActive(signal);
         return { id: tree.id, name };
@@ -646,7 +657,7 @@ export async function joinVault(storage, vaultId, options) {
                 membership = null;
             }
             else {
-                throw new StorageError("join failed");
+                throw new StorageError("join failed", { cause: err });
             }
         }
         if (membership === "join")
@@ -664,7 +675,7 @@ export async function joinVault(storage, vaultId, options) {
             }
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("join failed");
+            throw new StorageError("join failed", { cause: err });
         }
         ensureOperationActive(signal);
         return { vaultId, joined: true };
@@ -700,8 +711,6 @@ export async function listPendingInvites(storage, options) {
     return withOperationDeadline(options, async (signal) => {
         const client = storage.getClient();
         const rooms = client.getRooms();
-        if (rooms.length > MAX_LIST_ITEMS)
-            throw new StorageError("invite list is too large");
         const invites = [];
         for (const room of rooms) {
             ensureOperationActive(signal);
@@ -820,7 +829,7 @@ export async function declineInvite(storage, vaultId, options) {
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("decline failed");
+            throw new StorageError("decline failed", { cause: error });
         }
         ensureOperationActive(signal);
         return { vaultId, declined: true };
@@ -893,7 +902,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                 if (error instanceof MutationOutcomeUnknownError)
                     throw error;
                 if (completedRoomIds.size > 0) {
-                    throw new MutationPartialError("share", [...completedRoomIds], safePartialDetail(error));
+                    throw new MutationPartialError("share", [...completedRoomIds], safePartialDetail(error), { cause: error });
                 }
                 if (error instanceof StorageError &&
                     (error.message === "share failed" ||
@@ -902,7 +911,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                         error.message === "operation cancelled")) {
                     throw error;
                 }
-                throw new StorageError("share failed");
+                throw new StorageError("share failed", { cause: error });
             }
             return { vaultId, userId, role };
         }, operation.signal);
@@ -968,7 +977,7 @@ export async function unshareVault(storage, vaultId, userId, options) {
                 if (error instanceof MutationOutcomeUnknownError)
                     throw error;
                 if (completedRoomIds.size > 0) {
-                    throw new MutationPartialError("unshare", [...completedRoomIds], safePartialDetail(error));
+                    throw new MutationPartialError("unshare", [...completedRoomIds], safePartialDetail(error), { cause: error });
                 }
                 if (error instanceof StorageError &&
                     (error.message.includes("owner") ||
@@ -976,7 +985,7 @@ export async function unshareVault(storage, vaultId, userId, options) {
                         error.message === "operation cancelled")) {
                     throw error;
                 }
-                throw new StorageError("unshare failed");
+                throw new StorageError("unshare failed", { cause: error });
             }
             return { vaultId, userId, removed: true };
         }, operation.signal);
@@ -992,10 +1001,10 @@ export async function listMembers(storage, vaultId, options) {
         try {
             return await withRateLimitRetry(() => storage.listMembers(tree, { signal }), signal);
         }
-        catch {
+        catch (error) {
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("list members failed");
+            throw new StorageError("list members failed", { cause: error });
         }
     });
 }
@@ -1008,16 +1017,12 @@ export async function listFiles(storage, treeId, options) {
             const files = tree
                 .listFiles()
                 .filter((file) => !isMarkedFileDeleted(storage, tree.id, file.id));
-            if (files.length > MAX_LIST_ITEMS)
-                throw new StorageError("file list is too large");
             return files.map((f) => ({ id: f.id, name: f.getName() }));
         }
         catch (error) {
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            if (error instanceof StorageError && error.message === "file list is too large")
-                throw error;
-            throw new StorageError("list files failed");
+            throw new StorageError("list files failed", { cause: error });
         }
     });
 }
@@ -1027,11 +1032,8 @@ export async function listSubfolders(storage, parentId, options) {
         const tree = await resolveTree(storage, parentId, signal);
         await storage.refreshRoomState(parentId, { signal });
         ensureOperationActive(signal);
-        const directories = tree
-            .getDirectories()
+        const directories = activeTreeDirectories(storage.getClient(), tree)
             .filter((directory) => !isMarkedTreeDeleted(storage, directory.id));
-        if (directories.length > MAX_LIST_ITEMS)
-            throw new StorageError("folder list is too large");
         return directories.map((d) => ({ id: d.id, name: d.room.name }));
     });
 }
@@ -1044,16 +1046,12 @@ export async function createSubfolder(storage, parentId, name, options) {
             sub = await withRateLimitRetry(() => storage.createSubtree(tree, name, signal), signal);
         }
         catch (error) {
-            if (error instanceof RoomCleanupIncompleteError ||
-                error instanceof RoomCreationAmbiguousError ||
-                error instanceof MutationOutcomeUnknownError ||
-                (error instanceof Error &&
-                    error.cleanupIncomplete === true)) {
+            if (requiresMutationReconciliation(error)) {
                 throw error;
             }
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("create folder failed");
+            throw new StorageError("create folder failed", { cause: error });
         }
         ensureOperationActive(signal);
         return { id: sub.id, name };
@@ -1071,12 +1069,7 @@ async function renameTree(storage, treeId, name, options) {
                 const current = storage.getTree(treeId);
                 if (current?.room.name === name)
                     return current;
-                try {
-                    await storage.refreshRoomState(treeId, { signal });
-                }
-                catch {
-                    return null;
-                }
+                await storage.refreshRoomState(treeId, { signal });
                 const refreshed = storage.getTree(treeId);
                 return refreshed?.room.name === name ? refreshed : null;
             }, { timeoutMs: 15000, signal });
@@ -1086,7 +1079,7 @@ async function renameTree(storage, treeId, name, options) {
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("rename failed");
+            throw new StorageError("rename failed", { cause: error });
         }
         return { id: treeId, name };
     }, "mutation");
@@ -1119,7 +1112,7 @@ async function deleteTree(storage, treeId, options) {
                 // part of this operation and must not block deletion merely because
                 // their membership is not joined.
                 await refreshDeletionRooms(storage, tree.id, operation.signal);
-                const spaces = snapshotTreeSpaces(tree, "delete graph is too large");
+                const spaces = snapshotTreeSpaces(tree, "delete graph is too large", client);
                 const activeSpaces = spaces.filter((space) => !removedRooms.has(space.id));
                 const ids = new Set(activeSpaces.map((space) => space.id));
                 if (!ids.has(tree.id)) {
@@ -1132,13 +1125,9 @@ async function deleteTree(storage, treeId, options) {
                 graph = validateDeletionGraph(client, tree, ids, removedRooms);
             }
             catch (error) {
-                if (error instanceof MutationOutcomeUnknownError ||
-                    error instanceof MutationPartialError ||
-                    error instanceof NonEmptyTreeError)
-                    throw error;
                 if (error instanceof StorageError)
                     throw error;
-                throw new StorageError("delete failed");
+                throw new StorageError("delete failed", { cause: error });
             }
             // Keep external parent links intact until the room deletion succeeds.
             // Unlinking first would silently detach a live vault on failure.
@@ -1146,16 +1135,9 @@ async function deleteTree(storage, treeId, options) {
                 await unlinkExternalParents(storage, tree.id, graph.externalParents, operation.signal);
             }
             catch (error) {
-                if (error instanceof MutationOutcomeUnknownError)
-                    throw error;
-                if (error instanceof MutationPartialError)
-                    throw error;
-                if (error instanceof StorageError && error.message === "delete graph unlink cleanup is incomplete") {
-                    throw error;
-                }
                 if (error instanceof StorageError)
                     throw error;
-                throw new StorageError("delete failed");
+                throw new StorageError("delete failed", { cause: error });
             }
             try {
                 await deleteRoomDeterministically(storage, tree.id, operation.signal);
@@ -1167,16 +1149,14 @@ async function deleteTree(storage, treeId, options) {
                 try {
                     await relinkExternalParents(storage, tree.id, graph.externalParents, new AbortController().signal);
                 }
-                catch {
-                    throw new StorageError("delete cleanup is incomplete");
+                catch (cleanupError) {
+                    throw new StorageError("delete cleanup is incomplete", {
+                        cause: new AggregateError([error, cleanupError], "delete and external-parent relink both failed", { cause: error }),
+                    });
                 }
-                if (error instanceof MutationOutcomeUnknownError)
-                    throw error;
-                if (error instanceof MutationPartialError)
-                    throw error;
                 if (error instanceof StorageError)
                     throw error;
-                throw new StorageError("delete failed");
+                throw new StorageError("delete failed", { cause: error });
             }
             return { id: treeId, deleted: true };
         }, operation.signal);
@@ -1216,7 +1196,7 @@ export async function renameFile(storage, treeId, fileId, name, options) {
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("rename file failed");
+            throw new StorageError("rename file failed", { cause: error });
         }
         return { id: fileId, name };
     }, "mutation");
@@ -1235,11 +1215,11 @@ async function resolveFileVersions(branch, signal) {
     try {
         history = await branch.getVersionHistory();
     }
-    catch {
-        throw new StorageError("could not resolve file version history safely");
+    catch (error) {
+        throw new StorageError("could not resolve file version history safely", { cause: error });
     }
-    if (!Array.isArray(history) || history.length === 0 || history.length > MAX_FILE_VERSION_CHAIN) {
-        throw new StorageError("file version history is invalid or too large");
+    if (!Array.isArray(history) || history.length === 0) {
+        throw new StorageError("file version history is invalid");
     }
     const eventIds = new Set();
     const mediaIds = new Set();
@@ -1253,8 +1233,8 @@ async function resolveFileVersions(branch, signal) {
         try {
             validateMatrixEventId(version.id, "file version event ID");
         }
-        catch {
-            throw new StorageError("file version history contains an invalid event ID");
+        catch (error) {
+            throw new StorageError("file version history contains an invalid event ID", { cause: error });
         }
         if (eventIds.has(version.id)) {
             throw new StorageError("file version history contains a cycle");
@@ -1264,17 +1244,14 @@ async function resolveFileVersions(branch, signal) {
         try {
             fileInfo = await version.getFileInfo();
         }
-        catch {
-            throw new StorageError("could not resolve encrypted file version safely");
+        catch (error) {
+            throw new StorageError("could not resolve encrypted file version safely", { cause: error });
         }
         const mediaId = fileInfo?.info?.url;
         if (typeof mediaId !== "string" || mediaId.length === 0) {
             throw new StorageError("encrypted file version has no media identifier");
         }
         mediaIds.add(mediaId);
-        if (mediaIds.size > MAX_FILE_VERSION_CHAIN) {
-            throw new StorageError("file media version history is too large");
-        }
         versions.push({ branch: version, mediaId });
     }
     return versions;
@@ -1297,7 +1274,7 @@ async function deleteFileMedia(storage, mediaIds, signal) {
             throw error;
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
-        throw new StorageError("delete file media failed");
+        throw new StorageError("delete file media failed", { cause: error });
     }
 }
 export async function deleteFile(storage, treeId, fileId, options) {
@@ -1322,9 +1299,9 @@ export async function deleteFile(storage, treeId, fileId, options) {
             if (error instanceof MutationOutcomeUnknownError)
                 throw error;
             if (signal.aborted) {
-                throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup was cancelled");
+                throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup was cancelled", { cause: error });
             }
-            throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup stopped");
+            throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup stopped", { cause: error });
         }
         try {
             await waitForCondition(async () => {
@@ -1338,7 +1315,7 @@ export async function deleteFile(storage, treeId, fileId, options) {
             if (error instanceof MutationOutcomeUnknownError)
                 throw error;
             const detail = "Matrix deletion completed but the inactive file state could not be verified";
-            throw new MutationPartialError("delete file", completedIds, detail);
+            throw new MutationPartialError("delete file", completedIds, detail, { cause: error });
         }
         for (const { branch: version } of versions) {
             markFileDeleted(storage.getClient(), tree.id, version.id);
@@ -1357,7 +1334,7 @@ export async function uploadFile(storage, treeId, name, bytes, mimetype, options
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("upload failed");
+            throw new StorageError("upload failed", { cause: error });
         });
         // The create-file request is acknowledged before the event necessarily
         // arrives in this client's sync timeline. A caller can otherwise report a
@@ -1376,7 +1353,7 @@ export async function uploadFile(storage, treeId, name, bytes, mimetype, options
         catch (error) {
             if (error instanceof MutationOutcomeUnknownError)
                 throw error;
-            throw new MutationPartialError("upload file", [fileId], "upload completed but the file could not be observed locally");
+            throw new MutationPartialError("upload file", [fileId], "upload completed but the file could not be observed locally", { cause: error });
         }
         ensureOperationActive(signal);
         return { id: fileId, name, mimetype };
@@ -1391,11 +1368,11 @@ export async function downloadFile(storage, treeId, fileId, options) {
             result = await storage.downloadFile(branch, signal);
         }
         catch (error) {
-            if (error instanceof UndecryptableFileError)
+            if (error instanceof StorageError)
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            throw new StorageError("download failed");
+            throw new StorageError("download failed", { cause: error });
         }
         ensureOperationActive(signal);
         return {
@@ -1425,41 +1402,21 @@ export async function getFileDetails(storage, treeId, fileId, options) {
         let size = null;
         let createdAt = null;
         let updatedAt = null;
-        try {
-            ensureOperationActive(signal);
-            const { info } = await branch.getFileInfo();
-            if (info) {
-                if (typeof info["mimetype"] === "string")
-                    mimetype = info["mimetype"];
-                if (typeof info["size"] === "number")
-                    size = info["size"];
-            }
-        }
-        catch {
-            if (signal.aborted)
-                throw new StorageError("operation cancelled");
-            // Partial metadata is fine — UI shows "—" for unknown fields.
-        }
         try {
             ensureOperationActive(signal);
             const event = await branch.getFileEvent();
-            const content = event.getContent();
-            const infoBlock = content["info"];
-            if (!mimetype && typeof infoBlock?.["mimetype"] === "string") {
-                mimetype = infoBlock["mimetype"];
-            }
-            if (size == null && typeof infoBlock?.["size"] === "number") {
-                size = infoBlock["size"];
-            }
-            const eventAny = event;
-            const ts = eventAny.getTs?.() ?? eventAny.origin_server_ts;
-            createdAt = tsToIso(ts);
+            const metadata = readFileEventMetadata(event.getContent());
+            mimetype = metadata.mimetype;
+            size = metadata.size;
+            createdAt = tsToIso(event.getTs());
             updatedAt = createdAt;
         }
-        catch {
+        catch (error) {
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            // Same as above.
+            if (error instanceof StorageError)
+                throw error;
+            throw new StorageError("get file details failed", { cause: error });
         }
         ensureOperationActive(signal);
         return { name, mimetype, size, createdAt, updatedAt };
@@ -1479,8 +1436,8 @@ async function getTreeDetails(storage, treeId, signal) {
         try {
             memberCount = room.getJoinedMemberCount();
         }
-        catch {
-            memberCount = null;
+        catch (error) {
+            throw new StorageError("member count lookup failed", { cause: error });
         }
     }
     return {