@telecrypt-io/storage 0.9.0 → 0.9.2

package/LICENSE

@@ -2,7 +2,7 @@ Business Source License 1.1
 
 Parameters
 
-Licensor:              TeleCrypt.io
+Licensor:              Alexander Potemkin
 Licensed Work:         TeleCrypt.io Storage
                         The Licensed Work is (c) 2026 TeleCrypt.io
 Additional Use Grant:  You may use, copy, modify, and create derivative

package/README.md

@@ -83,6 +83,18 @@ and a per-file key distributed through the room's Megolm session). The server st
 media and Matrix events, but encryption does not hide all room, event, or other metadata from the
 server or users who can read the room.
 
+If an upload is rejected after media was accepted, the SDK removes that media and any acknowledged
+attachment. A transport failure leaves accepted work intact. An upload `MutationPartialError`
+retains `treeId` and `completedIds` in the order `[mediaId, attachmentEventId?]`. Keep those IDs;
+do not repeat the upload blindly. To discard the partial upload, call
+`core.cleanupFileUpload(storage, error.treeId, error.completedIds[0], error.completedIds[1])`.
+Retry cleanup with the same IDs if it fails. A known attachment ID can also be passed to ordinary
+`core.deleteFile` even when its listing was never committed. An initial media response lost before
+the server returns any identifier still has an unknown outcome and cannot provide cleanup IDs.
+Upload cancellation stops before the next write and waits for the current request's bounded
+settlement so returned media/event IDs are retained. Keep observing the upload promise after
+cancelling a UI wait or closing a view; persist any partial receipt for the originating account.
+
 The Decryption Key Safe is mandatory before the public core storage operations. Inspect
 `storage.keySafe.getStatus(signal?)`. For `setup-required`, call `setup(signal?)`, offer the returned
 `recoveryKey` for copying/saving, explain that losing both this key and local decryption keys can
@@ -93,6 +105,12 @@ room keys and signs the current login using the existing account keys. Normal us
 Setup and restore never replace an existing safe or account signing identity. Resetting the account
 password cannot recover encrypted files.
 
+Short-lived clients should call `storage.waitForKeyBackup(treeId, fileId?, options?)` after creating
+or renaming encrypted metadata and before closing. Omit `fileId` for a vault or folder. This checks
+the exact encryption session in the active server backup, including reused keys that produce no
+new backup-progress event. If verification fails, retain the local profile and retry backup;
+the metadata mutation has already committed.
+
 Pending setup state is kept beside the login's IndexedDB crypto data. A platform that snapshots
 IndexedDB to disk, such as the CLI, must supply `onKeySafeStateChanged` at creation and durably flush
 its snapshot before resolving that callback. Key Safe methods accept an optional `AbortSignal`.
@@ -105,6 +123,17 @@ the SDK checks native recipient-device eligibility afterward and reports partial
 keys could not be shared. An upload restriction can reject the encrypted history bundle upload;
 the error is preserved, including when retrying an existing invitation.
 
+`joinVault` accepts the vault and its linked folder invitations, including their history keys.
+New folders inherit the parent's joined and invited readers; browsing accepts their folder
+invitations. If reader access fails after folder creation, the partial-completion error retains
+the created folder ID. Retry sharing the parent vault to complete access to that folder.
+
+Storage spaces are private and only their creator changes room state. Loading owned trees or
+refreshing their state repairs the permissive defaults emitted by older SDKs and restores
+invite-only joining. The repair preserves membership, unrelated power settings and encryption
+keys; readers do not write it. Owners must use an updated client for their existing trees to be
+repaired. Disabled Storage markers and deleted trees are not restored automatically.
+
 Deletion has strict ordering. Delete files before their folders or vaults because folders and
 vaults must be empty. File deletion removes the encrypted media object before redacting its Matrix
 event and requires TeleCrypt's Synapse storage extension; stock Synapse cannot provide that

package/dist/TeleCryptIOStorage.d.ts

