@telecrypt-io/storage 0.5.28 → 0.5.30

package/dist/TeleCryptIOStorage.js

@@ -5,7 +5,8 @@ import { encryptAttachment, decryptAttachment } from "matrix-encrypt-attachment"
 import { decodeRecoveryKey } from "matrix-js-sdk/lib/crypto-api/recovery-key.js";
 import { FileTooLargeError, RecoveryAlreadyConfiguredError, RecoveryRestoreError, RecoverySetupAmbiguousError, RecoverySetupError, RecoveryRestoreAmbiguousError, MutationOutcomeUnknownError, RoomCreationAmbiguousError, RoomCleanupIncompleteError, StorageError, UndecryptableFileError, } from "./core/errors.js";
 import { MAX_MEDIA_FILE_BYTES, MAX_MATRIX_IDENTIFIER_LENGTH, validateCanonicalMatrixUserId, validateMatrixDeviceId, validateMatrixEventId, validateMatrixRoomId, } from "./core/constants.js";
-import { raceWithAbort, readBoundedResponseBody } from "./core/http.js";
+import { cancelResponseBody, raceWithAbort, readMediaResponseBody, readResponseBody, ResponseBodyReadError, } from "./core/http.js";
+import { sanitizeDiagnosticText } from "./core/oidc.js";
 import { validateName } from "./core/validation.js";
 import { isTreeDeleted } from "./deletion-markers.js";
 const recoveryMutationQueues = new WeakMap();
@@ -18,11 +19,6 @@ const RECOVERY_CRYPTO_TIMEOUT_MS = 60000;
 const MAX_MEDIA_REDIRECTS = 5;
 const MAX_MATRIX_TOKEN_LENGTH = 8192;
 const MAX_MIMETYPE_LENGTH = 255;
-const MAX_MATRIX_STATE_RESPONSE_BYTES = 4 * 1024 * 1024;
-const MAX_MATRIX_RESPONSE_BYTES = 16 * 1024 * 1024;
-const MAX_MATRIX_STATE_EVENTS = 10000;
-const MAX_MATRIX_MEMBERS = 10000;
-const MAX_MATRIX_JOINED_ROOMS = 4096;
 function cloneCryptoCallbacks(callbacks) {
     // MatrixClient retains this object for the lifetime of the client. Keep the
     // caller's object immutable: recovery temporarily installs key callbacks on
@@ -64,26 +60,21 @@ export function withMatrixMutationAbort(_client, operation, signal, operationNam
             pending = operation();
         }
         catch (error) {
-            finish(() => reject(cancelled ? new MutationOutcomeUnknownError(operationName) : error));
+            finish(() => reject(cancelled ? new MutationOutcomeUnknownError(operationName, { cause: error }) : error));
             return;
         }
-        pending.then((value) => finish(() => (cancelled ? reject(new MutationOutcomeUnknownError(operationName)) : resolve(value))), (error) => finish(() => reject(cancelled ? new MutationOutcomeUnknownError(operationName) : error)));
+        pending.then((value) => finish(() => (cancelled ? reject(new MutationOutcomeUnknownError(operationName)) : resolve(value))), (error) => finish(() => reject(cancelled ? new MutationOutcomeUnknownError(operationName, { cause: error }) : error)));
     });
 }
