@telecrypt-io/storage 0.3.0 → 0.5.7

package/dist/core/operations.js

@@ -1,5 +1,23 @@
-import { StorageError } from "./errors.js";
+/**
+ * Platform-agnostic operations: one function per user-facing action, each
+ * taking an already-created `TeleCryptIOStorage` plus plain inputs and returning
+ * one of the typed results in `./types.ts`. No I/O beyond the Matrix client
+ * itself, no stdout, no `process`, no file paths — bytes in/out are always
+ * `Uint8Array`. All callers run the same tested logic and share the same result
+ * shapes.
+ *
+ * `core/` never creates the `TeleCryptIOStorage`/`MatrixClient` itself — store
+ * config (persistent crypto store, session credentials, etc.) is
+ * platform-specific and stays with the caller.
+ */
+import { withMatrixMutationAbort, withTreeMutation, } from "../TeleCryptIOStorage.js";
+import { EventType, MatrixError, RoomCreateTypeField, RoomType, UNSTABLE_MSC3089_BRANCH, UNSTABLE_MSC3088_ENABLED, UNSTABLE_MSC3088_PURPOSE, UNSTABLE_MSC3089_TREE_SUBTYPE, } from "matrix-js-sdk";
+import { ClientPrefix } from "matrix-js-sdk/lib/http-api/prefix.js";
+import { Method } from "matrix-js-sdk/lib/http-api/method.js";
+import { FileTooLargeError, MutationPartialError, MutationOutcomeUnknownError, NonEmptyTreeError, RoomCreationAmbiguousError, RoomCleanupIncompleteError, StorageError, UndecryptableFileError, } from "./errors.js";
 import { waitForCondition } from "./poll.js";
+import { validateMatrixEventId } from "./constants.js";
+import { validateName } from "./validation.js";
 /**
  * Production Synapse enforces the built-in rc_messages budget (per-account
  * burst 10, refill 1/5s) on every room/state mutation the tree operations
@@ -9,6 +27,77 @@ import { waitForCondition } from "./poll.js";
  * `withRateLimitRetry`; must not mask non-rate-limit failures.
  */
 const RATE_LIMIT_RETRIES = 6;