@@ -21,7 +21,7 @@ export interface TreeSpace {
     setPermissions(userId: string, role: string): Promise<void>;
     getFile(fileEventId: string): FileBranch | null;
     listFiles(): FileBranch[];
-    createFile(name: string, encryptedContents: ArrayBuffer | Uint8Array, info: Record<string, unknown>, additionalContent?: Record<string, unknown>): Promise<{
+    createFile(name: string, encryptedContents: ArrayBuffer | Uint8Array, info: Record<string, unknown>, additionalContent?: Record<string, unknown>, signal?: AbortSignal): Promise<{
         event_id: string;
     }>;
 }
@@ -172,8 +172,15 @@ export declare class TeleCryptIOStorage {
     private sendEncryptedMetadataMessage;
     private readEncryptedMetadataMessage;
     private writeTreeName;
+    private getTreeMetadataEvent;
     /** Resolves an encrypted vault/folder name through its pointer state event. */
     getTreeName(roomId: string, options?: MatrixRequestOptions): Promise<string>;
+    /**
+     * 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.
+     */
+    waitForKeyBackup(treeId: string, fileId?: string, options?: MatrixRequestOptions): Promise<void>;
     private writeFileName;
     /** Resolves an encrypted file name from the MSC3089 index pointer. */
     getFileName(treeId: string, fileId: string, options?: MatrixRequestOptions & {
@@ -186,6 +193,12 @@ export declare class TeleCryptIOStorage {
     /** Fetches the original encrypted file message directly by event ID. */
     getOriginalFileEvent(treeId: string, fileId: string, allowRedacted?: boolean): Promise<MatrixEvent>;
     private createEncryptedFile;
+    /**
+     * 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.
+     */
+    cleanupFileUpload(treeId: string, mediaId: string, fileId?: string, options?: MatrixRequestOptions): Promise<void>;
     /**
      * Refreshes a room's current state from the homeserver. The background sync
      * loop is intentionally asynchronous, so a short-lived CLI process can
@@ -193,6 +206,7 @@ export declare class TeleCryptIOStorage {
      * changed a file name or branch.
      */
     refreshRoomState(roomId: string, options?: MatrixRequestOptions): Promise<void>;
+    private repairOwnedTreePermissions;
     /**
      * Recommended entry point: builds the MatrixClient with a persistent crypto
      * store and the secret-storage callback wiring `keys.*` needs, starts the

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 { 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");
@@ -515,8 +518,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 +531,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 +556,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 !== "m.megolm.v1.aes-sha2" || 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 +738,128 @@ 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");
         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 +878,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 +910,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);
+        if (create?.content?.[RoomCreateTypeField] !== RoomType.Space ||
+            purpose?.content?.[UNSTABLE_MSC3088_ENABLED.name] !== true)
+            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 +1530,7 @@ export class TeleCryptIOStorage {
                 kick: 100,
                 ban: 100,
                 redact: 100,
-                state_default: 0,
+                state_default: 100,
                 events_default: 0,
                 users_default: 0,
                 events: {
@@ -1404,7 +1627,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) {
@@ -1560,8 +1783,14 @@ export class TeleCryptIOStorage {
             if (isTreeDeleted(this.client, room.roomId))
                 continue;
             const tree = this.client.unstableGetFileTreeSpace(room.roomId);
-            if (tree)
+            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 });
+                }
                 trees.push(this.decorateTreeSpace(tree));
+            }
         }
         return trees;
     }
@@ -1573,6 +1802,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 +1831,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,6 +1922,22 @@ 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) {
@@ -1779,19 +2026,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 +2079,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 +2113,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 +2156,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 +2182,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/operations.d.ts

@@ -50,6 +50,8 @@ export declare function deleteFolder(storage: TeleCryptIOStorage, folderId: stri
 export declare function renameFile(storage: TeleCryptIOStorage, treeId: string, fileId: string, name: string, options?: OperationOptions): Promise<RenameResult>;
 export declare function deleteFile(storage: TeleCryptIOStorage, treeId: string, fileId: string, options?: OperationOptions): Promise<DeleteResult>;
 export declare function uploadFile(storage: TeleCryptIOStorage, treeId: string, name: string, bytes: Uint8Array, mimetype: string, options?: OperationOptions): Promise<FileInfo>;
+/** Discard the acknowledged stages of a failed upload using its retained IDs. */
+export declare function cleanupFileUpload(storage: TeleCryptIOStorage, treeId: string, mediaId: string, fileId?: string, options?: OperationOptions): Promise<void>;
 export declare function downloadFile(storage: TeleCryptIOStorage, treeId: string, fileId: string, options?: OperationOptions): Promise<DownloadedFile>;
 export declare function setupRecovery(storage: TeleCryptIOStorage, options?: OperationOptions): Promise<RecoverySetup>;
 export declare function restoreRecovery(storage: TeleCryptIOStorage, recoveryKey: string, options?: OperationOptions): Promise<RecoveryRestore>;

package/dist/core/operations.js

@@ -12,12 +12,12 @@
  */
 import { readFileEventMetadata, withMatrixMutationAbort, withTreeMutation, } from "../TeleCryptIOStorage.js";
 import { EventType, MatrixError, RoomCreateTypeField, RoomType, 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 { deleteOwnedMedia } from "../media.js";
 import { validateMatrixEventId } from "./constants.js";
 import { FileTooLargeError, MutationPartialError, MutationOutcomeUnknownError, NonEmptyTreeError, RoomCreationAmbiguousError, RoomCleanupIncompleteError, StorageError, } from "./errors.js";
 import { ConditionTimeoutError, waitForCondition } from "./poll.js";
 import { validateName } from "./validation.js";
+import { prepareReaderHistorySharing } from "../sharing.js";
 import { isFileDeleted, isTreeDeleted, markFileDeleted, markTreeDeleted, } from "../deletion-markers.js";
 /**
  * Production Synapse enforces the built-in rc_messages budget (per-account
@@ -100,6 +100,7 @@ function isRateLimited(error) {
 }
 function requiresMutationReconciliation(error) {
     return (error instanceof MutationOutcomeUnknownError ||
+        error instanceof MutationPartialError ||
         error instanceof RoomCreationAmbiguousError ||
         error instanceof RoomCleanupIncompleteError);
 }
@@ -325,7 +326,17 @@ async function activeTreeDirectories(storage, tree, signal) {
             // MSC3089 TreeSpace projection includes that child. Resolve the exact
             // room named by the active relation instead of treating that brief
             // projection lag as corrupt folder state.
-            return await waitForCondition(() => storage.getTree(childId), { timeoutMs: 15000, signal });
+            let joined = false;
+            return await waitForCondition(async () => {
+                const directory = storage.getTree(childId);
+                if (directory)
+                    return directory;
+                if (!joined && client.getRoom?.(childId)?.getMyMembership?.() === "invite") {
+                    await joinTreeRoom(storage, childId, signal ?? new AbortController().signal);
+                    joined = true;
+                }
+                return null;
+            }, { timeoutMs: 15000, signal });
         }
         catch (error) {
             if (signal?.aborted)
@@ -546,64 +557,98 @@ export function getMyVaultRole(storage, vaultId) {
         return null;
     return tree.getPermissions(userId);
 }
-export async function joinVault(storage, vaultId, options) {
-    await storage.keySafe.requireReady({ signal: options?.signal });
-    return withOperationDeadline(options, async (signal) => {
-        let membership;
+async function joinTreeRoom(storage, vaultId, signal) {
+    let membership;
+    try {
+        membership = await storage.getRoomMembership(vaultId, undefined, { signal });
+    }
+    catch (err) {
+        if (signal.aborted)
+            throw new StorageError("operation cancelled");
+        // Synapse refuses GET /rooms/:room/members for an invited user with
+        // M_FORBIDDEN. That response means the membership preflight cannot
+        // inspect the room yet; it is not evidence that joining is forbidden.
+        // Attempt the idempotent join and let its own response decide access.
+        if (err instanceof MatrixError && err.errcode === "M_FORBIDDEN") {
+            membership = null;
+        }
+        else {
+            throw new StorageError("join failed", { cause: err });
+        }
+    }
+    if (membership === "join")
+        return;
+    const client = storage.getClient();
+    const userId = client.getUserId();
+    if (userId && client.getRoom(vaultId)?.getMember(userId)?.membership !== "invite") {
+        // MatrixClient.joinRoom reads the inviter from its local invite-room
+        // state. A to-device history bundle can arrive first in the initial
+        // sync, before that stripped invite state has reached the room store;
+        // joining without it skips Matrix JS SDK's pending-bundle acceptance.
         try {
-            membership = await storage.getRoomMembership(vaultId, undefined, { signal });
+            await waitForCondition(() => client.getRoom(vaultId)?.getMember(userId)?.membership === "invite" ? true : null, { timeoutMs: 15000, signal });
         }
         catch (err) {
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            // Synapse refuses GET /rooms/:room/members for an invited user with
-            // M_FORBIDDEN. That response means the membership preflight cannot
-            // inspect the room yet; it is not evidence that joining is forbidden.
-            // Attempt the idempotent join and let its own response decide access.
-            if (err instanceof MatrixError && err.errcode === "M_FORBIDDEN") {
-                membership = null;
-            }
-            else {
-                throw new StorageError("join failed", { cause: err });
+            if (err instanceof ConditionTimeoutError) {
+                throw new StorageError("the room invitation has not reached this login yet; retry joining", { cause: err });
             }
+            throw err;
         }
-        if (membership === "join")
-            return { vaultId, joined: true };
-        const client = storage.getClient();
-        const userId = client.getUserId();
-        if (userId && client.getRoom(vaultId)?.getMember(userId)?.membership !== "invite") {
-            // MatrixClient.joinRoom reads the inviter from its local invite-room
-            // state. A to-device history bundle can arrive first in the initial
-            // sync, before that stripped invite state has reached the room store;
-            // joining without it skips Matrix JS SDK's pending-bundle acceptance.
-            try {
-                await waitForCondition(() => client.getRoom(vaultId)?.getMember(userId)?.membership === "invite" ? true : null, { timeoutMs: 15000, signal });
-            }
-            catch (err) {
-                if (signal.aborted)
-                    throw new StorageError("operation cancelled");
-                if (err instanceof ConditionTimeoutError) {
-                    throw new StorageError("the room invitation has not reached this login yet; retry joining", { cause: err });
-                }
-                throw err;
-            }
+    }
+    try {
+        await withRateLimitRetry(() => withMatrixMutationAbort(() => client.joinRoom(vaultId), signal), signal);
+    }
+    catch (err) {
+        if (err instanceof MutationOutcomeUnknownError)
+            throw err;
+        if (err instanceof MatrixError && err.errcode === "M_FORBIDDEN") {
+            const afterForbidden = await storage.getRoomMembership(vaultId, undefined, { signal });
+            if (afterForbidden === "join")
+                return;
         }
+        if (signal.aborted)
+            throw new StorageError("operation cancelled");
+        throw new StorageError("join failed", { cause: err });
+    }
+}
+export async function joinVault(storage, vaultId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
+    return withOperationDeadline(options, async (signal) => {
+        const joined = new Set();
+        const pending = [vaultId];
         try {
-            await withRateLimitRetry(() => withMatrixMutationAbort(() => client.joinRoom(vaultId), signal), signal);
+            while (pending.length > 0) {
+                ensureOperationActive(signal);
+                const roomId = pending.shift();
+                if (joined.has(roomId) || isMarkedTreeDeleted(storage, roomId))
+                    continue;
+                // Keep native joinRoom's inviter/history-bundle handling for every
+                // child. Merely joining the root does not accept its child invites.
+                await joinTreeRoom(storage, roomId, signal);
+                joined.add(roomId);
+                await resolveTree(storage, roomId, signal);
+                await storage.refreshRoomState(roomId, { signal });
+                const children = readRelationEvents(storage.getClient(), roomId, EventType.SpaceChild);
+                if (children === null)
+                    throw new StorageError("storage folder state is unavailable");
+                for (const child of children) {
+                    if (!isActiveRelationEvent(child))
+                        continue;
+                    const childId = relationStateKey(child);
+                    if (!childId)
+                        throw new StorageError("storage folder state is inconsistent");
+                    pending.push(childId);
+                }
+            }
         }
-        catch (err) {
-            if (err instanceof MutationOutcomeUnknownError)
-                throw err;
-            if (err instanceof MatrixError && err.errcode === "M_FORBIDDEN") {
-                const afterForbidden = await storage.getRoomMembership(vaultId, undefined, { signal });
-                if (afterForbidden === "join")
-                    return { vaultId, joined: true };
+        catch (error) {
+            if (joined.size > 0) {
+                throw new MutationPartialError("join", [...joined], "some folders were joined; retry accepting the same vault to finish", { cause: error });
             }
-            if (signal.aborted)
-                throw new StorageError("operation cancelled");
-            throw new StorageError("join failed", { cause: err });
+            throw error;
         }
-        ensureOperationActive(signal);
         return { vaultId, joined: true };
     }, "mutation");
 }
@@ -780,14 +825,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                     throw new StorageError("share will not demote an existing owner");
                 }
                 const client = storage.getClient();
-                const crypto = client.getCrypto();
-                if (!crypto)
-                    throw new StorageError("sharing requires initialized encryption");
-                const recipient = await client.downloadKeysForUsers([userId]);
-                const devices = Object.keys(recipient.device_keys?.[userId] ?? {});
-                if (!recipient.master_keys?.[userId] || !recipient.self_signing_keys?.[userId] || devices.length === 0) {
-                    throw new StorageError("The reader must set up or unlock their Decryption Key Safe before sharing");
-                }
+                const verifyHistorySharing = await prepareReaderHistorySharing(client, userId);
                 for (const [index, space] of spaces.entries()) {
                     ensureOperationActive(operation.signal);
                     const members = index === 0
@@ -807,12 +845,9 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                     // pending invitations too: an earlier attempt may have sent only an
                     // invitation. In particular, never swallow a media-upload 403 merely
                     // because an invitation already exists.
-                    await withRateLimitRetry(() => withMatrixMutationAbort(() => space.invite(userId), operation.signal), operation.signal);
+                    await withRateLimitRetry(() => withMatrixMutationAbort(() => space.invite(userId, false), operation.signal), operation.signal);
                     completedRoomIds.add(space.id);
-                    const statuses = await Promise.all(devices.map((id) => crypto.getDeviceVerificationStatus(userId, id)));
-                    if (!statuses.some((status) => status?.signedByOwner)) {
-                        throw new StorageError("The invitation was sent, but history keys could not be shared; the reader must unlock their Decryption Key Safe, then retry sharing");
-                    }
+                    await verifyHistorySharing();
                 }
                 // Storage rooms have one immutable owner power level and readers use
                 // the room's default user level. Changing per-user power levels would create editors and
@@ -1121,18 +1156,10 @@ export async function renameFile(storage, treeId, fileId, name, options) {
         return { id: fileId, name };
     }, "mutation");
 }
-function requireFileDeletionTransport(client) {
-    const http = client.http;
-    if (!http || typeof http.authedRequest !== "function") {
-        throw new StorageError("Matrix HTTP transport unavailable");
-    }
-    return http;
-}
 async function deleteFileMedia(storage, mediaIds, signal) {
     const client = storage.getClient();
-    const http = requireFileDeletionTransport(client);
     try {
-        await withRateLimitRetry(() => withMatrixMutationAbort(() => http.authedRequest(Method.Post, "/io.telecrypt.storage/delete_media", undefined, { media_ids: [...mediaIds] }, { prefix: ClientPrefix.Unstable, rawResponseBody: true, abortSignal: signal }), signal, "delete file media"), signal);
+        await withRateLimitRetry(() => withMatrixMutationAbort(() => deleteOwnedMedia(client, mediaIds, signal), signal, "delete file media"), signal);
     }
     catch (error) {
         if (error instanceof MutationOutcomeUnknownError)
@@ -1150,8 +1177,6 @@ export async function deleteFile(storage, treeId, fileId, options) {
             return { id: fileId, deleted: true };
         await storage.refreshRoomState(treeId, { signal });
         const branch = tree.getFile(fileId);
-        if (!branch)
-            throw new StorageError("file not found");
         let originalEvent;
         try {
             originalEvent = await storage.getOriginalFileEvent(tree.id, fileId, true);
@@ -1160,7 +1185,7 @@ export async function deleteFile(storage, treeId, fileId, options) {
             throw new StorageError("could not resolve encrypted file safely", { cause: error });
         }
         if (originalEvent.isRedacted()) {
-            if (branch.isActive === false) {
+            if (!branch || branch.isActive === false) {
                 markFileDeleted(storage.getClient(), tree.id, fileId);
                 return { id: fileId, deleted: true };
             }
@@ -1184,7 +1209,9 @@ export async function deleteFile(storage, treeId, fileId, options) {
         const completedIds = [mediaId];
         try {
             const client = storage.getClient();
-            const metadataEventId = await storage.getFileMetadataEventId(tree.id, fileId, { signal });
+            const metadataEventId = branch
+                ? await storage.getFileMetadataEventId(tree.id, fileId, { signal })
+                : null;
             if (metadataEventId && metadataEventId !== fileId) {
                 const metadataEvent = await storage.getFileRenameMetadataEvent(tree.id, fileId, metadataEventId);
                 if (!metadataEvent.isRedacted()) {
@@ -1195,16 +1222,17 @@ export async function deleteFile(storage, treeId, fileId, options) {
             const currentBranch = tree.getFile(fileId);
             const indexEvent = currentBranch?.indexEvent;
             const listingEventId = indexEvent?.getId();
-            if (!indexEvent || typeof listingEventId !== "string" || listingEventId.length === 0) {
+            if (currentBranch && (!indexEvent || typeof listingEventId !== "string" || listingEventId.length === 0)) {
                 throw new StorageError("encrypted file has no listing event identifier");
             }
-            if (!indexEvent.isRedacted()) {
+            if (indexEvent && !indexEvent.isRedacted()) {
                 if (indexEvent.getSender() !== client.getUserId()) {
                     throw new StorageError("file listing was not authored by the owner");
                 }
                 await withRateLimitRetry(() => withMatrixMutationAbort(() => client.redactEvent(tree.id, listingEventId), signal, "delete file listing"), signal);
             }
-            completedIds.push(listingEventId);
+            if (listingEventId)
+                completedIds.push(listingEventId);
             await withRateLimitRetry(() => withMatrixMutationAbort(() => client.redactEvent(tree.id, fileId), signal, "delete file attachment event"), signal);
             completedIds.push(fileId);
         }
@@ -1235,12 +1263,18 @@ export async function deleteFile(storage, treeId, fileId, options) {
 }
 export async function uploadFile(storage, treeId, name, bytes, mimetype, options) {
     await storage.keySafe.requireReady({ signal: options?.signal });
-    return withOperationDeadline(options, async (signal) => {
+    const deadline = createOperationDeadline(options);
+    try {
+        const signal = deadline.signal;
+        ensureOperationActive(signal);
+        // Unlike a read, an upload must retain a receipt returned by an in-flight
+        // mutation after cancellation. Native HTTP requests remain time-bounded;
+        // the uploader stops before starting another write when this signal aborts.
         const tree = await resolveTree(storage, treeId, signal);
         const fileId = await withRateLimitRetry(() => storage.uploadFile(tree, name, toArrayBuffer(bytes), mimetype, signal), signal).catch((error) => {
             if (error instanceof FileTooLargeError)
                 throw error;
-            if (error instanceof MutationOutcomeUnknownError)
+            if (error instanceof MutationOutcomeUnknownError || error instanceof MutationPartialError)
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
@@ -1263,10 +1297,20 @@ 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", { cause: error });
+            throw new MutationPartialError("upload file", [fileId], "upload completed but the file could not be observed locally", { cause: error, treeId });
         }
         ensureOperationActive(signal);
         return { id: fileId, name, mimetype };
+    }
+    finally {
+        deadline.close();
+    }
+}
+/** Discard the acknowledged stages of a failed upload using its retained IDs. */
+export async function cleanupFileUpload(storage, treeId, mediaId, fileId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
+    return withOperationDeadline(options, async (signal) => {
+        await storage.cleanupFileUpload(treeId, mediaId, fileId, { signal });
     }, "mutation");
 }
 export async function downloadFile(storage, treeId, fileId, options) {

package/dist/media.d.ts

@@ -0,0 +1,3 @@
+import type { MatrixClient } from "matrix-js-sdk";
+/** The policy endpoint authorizes deletion against the uploading user. */
+export declare function deleteOwnedMedia(client: MatrixClient, mediaIds: readonly string[], signal?: AbortSignal): Promise<void>;

package/dist/media.js

@@ -0,0 +1,10 @@
+import { Method } from "matrix-js-sdk/lib/http-api/method.js";
+import { ClientPrefix } from "matrix-js-sdk/lib/http-api/prefix.js";
+import { StorageError } from "./core/errors.js";
+/** The policy endpoint authorizes deletion against the uploading user. */
+export async function deleteOwnedMedia(client, mediaIds, signal) {
+    if (!client.http || typeof client.http.authedRequest !== "function") {
+        throw new StorageError("Matrix HTTP transport unavailable");
+    }
+    await client.http.authedRequest(Method.Post, "/io.telecrypt.storage/delete_media", undefined, { media_ids: [...mediaIds] }, { prefix: ClientPrefix.Unstable, rawResponseBody: true, abortSignal: signal });
+}

package/dist/sharing.d.ts

@@ -0,0 +1,3 @@
+import type { MatrixClient } from "matrix-js-sdk";
+/** Use the same account/device requirements for explicit and inherited sharing. */
+export declare function prepareReaderHistorySharing(client: MatrixClient, userId: string): Promise<() => Promise<void>>;

package/dist/sharing.js

@@ -0,0 +1,18 @@
+import { StorageError } from "./core/errors.js";
+/** Use the same account/device requirements for explicit and inherited sharing. */
+export async function prepareReaderHistorySharing(client, userId) {
+    const crypto = client.getCrypto();
+    if (!crypto)
+        throw new StorageError("sharing requires initialized encryption");
+    const recipient = await client.downloadKeysForUsers([userId]);
+    const devices = Object.keys(recipient.device_keys?.[userId] ?? {});
+    if (!recipient.master_keys?.[userId] || !recipient.self_signing_keys?.[userId] || devices.length === 0) {
+        throw new StorageError("The reader must set up or unlock their Decryption Key Safe before sharing");
+    }
+    return async () => {
+        const statuses = await Promise.all(devices.map((id) => crypto.getDeviceVerificationStatus(userId, id)));
+        if (!statuses.some((status) => status?.signedByOwner)) {
+            throw new StorageError("The invitation was sent, but history keys could not be shared; the reader must unlock their Decryption Key Safe, then retry sharing");
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telecrypt-io/storage",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "license": "BUSL-1.1",
   "type": "module",
   "packageManager": "npm@11.19.0",