@telecrypt-io/storage 0.9.0 → 0.9.3

package/dist/TeleCryptIOStorage.js

@@ -1,15 +1,18 @@
-import { ClientEvent, createClient, EventType, MatrixEvent, MatrixError, MsgType, Preset, RoomCreateTypeField, RoomType, SyncState, UNSTABLE_MSC3088_ENABLED, UNSTABLE_MSC3088_PURPOSE, UNSTABLE_MSC3089_BRANCH, UNSTABLE_MSC3089_LEAF, UNSTABLE_MSC3089_TREE_SUBTYPE, } from "matrix-js-sdk";
+import { ClientEvent, createClient, EventType, JoinRule, MatrixEvent, MatrixError, MsgType, Preset, RoomCreateTypeField, RoomType, SyncState, UNSTABLE_MSC3088_ENABLED, UNSTABLE_MSC3088_PURPOSE, UNSTABLE_MSC3089_BRANCH, UNSTABLE_MSC3089_LEAF, UNSTABLE_MSC3089_TREE_SUBTYPE, } from "matrix-js-sdk";
 import { Method } from "matrix-js-sdk/lib/http-api/method.js";
 import { ClientPrefix } from "matrix-js-sdk/lib/http-api/prefix.js";
 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 { FileTooLargeError, RecoveryAlreadyConfiguredError, RecoveryRestoreError, RecoverySetupAmbiguousError, RecoverySetupError, RecoveryRestoreAmbiguousError, MutationOutcomeUnknownError, MutationPartialError, RoomCreationAmbiguousError, RoomCleanupIncompleteError, StorageError, UndecryptableFileError, } from "./core/errors.js";
 import { MAX_MEDIA_FILE_BYTES, MAX_MATRIX_IDENTIFIER_BYTES, validateCanonicalMatrixUserId, validateMatrixDeviceId, validateMatrixEventId, validateMatrixRoomId, } from "./core/constants.js";
 import { cancelResponseBody, raceWithAbort, readMediaResponseBody, readResponseBody, ResponseBodyReadError, } from "./core/http.js";
 import { sanitizeDiagnosticText } from "./core/oidc.js";
-import { validateName } from "./core/validation.js";
+import { isStorageTreeRoom, isStorageTreeState, STORAGE_ROOM_ENCRYPTION_ALGORITHM, validateName, } from "./core/validation.js";
+import { ConditionTimeoutError, waitForCondition } from "./core/poll.js";
 import { isTreeDeleted } from "./deletion-markers.js";
 import { DecryptionKeySafe } from "./key-safe.js";
+import { prepareReaderHistorySharing } from "./sharing.js";
+import { deleteOwnedMedia } from "./media.js";
 const STORAGE_METADATA_EVENT_TYPE = "io.telecrypt.storage.metadata";
 const STORAGE_METADATA_MSGTYPE = "io.telecrypt.storage.metadata";
 const GENERIC_TREE_NAME = "Encrypted storage";