-async function readBoundedMatrixResponse(response, maxBytes, signal, abortError) {
-    const body = await readBoundedResponseBody(response, maxBytes, signal, {
+async function readMatrixResponse(response, signal, abortError) {
+    const body = await readResponseBody(response, signal, {
         abortError,
-        deferReaderRelease: true,
     });
-    if (body.truncated)
-        throw new Error("Matrix response body is too large");
     if (!response.body)
         return response;
     // Fetch forbids a response body for 204, 205, and 304 responses. Some
     // browser implementations nevertheless expose an empty response stream for
-    // a 204 from a proxy. Reconstructing that response with even an empty
-    // Uint8Array then throws before matrix-js-sdk can accept the successful
-    // response. Preserve the bodyless status after boundedly consuming the
+    // a 204 from a proxy. Preserve the bodyless status after consuming the
     // stream so callers such as FetchHttpApi can still read an empty Blob.
     const bodylessStatus = response.status === 204 || response.status === 205 || response.status === 304;
     if (bodylessStatus) {
@@ -102,14 +93,6 @@ async function readBoundedMatrixResponse(response, maxBytes, signal, abortError)
         headers: response.headers,
     });
 }
-function isMatrixStateOrMembershipUrl(input) {
-    const url = typeof input === "string"
-        ? new URL(input, "https://matrix.invalid")
-        : input instanceof URL
-            ? input
-            : new URL(input.url, "https://matrix.invalid");
-    return /\/rooms\/[^/]+\/(?:state|members)(?:\/|$)/.test(url.pathname);
-}
 export function boundedMatrixFetch(fetchFn) {
     const wrapped = ((input, init) => {
         const pending = (async () => {
@@ -126,25 +109,21 @@ export function boundedMatrixFetch(fetchFn) {
             else
                 externalSignal?.addEventListener("abort", abortExternal, { once: true });
             try {
-                const response = await raceWithAbort(fetchFn(input, { ...init, redirect: "manual", signal: controller.signal }), controller.signal, () => undefined, () => (timedOut ? new Error("Matrix request timed out") : new DOMException("The operation was aborted", "AbortError")));
+                const response = await raceWithAbort(fetchFn(input, { ...init, redirect: "manual", signal: controller.signal }), controller.signal, () => (timedOut ? new Error("Matrix request timed out") : new DOMException("The operation was aborted", "AbortError")));
                 if (response.redirected ||
                     response.type === "opaqueredirect" ||
                     (response.status >= 300 && response.status < 400)) {
-                    response.body?.cancel().catch(() => undefined);
-                    throw new Error("Matrix redirect rejected");
+                    const failure = new Error("Matrix redirect rejected");
+                    await cancelResponseBody(response, "Matrix redirect", failure);
+                    throw failure;
                 }
-                return await readBoundedMatrixResponse(response, isMatrixStateOrMembershipUrl(input)
-                    ? MAX_MATRIX_STATE_RESPONSE_BYTES
-                    : MAX_MATRIX_RESPONSE_BYTES, controller.signal, () => (timedOut ? new Error("Matrix request timed out") : new DOMException("The operation was aborted", "AbortError")));
+                return await readMatrixResponse(response, controller.signal, () => (timedOut ? new Error("Matrix request timed out") : new DOMException("The operation was aborted", "AbortError")));
             }
             finally {
                 clearTimeout(timeout);
                 externalSignal?.removeEventListener("abort", abortExternal);
             }
         })();
-        // Preserve fetch-style rejection for callers while observing an immediate
-        // abort until the caller has had a chance to attach its own handler.
-        void pending.catch(() => undefined);
         return pending;
     });
     return wrapped;
@@ -181,8 +160,8 @@ function validateHomeserverUrl(value) {
     try {
         url = new URL(value);
     }
-    catch {
-        throw new Error("invalid Matrix homeserver URL");
+    catch (error) {
+        throw new Error("invalid Matrix homeserver URL", { cause: error });
     }
     if ((url.protocol !== "http:" && url.protocol !== "https:") ||
         (url.protocol === "http:" && !isLoopbackHostname(url.hostname)) ||
@@ -224,9 +203,50 @@ function validateMimetype(value) {
         throw new Error("invalid MIME type");
     }
 }
+/** Reads the event-owned metadata shared by details and download operations. */
+export function readFileEventMetadata(content) {
+    if (!isRecord(content))
+        throw new StorageError("media metadata is invalid");
+    const rawInfo = content["info"];
+    if (rawInfo !== undefined && !isRecord(rawInfo)) {
+        throw new StorageError("media metadata is invalid");
+    }
+    const info = isRecord(rawInfo) ? rawInfo : undefined;
+    const rawSize = info?.["size"];
+    if (rawSize !== undefined) {
+        if (typeof rawSize !== "number" || !Number.isSafeInteger(rawSize) || rawSize < 0) {
+            throw new StorageError("media metadata is invalid");
+        }
+        if (rawSize > MAX_MEDIA_FILE_BYTES)
+            throw new FileTooLargeError();
+    }
+    const rawMimetype = info?.["mimetype"];
+    if (rawMimetype !== undefined && typeof rawMimetype !== "string") {
+        throw new StorageError("media metadata is invalid");
+    }
+    const mimetype = rawMimetype ?? null;
+    if (mimetype !== null) {
+        try {
+            validateMimetype(mimetype);
+        }
+        catch (error) {
+            throw new StorageError("media metadata is invalid", { cause: error });
+        }
+    }
+    return {
+        mimetype,
+        size: typeof rawSize === "number" ? rawSize : null,
+    };
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+async function isUndecryptableFilePlaceholder(branch) {
+    // matrix-js-sdk replaces failed encrypted event content with m.bad.encrypted;
+    // its public failure flag is the authoritative state and avoids guessing
+    // from that display content (or misclassifying malformed plaintext events).
+    return (await branch.getFileEvent()).isDecryptionFailure();
+}
 function validateSecretStorageStatus(value) {
     if (!isRecord(value))
         throw new RecoverySetupAmbiguousError();
@@ -295,7 +315,7 @@ async function withRecoveryCryptoDeadline(operation, signal, operationName) {
         signal?.addEventListener("abort", abortExternal, { once: true });
     const pending = Promise.resolve().then(operation);
     try {
-        return await raceWithAbort(pending, controller.signal, () => undefined, () => timedOut
+        return await raceWithAbort(pending, controller.signal, () => timedOut
             ? new RecoveryCryptoTimeoutError(operationName)
             : new StorageError("operation cancelled"));
     }
@@ -308,9 +328,6 @@ function parseMatrixMembersResponse(value) {
     if (!isRecord(value) || !Array.isArray(value.chunk)) {
         throw new Error("invalid Matrix members response");
     }
-    if (value.chunk.length > MAX_MATRIX_MEMBERS) {
-        throw new Error("Matrix members response is too large");
-    }
     return value.chunk.map((entry) => {
         if (!isRecord(entry) ||
             typeof entry.state_key !== "string" ||
@@ -329,9 +346,6 @@ function parseMatrixMembersResponse(value) {
 function parseMatrixStateResponse(value) {
     if (!Array.isArray(value))
         throw new Error("invalid Matrix room state response");
-    if (value.length > MAX_MATRIX_STATE_EVENTS) {
-        throw new Error("Matrix room state response is too large");
-    }
     return value.map((event) => {
         if (!isRecord(event) ||
             typeof event.type !== "string" ||
@@ -362,9 +376,6 @@ function parseMatrixPowerLevels(value) {
             continue;
         if (!isRecord(field))
             throw new Error("invalid Matrix power-level response");
-        if (Object.keys(field).length > MAX_MATRIX_MEMBERS) {
-            throw new Error("Matrix power-level response is too large");
-        }
         for (const key of Object.keys(field))
             validateMatrixIdentifier(key, `${name} key`);
         for (const level of Object.values(field)) {
@@ -379,8 +390,11 @@ function isGoneRoomError(error) {
     return (error instanceof MatrixError &&
         (error.errcode === "M_NOT_FOUND" || error.errcode === "M_UNKNOWN"));
 }
-function throwWithCleanupDetail(error, roomId) {
-    const cleanup = new RoomCleanupIncompleteError(roomId);
+function throwWithCleanupDetail(error, roomId, cleanupError) {
+    const cleanupCause = cleanupError === undefined
+        ? error
+        : new AggregateError([error, cleanupError], "operation and room cleanup failed", { cause: error });
+    const cleanup = new RoomCleanupIncompleteError(roomId, cleanupCause);
     if (error instanceof Error) {
         try {
             Object.defineProperty(error, "cleanupIncomplete", {
@@ -393,9 +407,10 @@ function throwWithCleanupDetail(error, roomId) {
             });
         }
         catch {
-            // Preserve the original mutation error even if an unusual Error object
-            // is non-extensible; the cleanup detail remains in the cause chain only
-            // when it could be attached safely.
+            // A non-extensible provider error cannot carry the cleanup marker. Throw
+            // the existing typed cleanup error and retain the provider error as cause
+            // so callers cannot mistake the mutation for a safe retry.
+            throw cleanup;
         }
         throw error;
     }
@@ -465,9 +480,6 @@ export class TeleCryptIOStorage {
                     for (const [stateKey, event] of byStateKey) {
                         if (present.has(`${eventType}\u0000${stateKey}`))
                             continue;
-                        if (refreshed.length >= MAX_MATRIX_STATE_EVENTS) {
-                            throw new Error("Matrix room state response is too large");
-                        }
                         const original = event.getEffectiveEvent();
                         refreshed.push(new MatrixEvent({
                             ...original,
@@ -567,8 +579,10 @@ export class TeleCryptIOStorage {
             try {
                 client.stopClient();
             }
-            catch {
-                // Preserve the original bootstrap failure.
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], "storage bootstrap and client cleanup failed", {
+                    cause: error,
+                });
             }
             throw error;
         }
@@ -769,7 +783,7 @@ export class TeleCryptIOStorage {
             if (signal?.aborted && error instanceof StorageError) {
                 throw error;
             }
-            throw new RecoverySetupAmbiguousError();
+            throw new RecoverySetupAmbiguousError(error);
         }
         if (status.defaultKeyId || status.ready || backupVersion !== null) {
             throw new RecoveryAlreadyConfiguredError();
@@ -789,11 +803,11 @@ export class TeleCryptIOStorage {
                 authUploadDeviceSigningKeys: async () => undefined,
             }), signal, "cross-signing bootstrap");
         }
-        catch {
+        catch (error) {
             // Cross-signing setup can commit server-side state before a transport
             // failure is observed. Do not turn that uncertainty into a retry that
             // could replace recovery state.
-            throw new RecoverySetupAmbiguousError();
+            throw new RecoverySetupAmbiguousError(error);
         }
         // CryptoApi mutations do not accept an AbortSignal. Once one has settled,
         // do not cross the next one-way mutation boundary: the caller may already
@@ -804,8 +818,8 @@ export class TeleCryptIOStorage {
         try {
             generated = await withRecoveryCryptoDeadline(() => crypto.createRecoveryKeyFromPassphrase(), signal, "recovery-key generation");
         }
-        catch {
-            throw new RecoverySetupAmbiguousError();
+        catch (error) {
+            throw new RecoverySetupAmbiguousError(error);
         }
         if (!generated.encodedPrivateKey) {
             throw new RecoverySetupAmbiguousError();
@@ -858,15 +872,22 @@ export class TeleCryptIOStorage {
                     throw new RecoverySetupAmbiguousError();
                 }
             }
-            catch (error) {
-                if (error instanceof RecoverySetupAmbiguousError || error instanceof RecoverySetupError)
-                    throw error;
+            catch (statusError) {
+                if (statusError instanceof RecoverySetupAmbiguousError) {
+                    throw new RecoverySetupAmbiguousError(new AggregateError([error, statusError], "recovery setup and status verification were both inconclusive", {
+                        cause: error,
+                    }));
+                }
+                if (statusError instanceof RecoverySetupError)
+                    throw statusError;
                 // A failed status probe cannot prove that the one-way operation did
                 // not commit. Never turn that uncertainty into an apparently safe
                 // retry that could replace account recovery state.
-                throw new RecoverySetupAmbiguousError();
+                throw new RecoverySetupAmbiguousError(new AggregateError([error, statusError], "recovery setup and status verification failed", {
+                    cause: error,
+                }));
             }
-            throw new RecoverySetupError();
+            throw new RecoverySetupError(error);
         }
         try {
             const [rawAfterStatus, rawAfterBackup] = await Promise.all([
@@ -881,7 +902,7 @@ export class TeleCryptIOStorage {
         catch (error) {
             if (error instanceof RecoverySetupAmbiguousError)
                 throw error;
-            throw new RecoverySetupAmbiguousError();
+            throw new RecoverySetupAmbiguousError(error);
         }
         // This is the last boundary before exposing the only recovery credential
         // to the caller. Cancellation here must not return a key that the caller
@@ -911,8 +932,8 @@ export class TeleCryptIOStorage {
             const backupVersion = validateBackupVersion(rawBackupVersion);
             return storageStatus.ready && backupVersion !== null;
         }
-        catch {
-            throw new RecoverySetupAmbiguousError();
+        catch (error) {
+            throw new RecoverySetupAmbiguousError(error);
         }
     }
     /** Returns one consistent recovery topology snapshot without exposing raw crypto callbacks. */
@@ -952,8 +973,8 @@ export class TeleCryptIOStorage {
                     backupVersion,
                 };
             }
-            catch {
-                throw new RecoverySetupAmbiguousError();
+            catch (error) {
+                throw new RecoverySetupAmbiguousError(error);
             }
         }, signal);
     }
@@ -983,8 +1004,8 @@ export class TeleCryptIOStorage {
         try {
             privateKey = decodeRecoveryKey(recoveryKey);
         }
-        catch {
-            throw new RecoveryRestoreError();
+        catch (error) {
+            throw new RecoveryRestoreError(error);
         }
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
@@ -997,7 +1018,7 @@ export class TeleCryptIOStorage {
             catch (error) {
                 if (error instanceof RecoveryRestoreAmbiguousError)
                     throw error;
-                throw new RecoveryRestoreError();
+                throw new RecoveryRestoreError(error);
             }
             try {
                 const result = await withRecoveryCryptoDeadline(() => crypto.restoreKeyBackup(), signal, "key-backup restore");
@@ -1011,7 +1032,9 @@ export class TeleCryptIOStorage {
             catch (error) {
                 if (error instanceof RecoveryRestoreAmbiguousError)
                     throw error;
-                throw new RecoveryRestoreError();
+                if (error instanceof RecoveryRestoreError)
+                    throw error;
+                throw new RecoveryRestoreError(error);
             }
         }, signal);
     }
@@ -1075,6 +1098,7 @@ export class TeleCryptIOStorage {
     }
     async waitForTreeSpace(roomId, operation, signal) {
         const deadline = Date.now() + TREE_SYNC_TIMEOUT_MS;
+        let lastError;
         for (;;) {
             if (signal?.aborted)
                 throw new StorageError("operation cancelled");
@@ -1083,12 +1107,15 @@ export class TeleCryptIOStorage {
                 if (tree)
                     return this.decorateTreeSpace(tree);
             }
-            catch {
+            catch (error) {
+                lastError = error;
                 // The room can be present before its complete state has been applied
                 // to this client's local store. Keep polling the exact returned ID.
             }
             if (Date.now() >= deadline) {
-                throw new Error(`${operation}: created room did not become a file tree space in local sync state`);
+                throw new Error(`${operation}: created room did not become a file tree space in local sync state`, {
+                    cause: lastError,
+                });
             }
             await new Promise((resolve, reject) => {
                 let timer;
@@ -1129,12 +1156,14 @@ export class TeleCryptIOStorage {
         const cleanupSignal = new AbortController().signal;
         let incomplete = false;
         let safeToForget = true;
+        const failures = [];
         try {
             await TeleCryptIOStorage.withTimeout(withMatrixMutationAbort(this.client, () => this.client.leave(roomId), cleanupSignal), CLEANUP_TIMEOUT_MS, "room leave cleanup", cleanupSignal);
         }
         catch (error) {
             if (!isGoneRoomError(error)) {
                 incomplete = true;
+                failures.push(error);
                 // A timed-out or failed leave may still be in flight. Do not race a
                 // forget request against it; the caller must retry cleanup later.
                 safeToForget = false;
@@ -1145,12 +1174,17 @@ export class TeleCryptIOStorage {
                 await TeleCryptIOStorage.withTimeout(withMatrixMutationAbort(this.client, () => this.client.forget(roomId), cleanupSignal), CLEANUP_TIMEOUT_MS, "room forget cleanup", cleanupSignal);
             }
             catch (error) {
-                if (!isGoneRoomError(error))
+                if (!isGoneRoomError(error)) {
                     incomplete = true;
+                    failures.push(error);
+                }
             }
         }
         if (incomplete) {
-            throw new RoomCleanupIncompleteError(roomId);
+            const cause = failures.length === 1
+                ? failures[0]
+                : new AggregateError(failures, "room cleanup failed");
+            throw new RoomCleanupIncompleteError(roomId, cause);
         }
     }
     async removeRelationLink(roomId, eventType, stateKey, signal) {
@@ -1188,14 +1222,14 @@ export class TeleCryptIOStorage {
             // retryable generic error that could orphan a second room.
             if (error instanceof RoomCreationAmbiguousError)
                 throw error;
-            throw new RoomCreationAmbiguousError(operation);
+            throw new RoomCreationAmbiguousError(operation, error);
         });
         let roomId;
         try {
             roomId = validateMatrixRoomId(response?.room_id, "room creation response");
         }
-        catch {
-            throw new RoomCreationAmbiguousError(operation);
+        catch (error) {
+            throw new RoomCreationAmbiguousError(operation, error);
         }
         try {
             return await this.waitForTreeSpace(roomId, operation, signal);
@@ -1204,13 +1238,13 @@ export class TeleCryptIOStorage {
             try {
                 await this.cleanupCreatedRoom(roomId, signal);
             }
-            catch {
-                throwWithCleanupDetail(error, roomId);
+            catch (cleanupError) {
+                throwWithCleanupDetail(error, roomId, cleanupError);
             }
             // The room existed even if cleanup happened to succeed. Keep the
             // caller on the reconciliation path: a retry based on a local timeout
             // or malformed response must never assume that no room was created.
-            throw new RoomCreationAmbiguousError(operation);
+            throw new RoomCreationAmbiguousError(operation, error);
         }
     }
     /**
@@ -1224,8 +1258,6 @@ export class TeleCryptIOStorage {
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
         const rooms = this.client.getRooms();
-        if (rooms.length > MAX_MATRIX_JOINED_ROOMS)
-            throw new StorageError("room list is too large");
         const trees = [];
         for (const room of rooms) {
             if (signal?.aborted)
@@ -1280,6 +1312,7 @@ export class TeleCryptIOStorage {
                 // signal, then report incomplete cleanup if they cannot be verified.
                 const compensationSignal = new AbortController().signal;
                 let rollbackIncomplete = false;
+                const cleanupFailures = [];
                 // A sendStateEvent rejection is ambiguous: the homeserver may have
                 // committed the event before the client observed a transport error.
                 // Refresh the parent before probing even when no event ID was
@@ -1303,6 +1336,7 @@ export class TeleCryptIOStorage {
                                         Object.keys(content).length > 0);
                                 })) {
                                 rollbackIncomplete = true;
+                                cleanupFailures.push(new Error("parent link rollback could not be verified"));
                             }
                         }
                         else {
@@ -1310,12 +1344,15 @@ export class TeleCryptIOStorage {
                             const removed = await this.removeChildLink(currentParent.id, tree.id, compensationSignal);
                             // Without an event ID, a missing link after one refresh does not
                             // prove that a request which timed out will never commit.
-                            if (!removed)
+                            if (!removed) {
                                 rollbackIncomplete = true;
+                                cleanupFailures.push(new Error("parent link rollback could not be verified"));
+                            }
                         }
                     }
-                    catch {
+                    catch (cleanupError) {
                         rollbackIncomplete = true;
+                        cleanupFailures.push(cleanupError);
                     }
                 }
                 if (childLinkAttempted) {
@@ -1335,27 +1372,35 @@ export class TeleCryptIOStorage {
                                         Object.keys(content).length > 0);
                                 })) {
                                 rollbackIncomplete = true;
+                                cleanupFailures.push(new Error("child link rollback could not be verified"));
                             }
                         }
                         else {
                             await this.refreshRoomState(tree.id, { signal: compensationSignal });
                             const removed = await this.removeParentLink(tree.id, currentParent.id, compensationSignal);
-                            if (!removed)
+                            if (!removed) {
                                 rollbackIncomplete = true;
+                                cleanupFailures.push(new Error("child link rollback could not be verified"));
+                            }
                         }
                     }
-                    catch {
+                    catch (cleanupError) {
                         rollbackIncomplete = true;
+                        cleanupFailures.push(cleanupError);
                     }
                 }
                 try {
                     await this.cleanupCreatedRoom(tree.id, effectiveSignal);
                 }
-                catch {
-                    throwWithCleanupDetail(error, tree.id);
+                catch (cleanupError) {
+                    cleanupFailures.push(cleanupError);
+                }
+                if (rollbackIncomplete || cleanupFailures.length > 0) {
+                    const cleanupCause = cleanupFailures.length === 1
+                        ? cleanupFailures[0]
+                        : new AggregateError(cleanupFailures, "tree creation cleanup failed");
+                    throwWithCleanupDetail(error, tree.id, cleanupCause);
                 }
-                if (rollbackIncomplete)
-                    throwWithCleanupDetail(error, tree.id);
                 throw error;
             }
         }, signal);
@@ -1453,17 +1498,17 @@ export class TeleCryptIOStorage {
             // mutation outcome is safe to propagate unchanged.
             if (error instanceof MutationOutcomeUnknownError)
                 throw error;
-            throw new MutationOutcomeUnknownError("file upload");
+            throw new MutationOutcomeUnknownError("file upload", { cause: error });
         }
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
         try {
             return validateMatrixEventId(response?.event_id, "file upload response event ID");
         }
-        catch {
+        catch (error) {
             // An invalid response can still follow a committed event. Treat it as
             // unknown rather than presenting a retryable generic upload failure.
-            throw new MutationOutcomeUnknownError("file upload");
+            throw new MutationOutcomeUnknownError("file upload", { cause: error });
         }
     }
     async downloadFile(branch, signal) {
@@ -1473,26 +1518,38 @@ export class TeleCryptIOStorage {
         try {
             ({ info } = await branch.getFileInfo());
         }
-        catch {
-            // matrix-js-sdk's MSC3089Branch.getFileInfo() reads `file["url"]` off
-            // the raw event content; when the event is undecryptable on this
-            // device it hands back a placeholder with no `file` block, so that
-            // read throws an opaque "Cannot read properties of undefined" instead
-            // of a useful error. Surface the real cause.
-            throw new UndecryptableFileError();
-        }
-        // Also reject an incomplete placeholder if matrix-js-sdk returns one.
+        catch (error) {
+            if (signal?.aborted)
+                throw new StorageError("operation cancelled");
+            if (error instanceof StorageError || error instanceof MatrixError)
+                throw error;
+            // matrix-js-sdk's file-info accessor reads an attachment absent from
+            // failed-decryption events. Use its explicit decryption status, not a
+            // guessed content shape; preserve other SDK/transport failures.
+            let isPlaceholder = false;
+            try {
+                isPlaceholder = await isUndecryptableFilePlaceholder(branch);
+            }
+            catch (placeholderError) {
+                throw new AggregateError([error, placeholderError], "file metadata lookup and placeholder inspection both failed", { cause: error });
+            }
+            if (isPlaceholder) {
+                throw new UndecryptableFileError();
+            }
+            throw error;
+        }
+        // Missing metadata alone does not establish a decryption failure.
         if (!info || typeof info.url !== "string") {
-            throw new UndecryptableFileError();
-        }
-        const declaredSize = info.size;
-        if (declaredSize !== undefined &&
-            (typeof declaredSize !== "number" ||
-                !Number.isSafeInteger(declaredSize) ||
-                declaredSize < 0 ||
-                declaredSize > MAX_MEDIA_FILE_BYTES)) {
-            throw new FileTooLargeError();
+            throw new StorageError("file metadata is missing a media URL");
         }
+        // `info` is the encrypted attachment descriptor. Its shape is owned by
+        // matrix-encrypt-attachment and does not carry the plaintext size. The
+        // event's `info` block is the sole source of user-facing file metadata.
+        const eventMetadata = readFileEventMetadata((await branch.getFileEvent()).getContent());
+        if (signal?.aborted)
+            throw new StorageError("operation cancelled");
+        const declaredSize = eventMetadata.size;
+        const mimetype = eventMetadata.mimetype ?? "application/octet-stream";
         const mxcUrl = info.url;
         const clientAny = this.client;
         const accessToken = clientAny.getAccessToken();
@@ -1501,8 +1558,8 @@ export class TeleCryptIOStorage {
         try {
             trustedOrigin = validateHomeserverUrl(clientAny.getHomeserverUrl()).origin;
         }
-        catch {
-            throw new Error("failed to build media URL");
+        catch (error) {
+            throw new Error("failed to build media URL", { cause: error });
         }
         const downloadUrl = clientAny.mxcUrlToHttp(mxcUrl, undefined, undefined, undefined, false, true, true);
         if (!downloadUrl)
@@ -1511,8 +1568,8 @@ export class TeleCryptIOStorage {
         try {
             currentUrl = new URL(downloadUrl);
         }
-        catch {
-            throw new Error("failed to build media URL");
+        catch (error) {
+            throw new Error("failed to build media URL", { cause: error });
         }
         if ((currentUrl.protocol !== "http:" && currentUrl.protocol !== "https:") ||
             currentUrl.username !== "" ||
@@ -1535,67 +1592,92 @@ export class TeleCryptIOStorage {
                     redirect: "manual",
                     signal: controller.signal,
                     headers: { Authorization: `Bearer ${accessToken}` },
-                }), controller.signal, () => undefined, () => signal?.aborted
+                }), controller.signal, () => signal?.aborted
                     ? new StorageError("operation cancelled")
                     : new Error("media download timed out"));
                 if ([301, 302, 303, 307, 308].includes(res.status)) {
-                    try {
-                        void res.body?.cancel().catch(() => undefined);
-                    }
-                    catch {
-                        // The redirect response is already being rejected or discarded.
-                    }
-                    if (redirect >= MAX_MEDIA_REDIRECTS)
-                        throw new Error("media download redirect limit exceeded");
-                    const location = res.headers.get("location");
-                    if (!location)
-                        throw new Error("media download redirect missing location");
-                    try {
-                        currentUrl = new URL(location, currentUrl);
+                    let redirectError;
+                    let nextUrl;
+                    if (redirect >= MAX_MEDIA_REDIRECTS) {
+                        redirectError = new Error("media download redirect limit exceeded");
                     }
-                    catch {
-                        throw new Error("media download redirect is invalid");
-                    }
-                    if ((currentUrl.protocol !== "http:" && currentUrl.protocol !== "https:") ||
-                        currentUrl.username !== "" ||
-                        currentUrl.password !== "") {
-                        throw new Error("media download redirect is invalid");
-                    }
-                    if (currentUrl.origin !== trustedOrigin) {
-                        throw new Error("media download redirect crossed origin");
+                    else {
+                        const location = res.headers.get("location");
+                        if (!location) {
+                            redirectError = new Error("media download redirect missing location");
+                        }
+                        else {
+                            try {
+                                nextUrl = new URL(location, currentUrl);
+                            }
+                            catch (error) {
+                                redirectError = new Error("media download redirect is invalid", { cause: error });
+                            }
+                            if (nextUrl &&
+                                ((nextUrl.protocol !== "http:" && nextUrl.protocol !== "https:") ||
+                                    nextUrl.username !== "" ||
+                                    nextUrl.password !== "")) {
+                                redirectError = new Error("media download redirect is invalid");
+                            }
+                            if (nextUrl && nextUrl.origin !== trustedOrigin) {
+                                redirectError = new Error("media download redirect crossed origin");
+                            }
+                        }
                     }
+                    await cancelResponseBody(res, "media redirect", redirectError);
+                    if (redirectError)
+                        throw redirectError;
+                    currentUrl = nextUrl;
                     continue;
                 }
                 if (!res.ok) {
+                    const statusFailure = new Error(`media download failed: ${res.status}`);
+                    let detail = "";
                     try {
-                        void res.body?.cancel().catch(() => undefined);
+                        // Error responses are diagnostics, not product media. Consume the
+                        // complete body so no provider detail is discarded, then apply
+                        // the SDK's shared secret/control-character sanitizer before it
+                        // crosses the SDK boundary.
+                        const body = await readResponseBody(res, controller.signal);
+                        detail = sanitizeDiagnosticText(new TextDecoder().decode(body.bytes));
                     }
-                    catch {
-                        // The error response is already being rejected.
+                    catch (bodyError) {
+                        const partial = bodyError instanceof ResponseBodyReadError
+                            ? sanitizeDiagnosticText(new TextDecoder().decode(bodyError.bytes))
+                            : "";
+                        const readFailure = bodyError instanceof ResponseBodyReadError
+                            ? new Error(`media error response body could not be read${partial === "" ? "" : `: ${partial}`}`, { cause: bodyError })
+                            : bodyError;
+                        throw new AggregateError([statusFailure, readFailure], "media download failed while reading the response body", { cause: statusFailure });
                     }
-                    throw new Error(`media download failed: ${res.status}`);
+                    throw new Error(`${statusFailure.message}${detail === "" ? "" : `: ${detail}`}`);
                 }
                 if (!res.body) {
-                    // A bodyless Response has no bounded reader. Even a plausible
-                    // Content-Length is only advisory and must not authorize an
-                    // unbounded arrayBuffer() allocation.
-                    throw new Error("media download has no bounded response body");
+                    throw new Error("media download has no response body");
                 }
-                const body = await readBoundedResponseBody(res, MAX_MEDIA_FILE_BYTES, controller.signal);
-                if (body.truncated)
-                    throw new FileTooLargeError();
+                const body = await readMediaResponseBody(res, MAX_MEDIA_FILE_BYTES, controller.signal);
                 ciphertext = body.bytes.buffer;
                 break;
             }
         }
         catch (error) {
+            if (error instanceof AggregateError) {
+                if (signal?.aborted)
+                    throw new StorageError("operation cancelled", { cause: error });
+                if (controller.signal.aborted)
+                    throw new Error("media download timed out", { cause: error });
+                throw error;
+            }
+            if (error instanceof ResponseBodyReadError) {
+                throw new Error("media download failed", { cause: error.cause ?? new Error(error.message) });
+            }
             if (signal?.aborted)
-                throw new StorageError("operation cancelled");
+                throw new StorageError("operation cancelled", { cause: error });
             if (controller.signal.aborted)
-                throw new Error("media download timed out");
+                throw new Error("media download timed out", { cause: error });
             if (error instanceof FileTooLargeError)
                 throw error;
-            throw new Error("media download failed");
+            throw new Error("media download failed", { cause: error });
         }
         finally {
             clearTimeout(timeout);
@@ -1603,41 +1685,20 @@ export class TeleCryptIOStorage {
         }
         let data;
         try {
-            // matrix-encrypt-attachment's supported AES-CTR v1/v2 formats are
-            // size-preserving: decryption allocates exactly the ciphertext length.
-            // The ciphertext reader above therefore bounds the allocation before
-            // entering the non-streaming third-party decryptor; the authenticated
-            // event size is also rejected before decryption when present.
-            if (ciphertext.byteLength > MAX_MEDIA_FILE_BYTES)
-                throw new FileTooLargeError();
             data = await decryptAttachment(ciphertext, info);
         }
         catch (error) {
             if (error instanceof FileTooLargeError)
                 throw error;
-            throw new Error("media decryption failed");
+            throw new Error("media decryption failed", { cause: error });
         }
+        if (data.byteLength > MAX_MEDIA_FILE_BYTES)
+            throw new FileTooLargeError();
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
-        const eventContent = (await branch.getFileEvent()).getContent();
-        if (signal?.aborted)
-            throw new StorageError("operation cancelled");
-        if (!isRecord(eventContent))
-            throw new Error("media metadata is invalid");
-        const infoBlock = isRecord(eventContent["info"])
-            ? eventContent["info"]
-            : undefined;
-        const mimetype = typeof infoBlock?.["mimetype"] === "string"
-            ? infoBlock["mimetype"]
-            : "application/octet-stream";
-        try {
-            validateMimetype(mimetype);
-        }
-        catch {
-            throw new Error("media metadata is invalid");
+        if (declaredSize !== null && data.byteLength !== declaredSize) {
+            throw new StorageError("media metadata size does not match decrypted file");
         }
-        if (data.byteLength > MAX_MEDIA_FILE_BYTES)
-            throw new FileTooLargeError();
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
         return { data, mimetype };