+const RATE_LIMIT_DEFAULT_DELAY_MS = 15_000;
+const RATE_LIMIT_MAX_DELAY_MS = 30_000;
+const RATE_LIMIT_MAX_TOTAL_DELAY_MS = 90_000;
+const MAX_DELETION_ROOMS = 4096;
+const MAX_DELETION_DEPTH = 128;
+const MAX_FILE_VERSION_CHAIN = 128;
+const MAX_LIST_ITEMS = 10000;
+const DEFAULT_MUTATION_TIMEOUT_MS = 5 * 60_000;
+const MAX_MUTATION_TIMEOUT_MS = 15 * 60_000;
+function createOperationDeadline(options) {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_MUTATION_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_MUTATION_TIMEOUT_MS) {
+        throw new StorageError("invalid operation timeout");
+    }
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(options?.signal?.reason);
+    options?.signal?.addEventListener("abort", onAbort, { once: true });
+    if (options?.signal?.aborted)
+        onAbort();
+    const timer = setTimeout(() => controller.abort(new Error("operation timed out")), timeoutMs);
+    return {
+        signal: controller.signal,
+        close: () => {
+            clearTimeout(timer);
+            options?.signal?.removeEventListener("abort", onAbort);
+        },
+    };
+}
+function ensureOperationActive(signal) {
+    if (signal.aborted)
+        throw new StorageError("operation cancelled");
+}
+async function raceOperationDeadline(deadline, pending, kind) {
+    let onAbort;
+    try {
+        const abort = new Promise((_, reject) => {
+            const abortHandler = () => {
+                reject(kind === "mutation"
+                    ? new MutationOutcomeUnknownError("operation")
+                    : new StorageError("operation cancelled"));
+            };
+            onAbort = abortHandler;
+            deadline.signal.addEventListener("abort", abortHandler, { once: true });
+            if (deadline.signal.aborted)
+                abortHandler();
+        });
+        return await Promise.race([pending, abort]);
+    }
+    finally {
+        if (onAbort)
+            deadline.signal.removeEventListener("abort", onAbort);
+        void pending.catch(() => undefined);
+    }
+}
+async function withOperationDeadline(options, operation, kind = "read") {
+    const deadline = createOperationDeadline(options);
+    let pending;
+    try {
+        ensureOperationActive(deadline.signal);
+        pending = Promise.resolve().then(() => operation(deadline.signal));
+        return await raceOperationDeadline(deadline, pending, kind);
+    }
+    finally {
+        deadline.close();
+        // A caller-facing deadline must not wait for a broken provider, but the
+        // late result remains observed so an ignored AbortSignal cannot create an
+        // unhandled rejection.
+        if (pending)
+            void pending.catch(() => undefined);
+    }
+}
 function isRateLimited(error) {
     if (!(error instanceof Error))
         return false;
@@ -17,8 +106,11 @@ function isRateLimited(error) {
     const isRateLimitError = error.isRateLimitError;
     return typeof isRateLimitError === "function" && isRateLimitError.call(error) === true;
 }
-async function withRateLimitRetry(operation) {
+async function withRateLimitRetry(operation, signal) {
+    let totalDelay = 0;
     for (let attempt = 0;; attempt++) {
+        if (signal?.aborted)
+            throw new StorageError("operation cancelled");
         try {
             return await operation();
         }
@@ -28,7 +120,7 @@ async function withRateLimitRetry(operation) {
             // The server's retry_after_ms only covers one token; tree operations
             // need several (kick + leave + forget). Wait at least 15s so the
             // burst refills.
-            let retryAfter = 15_000;
+            let retryAfter = RATE_LIMIT_DEFAULT_DELAY_MS;
             if (error instanceof Error && "getRetryAfterMs" in error) {
                 const getRetryAfterMs = error.getRetryAfterMs;
                 if (typeof getRetryAfterMs === "function") {
@@ -38,66 +130,511 @@ async function withRateLimitRetry(operation) {
                     }
                 }
             }
-            await new Promise((resolve) => setTimeout(resolve, retryAfter));
+            retryAfter = Math.min(retryAfter, RATE_LIMIT_MAX_DELAY_MS);
+            const remaining = RATE_LIMIT_MAX_TOTAL_DELAY_MS - totalDelay;
+            if (remaining <= 0)
+                throw error;
+            retryAfter = Math.min(retryAfter, remaining);
+            totalDelay += retryAfter;
+            await new Promise((resolve, reject) => {
+                let timer;
+                const onAbort = () => {
+                    clearTimeout(timer);
+                    signal?.removeEventListener("abort", onAbort);
+                    reject(new StorageError("operation cancelled"));
+                };
+                timer = setTimeout(() => {
+                    signal?.removeEventListener("abort", onAbort);
+                    resolve();
+                }, retryAfter);
+                signal?.addEventListener("abort", onAbort, { once: true });
+                if (signal?.aborted)
+                    onAbort();
+            });
         }
     }
 }
 /**
- * Resolves a folder by ID, polling briefly: a room this same account just
+ * Resolves a vault or folder by ID, polling briefly: a room this same account just
  * created (or was just invited to, by another process/session) can be
  * momentarily absent from a from-scratch `/sync` before showing up moments
  * later — real async settling, not an instant "not found". Throws a clean
- * error if the folder still isn't visible once the poll times out.
+ * error if the storage tree still isn't visible once the poll times out.
  */
-async function resolveTree(storage, folderId) {
+async function resolveTree(storage, treeId, signal) {
     try {
-        return await waitForCondition(() => storage.getTree(folderId), {
+        return await waitForCondition(() => storage.getTree(treeId), {
             timeoutMs: 15000,
+            signal,
         });
     }
     catch {
-        throw new StorageError(`folder not found: ${folderId}`);
+        if (signal?.aborted)
+            throw new StorageError("operation cancelled");
+        throw new StorageError("storage space not found");
     }
 }
 /** As `resolveTree`, but for a specific file within an already-resolved
- * folder — covers the same settling window for a file another
+ * vault or folder — covers the same settling window for a file another
  * process/session just uploaded. */
-async function resolveFile(tree, fileId) {
+async function resolveFile(tree, fileId, signal) {
+    try {
+        return await waitForCondition(() => tree.getFile(fileId), { timeoutMs: 15000, signal });
+    }
+    catch {
+        if (signal?.aborted)
+            throw new StorageError("operation cancelled");
+        throw new StorageError("file not found");
+    }
+}
+function snapshotTreeSpaces(root, tooLargeMessage = "storage tree is too large") {
+    const spaces = [];
+    const seen = new Set();
+    const pending = [{ tree: root, depth: 0 }];
+    while (pending.length > 0) {
+        const next = pending.pop();
+        if (!next)
+            continue;
+        const { tree, depth } = next;
+        if (seen.has(tree.id))
+            continue;
+        if (depth > MAX_DELETION_DEPTH || spaces.length >= MAX_DELETION_ROOMS) {
+            throw new StorageError(tooLargeMessage);
+        }
+        seen.add(tree.id);
+        spaces.push(tree);
+        let children;
+        try {
+            children = tree.getDirectories();
+        }
+        catch {
+            throw new StorageError("could not enumerate storage space descendants safely");
+        }
+        if (children.length > MAX_DELETION_ROOMS) {
+            throw new StorageError(tooLargeMessage);
+        }
+        for (const child of children)
+            pending.push({ tree: child, depth: depth + 1 });
+    }
+    return spaces;
+}
+/**
+ * Deleting a tree is deliberately a one-room operation.  File versions are
+ * physical Matrix media events, so callers must delete files explicitly and
+ * observe each result before removing their containing room.  This also
+ * prevents a folder/vault delete from silently deleting a nested shared tree.
+ */
+function assertTreeEmptyForDeletion(tree, spaces) {
+    if (spaces.length !== 1)
+        throw new NonEmptyTreeError(tree.id);
+    let files;
     try {
-        return await waitForCondition(() => tree.getFile(fileId), { timeoutMs: 15000 });
+        files = tree.listAllFiles();
     }
     catch {
-        throw new StorageError(`file not found: ${fileId}`);
+        throw new StorageError("could not enumerate storage files safely");
     }
+    if (files.length > 0)
+        throw new NonEmptyTreeError(tree.id);
+}
+async function refreshDeletionRooms(storage, signal) {
+    const client = storage.getClient();
+    const http = client.http;
+    // A real MatrixClient always exposes its authenticated HTTP transport. A
+    // client without one cannot prove that its local relation graph is current.
+    if (typeof http?.authedRequest !== "function") {
+        throw new StorageError("delete graph refresh is unavailable");
+    }
+    const roomIds = await storage.listJoinedRoomIds({ signal });
+    if (roomIds.length > MAX_DELETION_ROOMS)
+        throw new StorageError("delete graph is too large");
+    const joined = new Set(roomIds);
+    // Matrix has no bounded endpoint that enumerates every invited/non-joined
+    // room carrying a space relation. Refresh every locally visible room and
+    // fail closed for an invite/knock/unknown membership; a joined external
+    // parent remains inspectable and is validated by validateDeletionGraph.
+    for (const room of client.getRooms()) {
+        if (!joined.has(room.roomId)) {
+            const membership = room.getMyMembership?.();
+            if (membership !== "join")
+                throw new StorageError("delete graph inventory is incomplete");
+            await storage.refreshRoomState(room.roomId, { signal });
+        }
+    }
+    for (const roomId of roomIds) {
+        if (signal?.aborted)
+            throw new StorageError("operation cancelled");
+        await storage.refreshRoomState(roomId, { signal });
+    }
+}
+async function refreshTreeSpaces(storage, spaces, signal) {
+    for (const space of spaces) {
+        ensureOperationActive(signal);
+        await storage.refreshRoomState(space.id, { signal });
+    }
+}
+function readRelationEvents(client, roomId, eventType, stateKey) {
+    const room = client.getRoom?.(roomId);
+    const currentState = room?.currentState;
+    if (!currentState?.getStateEvents)
+        return null;
+    const result = currentState.getStateEvents(eventType, stateKey);
+    if (result === null || result === undefined)
+        return [];
+    return Array.isArray(result) ? result : [result];
+}
+function relationStateKey(event, fallback) {
+    return event.getStateKey?.() ?? fallback;
+}
+function isActiveRelationEvent(event) {
+    const content = event.getContent?.();
+    return (typeof content === "object" &&
+        content !== null &&
+        !Array.isArray(content) &&
+        Object.keys(content).length > 0);
+}
+/**
+ * Deletion is intentionally narrower than MSC3089TreeSpace.delete(): a local
+ * child graph is not proof that the rooms are exclusively owned by this tree.
+ * Validate every observed edge in both directions and reject any parent or
+ * child edge outside the exact deletion set before the first mutation.
+ */
+function validateDeletionGraph(client, root, ids, deletedRooms) {
+    const edges = new Set();
+    const externalParents = [];
+    const addEdge = (parentId, childId) => {
+        if (deletedRooms.has(childId))
+            return;
+        if (!ids.has(childId))
+            throw new StorageError("delete graph is unsafe");
+        edges.add(`${parentId}\u0000${childId}`);
+    };
+    for (const id of ids) {
+        const tree = client.unstableGetFileTreeSpace(id);
+        if (!tree)
+            throw new StorageError("delete graph is unsafe");
+        let directories;
+        try {
+            directories = tree.getDirectories();
+        }
+        catch {
+            throw new StorageError("delete graph is unsafe");
+        }
+        for (const child of directories)
+            addEdge(id, child.id);
+        const childEvents = readRelationEvents(client, id, EventType.SpaceChild);
+        if (childEvents === null)
+            throw new StorageError("delete graph is unsafe");
+        for (const event of childEvents) {
+            if (!isActiveRelationEvent(event))
+                continue;
+            const childId = relationStateKey(event);
+            if (!childId)
+                throw new StorageError("delete graph is unsafe");
+            addEdge(id, childId);
+        }
+    }
+    for (const edge of edges) {
+        const separator = edge.indexOf("\u0000");
+        const parentId = edge.slice(0, separator);
+        const childId = edge.slice(separator + 1);
+        const childLink = readRelationEvents(client, parentId, EventType.SpaceChild, childId);
+        const parentLink = readRelationEvents(client, childId, EventType.SpaceParent, parentId);
+        if (!childLink?.some((event) => isActiveRelationEvent(event) && relationStateKey(event, childId) === childId) ||
+            !parentLink?.some((event) => isActiveRelationEvent(event) && relationStateKey(event, parentId) === parentId)) {
+            throw new StorageError("delete graph is unsafe");
+        }
+    }
+    for (const id of ids) {
+        const parentEvents = readRelationEvents(client, id, EventType.SpaceParent);
+        if (parentEvents === null)
+            throw new StorageError("delete graph is unsafe");
+        for (const event of parentEvents) {
+            if (!isActiveRelationEvent(event))
+                continue;
+            const parentId = relationStateKey(event);
+            if (!parentId)
+                throw new StorageError("delete graph is unsafe");
+            if (!ids.has(parentId)) {
+                if (id !== root.id || externalParents.includes(parentId)) {
+                    throw new StorageError("delete graph is unsafe");
+                }
+                externalParents.push(parentId);
+            }
+        }
+    }
+    const rooms = client.getRooms();
+    if (rooms.length > MAX_DELETION_ROOMS)
+        throw new StorageError("delete graph is too large");
+    for (const room of rooms) {
+        const parentId = room.roomId;
+        const childEvents = readRelationEvents(client, parentId, EventType.SpaceChild);
+        if (childEvents === null)
+            throw new StorageError("delete graph is unsafe");
+        for (const event of childEvents) {
+            if (!isActiveRelationEvent(event))
+                continue;
+            const childId = relationStateKey(event);
+            if (!childId)
+                throw new StorageError("delete graph is unsafe");
+            if (ids.has(childId) && !ids.has(parentId)) {
+                if (childId === root.id) {
+                    if (!externalParents.includes(parentId))
+                        externalParents.push(parentId);
+                    continue;
+                }
+                throw new StorageError("delete graph is unsafe");
+            }
+        }
+    }
+    if (!ids.has(root.id))
+        throw new StorageError("delete graph is unsafe");
+    if (externalParents.length > 1)
+        throw new StorageError("delete graph is unsafe");
+    return { externalParents };
+}
+async function unlinkExternalParents(storage, rootId, externalParents, signal) {
+    const client = storage.getClient();
+    let mutationAttempted = false;
+    try {
+        for (const parentId of externalParents) {
+            if (signal?.aborted)
+                throw new StorageError("operation cancelled");
+            // Empty state-event content is the MSC3089-supported unlink form. Redaction
+            // is not used here because it can be delayed or rejected independently of
+            // the relation update.
+            mutationAttempted = true;
+            await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.sendStateEvent(parentId, EventType.SpaceChild, {}, rootId), signal), signal);
+            if (signal?.aborted)
+                throw new StorageError("operation cancelled");
+            await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.sendStateEvent(rootId, EventType.SpaceParent, {}, parentId), signal), signal);
+            await storage.refreshRoomState(parentId, { signal });
+            await storage.refreshRoomState(rootId, { signal });
+            const childLink = readRelationEvents(client, parentId, EventType.SpaceChild, rootId);
+            const parentLink = readRelationEvents(client, rootId, EventType.SpaceParent, parentId);
+            if (!childLink ||
+                !parentLink ||
+                childLink.some((event) => isActiveRelationEvent(event)) ||
+                parentLink.some((event) => isActiveRelationEvent(event))) {
+                throw new StorageError("delete graph unlink could not be verified");
+            }
+        }
+    }
+    catch (error) {
+        if (!mutationAttempted && error instanceof StorageError && error.message === "operation cancelled") {
+            throw error;
+        }
+        // Unlinking is a two-room transaction. A failed second state update must
+        // not leave a still-live vault detached from its external parent. Best
+        // effort is insufficient here: surface a distinct failure if the repair
+        // itself cannot be completed so callers never mistake a partial mutation
+        // for a successful delete.
+        try {
+            await relinkExternalParents(storage, rootId, externalParents, new AbortController().signal);
+        }
+        catch {
+            throw new StorageError("delete graph unlink cleanup is incomplete");
+        }
+        throw error;
+    }
+}
+async function relinkExternalParents(storage, rootId, externalParents, signal) {
+    const client = storage.getClient();
+    const via = client.getDomain();
+    if (!via)
+        throw new StorageError("delete graph relink is unavailable");
+    for (const parentId of externalParents) {
+        if (signal?.aborted)
+            throw new StorageError("operation cancelled");
+        await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.sendStateEvent(parentId, EventType.SpaceChild, { via: [via] }, rootId), signal), signal);
+        await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.sendStateEvent(rootId, EventType.SpaceParent, { via: [via] }, parentId), signal), signal);
+        await storage.refreshRoomState(parentId, { signal });
+        await storage.refreshRoomState(rootId, { signal });
+        const childLink = readRelationEvents(client, parentId, EventType.SpaceChild, rootId);
+        const parentLink = readRelationEvents(client, rootId, EventType.SpaceParent, parentId);
+        if (!childLink?.some((event) => isActiveRelationEvent(event)) ||
+            !parentLink?.some((event) => isActiveRelationEvent(event))) {
+            throw new StorageError("delete graph relink could not be verified");
+        }
+    }
+}
+const deletedTreeIds = new WeakMap();
+const deletedRoomIds = new WeakMap();
+function isGoneError(error) {
+    return (error instanceof MatrixError &&
+        (error.errcode === "M_NOT_FOUND" || error.errcode === "M_UNKNOWN"));
+}
+async function deleteRoomDeterministically(storage, roomId, signal) {
+    const client = storage.getClient();
+    const tree = storage.getTree(roomId);
+    if (!tree)
+        throw new StorageError("delete graph is unsafe");
+    const self = client.getUserId();
+    if (!self)
+        throw new StorageError("delete graph is unsafe");
+    const members = await storage.listMembers(tree, { signal });
+    if (members.some((member) => member.userId !== self && member.role === "owner" &&
+        (member.membership === "join" || member.membership === "invite" || member.membership === "knock"))) {
+        throw new StorageError("delete will not kick another room owner");
+    }
+    for (const member of members) {
+        const membership = member.membership;
+        if (member.userId === self ||
+            (membership !== "join" && membership !== "invite" && membership !== "knock")) {
+            continue;
+        }
+        try {
+            await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.kick(roomId, member.userId, "Room deleted"), signal), signal);
+        }
+        catch (error) {
+            if (isGoneError(error))
+                continue;
+            if (error instanceof MatrixError && error.errcode === "M_FORBIDDEN") {
+                const currentMembership = await storage.getRoomMembership(roomId, member.userId, { signal });
+                if (currentMembership === "leave" ||
+                    currentMembership === "ban" ||
+                    !currentMembership) {
+                    continue;
+                }
+            }
+            throw error;
+        }
+    }
+    const ownMembership = await storage.getRoomMembership(roomId, undefined, { signal });
+    if (ownMembership === "join" || ownMembership === "invite" || ownMembership === "knock") {
+        try {
+            await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.leave(roomId), signal), signal);
+        }
+        catch (error) {
+            if (!isGoneError(error))
+                throw error;
+        }
+    }
+    try {
+        await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.forget(roomId), signal), signal);
+    }
+    catch (error) {
+        if (!isGoneError(error))
+            throw error;
+    }
+    removeRoomFromLocalStore(client, roomId);
+    let deleted = deletedRoomIds.get(client);
+    if (!deleted) {
+        deleted = new Set();
+        deletedRoomIds.set(client, deleted);
+    }
+    deleted.add(roomId);
+}
+/**
+ * The SDK normally evicts a room as part of forget(). Keep the local-store
+ * postcondition explicit because a custom store or a raced membership update
+ * may otherwise leave a stale invite visible until the next sync.
+ */
+function removeRoomFromLocalStore(client, roomId) {
+    try {
+        client.store?.removeRoom(roomId);
+    }
+    catch {
+        // Server-side leave/forget already completed; a store implementation that
+        // cannot evict synchronously must not turn authoritative cleanup into a
+        // false failure.
+    }
+}
+function isActiveMembership(membership) {
+    return membership === "join" || membership === "invite";
+}
+function isRevocableMembership(membership) {
+    return membership === "join" || membership === "invite" || membership === "knock";
+}
+function safePartialDetail(error) {
+    // Provider/Matrix errors can contain response bodies, URLs, or credentials.
+    // StorageError messages are authored by this package and are already
+    // bounded; retain those local policy details so callers still get useful
+    // owner/self-target diagnostics.
+    if (!(error instanceof StorageError) || error instanceof MutationOutcomeUnknownError)
+        return undefined;
+    return error.message.length <= 256 ? error.message : undefined;
 }
 function toArrayBuffer(bytes) {
     return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
 }
