@telecrypt-io/storage 0.8.0 → 0.9.2

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);
 }
@@ -303,7 +304,8 @@ function isActiveRelationEvent(event) {
         !Array.isArray(content) &&
         Object.keys(content).length > 0);
 }
-function activeTreeDirectories(client, tree) {
+async function activeTreeDirectories(storage, tree, signal) {
+    const client = storage.getClient();
     const childEvents = readRelationEvents(client, tree.id, EventType.SpaceChild);
     if (childEvents === null)
         throw new StorageError("storage folder state is unavailable");
@@ -316,13 +318,36 @@ function activeTreeDirectories(client, tree) {
             throw new StorageError("storage folder state is inconsistent");
         activeChildIds.add(childId);
     }
-    const knownChildren = new Map(tree.getDirectories().map((child) => [child.id, child]));
-    return [...activeChildIds].map((childId) => {
-        const child = knownChildren.get(childId);
-        if (!child)
-            throw new StorageError("storage folder state is inconsistent");
-        return child;
-    });
+    const directories = await Promise.all([...activeChildIds].map(async (childId) => {
+        if (isMarkedTreeDeleted(storage, childId))
+            return null;
+        try {
+            // The parent room's relationship state can arrive before Matrix SDK's
+            // 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.
+            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)
+                throw new StorageError("operation cancelled");
+            if (error instanceof ConditionTimeoutError) {
+                throw new StorageError("storage folder state is inconsistent");
+            }
+            throw new StorageError("storage folder state lookup failed", { cause: error });
+        }
+    }));
+    return directories.filter((directory) => directory !== null);
 }
 async function unlinkExternalParents(storage, rootId, externalParents, signal) {
     const client = storage.getClient();
@@ -479,9 +504,6 @@ async function deleteRoomDeterministically(storage, roomId, signal) {
 function removeRoomFromLocalStore(client, roomId) {
     client.store?.removeRoom(roomId);
 }
-function isActiveMembership(membership) {
-    return membership === "join" || membership === "invite";
-}
 function isRevocableMembership(membership) {
     return membership === "join" || membership === "invite" || membership === "knock";
 }
@@ -497,6 +519,7 @@ function toArrayBuffer(bytes) {
     return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
 }
 export async function createVault(storage, name, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         let tree;
         try {
@@ -516,6 +539,7 @@ export async function createVault(storage, name, options) {
 }
 /** Top-level vaults only — excludes subdirectories of an existing tree. */
 export async function listVaults(storage, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const trees = await storage.listTrees(signal);
         const topLevel = trees.filter((tree) => tree.isTopLevel);
@@ -533,44 +557,98 @@ export function getMyVaultRole(storage, vaultId) {
         return null;
     return tree.getPermissions(userId);
 }
-export async function joinVault(storage, vaultId, options) {
-    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 };
+    }
+    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(() => storage.getClient().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");
 }
@@ -592,6 +670,7 @@ function isReviewedStorageTreeRoom(room) {
 }
 /** Rooms where this account is invited and the room looks like a file tree. */
 export async function listPendingInvites(storage, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const client = storage.getClient();
         const rooms = client.getRooms();
@@ -628,6 +707,7 @@ export async function listPendingInvites(storage, options) {
 }
 /** Decline a vault invite (same as leaving before join). */
 export async function declineInvite(storage, vaultId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const client = storage.getClient();
         try {
@@ -721,6 +801,7 @@ export async function declineInvite(storage, vaultId, options) {
 }
 /** Invites `userId` to the vault as a reader. */
 export async function shareVault(storage, vaultId, userId, role, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     if (role !== "viewer") {
         throw new StorageError("storage sharing supports viewers only");
     }
@@ -743,6 +824,8 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                 if (currentMembers.some((member) => member.userId === userId && member.role === "owner")) {
                     throw new StorageError("share will not demote an existing owner");
                 }
+                const client = storage.getClient();
+                const verifyHistorySharing = await prepareReaderHistorySharing(client, userId);
                 for (const [index, space] of spaces.entries()) {
                     ensureOperationActive(operation.signal);
                     const members = index === 0
@@ -756,28 +839,18 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                         : await storage.getRoomMembership(space.id, userId, {
                             signal: operation.signal,
                         });
-                    if (isActiveMembership(currentMembership ?? ""))
+                    if (currentMembership === "join")
                         continue;
-                    try {
-                        await withRateLimitRetry(() => withMatrixMutationAbort(() => space.invite(userId), operation.signal), operation.signal);
-                        completedRoomIds.add(space.id);
-                    }
-                    catch (error) {
-                        if (!(error instanceof MatrixError) || error.errcode !== "M_FORBIDDEN")
-                            throw error;
-                        // Synapse may race another invite/join and answer M_FORBIDDEN. Only
-                        // suppress that typed condition after re-reading authoritative
-                        // membership; never infer it from provider-controlled error text.
-                        const membership = await storage.getRoomMembership(space.id, userId, {
-                            signal: operation.signal,
-                        });
-                        if (!isActiveMembership(membership ?? ""))
-                            throw new StorageError("share failed");
-                    }
+                    // Native invite shares the encrypted history before inviting. Retry
+                    // 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, false), operation.signal), operation.signal);
+                    completedRoomIds.add(space.id);
+                    await verifyHistorySharing();
                 }
                 // Storage rooms have one immutable owner power level and readers use
-                // the room's default user level. Inviting is the complete sharing
-                // operation; changing per-user power levels would create editors and
+                // the room's default user level. Changing per-user power levels would create editors and
                 // let metadata authorship drift away from the owner.
             }
             catch (error) {
@@ -790,6 +863,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                     (error.message === "share failed" ||
                         error.message.includes("owner") ||
                         error.message.includes("current user") ||
+                        error.message.includes("Decryption Key Safe") ||
                         error.message === "operation cancelled")) {
                     throw error;
                 }
@@ -804,6 +878,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
     }
 }
 export async function unshareVault(storage, vaultId, userId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     const operation = createOperationDeadline(options);
     const completedRoomIds = new Set();
     try {
@@ -878,6 +953,7 @@ export async function unshareVault(storage, vaultId, userId, options) {
     }
 }
 export async function listMembers(storage, vaultId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, vaultId, signal);
         try {
@@ -891,6 +967,7 @@ export async function listMembers(storage, vaultId, options) {
     });
 }
 export async function listFiles(storage, treeId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, treeId, signal);
         try {
@@ -913,11 +990,12 @@ export async function listFiles(storage, treeId, options) {
 }
 /** Lists the direct child folders of a vault or folder. */
 export async function listSubfolders(storage, parentId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, parentId, signal);
         await storage.refreshRoomState(parentId, { signal });
         ensureOperationActive(signal);
-        const directories = activeTreeDirectories(storage.getClient(), tree)
+        const directories = (await activeTreeDirectories(storage, tree, signal))
             .filter((directory) => !isMarkedTreeDeleted(storage, directory.id));
         return Promise.all(directories.map(async (directory) => ({
             id: directory.id,
@@ -926,6 +1004,7 @@ export async function listSubfolders(storage, parentId, options) {
     });
 }
 export async function createSubfolder(storage, parentId, name, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     validateName(name, "name");
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, parentId, signal);
@@ -971,10 +1050,12 @@ async function renameTree(storage, treeId, name, options) {
 }
 /** Renames a top-level Vault. */
 export async function renameVault(storage, vaultId, name, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return renameTree(storage, vaultId, name, options);
 }
 /** Renames a nested folder. */
 export async function renameFolder(storage, folderId, name, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return renameTree(storage, folderId, name, options);
 }
 async function deleteTree(storage, treeId, options) {
@@ -1038,13 +1119,16 @@ async function deleteTree(storage, treeId, options) {
 }
 /** Deletes a top-level Vault. */
 export async function deleteVault(storage, vaultId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return deleteTree(storage, vaultId, options);
 }
 /** Deletes a nested folder. */
 export async function deleteFolder(storage, folderId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return deleteTree(storage, folderId, options);
 }
 export async function renameFile(storage, treeId, fileId, name, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     validateName(name, "file name");
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, treeId, signal);
@@ -1072,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)
@@ -1094,14 +1170,13 @@ async function deleteFileMedia(storage, mediaIds, signal) {
     }
 }
 export async function deleteFile(storage, treeId, fileId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, treeId, signal);
         if (isMarkedFileDeleted(storage, tree.id, fileId))
             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);
@@ -1110,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 };
             }
@@ -1134,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()) {
@@ -1145,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);
         }
@@ -1184,12 +1262,19 @@ export async function deleteFile(storage, treeId, fileId, options) {
     }, "mutation");
 }
 export async function uploadFile(storage, treeId, name, bytes, mimetype, options) {
-    return withOperationDeadline(options, async (signal) => {
+    await storage.keySafe.requireReady({ signal: options?.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");
@@ -1212,13 +1297,24 @@ 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) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, treeId, signal);
         const branch = await resolveFile(storage, tree, fileId, signal);
@@ -1253,6 +1349,7 @@ function tsToIso(ts) {
     return new Date(ts).toISOString();
 }
 export async function getFileDetails(storage, treeId, fileId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, treeId, signal);
         await resolveFile(storage, tree, fileId, signal);
@@ -1308,9 +1405,11 @@ async function getTreeDetails(storage, treeId, signal) {
 }
 /** Returns details for a top-level Vault. */
 export async function getVaultDetails(storage, vaultId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, (signal) => getTreeDetails(storage, vaultId, signal));
 }
 /** Returns details for a nested folder. */
 export async function getFolderDetails(storage, folderId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, (signal) => getTreeDetails(storage, folderId, signal));
 }

package/dist/core/types.d.ts

@@ -87,3 +87,4 @@ export interface FolderDetails {
     createdAt: string | null;
     memberCount: number | null;
 }
+export type { KeySafeStatus, KeySafeOptions } from "../key-safe.js";

package/dist/key-safe.d.ts

@@ -0,0 +1,62 @@
+import { type MatrixClient } from "matrix-js-sdk";
+export interface KeySafeOptions {
+    signal?: AbortSignal;
+}
+export interface KeySafeStatus {
+    state: "setup-required" | "confirmation-required" | "restore-required" | "ready";
+    recoveryKey?: string;
+}
+export interface KeySafePersistenceOptions {
+    persistentCryptoStore?: boolean;
+    cryptoDatabasePrefix?: string;
+    /** Flush platform crypto persistence before continuing a setup mutation. */
+    onKeySafeStateChanged?: () => Promise<void>;
+}
+type WithKey = <T>(key: Uint8Array<ArrayBuffer>, fn: () => Promise<T>, signal?: AbortSignal) => Promise<T>;
+/** The local saved-key acknowledgement and Matrix's existing encryption setup. */
+export declare class DecryptionKeySafe {
+    private client;
+    private withKey;
+    private options;
+    private startSync?;
+    private memory;
+    private tail;
+    private secretRecordsRefreshed;
+    private refreshedKeyDescriptorId;
+    constructor(client: MatrixClient, withKey: WithKey, options?: KeySafePersistenceOptions, startSync?: ((signal?: AbortSignal) => Promise<void>) | undefined);
+    private active;
+    private crypto;
+    private local;
+    private save;
+    private serial;
+    private refreshAccountData;
+    /**
+     * MatrixClient.getAccountDataFromServer reads its local store after initial
+     * sync. A resumed sync can complete before account-data events reach that
+     * store, so refresh the existing Safe records from the authenticated server
+     * API before native secret-storage code reads them. Seed those exact records
+     * through the public Store API used by Matrix sync itself.
+     */
+    private refreshSecretStorageAccountData;
+    private topology;
+    private serverBackup;
+    private signingReady;
+    getStatus(signal?: AbortSignal): Promise<KeySafeStatus>;
+    requireReady(options?: KeySafeOptions): Promise<void>;
+    /** Re-publish the same native signed records after an interrupted upload. */
+    private publishSigning;
+    private checkSigningCanResume;
+    private configure;
+    setup(signal?: AbortSignal): Promise<{
+        recoveryKey: string;
+    }>;
+    confirmSaved(signal?: AbortSignal): Promise<{
+        state: "ready";
+    }>;
+    restore(recoveryKey: string, signal?: AbortSignal): Promise<{
+        imported: number;
+        total: number;
+        state: "ready";
+    }>;
+}
+export {};