@@ -357,7 +360,7 @@ function parseMatrixStateResponse(value) {
 function parseMatrixPowerLevels(value) {
     if (!isRecord(value))
         throw new Error("invalid Matrix power-level response");
-    for (const name of ["users_default", "events_default"]) {
+    for (const name of ["users_default", "events_default", "state_default"]) {
         const field = value[name];
         if (field !== undefined && (typeof field !== "number" || !Number.isFinite(field))) {
             throw new Error("invalid Matrix power-level response");
@@ -481,9 +484,16 @@ export class TeleCryptIOStorage {
         return ownerId;
     }
     async sendEncryptedMetadataMessage(roomId, content) {
+        await this.refreshRoomState(roomId);
+        this.requireEncryptedStorageRoom(roomId);
         const response = await this.client.sendMessage(roomId, content);
         return validateMatrixEventId(response?.event_id, "storage metadata response event ID");
     }
+    requireEncryptedStorageRoom(roomId) {
+        if (!isStorageTreeRoom(this.client.getRoom(roomId))) {
+            throw new StorageError("storage room encryption is unavailable or unsupported");
+        }
+    }
     async readEncryptedMetadataMessage(roomId, eventId, allowRedacted = false) {
         const rawEvent = await this.client.fetchRoomEvent(roomId, eventId);
         const event = this.client.getEventMapper()(rawEvent);
@@ -515,8 +525,7 @@ export class TeleCryptIOStorage {
         await this.client.sendStateEvent(roomId, STORAGE_METADATA_EVENT_TYPE, { event_id: metadataEventId }, "");
         this.treeNames.set(roomId, name);
     }
-    /** Resolves an encrypted vault/folder name through its pointer state event. */
-    async getTreeName(roomId, options) {
+    async getTreeMetadataEvent(roomId, options) {
         if (options?.signal?.aborted)
             throw new StorageError("operation cancelled");
         await this.refreshRoomState(roomId, options);
@@ -529,9 +538,22 @@ export class TeleCryptIOStorage {
             throw new StorageError("encrypted storage name is unavailable");
         }
         const metadataEventId = validateMatrixEventId(pointerContent.event_id, "storage metadata event ID");
+        const event = await this.readEncryptedMetadataMessage(roomId, metadataEventId);
+        const content = event.getContent();
+        if (!isRecord(content) ||
+            content.msgtype !== STORAGE_METADATA_MSGTYPE ||
+            typeof content.body !== "string" ||
+            Object.hasOwn(content, "file_event_id")) {
+            throw new StorageError("encrypted storage name is invalid or unavailable");
+        }
+        validateName(content.body, "name");
+        return event;
+    }
+    /** Resolves an encrypted vault/folder name through its pointer state event. */
+    async getTreeName(roomId, options) {
         let event;
         try {
-            event = await this.readEncryptedMetadataMessage(roomId, metadataEventId);
+            event = await this.getTreeMetadataEvent(roomId, options);
         }
         catch (error) {
             // A new device can list storage before restoring room keys. Keep the
@@ -541,16 +563,78 @@ export class TeleCryptIOStorage {
             throw error;
         }
         const content = event.getContent();
-        if (!isRecord(content) ||
-            content.msgtype !== STORAGE_METADATA_MSGTYPE ||
-            typeof content.body !== "string" ||
-            Object.hasOwn(content, "file_event_id")) {
-            throw new StorageError("encrypted storage name is invalid or unavailable");
-        }
-        validateName(content.body, "name");
         this.treeNames.set(roomId, content.body);
         return content.body;
     }
+    /**
+     * Waits for the current encrypted vault/folder name, or file metadata, to
+     * have its session in the active native key backup. Checks the exact session
+     * even when encryption reuses a key and the backup engine emits no new event.
+     */
+    async waitForKeyBackup(treeId, fileId, options) {
+        validateMatrixRoomId(treeId);
+        if (fileId !== undefined)
+            validateMatrixEventId(fileId, "file event ID");
+        const timeoutMs = matrixRequestTimeout({ timeoutMs: options?.timeoutMs ?? options?.localTimeoutMs ?? 20_000 });
+        const signal = matrixRequestSignal(options);
+        const crypto = this.client.getCrypto();
+        if (!crypto)
+            throw new StorageError("crypto is not initialized");
+        let sessionId;
+        try {
+            await waitForCondition(async (signal) => {
+                if (!sessionId) {
+                    let event;
+                    if (fileId === undefined) {
+                        event = await this.getTreeMetadataEvent(treeId, { signal });
+                    }
+                    else {
+                        const metadataId = await this.getFileMetadataEventId(treeId, fileId, { signal });
+                        if (!metadataId)
+                            throw new StorageError("encrypted file name is unavailable");
+                        event = metadataId === fileId
+                            ? await this.getOriginalFileEvent(treeId, fileId)
+                            : await this.getFileRenameMetadataEvent(treeId, fileId, metadataId);
+                    }
+                    const wire = event.getWireContent();
+                    if (event.isRedacted() || event.isDecryptionFailure() ||
+                        wire.algorithm !== STORAGE_ROOM_ENCRYPTION_ALGORITHM || typeof wire.session_id !== "string" || !wire.session_id) {
+                        throw new StorageError("encrypted storage session is unavailable");
+                    }
+                    sessionId = wire.session_id;
+                }
+                if (signal?.aborted)
+                    throw new StorageError("operation cancelled");
+                const version = await crypto.getActiveSessionBackupVersion();
+                if (!version)
+                    return null;
+                let backup;
+                try {
+                    backup = await this.client.http.authedRequest(Method.Get, `/room_keys/keys/${encodeURIComponent(treeId)}/${encodeURIComponent(sessionId)}`, { version }, undefined, { prefix: ClientPrefix.V3, abortSignal: signal });
+                }
+                catch (error) {
+                    if (error instanceof MatrixError && error.httpStatus === 404 && error.errcode === "M_NOT_FOUND")
+                        return null;
+                    throw error;
+                }
+                const sessionData = isRecord(backup) ? backup.session_data : undefined;
+                if (!isRecord(backup) || !Number.isSafeInteger(backup.first_message_index) ||
+                    backup.first_message_index < 0 || !isRecord(sessionData) ||
+                    ["ciphertext", "ephemeral", "mac"].some((key) => typeof sessionData[key] !== "string" || !sessionData[key])) {
+                    throw new StorageError("server key backup session is invalid");
+                }
+                return true;
+            }, { timeoutMs, signal });
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new StorageError("operation cancelled", { cause: error });
+            if (error instanceof ConditionTimeoutError) {
+                throw new StorageError("key backup did not settle before timeout; retry key backup", { cause: error });
+            }
+            throw error;
+        }
+    }
     async writeFileName(treeId, fileId, name) {
         validateName(name, "file name");
         validateMatrixEventId(fileId, "file event ID");
@@ -661,30 +745,129 @@ export class TeleCryptIOStorage {
         }
         return event;
     }
-    async createEncryptedFile(treeId, name, encryptedContents, info, additionalContent) {
+    async createEncryptedFile(treeId, name, encryptedContents, info, additionalContent, signal) {
         validateFileName(name);
+        // Authoritative room refresh also repairs legacy owner permissions before
+        // publishing new encrypted content to an existing vault.
+        await this.refreshRoomState(treeId, { signal });
+        if (signal?.aborted)
+            throw new StorageError("operation cancelled");
+        this.requireEncryptedStorageRoom(treeId);
         const bytes = encryptedContents instanceof Uint8Array
             ? encryptedContents
             : new Uint8Array(encryptedContents);
         const body = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
-        const uploaded = await this.client.uploadContent(body, { includeFilename: false });
-        if (typeof uploaded.content_uri !== "string" || uploaded.content_uri.length === 0) {
-            throw new StorageError("encrypted media upload returned no content URI");
-        }
-        const fileInfo = { ...info, url: uploaded.content_uri };
-        const fileContent = {
-            ...additionalContent,
-            msgtype: MsgType.File,
-            body: name,
-            url: uploaded.content_uri,
-            file: fileInfo,
-            [UNSTABLE_MSC3089_LEAF.name]: {},
-        };
-        const sent = await this.client.sendMessage(treeId, fileContent);
-        const fileEventId = validateMatrixEventId(sent?.event_id, "file upload response event ID");
-        await this.client.sendStateEvent(treeId, UNSTABLE_MSC3089_BRANCH.name, { active: true, metadata_event_id: fileEventId }, fileEventId);
-        this.fileNames.set(this.fileNameKey(treeId, fileEventId), name);
-        return { event_id: fileEventId };
+        let mediaId;
+        let fileId;
+        try {
+            const uploaded = await this.client.uploadContent(body, { includeFilename: false });
+            if (typeof uploaded.content_uri !== "string" || uploaded.content_uri.length === 0) {
+                throw new StorageError("encrypted media upload returned no content URI");
+            }
+            mediaId = uploaded.content_uri;
+            if (signal?.aborted)
+                throw new StorageError("operation cancelled");
+            const fileContent = {
+                ...additionalContent,
+                msgtype: MsgType.File,
+                body: name,
+                url: mediaId,
+                file: { ...info, url: mediaId },
+                [UNSTABLE_MSC3089_LEAF.name]: {},
+            };
+            const sent = await this.client.sendMessage(treeId, fileContent);
+            fileId = validateMatrixEventId(sent?.event_id, "file upload response event ID");
+            if (signal?.aborted)
+                throw new StorageError("operation cancelled");
+            await this.client.sendStateEvent(treeId, UNSTABLE_MSC3089_BRANCH.name, { active: true, metadata_event_id: fileId }, fileId);
+            if (signal?.aborted)
+                throw new StorageError("operation cancelled");
+            this.fileNames.set(this.fileNameKey(treeId, fileId), name);
+            return { event_id: fileId };
+        }
+        catch (error) {
+            const rejected = error instanceof MatrixError &&
+                error.httpStatus !== undefined && error.httpStatus >= 400 && error.httpStatus < 500 && error.httpStatus !== 408;
+            if (!mediaId) {
+                if (rejected)
+                    throw error;
+                throw new MutationOutcomeUnknownError("file upload", { cause: error });
+            }
+            let cause = error;
+            if (rejected) {
+                try {
+                    await this.cleanupFileUpload(treeId, mediaId, fileId);
+                }
+                catch (cleanupError) {
+                    cause = new AggregateError([error, cleanupError], "file upload failed and cleanup is incomplete");
+                }
+                if (cause === error) {
+                    throw new StorageError("file upload was rejected; uploaded media and attachment were removed", { cause: error });
+                }
+            }
+            throw new MutationPartialError("file upload", fileId ? [mediaId, fileId] : [mediaId], `upload outcome needs reconciliation in ${treeId}; keep these media and attachment IDs and use cleanupFileUpload before uploading again`, { cause, treeId });
+        }
+    }
+    /**
+     * Discards a partial upload using its MutationPartialError.completedIds:
+     * [mediaId, fileId?]. Explicit cleanup also covers an unacknowledged listing.
+     * Keep the same IDs after failure and retry this operation, not the upload.
+     */
+    async cleanupFileUpload(treeId, mediaId, fileId, options) {
+        validateMatrixRoomId(treeId);
+        if (!/^mxc:\/\/[^/]+\/[^/?#]+$/u.test(mediaId))
+            throw new StorageError("invalid media identifier");
+        if (fileId !== undefined)
+            validateMatrixEventId(fileId, "file upload event ID");
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), matrixRequestTimeout(options));
+        const abort = () => controller.abort(options?.signal?.reason);
+        if (options?.signal?.aborted)
+            abort();
+        else
+            options?.signal?.addEventListener("abort", abort, { once: true });
+        try {
+            await raceWithAbort((async () => {
+                if (controller.signal.aborted)
+                    throw new StorageError("operation cancelled");
+                let attachment;
+                let listing = null;
+                if (fileId) {
+                    const raw = await this.client.fetchRoomEvent(treeId, fileId);
+                    attachment = this.client.getEventMapper()(raw);
+                    await this.client.decryptEventIfNeeded(attachment);
+                    const content = attachment.getContent();
+                    if (attachment.getId() !== fileId || attachment.getRoomId() !== treeId ||
+                        attachment.getSender() !== this.client.getUserId() ||
+                        (!attachment.isRedacted() && (attachment.getWireType() !== EventType.RoomMessageEncrypted ||
+                            attachment.getType() !== EventType.RoomMessage || content.msgtype !== MsgType.File ||
+                            !isRecord(content.file) || content.file.url !== mediaId))) {
+                        throw new StorageError("partial upload attachment does not match the current user and media");
+                    }
+                    await this.refreshRoomState(treeId, { signal: controller.signal });
+                    listing = this.getStateEvent(treeId, UNSTABLE_MSC3089_BRANCH.name, fileId);
+                    if (listing && !listing.isRedacted() &&
+                        (listing.getSender() !== this.client.getUserId() || listing.getContent().metadata_event_id !== fileId)) {
+                        throw new StorageError("file changed after upload; use ordinary file deletion");
+                    }
+                }
+                if (controller.signal.aborted)
+                    throw new StorageError("operation cancelled");
+                await deleteOwnedMedia(this.client, [mediaId], controller.signal);
+                if (listing && !listing.isRedacted()) {
+                    await withMatrixMutationAbort(() => this.client.redactEvent(treeId, listing.getId()), controller.signal);
+                }
+                if (attachment && !attachment.isRedacted()) {
+                    await withMatrixMutationAbort(() => this.client.redactEvent(treeId, fileId), controller.signal);
+                }
+                if (fileId)
+                    this.fileNames.delete(this.fileNameKey(treeId, fileId));
+            })(), controller.signal, () => new MutationOutcomeUnknownError("file upload cleanup"));
+        }
+        finally {
+            clearTimeout(timeout);
+            options?.signal?.removeEventListener("abort", abort);
+        }
     }
     /**
      * Refreshes a room's current state from the homeserver. The background sync
@@ -703,6 +886,11 @@ export class TeleCryptIOStorage {
             abortSignal: matrixRequestSignal(options),
         });
         const parsedStateEvents = parseMatrixStateResponse(stateEvents);
+        if (await this.repairOwnedTreePermissions(roomId, parsedStateEvents, options)) {
+            // Read the accepted native state back instead of fabricating a local
+            // permission snapshot. An interrupted repair retries on the next load.
+            return this.refreshRoomState(roomId, options);
+        }
         if (typeof room.currentState.setStateEvents === "function") {
             const refreshed = parsedStateEvents.map((event) => new MatrixEvent(event));
             // RoomState.setStateEvents overwrites matching tuples, but deliberately
@@ -730,6 +918,49 @@ export class TeleCryptIOStorage {
             room.currentState.setStateEvents(refreshed);
         }
     }
+    async repairOwnedTreePermissions(roomId, state, options) {
+        if (isTreeDeleted(this.client, roomId))
+            return false;
+        const event = (type, key = "") => state.find((item) => item.type === type && item.state_key === key);
+        const create = event(EventType.RoomCreate);
+        const purpose = event(UNSTABLE_MSC3088_PURPOSE.name, UNSTABLE_MSC3089_TREE_SUBTYPE.name);
+        const encryption = event(EventType.RoomEncryption);
+        if (!isStorageTreeState(create?.content, purpose?.content, encryption?.content))
+            return false;
+        const userId = this.client.getUserId();
+        if (!userId || create?.sender !== userId ||
+            event(EventType.RoomMember, userId)?.content?.membership !== "join") {
+            return false;
+        }
+        const rawPower = event(EventType.RoomPowerLevels)?.content;
+        const power = parseMatrixPowerLevels(rawPower);
+        const ownerLevel = power.events?.[EventType.RoomPowerLevels] ?? 100;
+        if ((power.users?.[userId] ?? power.users_default ?? 0) < ownerLevel)
+            return false;
+        const events = { ...power.events };
+        let changed = (power.state_default ?? 50) < 100;
+        for (const type of [EventType.RoomJoinRules, UNSTABLE_MSC3088_PURPOSE.name]) {
+            if (events[type] !== undefined && events[type] < 100) {
+                events[type] = 100;
+                changed = true;
+            }
+        }
+        if (changed) {
+            await withMatrixMutationAbort(() => this.client.sendStateEvent(roomId, EventType.RoomPowerLevels, {
+                ...rawPower,
+                state_default: Math.max(power.state_default ?? 50, 100),
+                events,
+            }, ""), matrixRequestSignal(options));
+        }
+        const joinRules = event(EventType.RoomJoinRules)?.content;
+        if (joinRules?.join_rule !== "invite") {
+            await withMatrixMutationAbort(() => this.client.sendStateEvent(roomId, EventType.RoomJoinRules, {
+                join_rule: JoinRule.Invite,
+            }, ""), matrixRequestSignal(options));
+            changed = true;
+        }
+        return changed;
+    }
     /**
      * Recommended entry point: builds the MatrixClient with a persistent crypto
      * store and the secret-storage callback wiring `keys.*` needs, starts the
@@ -1307,7 +1538,7 @@ export class TeleCryptIOStorage {
                 kick: 100,
                 ban: 100,
                 redact: 100,
-                state_default: 0,
+                state_default: 100,
                 events_default: 0,
                 users_default: 0,
                 events: {
@@ -1336,7 +1567,7 @@ export class TeleCryptIOStorage {
                 {
                     type: EventType.RoomEncryption,
                     state_key: "",
-                    content: { algorithm: "m.megolm.v1.aes-sha2" },
+                    content: { algorithm: STORAGE_ROOM_ENCRYPTION_ALGORITHM },
                 },
             ],
         };
@@ -1349,8 +1580,9 @@ export class TeleCryptIOStorage {
                 throw new StorageError("operation cancelled");
             try {
                 const tree = this.client.unstableGetFileTreeSpace(roomId);
-                if (tree)
+                if (tree && isStorageTreeRoom(this.client.getRoom(roomId))) {
                     return this.decorateTreeSpace(tree);
+                }
             }
             catch (error) {
                 lastError = error;
@@ -1390,13 +1622,29 @@ export class TeleCryptIOStorage {
             return tree;
         this.decoratedTreeSpaces.add(tree);
         const originalGetDirectories = tree.getDirectories.bind(tree);
+        const originalGetDirectory = typeof tree.getDirectory === "function"
+            ? tree.getDirectory.bind(tree)
+            : undefined;
         const originalListFiles = typeof tree.listFiles === "function"
             ? tree.listFiles.bind(tree)
             : () => [];
         const originalGetFile = typeof tree.getFile === "function"
             ? tree.getFile.bind(tree)
             : () => null;
-        tree.getDirectories = () => originalGetDirectories().map((child) => this.decorateTreeSpace(child));
+        tree.getDirectories = () => originalGetDirectories()
+            .filter((child) => !isTreeDeleted(this.client, child.id) &&
+            isStorageTreeRoom(this.client.getRoom(child.id)))
+            .map((child) => this.decorateTreeSpace(child));
+        if (originalGetDirectory) {
+            tree.getDirectory = (roomId) => {
+                const child = originalGetDirectory(roomId);
+                return child &&
+                    !isTreeDeleted(this.client, child.id) &&
+                    isStorageTreeRoom(this.client.getRoom(child.id))
+                    ? this.decorateTreeSpace(child)
+                    : undefined;
+            };
+        }
         tree.createDirectory = (name) => this.createSubtree(tree, name);
         tree.setName = (name) => this.writeTreeName(tree.id, name);
         tree.listFiles = () => originalListFiles().map((branch) => this.decorateFileBranch(tree.id, branch));
@@ -1404,7 +1652,7 @@ export class TeleCryptIOStorage {
             const branch = originalGetFile(fileId);
             return branch ? this.decorateFileBranch(tree.id, branch) : null;
         };
-        tree.createFile = (name, encryptedContents, info, additionalContent) => this.createEncryptedFile(tree.id, name, encryptedContents, info, additionalContent);
+        tree.createFile = (name, encryptedContents, info, additionalContent, signal) => this.createEncryptedFile(tree.id, name, encryptedContents, info, additionalContent, signal);
         return tree;
     }
     decorateFileBranch(treeId, branch) {
@@ -1559,9 +1807,17 @@ export class TeleCryptIOStorage {
                 throw new StorageError("operation cancelled");
             if (isTreeDeleted(this.client, room.roomId))
                 continue;
-            const tree = this.client.unstableGetFileTreeSpace(room.roomId);
-            if (tree)
-                trees.push(this.decorateTreeSpace(tree));
+            let tree = this.getTree(room.roomId);
+            if (tree) {
+                // Existing owner sessions repair the persisted permissions on load;
+                // readers never attempt this owner-only mutation.
+                if (this.getStateEvent(room.roomId, EventType.RoomCreate, "")?.getSender() === this.client.getUserId()) {
+                    await this.refreshRoomState(room.roomId, { signal });
+                    tree = this.getTree(room.roomId);
+                }
+                if (tree)
+                    trees.push(tree);
+            }
         }
         return trees;
     }
@@ -1573,6 +1829,9 @@ export class TeleCryptIOStorage {
             const currentParent = this.getTree(parent.id);
             if (!currentParent)
                 throw new Error("createSubtree: parent is unavailable");
+            const readers = (await this.listMembers(currentParent, { signal: effectiveSignal }))
+                .filter((member) => member.role === "viewer" &&
+                (member.membership === "join" || member.membership === "invite"));
             const tree = await this.createTreeSpace(name, "createSubtree", effectiveSignal);
             let parentLinkAttempted = false;
             let parentLinkEventId;
@@ -1599,7 +1858,6 @@ export class TeleCryptIOStorage {
                 if (this.client.getRoom(tree.id)) {
                     await this.refreshRoomState(tree.id, { signal: effectiveSignal });
                 }
-                return tree;
             }
             catch (error) {
                 // Compensation is independent of the caller's cancelled deadline.
@@ -1691,11 +1949,29 @@ export class TeleCryptIOStorage {
                 }
                 throw error;
             }
+            // The folder and both links now exist. A failed invitation must leave
+            // that known folder available for reconciliation instead of deleting a
+            // room to which another reader may already have received access.
+            try {
+                for (const reader of readers) {
+                    if (effectiveSignal?.aborted)
+                        throw new StorageError("operation cancelled");
+                    const verifyHistorySharing = await prepareReaderHistorySharing(this.client, reader.userId);
+                    await withMatrixMutationAbort(() => tree.invite(reader.userId), effectiveSignal);
+                    await verifyHistorySharing();
+                }
+            }
+            catch (error) {
+                throw new MutationPartialError("create folder", [tree.id], "the folder was created, but reader access is incomplete; retry sharing the parent vault with its readers", { cause: error });
+            }
+            return tree;
         }, signal);
     }
     getTree(roomId) {
         if (isTreeDeleted(this.client, roomId))
             return null;
+        if (!isStorageTreeRoom(this.client.getRoom(roomId)))
+            return null;
         const tree = this.client.unstableGetFileTreeSpace(roomId);
         return tree ? this.decorateTreeSpace(tree) : null;
     }
@@ -1779,19 +2055,19 @@ export class TeleCryptIOStorage {
             throw new StorageError("operation cancelled");
         let response;
         try {
-            response = await withMatrixMutationAbort(() => tree.createFile(name, new Uint8Array(encrypted.data), encrypted.info, { info: { mimetype, size: data.byteLength } }), signal, "file upload");
+            // Let the in-flight request settle so the uploader can retain returned
+            // media/event IDs on cancellation, then stop before the next write.
+            response = await tree.createFile(name, new Uint8Array(encrypted.data), encrypted.info, { info: { mimetype, size: data.byteLength } }, signal);
         }
         catch (error) {
-            // A transport failure after the encrypted event was submitted cannot be
-            // distinguished from a failure before commit. Do not let a caller retry
-            // this operation and create a duplicate file; only the explicit typed
-            // mutation outcome is safe to propagate unchanged.
-            if (error instanceof MutationOutcomeUnknownError)
+            // Preserve acknowledged upload stages after cancellation as well.
+            if (error instanceof MutationOutcomeUnknownError || error instanceof MutationPartialError)
                 throw error;
+            if (error instanceof StorageError || error instanceof MatrixError)
+                throw error;
+            // An unclassified transport failure can still follow a committed event.
             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");
         }
@@ -1832,7 +2108,7 @@ export class TeleCryptIOStorage {
         const mimetype = eventMetadata.mimetype ?? "application/octet-stream";
         const mxcUrl = info.url;
         const clientAny = this.client;
-        const accessToken = clientAny.getAccessToken();
+        let accessToken = clientAny.getAccessToken();
         validateMatrixToken(accessToken);
         let trustedOrigin;
         try {
@@ -1866,6 +2142,7 @@ export class TeleCryptIOStorage {
         else
             signal?.addEventListener("abort", abortExternal, { once: true });
         let ciphertext;
+        let retriedAuthentication = false;
         try {
             for (;;) {
                 const res = await raceWithAbort(fetch(currentUrl, {
@@ -1908,13 +2185,22 @@ export class TeleCryptIOStorage {
                 if (!res.ok) {
                     const statusFailure = new Error(`media download failed: ${res.status}`);
                     let detail = "";
+                    let unknownToken = false;
                     try {
                         // 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));
+                        const responseText = new TextDecoder().decode(body.bytes);
+                        detail = sanitizeDiagnosticText(responseText);
+                        if (res.status === 401) {
+                            try {
+                                const errorBody = JSON.parse(responseText);
+                                unknownToken = isRecord(errorBody) && errorBody.errcode === "M_UNKNOWN_TOKEN";
+                            }
+                            catch { /* Non-Matrix errors retain the complete diagnostic below. */ }
+                        }
                     }
                     catch (bodyError) {
                         const partial = bodyError instanceof ResponseBodyReadError
@@ -1925,6 +2211,20 @@ export class TeleCryptIOStorage {
                             : bodyError;
                         throw new AggregateError([statusFailure, readFailure], "media download failed while reading the response body", { cause: statusFailure });
                     }
+                    if (unknownToken && !retriedAuthentication) {
+                        retriedAuthentication = true;
+                        // Matrix's authenticated transport owns token refresh, including
+                        // concurrent refreshes and persistence. Its media request path
+                        // buffers the whole body and follows redirects, so use a small
+                        // authenticated read to renew the session, then retry our bounded
+                        // streaming download once with the current token.
+                        await raceWithAbort(this.client.whoami(), controller.signal, () => signal?.aborted
+                            ? new StorageError("operation cancelled")
+                            : new Error("media download timed out"));
+                        accessToken = clientAny.getAccessToken();
+                        validateMatrixToken(accessToken);
+                        continue;
+                    }
                     throw new Error(`${statusFailure.message}${detail === "" ? "" : `: ${detail}`}`);
                 }
                 if (!res.body) {

package/dist/core/errors.d.ts

@@ -36,12 +36,16 @@ export declare class MutationOutcomeUnknownError extends StorageError {
     readonly operation: string;
     constructor(operation?: string, options?: ErrorOptions);
 }
-/** A multi-room mutation committed some work before a later step failed. */
+/** A multi-step mutation committed some work before a later step failed. */
 export declare class MutationPartialError extends StorageError {
     readonly code: "MUTATION_PARTIAL";
     readonly operation: string;
     readonly completedIds: readonly string[];
-    constructor(operation: string, completedIds: readonly string[], detail?: string, options?: ErrorOptions);
+    /** Room containing the partial mutation, when the operation can target a nested folder. */
+    readonly treeId?: string;
+    constructor(operation: string, completedIds: readonly string[], detail?: string, options?: ErrorOptions & {
+        treeId?: string;
+    });
 }
 /** A vault or folder still contains files or child folders. */
 export declare class NonEmptyTreeError extends StorageError {

package/dist/core/errors.js

@@ -58,16 +58,19 @@ export class MutationOutcomeUnknownError extends StorageError {
         this.operation = operation;
     }
 }
-/** A multi-room mutation committed some work before a later step failed. */
+/** A multi-step mutation committed some work before a later step failed. */
 export class MutationPartialError extends StorageError {
     code = "MUTATION_PARTIAL";
     operation;
     completedIds;
+    /** Room containing the partial mutation, when the operation can target a nested folder. */
+    treeId;
     constructor(operation, completedIds, detail, options) {
         super(`${operation} failed after partial completion${detail ? `: ${detail}` : ""}; retry to reconcile current state`, options);
         this.name = "MutationPartialError";
         this.operation = operation;
         this.completedIds = [...completedIds];
+        this.treeId = options?.treeId;
     }
 }
 /** A vault or folder still contains files or child folders. */

package/dist/core/oidc.d.ts

@@ -30,9 +30,9 @@ export interface OidcRegistrationClientMetadata {
 }
 /** The issuer-bound endpoints accepted by the token refresh adapter. */
 export type OidcTokenEndpointMetadata = Pick<OidcClientConfig, "issuer" | "token_endpoint" | "revocation_endpoint">;
-/** Keep provider diagnostics useful without allowing credentials, customer
- * identifiers, or control characters from an untrusted response to cross the
- * SDK boundary. */
+/** Redact recognized secret fields and identifiers in provider diagnostics.
+ * Structured JSON uses decoded property names at every depth; the text fallback
+ * is limited to patterns recognized in unstructured input. */
 export declare function sanitizeDiagnosticText(value: string): string;
 /** Validates an endpoint against the configured homeserver and optional issuer path. */
 export declare function assertOidcEndpoint(value: unknown, trustedHomeserver: string, name: string, issuer?: URL, allowQuery?: boolean): string;