-export async function createFolder(storage, name) {
-    const tree = await withRateLimitRetry(() => storage.createTree(name));
-    return { id: tree.id, name };
+export async function createVault(storage, name, options) {
+    return withOperationDeadline(options, async (signal) => {
+        let tree;
+        try {
+            tree = await withRateLimitRetry(() => storage.createTree(name, signal), signal);
+        }
+        catch (error) {
+            if (error instanceof RoomCleanupIncompleteError ||
+                error instanceof RoomCreationAmbiguousError ||
+                error instanceof MutationOutcomeUnknownError ||
+                (error instanceof Error &&
+                    error.cleanupIncomplete === true)) {
+                throw error;
+            }
+            if (signal.aborted)
+                throw new StorageError("operation cancelled");
+            throw new StorageError("create vault failed");
+        }
+        ensureOperationActive(signal);
+        return { id: tree.id, name };
+    }, "mutation");
 }
-/** Top-level folders only — excludes subdirectories of an existing tree. */
-export async function listFolders(storage) {
-    const trees = await storage.listTrees();
-    return trees.filter((t) => t.isTopLevel).map((t) => ({ id: t.id, name: t.room.name }));
+/** Top-level vaults only — excludes subdirectories of an existing tree. */
+export async function listVaults(storage, options) {
+    return withOperationDeadline(options, async (signal) => {
+        const trees = await storage.listTrees(signal);
+        return trees.filter((t) => t.isTopLevel).map((t) => ({ id: t.id, name: t.room.name }));
+    });
 }
-/** Current account's effective role for a folder, or null while it is unavailable. */
-export function getMyFolderRole(storage, folderId) {
+/** Current account's effective role for a vault, or null while it is unavailable. */
+export function getMyVaultRole(storage, vaultId) {
     const userId = storage.getClient().getUserId();
-    const tree = storage.getTree(folderId);
+    const tree = storage.getTree(vaultId);
     if (!userId || !tree)
         return null;
     return tree.getPermissions(userId);
 }
-export async function joinFolder(storage, folderId) {
-    try {
-        await withRateLimitRetry(() => storage.getClient().joinRoom(folderId));
-    }
-    catch (err) {
-        throw new StorageError(`join failed: ${err.message}`);
-    }
-    return { folderId, joined: true };
+export async function joinVault(storage, vaultId, options) {
+    return withOperationDeadline(options, async (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");
+            }
+        }
+        if (membership === "join")
+            return { vaultId, joined: true };
+        try {
+            await withRateLimitRetry(() => withMatrixMutationAbort(storage.getClient(), () => storage.getClient().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 { vaultId, joined: true };
+            }
+            if (signal.aborted)
+                throw new StorageError("operation cancelled");
+            throw new StorageError("join failed");
+        }
+        ensureOperationActive(signal);
+        return { vaultId, joined: true };
+    }, "mutation");
 }
 function roomDisplayName(storage, roomId, fallbackName) {
     const client = storage.getClient();
@@ -111,227 +648,758 @@ function roomDisplayName(storage, roomId, fallbackName) {
         return room.getDefaultRoomName(userId);
     return roomId;
 }
+function hasActiveSpaceParent(room) {
+    const result = room.currentState?.getStateEvents?.(EventType.SpaceParent);
+    const events = result == null ? [] : Array.isArray(result) ? result : [result];
+    return events.some((event) => isActiveRelationEvent(event));
+}
+function isReviewedStorageTreeRoom(room) {
+    const createEvent = room?.currentState?.getStateEvents?.(EventType.RoomCreate, "");
+    const createContent = createEvent?.getContent?.();
+    const purposeEvent = room?.currentState?.getStateEvents?.(UNSTABLE_MSC3088_PURPOSE.name, UNSTABLE_MSC3089_TREE_SUBTYPE.name);
+    const purposeContent = purposeEvent?.getContent?.();
+    return (createContent?.[RoomCreateTypeField] === RoomType.Space &&
+        purposeContent?.[UNSTABLE_MSC3088_ENABLED.name] === true);
+}
 /** Rooms where this account is invited and the room looks like a file tree. */
-export async function listPendingInvites(storage) {
-    const client = storage.getClient();
-    const invites = [];
-    for (const room of client.getRooms()) {
-        if (room.getMyMembership() !== "invite")
-            continue;
-        const tree = storage.getTree(room.roomId);
-        if (tree) {
-            invites.push({
-                id: tree.id,
-                name: roomDisplayName(storage, room.roomId, tree.room.name),
-            });
-            continue;
+export async function listPendingInvites(storage, options) {
+    return withOperationDeadline(options, async (signal) => {
+        const client = storage.getClient();
+        const rooms = client.getRooms();
+        if (rooms.length > MAX_LIST_ITEMS)
+            throw new StorageError("invite list is too large");
+        const invites = [];
+        for (const room of rooms) {
+            ensureOperationActive(signal);
+            if (room.getMyMembership() !== "invite")
+                continue;
+            if (hasActiveSpaceParent(room))
+                continue;
+            const tree = storage.getTree(room.roomId);
+            if (tree) {
+                if (tree.isTopLevel) {
+                    invites.push({
+                        id: tree.id,
+                        name: roomDisplayName(storage, room.roomId, tree.room.name),
+                    });
+                }
+                continue;
+            }
+            // Invite state may not have MSC3089 tree metadata yet — accept rooms whose
+            // create event marks them as a file tree space.
+            if (isReviewedStorageTreeRoom(room)) {
+                invites.push({
+                    id: room.roomId,
+                    name: roomDisplayName(storage, room.roomId),
+                });
+            }
         }
-        // Invite state may not have MSC3089 tree metadata yet — accept rooms whose
-        // create event marks them as a file tree space.
-        const createEvent = room.currentState?.getStateEvents("m.room.create", "");
-        const createContent = createEvent?.getContent();
-        const roomType = createContent?.["type"];
-        if (roomType === "org.matrix.msc3088.file" || roomType === "m.space") {
-            invites.push({
-                id: room.roomId,
-                name: roomDisplayName(storage, room.roomId),
-            });
+        return invites;
+    });
+}
+/** Decline a vault invite (same as leaving before join). */
+export async function declineInvite(storage, vaultId, options) {
+    return withOperationDeadline(options, async (signal) => {
+        const client = storage.getClient();
+        try {
+            const room = typeof client.getRoom === "function" ? client.getRoom(vaultId) : undefined;
+            if (!room)
+                throw new StorageError("decline failed");
+            const localMembership = typeof room.getMyMembership === "function"
+                ? room.getMyMembership()
+                : null;
+            // Invites are destructive: refresh the exact room before validating its
+            // space relation and local tree metadata. A stale sync snapshot could
+            // otherwise make a now-nested or unrelated room look safe to forget.
+            // Synapse deliberately rejects full-state reads for pre-join rooms, so
+            // an invite/knock must use the reviewed stripped state delivered with
+            // the invite; joined rooms still get the authoritative refresh.
+            if (localMembership !== "invite" && localMembership !== "knock") {
+                await storage.refreshRoomState(vaultId, { signal });
+            }
+            const currentRoom = typeof client.getRoom === "function" ? client.getRoom(vaultId) : undefined;
+            // Matrix 42's unstableGetFileTreeSpace() intentionally returns null for
+            // invited rooms: it only constructs a tree after local membership is
+            // `join`. A pending invite is nevertheless a reviewed top-level tree
+            // room, so validate the authoritative room state directly instead of
+            // requiring a joined TreeSpace object.
+            if (!currentRoom ||
+                hasActiveSpaceParent(currentRoom) ||
+                !isReviewedStorageTreeRoom(currentRoom)) {
+                throw new StorageError("decline failed");
+            }
+            let membership;
+            try {
+                membership = await storage.getRoomMembership(vaultId, undefined, { signal });
+            }
+            catch (error) {
+                // The membership endpoint is also forbidden for an invited user. The
+                // local pre-join membership is the server-delivered invite state that
+                // authorizes this narrowly scoped leave/forget operation.
+                if (error instanceof MatrixError &&
+                    error.errcode === "M_FORBIDDEN" &&
+                    (localMembership === "invite" || localMembership === "knock")) {
+                    membership = localMembership;
+                }
+                else {
+                    throw error;
+                }
+            }
+            // Decline is intentionally narrower than delete/leave: it must never
+            // remove an already-joined vault or forget an unrelated room ID.
+            if (membership !== "invite" && membership !== "knock") {
+                return { vaultId, declined: false };
+            }
+            try {
+                await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.leave(vaultId), signal), signal);
+            }
+            catch (error) {
+                let suppress = isGoneError(error);
+                if (!suppress && error instanceof MatrixError && error.errcode === "M_FORBIDDEN") {
+                    const after = await storage.getRoomMembership(vaultId, undefined, { signal });
+                    suppress = after !== "join" && after !== "invite" && after !== "knock";
+                }
+                if (!suppress)
+                    throw error;
+            }
+            try {
+                await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.forget(vaultId), signal), signal);
+            }
+            catch (error) {
+                let suppress = isGoneError(error);
+                if (!suppress && error instanceof MatrixError && error.errcode === "M_FORBIDDEN") {
+                    const after = await storage.getRoomMembership(vaultId, undefined, { signal });
+                    suppress = after !== "join" && after !== "invite" && after !== "knock";
+                }
+                if (!suppress)
+                    throw error;
+            }
+            removeRoomFromLocalStore(client, vaultId);
+        }
+        catch (error) {
+            // A cancellation or transport failure after leave/forget may have
+            // changed membership. Keep the outcome explicit instead of claiming a
+            // clean decline.
+            if (error instanceof MutationOutcomeUnknownError)
+                throw error;
+            if (signal.aborted)
+                throw new StorageError("operation cancelled");
+            throw new StorageError("decline failed");
         }
+        ensureOperationActive(signal);
+        return { vaultId, declined: true };
+    }, "mutation");
+}
+/** Invites `userId` to the vault and applies the requested role. */
+export async function shareVault(storage, vaultId, userId, role, options) {
+    if (role !== "viewer" && role !== "editor") {
+        throw new StorageError("invalid --role (must be viewer or editor)");
+    }
+    const operation = createOperationDeadline(options);
+    const completedRoomIds = new Set();
+    try {
+        ensureOperationActive(operation.signal);
+        const tree = await resolveTree(storage, vaultId, operation.signal);
+        const pending = withTreeMutation(storage.getClient(), async () => {
+            const client = storage.getClient();
+            try {
+                ensureOperationActive(operation.signal);
+                await storage.refreshRoomState(tree.id, { signal: operation.signal });
+                const spaces = snapshotTreeSpaces(tree);
+                await refreshTreeSpaces(storage, spaces, operation.signal);
+                const currentUser = storage.getClient().getUserId();
+                if (currentUser && userId === currentUser) {
+                    throw new StorageError("share target is the current user");
+                }
+                const currentMembers = await withRateLimitRetry(() => storage.listMembers(tree, { signal: operation.signal }), operation.signal);
+                if (currentMembers.some((member) => member.userId === userId && member.role === "owner")) {
+                    throw new StorageError("share will not demote an existing owner");
+                }
+                for (const [index, space] of spaces.entries()) {
+                    ensureOperationActive(operation.signal);
+                    const currentMembership = index === 0
+                        ? currentMembers.find((member) => member.userId === userId)?.membership
+                        : await storage.getRoomMembership(space.id, userId, {
+                            signal: operation.signal,
+                        });
+                    if (isActiveMembership(currentMembership ?? ""))
+                        continue;
+                    try {
+                        await withRateLimitRetry(() => withMatrixMutationAbort(client, () => 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");
+                    }
+                }
+                for (const space of spaces) {
+                    ensureOperationActive(operation.signal);
+                    const members = space.id === tree.id
+                        ? currentMembers
+                        : await withRateLimitRetry(() => storage.listMembers(space, { signal: operation.signal }), operation.signal);
+                    if (members.some((member) => member.userId === userId && member.role === "owner")) {
+                        throw new StorageError("share will not demote an existing owner");
+                    }
+                    await withRateLimitRetry(() => withMatrixMutationAbort(client, () => space.setPermissions(userId, role), operation.signal), operation.signal);
+                    completedRoomIds.add(space.id);
+                }
+            }
+            catch (error) {
+                if (error instanceof MutationOutcomeUnknownError)
+                    throw error;
+                if (completedRoomIds.size > 0) {
+                    throw new MutationPartialError("share", [...completedRoomIds], safePartialDetail(error));
+                }
+                if (error instanceof StorageError &&
+                    (error.message === "share failed" ||
+                        error.message.includes("owner") ||
+                        error.message.includes("current user") ||
+                        error.message === "operation cancelled")) {
+                    throw error;
+                }
+                throw new StorageError("share failed");
+            }
+            return { vaultId, userId, role };
+        }, operation.signal);
+        return await raceOperationDeadline(operation, pending, "mutation");
+    }
+    finally {
+        operation.close();
+    }
+}
+export async function unshareVault(storage, vaultId, userId, options) {
+    const operation = createOperationDeadline(options);
+    const completedRoomIds = new Set();
+    try {
+        ensureOperationActive(operation.signal);
+        const tree = await resolveTree(storage, vaultId, operation.signal);
+        const pending = withTreeMutation(storage.getClient(), async () => {
+            try {
+                const currentUser = storage.getClient().getUserId();
+                if (currentUser && userId === currentUser) {
+                    throw new StorageError("unshare target is the current user");
+                }
+                await storage.refreshRoomState(tree.id, { signal: operation.signal });
+                const spaces = snapshotTreeSpaces(tree);
+                await refreshTreeSpaces(storage, spaces, operation.signal);
+                for (const space of spaces) {
+                    ensureOperationActive(operation.signal);
+                    const members = await withRateLimitRetry(() => storage.listMembers(space, { signal: operation.signal }), operation.signal);
+                    if (members.some((member) => member.userId === userId && member.role === "owner")) {
+                        throw new StorageError("unshare will not remove an existing owner");
+                    }
+                    let membership;
+                    try {
+                        membership = await storage.getRoomMembership(space.id, userId, {
+                            signal: operation.signal,
+                        });
+                    }
+                    catch (error) {
+                        if (isGoneError(error))
+                            continue;
+                        throw error;
+                    }
+                    if (!isRevocableMembership(membership))
+                        continue;
+                    try {
+                        await withRateLimitRetry(() => withMatrixMutationAbort(storage.getClient(), () => storage.getClient().kick(space.id, userId, "unshared"), operation.signal), operation.signal);
+                        completedRoomIds.add(space.id);
+                    }
+                    catch (error) {
+                        if (isGoneError(error))
+                            continue;
+                        if (error instanceof MatrixError && error.errcode === "M_FORBIDDEN") {
+                            const afterForbidden = await storage.getRoomMembership(space.id, userId, {
+                                signal: operation.signal,
+                            });
+                            if (!isRevocableMembership(afterForbidden))
+                                continue;
+                        }
+                        throw error;
+                    }
+                }
+            }
+            catch (error) {
+                if (error instanceof MutationOutcomeUnknownError)
+                    throw error;
+                if (completedRoomIds.size > 0) {
+                    throw new MutationPartialError("unshare", [...completedRoomIds], safePartialDetail(error));
+                }
+                if (error instanceof StorageError &&
+                    (error.message.includes("owner") ||
+                        error.message.includes("current user") ||
+                        error.message === "operation cancelled")) {
+                    throw error;
+                }
+                throw new StorageError("unshare failed");
+            }
+            return { vaultId, userId, removed: true };
+        }, operation.signal);
+        return await raceOperationDeadline(operation, pending, "mutation");
+    }
+    finally {
+        operation.close();
     }
-    return invites;
 }
-/** Decline a folder invite (same as leaving before join). */
-export async function declineInvite(storage, folderId) {
+export async function listMembers(storage, vaultId, options) {
+    return withOperationDeadline(options, async (signal) => {
+        const tree = await resolveTree(storage, vaultId, signal);
+        try {
+            return await withRateLimitRetry(() => storage.listMembers(tree, { signal }), signal);
+        }
+        catch {
+            if (signal.aborted)
+                throw new StorageError("operation cancelled");
+            throw new StorageError("list members failed");
+        }
+    });
+}
+export async function listFiles(storage, treeId, options) {
+    return withOperationDeadline(options, async (signal) => {
+        const tree = await resolveTree(storage, treeId, signal);
+        try {
+            await storage.refreshRoomState(treeId, { signal });
+            ensureOperationActive(signal);
+            const files = tree.listFiles();
+            if (files.length > MAX_LIST_ITEMS)
+                throw new StorageError("file list is too large");
+            return files.map((f) => ({ id: f.id, name: f.getName() }));
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw new StorageError("operation cancelled");
+            if (error instanceof StorageError && error.message === "file list is too large")
+                throw error;
+            throw new StorageError("list files failed");
+        }
+    });
+}
+/** Lists the direct child folders of a vault or folder. */
+export async function listSubfolders(storage, parentId, options) {
+    return withOperationDeadline(options, async (signal) => {
+        const tree = await resolveTree(storage, parentId, signal);
+        ensureOperationActive(signal);
+        const directories = tree.getDirectories();
+        if (directories.length > MAX_LIST_ITEMS)
+            throw new StorageError("folder list is too large");
+        return directories.map((d) => ({ id: d.id, name: d.room.name }));
+    });
+}
+export async function createSubfolder(storage, parentId, name, options) {
+    validateName(name, "name");
+    return withOperationDeadline(options, async (signal) => {
+        const tree = await resolveTree(storage, parentId, signal);
+        let sub;
+        try {
+            sub = await withRateLimitRetry(() => storage.createSubtree(tree, name, signal), signal);
+        }
+        catch (error) {
+            if (error instanceof RoomCleanupIncompleteError ||
+                error instanceof RoomCreationAmbiguousError ||
+                error instanceof MutationOutcomeUnknownError ||
+                (error instanceof Error &&
+                    error.cleanupIncomplete === true)) {
+                throw error;
+            }
+            if (signal.aborted)
+                throw new StorageError("operation cancelled");
+            throw new StorageError("create folder failed");
+        }
+        ensureOperationActive(signal);
+        return { id: sub.id, name };
+    }, "mutation");
+}
+async function renameTree(storage, treeId, name, options) {
+    validateName(name, "name");
+    return withOperationDeadline(options, async (signal) => {
+        const tree = await resolveTree(storage, treeId, signal);
+        try {
+            const client = typeof storage.getClient === "function" ? storage.getClient() : undefined;
+            await withRateLimitRetry(() => client ? withMatrixMutationAbort(client, () => tree.setName(name), signal) : tree.setName(name), signal);
+            await waitForCondition(async () => {
+                ensureOperationActive(signal);
+                const current = storage.getTree(treeId);
+                if (current?.room.name === name)
+                    return current;
+                try {
+                    await storage.refreshRoomState(treeId, { signal });
+                }
+                catch {
+                    return null;
+                }
+                const refreshed = storage.getTree(treeId);
+                return refreshed?.room.name === name ? refreshed : null;
+            }, { timeoutMs: 15000, signal });
+        }
+        catch (error) {
+            if (error instanceof MutationOutcomeUnknownError)
+                throw error;
+            if (signal.aborted)
+                throw new StorageError("operation cancelled");
+            throw new StorageError("rename failed");
+        }
+        return { id: treeId, name };
+    }, "mutation");
+}
+/** Renames a top-level Vault. */
+export async function renameVault(storage, vaultId, name, options) {
+    return renameTree(storage, vaultId, name, options);
+}
+/** Renames a nested folder. */
+export async function renameFolder(storage, folderId, name, options) {
+    return renameTree(storage, folderId, name, options);
+}
+async function deleteTree(storage, treeId, options) {
+    const operation = createOperationDeadline(options);
     const client = storage.getClient();
+    let deleted = deletedTreeIds.get(client);
+    if (!deleted) {
+        deleted = new Set();
+        deletedTreeIds.set(client, deleted);
+    }
     try {
-        await withRateLimitRetry(async () => {
-            await client.leave(folderId);
-            // The server only allows forgetting a room once this account's
-            // membership is `leave`; forgetting removes the room from the local
-            // store immediately, so a declined invite stops showing up in
-            // listFolders/listPendingInvites without waiting for the leave event
-            // to round-trip through the background sync loop.
-            await client.forget(folderId);
-        });
+        ensureOperationActive(operation.signal);
+        const pending = withTreeMutation(client, async () => {
+            if (deleted.has(treeId))
+                return { id: treeId, deleted: true };
+            const tree = await resolveTree(storage, treeId, operation.signal);
+            // Read reconciliation state after this operation reaches the single
+            // client queue; a preceding delete may have populated the set while we
+            // were waiting for its turn.
+            const removedRooms = deletedRoomIds.get(client) ?? new Set();
+            let graph;
+            try {
+                // Re-read every locally visible room before taking the immutable graph
+                // snapshot. Local MSC3089 relations and memberships can lag another
+                // session; deleting from that stale view can orphan shared descendants.
+                await refreshDeletionRooms(storage, operation.signal);
+                const spaces = snapshotTreeSpaces(tree, "delete graph is too large");
+                const activeSpaces = spaces.filter((space) => !removedRooms.has(space.id));
+                const ids = new Set(activeSpaces.map((space) => space.id));
+                if (!ids.has(tree.id)) {
+                    if (removedRooms.has(tree.id)) {
+                        deleted.add(treeId);
+                        return { id: treeId, deleted: true };
+                    }
+                    throw new StorageError("delete graph is unsafe");
+                }
+                assertTreeEmptyForDeletion(tree, activeSpaces);
+                graph = validateDeletionGraph(client, tree, ids, removedRooms);
+            }
+            catch (error) {
+                if (error instanceof MutationOutcomeUnknownError ||
+                    error instanceof MutationPartialError ||
+                    error instanceof NonEmptyTreeError)
+                    throw error;
+                if (error instanceof StorageError && error.message === "operation cancelled")
+                    throw error;
+                throw new StorageError("delete failed");
+            }
+            // Keep external parent links intact until the room deletion succeeds.
+            // Unlinking first would silently detach a live vault on failure.
+            try {
+                await unlinkExternalParents(storage, tree.id, graph.externalParents, operation.signal);
+            }
+            catch (error) {
+                if (error instanceof MutationOutcomeUnknownError)
+                    throw error;
+                if (error instanceof MutationPartialError)
+                    throw error;
+                if (error instanceof StorageError && error.message === "delete graph unlink cleanup is incomplete") {
+                    throw error;
+                }
+                if (error instanceof StorageError && error.message === "operation cancelled")
+                    throw error;
+                throw new StorageError("delete failed");
+            }
+            try {
+                await deleteRoomDeterministically(storage, tree.id, operation.signal);
+            }
+            catch (error) {
+                // The root is still live when its relation is removed. If deletion then
+                // fails, restore both sides before reporting failure; otherwise a live
+                // vault would be silently detached from its external parent.
+                try {
+                    await relinkExternalParents(storage, tree.id, graph.externalParents, new AbortController().signal);
+                }
+                catch {
+                    throw new StorageError("delete cleanup is incomplete");
+                }
+                if (error instanceof MutationOutcomeUnknownError)
+                    throw error;
+                if (error instanceof MutationPartialError)
+                    throw error;
+                if (error instanceof StorageError && error.message === "operation cancelled")
+                    throw error;
+                throw new StorageError("delete failed");
+            }
+            deleted.add(treeId);
+            return { id: treeId, deleted: true };
+        }, operation.signal);
+        return await raceOperationDeadline(operation, pending, "mutation");
     }
-    catch (err) {
-        throw new StorageError(`decline failed: ${err.message}`);
+    finally {
+        operation.close();
     }
-    return { folderId, declined: true };
+}
+/** Deletes a top-level Vault. */
+export async function deleteVault(storage, vaultId, options) {
+    return deleteTree(storage, vaultId, options);
+}
+/** Deletes a nested folder. */
+export async function deleteFolder(storage, folderId, options) {
+    return deleteTree(storage, folderId, options);
+}
+export async function renameFile(storage, treeId, fileId, name, options) {
+    validateName(name, "file name");
+    return withOperationDeadline(options, async (signal) => {
+        const tree = await resolveTree(storage, treeId, signal);
+        const branch = await resolveFile(tree, fileId, signal);
+        try {
+            const client = typeof storage.getClient === "function" ? storage.getClient() : undefined;
+            await withRateLimitRetry(() => client ? withMatrixMutationAbort(client, () => branch.setName(name), signal) : branch.setName(name), signal);
+            // `setName` resolves when the homeserver accepts the state event, but a
+            // fresh CLI/UI process can still read the previous local room state for a
+            // short time. Do not report success until this client has observed the new
+            // name through its normal sync loop.
+            await waitForCondition(() => {
+                const current = tree.getFile(fileId);
+                return current?.getName() === name ? current : null;
+            }, { timeoutMs: 15000, signal });
+        }
+        catch (error) {
+            if (error instanceof MutationOutcomeUnknownError)
+                throw error;
+            if (signal.aborted)
+                throw new StorageError("operation cancelled");
+            throw new StorageError("rename file failed");
+        }
+        return { id: fileId, name };
+    }, "mutation");
 }
 /**
- * Invites `userId` to the folder at `role` and applies the role's
- * permissions. Doubles as "change an existing participant's role" (call
- * again with a different role): inviting someone who's already a member is
- * a 403 from the server, not a real failure — that specific error is
- * swallowed and the role change still applies. Any other invite failure
- * (e.g. unknown user) propagates.
+ * Resolve the complete encrypted version chain before mutating Matrix.
+ *
+ * matrix-js-sdk returns the active version first and older versions after it.
+ * Treat a repeated event ID as a cycle/invalid relation graph, and bound both
+ * the event walk and the media identifiers sent to Synapse. Resolving every
+ * media URL first is important: a decryption or relation failure must not leave
+ * a partially deleted file chain.
  */
-export async function shareFolder(storage, folderId, userId, role) {
-    if (role !== "viewer" && role !== "editor") {
-        throw new StorageError(`invalid --role "${role}" (must be viewer or editor)`);
-    }
-    const tree = await resolveTree(storage, folderId);
+async function resolveFileVersions(branch, signal) {
+    let history;
     try {
-        await withRateLimitRetry(() => tree.invite(userId));
+        history = await branch.getVersionHistory();
+    }
+    catch {
+        throw new StorageError("could not resolve file version history safely");
     }
-    catch (err) {
-        if (!/already in the room/i.test(err.message)) {
-            throw err;
+    if (!Array.isArray(history) || history.length === 0 || history.length > MAX_FILE_VERSION_CHAIN) {
+        throw new StorageError("file version history is invalid or too large");
+    }
+    const eventIds = new Set();
+    const mediaIds = new Set();
+    const versions = [];
+    for (const version of history) {
+        if (signal?.aborted)
+            throw new StorageError("operation cancelled");
+        if (!version || typeof version.id !== "string") {
+            throw new StorageError("file version history is invalid");
+        }
+        try {
+            validateMatrixEventId(version.id, "file version event ID");
+        }
+        catch {
+            throw new StorageError("file version history contains an invalid event ID");
+        }
+        if (eventIds.has(version.id)) {
+            throw new StorageError("file version history contains a cycle");
+        }
+        eventIds.add(version.id);
+        let fileInfo;
+        try {
+            fileInfo = await version.getFileInfo();
+        }
+        catch {
+            throw new StorageError("could not resolve encrypted file version safely");
         }
+        const mediaId = fileInfo?.info?.url;
+        if (typeof mediaId !== "string" || mediaId.length === 0) {
+            throw new StorageError("encrypted file version has no media identifier");
+        }
+        mediaIds.add(mediaId);
+        if (mediaIds.size > MAX_FILE_VERSION_CHAIN) {
+            throw new StorageError("file media version history is too large");
+        }
+        versions.push({ branch: version, mediaId });
     }
-    await withRateLimitRetry(() => tree.setPermissions(userId, role));
-    return { folderId, userId, role };
+    return versions;
 }
-export async function unshareFolder(storage, folderId, userId) {
-    await resolveTree(storage, folderId);
-    try {
-        await withRateLimitRetry(() => storage.getClient().kick(folderId, userId, "unshared"));
-    }
-    catch (err) {
-        throw new StorageError(`unshare failed: ${err.message}`);
-    }
-    return { folderId, userId, removed: true };
-}
-export async function listMembers(storage, folderId) {
-    const tree = await resolveTree(storage, folderId);
-    return withRateLimitRetry(() => storage.listMembers(tree));
-}
-export async function listFiles(storage, folderId) {
-    const tree = await resolveTree(storage, folderId);
-    await storage.refreshRoomState(folderId);
-    return tree.listFiles().map((f) => ({ id: f.id, name: f.getName() }));
-}
-export async function listSubfolders(storage, folderId) {
-    const tree = await resolveTree(storage, folderId);
-    return tree.getDirectories().map((d) => ({ id: d.id, name: d.room.name }));
-}
-export async function createSubfolder(storage, folderId, name) {
-    const tree = await resolveTree(storage, folderId);
-    const sub = await withRateLimitRetry(() => storage.createSubtree(tree, name));
-    return { id: sub.id, name };
-}
-export async function renameFolder(storage, folderId, name) {
-    const tree = await resolveTree(storage, folderId);
-    await withRateLimitRetry(() => tree.setName(name));
-    return { id: folderId, name };
-}
-export async function deleteFolder(storage, folderId) {
-    const tree = await resolveTree(storage, folderId);
-    // `tree.delete()` kicks members and leaves this room AND every
-    // subdirectory room, but never forgets any of them, so they all linger in
-    // the local store and listFolders keeps returning the deleted folder until
-    // the leave events round-trip through the background sync loop (30-60s
-    // under full-suite load). Forgetting removes each room from the local
-    // store immediately; the server only accepts a forget once membership is
-    // `leave`, which `tree.delete()` has just completed for the whole tree.
-    const subdirectoryIds = tree.getDirectories().map((d) => d.id);
+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();
-    await withRateLimitRetry(async () => {
-        await tree.delete();
-        await client.forget(folderId);
-        for (const subId of subdirectoryIds) {
-            await client.forget(subId);
-        }
-    });
-    return { id: folderId, deleted: true };
-}
-export async function renameFile(storage, folderId, fileId, name) {
-    const tree = await resolveTree(storage, folderId);
-    const branch = await resolveFile(tree, fileId);
-    await withRateLimitRetry(() => branch.setName(name));
-    // `setName` resolves when the homeserver accepts the state event, but a
-    // fresh CLI/UI process can still read the previous local room state for a
-    // short time. Do not report success until this client has observed the new
-    // name through its normal sync loop.
-    await waitForCondition(() => {
-        const current = tree.getFile(fileId);
-        return current?.getName() === name ? current : null;
-    }, { timeoutMs: 15000 });
-    return { id: fileId, name };
-}
-export async function deleteFile(storage, folderId, fileId) {
-    const tree = await resolveTree(storage, folderId);
-    const branch = await resolveFile(tree, fileId);
-    await withRateLimitRetry(() => branch.delete());
-    return { id: fileId, deleted: true };
-}
-export async function uploadFile(storage, folderId, name, bytes, mimetype) {
-    const tree = await resolveTree(storage, folderId);
-    const fileId = await withRateLimitRetry(() => storage.uploadFile(tree, name, toArrayBuffer(bytes), mimetype));
-    return { id: fileId, name, mimetype };
-}
-export async function downloadFile(storage, folderId, fileId) {
-    const tree = await resolveTree(storage, folderId);
-    const branch = await resolveFile(tree, fileId);
-    let result;
+    const http = requireFileDeletionTransport(client);
     try {
-        result = await storage.downloadFile(branch);
+        await withRateLimitRetry(() => withMatrixMutationAbort(client, () => http.authedRequest(Method.Post, "/io.telecrypt.storage/delete_media", undefined, { media_ids: [...mediaIds] }, { prefix: ClientPrefix.Unstable, abortSignal: signal }), signal, "delete file media"), signal);
     }
-    catch (err) {
-        throw new StorageError(`download failed: ${err.message}`);
+    catch (error) {
+        if (error instanceof MutationOutcomeUnknownError)
+            throw error;
+        if (signal?.aborted)
+            throw new StorageError("operation cancelled");
+        throw new StorageError("delete file media failed");
     }
-    return {
-        bytes: new Uint8Array(result.data),
-        mimetype: result.mimetype,
-        name: branch.getName(),
-    };
 }
-export async function setupRecovery(storage) {
-    return storage.keys.setupRecovery();
+export async function deleteFile(storage, treeId, fileId, options) {
+    return withOperationDeadline(options, async (signal) => {
+        const tree = await resolveTree(storage, treeId, signal);
+        const branch = await resolveFile(tree, fileId, signal);
+        const versions = await resolveFileVersions(branch, signal);
+        const mediaIds = [...new Set(versions.map(({ mediaId }) => mediaId))];
+        await deleteFileMedia(storage, mediaIds, signal);
+        const completedIds = [];
+        try {
+            const client = typeof storage.getClient === "function" ? storage.getClient() : undefined;
+            if (!client)
+                throw new StorageError("Matrix client unavailable");
+            for (const { branch: version } of versions) {
+                await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.sendStateEvent(tree.id, UNSTABLE_MSC3089_BRANCH.name, {}, version.id), signal, "delete file state"), signal);
+                await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.redactEvent(tree.id, version.id), signal, "delete file event"), signal);
+                completedIds.push(version.id);
+            }
+        }
+        catch (error) {
+            if (error instanceof MutationOutcomeUnknownError)
+                throw error;
+            if (signal.aborted) {
+                throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup was cancelled");
+            }
+            throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup stopped");
+        }
+        ensureOperationActive(signal);
+        return { id: fileId, deleted: true };
+    }, "mutation");
+}
+export async function uploadFile(storage, treeId, name, bytes, mimetype, options) {
+    return withOperationDeadline(options, async (signal) => {
+        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)
+                throw error;
+            if (signal.aborted)
+                throw new StorageError("operation cancelled");
+            throw new StorageError("upload failed");
+        });
+        ensureOperationActive(signal);
+        return { id: fileId, name, mimetype };
+    }, "mutation");
+}
+export async function downloadFile(storage, treeId, fileId, options) {
+    return withOperationDeadline(options, async (signal) => {
+        const tree = await resolveTree(storage, treeId, signal);
+        const branch = await resolveFile(tree, fileId, signal);
+        let result;
+        try {
+            result = await storage.downloadFile(branch, signal);
+        }
+        catch (error) {
+            if (error instanceof UndecryptableFileError)
+                throw error;
+            if (signal.aborted)
+                throw new StorageError("operation cancelled");
+            throw new StorageError("download failed");
+        }
+        ensureOperationActive(signal);
+        return {
+            bytes: new Uint8Array(result.data),
+            mimetype: result.mimetype,
+            name: branch.getName(),
+        };
+    });
 }
-export async function restoreRecovery(storage, recoveryKey) {
-    return storage.keys.restoreFromRecoveryKey(recoveryKey);
+export async function setupRecovery(storage, options) {
+    return withOperationDeadline(options, (signal) => storage.keys.setupRecovery(signal), "mutation");
+}
+export async function restoreRecovery(storage, recoveryKey, options) {
+    return withOperationDeadline(options, (signal) => storage.keys.restoreFromRecoveryKey(recoveryKey, signal), "mutation");
 }
 function tsToIso(ts) {
     if (ts == null || !Number.isFinite(ts))
         return null;
     return new Date(ts).toISOString();
 }
-export async function getFileDetails(storage, folderId, fileId) {
-    const tree = await resolveTree(storage, folderId);
-    const branch = await resolveFile(tree, fileId);
-    const name = branch.getName();
-    let mimetype = null;
-    let size = null;
-    let createdAt = null;
-    let updatedAt = null;
-    try {
-        const { info } = await branch.getFileInfo();
-        if (info) {
-            if (typeof info["mimetype"] === "string")
-                mimetype = info["mimetype"];
-            if (typeof info["size"] === "number")
-                size = info["size"];
+export async function getFileDetails(storage, treeId, fileId, options) {
+    return withOperationDeadline(options, async (signal) => {
+        const tree = await resolveTree(storage, treeId, signal);
+        const branch = await resolveFile(tree, fileId, signal);
+        const name = branch.getName();
+        let mimetype = null;
+        let size = null;
+        let createdAt = null;
+        let updatedAt = null;
+        try {
+            ensureOperationActive(signal);
+            const { info } = await branch.getFileInfo();
+            if (info) {
+                if (typeof info["mimetype"] === "string")
+                    mimetype = info["mimetype"];
+                if (typeof info["size"] === "number")
+                    size = info["size"];
+            }
         }
-    }
-    catch {
-        // Partial metadata is fine — UI shows "—" for unknown fields.
-    }
-    try {
-        const event = await branch.getFileEvent();
-        const content = event.getContent();
-        const infoBlock = content["info"];
-        if (!mimetype && typeof infoBlock?.["mimetype"] === "string") {
-            mimetype = infoBlock["mimetype"];
+        catch {
+            if (signal.aborted)
+                throw new StorageError("operation cancelled");
+            // Partial metadata is fine — UI shows "—" for unknown fields.
         }
-        if (size == null && typeof infoBlock?.["size"] === "number") {
-            size = infoBlock["size"];
+        try {
+            ensureOperationActive(signal);
+            const event = await branch.getFileEvent();
+            const content = event.getContent();
+            const infoBlock = content["info"];
+            if (!mimetype && typeof infoBlock?.["mimetype"] === "string") {
+                mimetype = infoBlock["mimetype"];
+            }
+            if (size == null && typeof infoBlock?.["size"] === "number") {
+                size = infoBlock["size"];
+            }
+            const eventAny = event;
+            const ts = eventAny.getTs?.() ?? eventAny.origin_server_ts;
+            createdAt = tsToIso(ts);
+            updatedAt = createdAt;
         }
-        const eventAny = event;
-        const ts = eventAny.getTs?.() ?? eventAny.origin_server_ts;
-        createdAt = tsToIso(ts);
-        updatedAt = createdAt;
-    }
-    catch {
-        // Same as above.
-    }
-    return { name, mimetype, size, createdAt, updatedAt };
+        catch {
+            if (signal.aborted)
+                throw new StorageError("operation cancelled");
+            // Same as above.
+        }
+        ensureOperationActive(signal);
+        return { name, mimetype, size, createdAt, updatedAt };
+    });
 }
-export async function getFolderDetails(storage, folderId) {
-    const tree = await resolveTree(storage, folderId);
+async function getTreeDetails(storage, treeId, signal) {
+    const tree = await resolveTree(storage, treeId, signal);
+    if (signal?.aborted)
+        throw new StorageError("operation cancelled");
     const client = storage.getClient();
-    const room = client.getRoom(folderId);
+    const room = client.getRoom(treeId);
     let createdAt = null;
     let memberCount = null;
     if (room) {
@@ -345,9 +1413,17 @@ export async function getFolderDetails(storage, folderId) {
         }
     }
     return {
-        name: tree.room.name || roomDisplayName(storage, folderId),
-        id: folderId,
+        name: tree.room.name || roomDisplayName(storage, treeId),
+        id: treeId,
         createdAt,
         memberCount,
     };
 }
+/** Returns details for a top-level Vault. */
+export async function getVaultDetails(storage, vaultId, options) {
+    return withOperationDeadline(options, (signal) => getTreeDetails(storage, vaultId, signal));
+}
+/** Returns details for a nested folder. */
+export async function getFolderDetails(storage, folderId, options) {
+    return withOperationDeadline(options, (signal) => getTreeDetails(storage, folderId, signal));
+}