@telecrypt-io/storage 0.7.2 → 0.8.0

package/README.md

@@ -62,6 +62,15 @@ The SDK maps the file tree to Matrix primitives defined by MSC3089:
 Vault, folder, and file IDs are opaque Matrix room and event IDs. Names are display labels: two
 objects with the same name are still distinct, and a name is not an idempotency key.
 
+Vault and folder names, and file names, are stored in encrypted room messages. Matrix room names
+remain the generic `Encrypted storage`; file-listing state stores only an event pointer, and media
+uploads omit the original filename. Use the asynchronous operations in `@telecrypt-io/storage/core`
+to read names. The synchronous Matrix SDK tree helper cannot decrypt on demand and exposes a generic
+file label until an async operation resolves the name. This is a TeleCrypt metadata format: standard
+MSC3089 clients will not display the private names or understand these file indexes. SDK 0.8 starts
+this format without a reader or migration for trees written by older SDK versions; those old trees
+may be ignored or removed.
+
 File bytes are encrypted in the client before upload with Matrix attachment encryption (AES-CTR
 and a per-file key distributed through the room's Megolm session). The server stores encrypted
 media and Matrix events, but encryption does not hide all room, event, or other metadata from the

package/dist/TeleCryptIOStorage.d.ts

@@ -26,8 +26,9 @@ export interface TreeSpace {
 }
 export interface FileBranch {
     readonly id: string;
+    readonly roomId: string;
     /** Current MSC3089 branch/listing event. Its event ID is distinct from `id` (the state key). */
-    readonly indexEvent?: Pick<MatrixEvent, "getId">;
+    readonly indexEvent?: Pick<MatrixEvent, "getId" | "getContent" | "getSender" | "isRedacted">;
     /** Matrix SDK keeps a redacted branch in state as an inactive object. */
     readonly isActive?: boolean;
     getName(): string;
@@ -144,9 +145,32 @@ export declare function withTreeMutation<T>(client: MatrixClient, operation: (si
 export declare class TeleCryptIOStorage {
     private client;
     private readonly decoratedTreeSpaces;
+    private readonly decoratedFileBranches;
+    private readonly treeNames;
+    private readonly fileNames;
     constructor(client: MatrixClient);
     /** The underlying matrix-js-sdk client (e.g. to stop it, or for advanced/interop use). */
     getClient(): MatrixClient;
+    private fileNameKey;
+    private getStateEvent;
+    private getTreeOwnerId;
+    private sendEncryptedMetadataMessage;
+    private readEncryptedMetadataMessage;
+    private writeTreeName;
+    /** Resolves an encrypted vault/folder name through its pointer state event. */
+    getTreeName(roomId: string, options?: MatrixRequestOptions): Promise<string>;
+    private writeFileName;
+    /** Resolves an encrypted file name from the MSC3089 index pointer. */
+    getFileName(treeId: string, fileId: string, options?: MatrixRequestOptions & {
+        refreshState?: boolean;
+    }): Promise<string>;
+    /** Returns the current file metadata pointer, including on inactive branches. */
+    getFileMetadataEventId(treeId: string, fileId: string, options?: MatrixRequestOptions): Promise<string | null>;
+    /** Fetches and validates a current encrypted rename event, allowing retries after redaction. */
+    getFileRenameMetadataEvent(treeId: string, fileId: string, metadataEventId: string): Promise<MatrixEvent>;
+    /** Fetches the original encrypted file message directly by event ID. */
+    getOriginalFileEvent(treeId: string, fileId: string, allowRedacted?: boolean): Promise<MatrixEvent>;
+    private createEncryptedFile;
     /**
      * Refreshes a room's current state from the homeserver. The background sync
      * loop is intentionally asynchronous, so a short-lived CLI process can
@@ -249,6 +273,7 @@ export declare class TeleCryptIOStorage {
      * which refreshes the exact parent/child state before reporting success.
      */
     private decorateTreeSpace;
+    private decorateFileBranch;
     /** Cleans up only a room created by this operation and reports incomplete cleanup. */
     private cleanupCreatedRoom;
     private removeRelationLink;

package/dist/TeleCryptIOStorage.js

@@ -1,4 +1,4 @@
-import { ClientEvent, createClient, EventType, MatrixEvent, MatrixError, Preset, RoomCreateTypeField, RoomType, SyncState, UNSTABLE_MSC3088_ENABLED, UNSTABLE_MSC3088_PURPOSE, UNSTABLE_MSC3089_BRANCH, UNSTABLE_MSC3089_TREE_SUBTYPE, } from "matrix-js-sdk";
+import { ClientEvent, createClient, EventType, MatrixEvent, MatrixError, MsgType, Preset, RoomCreateTypeField, RoomType, SyncState, UNSTABLE_MSC3088_ENABLED, UNSTABLE_MSC3088_PURPOSE, UNSTABLE_MSC3089_BRANCH, UNSTABLE_MSC3089_LEAF, UNSTABLE_MSC3089_TREE_SUBTYPE, } from "matrix-js-sdk";
 import { Method } from "matrix-js-sdk/lib/http-api/method.js";
 import { ClientPrefix } from "matrix-js-sdk/lib/http-api/prefix.js";
 import { encryptAttachment, decryptAttachment } from "matrix-encrypt-attachment";
@@ -9,6 +9,10 @@ import { cancelResponseBody, raceWithAbort, readMediaResponseBody, readResponseB
 import { sanitizeDiagnosticText } from "./core/oidc.js";
 import { validateName } from "./core/validation.js";
 import { isTreeDeleted } from "./deletion-markers.js";
+const STORAGE_METADATA_EVENT_TYPE = "io.telecrypt.storage.metadata";
+const STORAGE_METADATA_MSGTYPE = "io.telecrypt.storage.metadata";
+const GENERIC_TREE_NAME = "Encrypted storage";
+const GENERIC_FILE_NAME = "Encrypted file";
 const recoveryMutationQueues = new WeakMap();
 const treeMutationQueues = new WeakMap();
 const TREE_SYNC_TIMEOUT_MS = 15000;
@@ -235,12 +239,6 @@ export function readFileEventMetadata(content) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-async function isUndecryptableFilePlaceholder(branch) {
-    // matrix-js-sdk replaces failed encrypted event content with m.bad.encrypted;
-    // its public failure flag is the authoritative state and avoids guessing
-    // from that display content (or misclassifying malformed plaintext events).
-    return (await branch.getFileEvent()).isDecryptionFailure();
-}
 function validateSecretStorageStatus(value) {
     if (!isRecord(value))
         throw new RecoverySetupAmbiguousError();
@@ -409,6 +407,9 @@ export async function withTreeMutation(client, operation, signal) {
 export class TeleCryptIOStorage {
     client;
     decoratedTreeSpaces = new WeakSet();
+    decoratedFileBranches = new WeakMap();
+    treeNames = new Map();
+    fileNames = new Map();
     constructor(client) {
         this.client = client;
         // Advanced callers may construct a MatrixClient themselves. The SDK does
@@ -420,6 +421,229 @@ export class TeleCryptIOStorage {
     getClient() {
         return this.client;
     }
+    fileNameKey(treeId, fileId) {
+        return `${treeId}\u0000${fileId}`;
+    }
+    getStateEvent(roomId, eventType, stateKey) {
+        const state = this.client.getRoom(roomId)?.currentState;
+        const raw = state?.getStateEvents(eventType, stateKey);
+        if (Array.isArray(raw))
+            return raw[0] ?? null;
+        return raw ?? null;
+    }
+    getTreeOwnerId(roomId) {
+        const create = this.getStateEvent(roomId, EventType.RoomCreate, "");
+        const ownerId = create?.getSender();
+        if (!ownerId)
+            throw new StorageError("storage owner is unavailable");
+        return ownerId;
+    }
+    async sendEncryptedMetadataMessage(roomId, content) {
+        const response = await this.client.sendMessage(roomId, content);
+        return validateMatrixEventId(response?.event_id, "storage metadata response event ID");
+    }
+    async readEncryptedMetadataMessage(roomId, eventId, allowRedacted = false) {
+        const rawEvent = await this.client.fetchRoomEvent(roomId, eventId);
+        const event = this.client.getEventMapper()(rawEvent);
+        await this.client.decryptEventIfNeeded(event);
+        if (event.isDecryptionFailure())
+            throw new UndecryptableFileError();
+        if (allowRedacted &&
+            event.getId() === eventId &&
+            event.getRoomId() === roomId &&
+            event.getSender() === this.getTreeOwnerId(roomId) &&
+            event.isRedacted()) {
+            return event;
+        }
+        if (event.getId() !== eventId ||
+            event.getRoomId() !== roomId ||
+            event.getSender() !== this.getTreeOwnerId(roomId) ||
+            event.getWireType() !== EventType.RoomMessageEncrypted ||
+            event.getType() !== EventType.RoomMessage) {
+            throw new StorageError("encrypted storage metadata is invalid or unavailable");
+        }
+        return event;
+    }
+    async writeTreeName(roomId, name) {
+        validateName(name, "name");
+        const metadataEventId = await this.sendEncryptedMetadataMessage(roomId, {
+            msgtype: STORAGE_METADATA_MSGTYPE,
+            body: name,
+        });
+        await this.client.sendStateEvent(roomId, STORAGE_METADATA_EVENT_TYPE, { event_id: metadataEventId }, "");
+        this.treeNames.set(roomId, name);
+    }
+    /** Resolves an encrypted vault/folder name through its pointer state event. */
+    async getTreeName(roomId, options) {
+        if (options?.signal?.aborted)
+            throw new StorageError("operation cancelled");
+        await this.refreshRoomState(roomId, options);
+        const pointer = this.getStateEvent(roomId, STORAGE_METADATA_EVENT_TYPE, "");
+        const pointerContent = pointer?.getContent();
+        if (!pointer ||
+            pointer.getSender() !== this.getTreeOwnerId(roomId) ||
+            !isRecord(pointerContent) ||
+            typeof pointerContent.event_id !== "string") {
+            throw new StorageError("encrypted storage name is unavailable");
+        }
+        const metadataEventId = validateMatrixEventId(pointerContent.event_id, "storage metadata event ID");
+        let event;
+        try {
+            event = await this.readEncryptedMetadataMessage(roomId, metadataEventId);
+        }
+        catch (error) {
+            // A new device can list storage before restoring room keys. Keep the
+            // room visible with a generic label; a later call retries decryption.
+            if (error instanceof UndecryptableFileError)
+                return GENERIC_TREE_NAME;
+            throw error;
+        }
+        const content = event.getContent();
+        if (!isRecord(content) ||
+            content.msgtype !== STORAGE_METADATA_MSGTYPE ||
+            typeof content.body !== "string" ||
+            Object.hasOwn(content, "file_event_id")) {
+            throw new StorageError("encrypted storage name is invalid or unavailable");
+        }
+        validateName(content.body, "name");
+        this.treeNames.set(roomId, content.body);
+        return content.body;
+    }
+    async writeFileName(treeId, fileId, name) {
+        validateName(name, "file name");
+        validateMatrixEventId(fileId, "file event ID");
+        const metadataEventId = await this.sendEncryptedMetadataMessage(treeId, {
+            msgtype: STORAGE_METADATA_MSGTYPE,
+            body: name,
+            file_event_id: fileId,
+        });
+        await this.client.sendStateEvent(treeId, UNSTABLE_MSC3089_BRANCH.name, { active: true, metadata_event_id: metadataEventId }, fileId);
+        this.fileNames.set(this.fileNameKey(treeId, fileId), name);
+    }
+    /** Resolves an encrypted file name from the MSC3089 index pointer. */
+    async getFileName(treeId, fileId, options) {
+        if (options?.signal?.aborted)
+            throw new StorageError("operation cancelled");
+        if (options?.refreshState !== false)
+            await this.refreshRoomState(treeId, options);
+        const tree = this.getTree(treeId);
+        const branch = tree?.getFile(fileId);
+        if (!branch || branch.isActive === false)
+            throw new StorageError("file not found");
+        const indexEvent = branch.indexEvent;
+        const indexContent = indexEvent?.getContent();
+        if (!indexEvent ||
+            indexEvent.getSender() !== this.getTreeOwnerId(treeId) ||
+            !isRecord(indexContent) ||
+            indexContent.active !== true ||
+            typeof indexContent.metadata_event_id !== "string") {
+            throw new StorageError("encrypted file name is unavailable");
+        }
+        const metadataEventId = validateMatrixEventId(indexContent.metadata_event_id, "file metadata event ID");
+        let event;
+        try {
+            event = await this.readEncryptedMetadataMessage(treeId, metadataEventId);
+        }
+        catch (error) {
+            // File IDs remain listable on a fresh device while its room keys are
+            // being restored. The caller can resolve the private name on retry.
+            if (error instanceof UndecryptableFileError)
+                return GENERIC_FILE_NAME;
+            throw error;
+        }
+        const content = event.getContent();
+        if (!isRecord(content) || typeof content.body !== "string") {
+            throw new StorageError("encrypted file name is invalid or unavailable");
+        }
+        if (content.msgtype === MsgType.File) {
+            if (metadataEventId !== fileId || !isRecord(content.file)) {
+                throw new StorageError("encrypted file metadata does not match its listing");
+            }
+        }
+        else if (content.msgtype !== STORAGE_METADATA_MSGTYPE ||
+            content.file_event_id !== fileId) {
+            throw new StorageError("encrypted file metadata does not match its listing");
+        }
+        validateName(content.body, "file name");
+        this.fileNames.set(this.fileNameKey(treeId, fileId), content.body);
+        return content.body;
+    }
+    /** Returns the current file metadata pointer, including on inactive branches. */
+    async getFileMetadataEventId(treeId, fileId, options) {
+        if (options?.signal?.aborted)
+            throw new StorageError("operation cancelled");
+        await this.refreshRoomState(treeId, options);
+        const branch = this.getTree(treeId)?.getFile(fileId);
+        if (!branch)
+            throw new StorageError("file not found");
+        const indexEvent = branch.indexEvent;
+        const content = indexEvent?.getContent();
+        if (!indexEvent || indexEvent.getSender() !== this.getTreeOwnerId(treeId)) {
+            throw new StorageError("encrypted file listing is unavailable");
+        }
+        if (!isRecord(content) ||
+            typeof content.metadata_event_id !== "string") {
+            if (branch.isActive === false || indexEvent.isRedacted())
+                return null;
+            throw new StorageError("encrypted file name is unavailable");
+        }
+        return validateMatrixEventId(content.metadata_event_id, "file metadata event ID");
+    }
+    /** Fetches and validates a current encrypted rename event, allowing retries after redaction. */
+    async getFileRenameMetadataEvent(treeId, fileId, metadataEventId) {
+        const event = await this.readEncryptedMetadataMessage(treeId, metadataEventId, true);
+        if (event.isRedacted())
+            return event;
+        const content = event.getContent();
+        if (!isRecord(content) ||
+            content.msgtype !== STORAGE_METADATA_MSGTYPE ||
+            content.file_event_id !== fileId ||
+            typeof content.body !== "string") {
+            throw new StorageError("encrypted file metadata does not match its listing");
+        }
+        validateName(content.body, "file name");
+        return event;
+    }
+    /** Fetches the original encrypted file message directly by event ID. */
+    async getOriginalFileEvent(treeId, fileId, allowRedacted = false) {
+        const event = await this.readEncryptedMetadataMessage(treeId, fileId, allowRedacted);
+        if (event.isRedacted() && allowRedacted)
+            return event;
+        const content = event.getContent();
+        if (!isRecord(content) ||
+            content.msgtype !== MsgType.File ||
+            typeof content.body !== "string" ||
+            !isRecord(content.file) ||
+            typeof content.file.url !== "string") {
+            throw new StorageError("encrypted file message is invalid or unavailable");
+        }
+        return event;
+    }
+    async createEncryptedFile(treeId, name, encryptedContents, info, additionalContent) {
+        validateFileName(name);
+        const bytes = encryptedContents instanceof Uint8Array
+            ? encryptedContents
+            : new Uint8Array(encryptedContents);
+        const body = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        const uploaded = await this.client.uploadContent(body, { includeFilename: false });
+        if (typeof uploaded.content_uri !== "string" || uploaded.content_uri.length === 0) {
+            throw new StorageError("encrypted media upload returned no content URI");
+        }
+        const fileInfo = { ...info, url: uploaded.content_uri };
+        const fileContent = {
+            ...additionalContent,
+            msgtype: MsgType.File,
+            body: name,
+            url: uploaded.content_uri,
+            file: fileInfo,
+            [UNSTABLE_MSC3089_LEAF.name]: {},
+        };
+        const sent = await this.client.sendMessage(treeId, fileContent);
+        const fileEventId = validateMatrixEventId(sent?.event_id, "file upload response event ID");
+        await this.client.sendStateEvent(treeId, UNSTABLE_MSC3089_BRANCH.name, { active: true, metadata_event_id: fileEventId }, fileEventId);
+        this.fileNames.set(this.fileNameKey(treeId, fileEventId), name);
+        return { event_id: fileEventId };
+    }
     /**
      * Refreshes a room's current state from the homeserver. The background sync
      * loop is intentionally asynchronous, so a short-lived CLI process can
@@ -1030,7 +1254,7 @@ export class TeleCryptIOStorage {
         if (!userId)
             throw new Error("createTree: Matrix client has no user ID");
         return {
-            name,
+            name: GENERIC_TREE_NAME,
             preset: Preset.PrivateChat,
             power_level_content_override: {
                 invite: 100,
@@ -1052,6 +1276,7 @@ export class TeleCryptIOStorage {
                     [EventType.SpaceChild]: 100,
                     [EventType.SpaceParent]: 100,
                     [UNSTABLE_MSC3089_BRANCH.name]: 100,
+                    [STORAGE_METADATA_EVENT_TYPE]: 100,
                 },
                 users: { [userId]: 100 },
             },
@@ -1119,10 +1344,46 @@ export class TeleCryptIOStorage {
             return tree;
         this.decoratedTreeSpaces.add(tree);
         const originalGetDirectories = tree.getDirectories.bind(tree);
+        const originalListFiles = typeof tree.listFiles === "function"
+            ? tree.listFiles.bind(tree)
+            : () => [];
+        const originalGetFile = typeof tree.getFile === "function"
+            ? tree.getFile.bind(tree)
+            : () => null;
         tree.getDirectories = () => originalGetDirectories().map((child) => this.decorateTreeSpace(child));
         tree.createDirectory = (name) => this.createSubtree(tree, name);
+        tree.setName = (name) => this.writeTreeName(tree.id, name);
+        tree.listFiles = () => originalListFiles().map((branch) => this.decorateFileBranch(tree.id, branch));
+        tree.getFile = (fileId) => {
+            const branch = originalGetFile(fileId);
+            return branch ? this.decorateFileBranch(tree.id, branch) : null;
+        };
+        tree.createFile = (name, encryptedContents, info, additionalContent) => this.createEncryptedFile(tree.id, name, encryptedContents, info, additionalContent);
         return tree;
     }
+    decorateFileBranch(treeId, branch) {
+        const existing = this.decoratedFileBranches.get(branch);
+        if (existing)
+            return existing;
+        const decorated = Object.create(branch);
+        const nameKey = this.fileNameKey(treeId, branch.id);
+        Object.defineProperties(decorated, {
+            getName: {
+                value: () => this.fileNames.get(nameKey) ?? GENERIC_FILE_NAME,
+            },
+            setName: {
+                value: (name) => this.writeFileName(treeId, branch.id, name),
+            },
+            delete: {
+                value: async () => {
+                    const { deleteFile } = await import("./core/operations.js");
+                    await deleteFile(this, treeId, branch.id);
+                },
+            },
+        });
+        this.decoratedFileBranches.set(branch, decorated);
+        return decorated;
+    }
     /** Cleans up only a room created by this operation and reports incomplete cleanup. */
     async cleanupCreatedRoom(roomId) {
         // Cleanup is compensating work. It must not inherit the caller's already
@@ -1203,9 +1464,26 @@ export class TeleCryptIOStorage {
             throw new RoomCreationAmbiguousError(operation, error);
         }
         try {
-            return await this.waitForTreeSpace(roomId, operation, signal);
+            const tree = await this.waitForTreeSpace(roomId, operation, signal);
+            try {
+                await this.writeTreeName(roomId, name);
+            }
+            catch (error) {
+                try {
+                    await this.cleanupCreatedRoom(roomId);
+                }
+                catch (cleanupError) {
+                    throwWithCleanupDetail(error, roomId, cleanupError);
+                }
+                throw new StorageError(`${operation}: encrypted name initialization failed`, { cause: error });
+            }
+            return tree;
         }
         catch (error) {
+            if (error instanceof StorageError &&
+                error.message === `${operation}: encrypted name initialization failed`) {
+                throw error;
+            }
             try {
                 await this.cleanupCreatedRoom(roomId);
             }
@@ -1409,7 +1687,9 @@ export class TeleCryptIOStorage {
         const members = parseMatrixMembersResponse(membersBody);
         const pls = parseMatrixPowerLevels(plsRaw);
         const viewLevel = pls.users_default ?? 0;
-        const editLevel = pls.events_default ?? 50;
+        // Match matrix-js-sdk's MSC3089TreeSpace.getPermissions() default. An
+        // explicit zero still means regular users lack the editor threshold.
+        const editLevel = pls.events_default || 50;
         const adminLevel = pls.events?.["m.room.power_levels"] ?? 100;
         const roleFor = (userId) => {
             const userLevel = pls.users?.[userId] ?? viewLevel;
@@ -1479,27 +1759,17 @@ export class TeleCryptIOStorage {
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
         let info;
+        let fileEvent;
         try {
-            ({ info } = await branch.getFileInfo());
+            fileEvent = await this.getOriginalFileEvent(branch.roomId, branch.id);
+            const content = fileEvent.getContent();
+            info = isRecord(content) && isRecord(content.file) ? content.file : undefined;
         }
         catch (error) {
             if (signal?.aborted)
                 throw new StorageError("operation cancelled");
             if (error instanceof StorageError || error instanceof MatrixError)
                 throw error;
-            // matrix-js-sdk's file-info accessor reads an attachment absent from
-            // failed-decryption events. Use its explicit decryption status, not a
-            // guessed content shape; preserve other SDK/transport failures.
-            let isPlaceholder = false;
-            try {
-                isPlaceholder = await isUndecryptableFilePlaceholder(branch);
-            }
-            catch (placeholderError) {
-                throw new AggregateError([error, placeholderError], "file metadata lookup and placeholder inspection both failed", { cause: error });
-            }
-            if (isPlaceholder) {
-                throw new UndecryptableFileError();
-            }
             throw error;
         }
         // Missing metadata alone does not establish a decryption failure.
@@ -1509,7 +1779,7 @@ export class TeleCryptIOStorage {
         // `info` is the encrypted attachment descriptor. Its shape is owned by
         // matrix-encrypt-attachment and does not carry the plaintext size. The
         // event's `info` block is the sole source of user-facing file metadata.
-        const eventMetadata = readFileEventMetadata((await branch.getFileEvent()).getContent());
+        const eventMetadata = readFileEventMetadata(fileEvent.getContent());
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
         const declaredSize = eventMetadata.size;

package/dist/core/operations.js

@@ -11,9 +11,10 @@
  * platform-specific and stays with the caller.
  */
 import { readFileEventMetadata, 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 { 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 { 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";
@@ -237,8 +238,6 @@ async function refreshDeletionRooms(storage, rootId, signal) {
         throw new StorageError("could not enumerate storage parent safely");
     const parentIds = new Set();
     for (const event of parentEvents) {
-        if (!isActiveRelationEvent(event))
-            continue;
         const parentId = relationStateKey(event);
         if (!parentId)
             throw new StorageError("could not enumerate storage parent safely");
@@ -250,11 +249,6 @@ async function refreshDeletionRooms(storage, rootId, signal) {
     const parents = [...parentIds];
     if (parents[0]) {
         await storage.refreshRoomState(parents[0], { signal });
-        const childEvents = readRelationEvents(client, parents[0], EventType.SpaceChild, rootId);
-        if (childEvents === null ||
-            !childEvents.some((event) => isActiveRelationEvent(event) && relationStateKey(event, rootId) === rootId)) {
-            throw new StorageError("storage parent relation is inconsistent");
-        }
     }
     if (signal?.aborted)
         throw new StorageError("operation cancelled");
@@ -332,25 +326,46 @@ function activeTreeDirectories(client, tree) {
 }
 async function unlinkExternalParents(storage, rootId, externalParents, signal) {
     const client = storage.getClient();
-    let mutationAttempted = false;
+    const completedRelationEventIds = [];
+    const redactRelation = async (roomId, eventType, stateKey) => {
+        await storage.refreshRoomState(roomId, { signal });
+        if (signal?.aborted)
+            throw new StorageError("operation cancelled");
+        const events = readRelationEvents(client, roomId, eventType, stateKey);
+        if (events === null)
+            throw new StorageError("storage folder state is unavailable");
+        const event = events[0];
+        if (!event || !isActiveRelationEvent(event))
+            return;
+        const currentUserId = client.getUserId();
+        if (!currentUserId || event.getSender?.() !== currentUserId) {
+            throw new StorageError("storage folder relation was not authored by the owner");
+        }
+        const eventId = validateMatrixEventId(event.getId?.(), "storage folder relation event ID");
+        await withRateLimitRetry(() => withMatrixMutationAbort(() => client.redactEvent(roomId, eventId), signal), signal);
+        if (!completedRelationEventIds.includes(eventId))
+            completedRelationEventIds.push(eventId);
+        await storage.refreshRoomState(roomId, { signal });
+        const remaining = readRelationEvents(client, roomId, eventType, stateKey);
+        if (remaining === null || remaining.some((candidate) => isActiveRelationEvent(candidate))) {
+            throw new StorageError("delete graph unlink could not be verified");
+        }
+    };
     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.sendStateEvent(parentId, EventType.SpaceChild, {}, rootId), signal), signal);
-            if (signal?.aborted)
-                throw new StorageError("operation cancelled");
-            await withRateLimitRetry(() => withMatrixMutationAbort(() => client.sendStateEvent(rootId, EventType.SpaceParent, {}, parentId), signal), signal);
+            // Redact owner-authored relations one room at a time. If the process stops
+            // after the parent-side redaction, the redacted state key remains visible
+            // and the next call continues with the child-side relation.
+            await redactRelation(parentId, EventType.SpaceChild, rootId);
+            await redactRelation(rootId, EventType.SpaceParent, parentId);
             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 ||
+            if (childLink === null ||
+                parentLink === null ||
                 childLink.some((event) => isActiveRelationEvent(event)) ||
                 parentLink.some((event) => isActiveRelationEvent(event))) {
                 throw new StorageError("delete graph unlink could not be verified");
@@ -358,45 +373,14 @@ async function unlinkExternalParents(storage, rootId, externalParents, signal) {
         }
     }
     catch (error) {
-        if (!mutationAttempted && error instanceof StorageError && error.message === "operation cancelled") {
+        if (error instanceof MutationOutcomeUnknownError || error instanceof MutationPartialError)
             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 (cleanupError) {
-            throw new StorageError("delete graph unlink cleanup is incomplete", {
-                cause: new AggregateError([error, cleanupError], "delete graph unlink and relink both failed", { cause: error }),
-            });
+        if (completedRelationEventIds.length > 0) {
+            throw new MutationPartialError("delete folder links", completedRelationEventIds, "some parent links were removed; retry deleting the same folder to finish unlinking", { cause: error });
         }
         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.sendStateEvent(parentId, EventType.SpaceChild, { via: [via] }, rootId), signal), signal);
-        await withRateLimitRetry(() => withMatrixMutationAbort(() => 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");
-        }
-    }
-}
 function isGoneError(error) {
     return (error instanceof MatrixError &&
         (error.errcode === "M_NOT_FOUND" || error.errcode === "M_UNKNOWN"));
@@ -409,12 +393,25 @@ async function deleteRoomDeterministically(storage, roomId, signal) {
     };
     try {
         const client = storage.getClient();
-        const tree = storage.getTree(roomId);
-        if (!tree)
-            throw new StorageError("storage room is unavailable for deletion");
         const self = client.getUserId();
         if (!self)
             throw new StorageError("Matrix user identity is unavailable");
+        const ownMembership = await storage.getRoomMembership(roomId, undefined, { signal });
+        if (ownMembership === "leave" || ownMembership === "ban") {
+            try {
+                await withRateLimitRetry(() => withMatrixMutationAbort(() => client.forget(roomId), signal), signal);
+            }
+            catch (error) {
+                if (!isGoneError(error))
+                    throw error;
+            }
+            removeRoomFromLocalStore(client, roomId);
+            markTreeDeleted(client, roomId);
+            return;
+        }
+        const tree = storage.getTree(roomId);
+        if (!tree)
+            throw new StorageError("storage room is unavailable for deletion");
         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"))) {
@@ -444,7 +441,6 @@ async function deleteRoomDeterministically(storage, roomId, signal) {
                 throw error;
             }
         }
-        const ownMembership = await storage.getRoomMembership(roomId, undefined, { signal });
         if (ownMembership === "join" || ownMembership === "invite" || ownMembership === "knock") {
             try {
                 await withRateLimitRetry(() => withMatrixMutationAbort(() => client.leave(roomId), signal), signal);
@@ -522,7 +518,11 @@ export async function createVault(storage, name, options) {
 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 }));
+        const topLevel = trees.filter((tree) => tree.isTopLevel);
+        return Promise.all(topLevel.map(async (tree) => ({
+            id: tree.id,
+            name: await storage.getTreeName(tree.id, { signal }),
+        })));
     });
 }
 /** Current account's effective role for a vault, or null while it is unavailable. */
@@ -574,17 +574,8 @@ export async function joinVault(storage, vaultId, options) {
         return { vaultId, joined: true };
     }, "mutation");
 }
-function roomDisplayName(storage, roomId, fallbackName) {
-    const client = storage.getClient();
-    const room = client.getRoom(roomId);
-    if (fallbackName?.trim())
-        return fallbackName.trim();
-    if (room?.name)
-        return room.name;
-    const userId = client.getUserId();
-    if (room && userId)
-        return room.getDefaultRoomName(userId);
-    return roomId;
+function roomDisplayName(_storage, _roomId, _fallbackName) {
+    return "Encrypted storage";
 }
 function hasActiveSpaceParent(room) {
     const result = room.currentState?.getStateEvents?.(EventType.SpaceParent);
@@ -908,7 +899,10 @@ export async function listFiles(storage, treeId, options) {
             const files = tree
                 .listFiles()
                 .filter((file) => !isMarkedFileDeleted(storage, tree.id, file.id));
-            return files.map((f) => ({ id: f.id, name: f.getName() }));
+            return await Promise.all(files.map(async (file) => ({
+                id: file.id,
+                name: await storage.getFileName(tree.id, file.id, { signal, refreshState: false }),
+            })));
         }
         catch (error) {
             if (signal.aborted)
@@ -925,7 +919,10 @@ export async function listSubfolders(storage, parentId, options) {
         ensureOperationActive(signal);
         const directories = activeTreeDirectories(storage.getClient(), tree)
             .filter((directory) => !isMarkedTreeDeleted(storage, directory.id));
-        return directories.map((d) => ({ id: d.id, name: d.room.name }));
+        return Promise.all(directories.map(async (directory) => ({
+            id: directory.id,
+            name: await storage.getTreeName(directory.id, { signal }),
+        })));
     });
 }
 export async function createSubfolder(storage, parentId, name, options) {
@@ -957,11 +954,9 @@ async function renameTree(storage, treeId, name, options) {
             await waitForCondition(async () => {
                 ensureOperationActive(signal);
                 const current = storage.getTree(treeId);
-                if (current?.room.name === name)
-                    return current;
-                await storage.refreshRoomState(treeId, { signal });
-                const refreshed = storage.getTree(treeId);
-                return refreshed?.room.name === name ? refreshed : null;
+                if (!current)
+                    return null;
+                return (await storage.getTreeName(treeId, { signal })) === name ? current : null;
             }, { timeoutMs: 15000, signal });
         }
         catch (error) {
@@ -990,6 +985,20 @@ async function deleteTree(storage, treeId, options) {
         const pending = withTreeMutation(client, async () => {
             if (isTreeDeleted(client, treeId))
                 return { id: treeId, deleted: true };
+            const ownMembership = await storage.getRoomMembership(treeId, undefined, {
+                signal: operation.signal,
+            });
+            if (ownMembership === "leave" || ownMembership === "ban") {
+                try {
+                    await deleteRoomDeterministically(storage, treeId, operation.signal);
+                }
+                catch (error) {
+                    if (error instanceof StorageError)
+                        throw error;
+                    throw new StorageError("delete cleanup failed", { cause: error });
+                }
+                return { id: treeId, deleted: true };
+            }
             const tree = await resolveTree(storage, treeId, operation.signal);
             let externalParents;
             try {
@@ -1015,14 +1024,6 @@ async function deleteTree(storage, treeId, options) {
                 await deleteRoomDeterministically(storage, tree.id, operation.signal);
             }
             catch (error) {
-                try {
-                    await relinkExternalParents(storage, tree.id, externalParents, new AbortController().signal);
-                }
-                catch (cleanupError) {
-                    throw new StorageError("delete cleanup is incomplete", {
-                        cause: new AggregateError([error, cleanupError], "delete and external-parent relink both failed", { cause: error }),
-                    });
-                }
                 if (error instanceof StorageError)
                     throw error;
                 throw new StorageError("delete failed", { cause: error });
@@ -1054,9 +1055,11 @@ export async function renameFile(storage, treeId, fileId, name, options) {
             // 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(() => {
+            await waitForCondition(async () => {
                 const current = tree.getFile(fileId);
-                return current?.getName() === name ? current : null;
+                if (!current)
+                    return null;
+                return (await storage.getFileName(treeId, fileId, { signal })) === name ? current : null;
             }, { timeoutMs: 15000, signal });
         }
         catch (error) {
@@ -1093,51 +1096,80 @@ async function deleteFileMedia(storage, mediaIds, signal) {
 export async function deleteFile(storage, treeId, fileId, options) {
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, treeId, signal);
-        const branch = await resolveFile(storage, tree, fileId, signal);
-        let fileInfo;
+        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 {
-            fileInfo = await branch.getFileInfo();
+            originalEvent = await storage.getOriginalFileEvent(tree.id, fileId, true);
         }
         catch (error) {
             throw new StorageError("could not resolve encrypted file safely", { cause: error });
         }
-        const mediaId = fileInfo?.info?.url;
+        if (originalEvent.isRedacted()) {
+            if (branch.isActive === false) {
+                markFileDeleted(storage.getClient(), tree.id, fileId);
+                return { id: fileId, deleted: true };
+            }
+            throw new StorageError("file listing is active but its attachment event is redacted");
+        }
+        const originalContent = originalEvent.getContent();
+        const fileDescriptor = typeof originalContent === "object" &&
+            originalContent !== null &&
+            !Array.isArray(originalContent) &&
+            "file" in originalContent &&
+            typeof originalContent.file === "object" &&
+            originalContent.file !== null &&
+            !Array.isArray(originalContent.file)
+            ? originalContent.file
+            : undefined;
+        const mediaId = fileDescriptor?.url;
         if (typeof mediaId !== "string" || mediaId.length === 0) {
             throw new StorageError("encrypted file has no media identifier");
         }
         await deleteFileMedia(storage, [mediaId], signal);
-        const completedIds = [];
+        const completedIds = [mediaId];
         try {
             const client = storage.getClient();
-            // MSC3089 uses the file event ID as the branch state key, but the current
-            // listing is a separate state event. Redact that current listing after
-            // clearing the branch state; redacting only the file event leaves the
-            // listing visible and is especially harmful when a user is suspended.
-            const listingEventId = branch.indexEvent?.getId?.() ?? branch.id;
-            if (typeof listingEventId !== "string" || listingEventId.length === 0) {
+            const metadataEventId = await storage.getFileMetadataEventId(tree.id, fileId, { signal });
+            if (metadataEventId && metadataEventId !== fileId) {
+                const metadataEvent = await storage.getFileRenameMetadataEvent(tree.id, fileId, metadataEventId);
+                if (!metadataEvent.isRedacted()) {
+                    await withRateLimitRetry(() => withMatrixMutationAbort(() => client.redactEvent(tree.id, metadataEventId), signal, "delete file rename metadata"), signal);
+                }
+                completedIds.push(metadataEventId);
+            }
+            const currentBranch = tree.getFile(fileId);
+            const indexEvent = currentBranch?.indexEvent;
+            const listingEventId = indexEvent?.getId();
+            if (!indexEvent || typeof listingEventId !== "string" || listingEventId.length === 0) {
                 throw new StorageError("encrypted file has no listing event identifier");
             }
-            await withRateLimitRetry(() => withMatrixMutationAbort(() => client.sendStateEvent(tree.id, UNSTABLE_MSC3089_BRANCH.name, {}, branch.id), signal, "delete file state"), signal);
-            await withRateLimitRetry(() => withMatrixMutationAbort(() => client.redactEvent(tree.id, listingEventId), signal, "delete file event"), signal);
+            if (!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);
+            await withRateLimitRetry(() => withMatrixMutationAbort(() => client.redactEvent(tree.id, fileId), signal, "delete file attachment event"), signal);
+            completedIds.push(fileId);
         }
         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", { cause: error });
-            }
-            throw new MutationPartialError("delete file", completedIds, "media was deleted but Matrix event cleanup stopped", { cause: error });
+            throw new MutationPartialError("delete file", completedIds, "file media and the listed completed steps were deleted; retry with the original file ID to finish Matrix cleanup", { cause: error });
         }
         try {
             await waitForCondition(async () => {
                 await storage.refreshRoomState(tree.id, { signal });
                 ensureOperationActive(signal);
                 const current = tree.getFile(fileId);
-                // Matrix SDK keeps a redacted branch event in room state as an
-                // inactive branch. Treat both an absent branch and that redacted
-                // inactive branch as confirmed deletion.
-                return !current || current.isActive === false ? true : null;
+                if (current && current.isActive !== false)
+                    return null;
+                const attachment = await storage.getOriginalFileEvent(tree.id, fileId, true);
+                return attachment.isRedacted() ? true : null;
             }, { timeoutMs: 15000, signal });
         }
         catch (error) {
@@ -1146,7 +1178,7 @@ export async function deleteFile(storage, treeId, fileId, options) {
             const detail = "Matrix deletion completed but the file state could not be verified";
             throw new MutationPartialError("delete file", completedIds, detail, { cause: error });
         }
-        markFileDeleted(storage.getClient(), tree.id, branch.id);
+        markFileDeleted(storage.getClient(), tree.id, fileId);
         ensureOperationActive(signal);
         return { id: fileId, deleted: true };
     }, "mutation");
@@ -1205,7 +1237,7 @@ export async function downloadFile(storage, treeId, fileId, options) {
         return {
             bytes: new Uint8Array(result.data),
             mimetype: result.mimetype,
-            name: branch.getName(),
+            name: await storage.getFileName(tree.id, fileId, { signal }),
         };
     });
 }
@@ -1223,15 +1255,15 @@ function tsToIso(ts) {
 export async function getFileDetails(storage, treeId, fileId, options) {
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, treeId, signal);
-        const branch = await resolveFile(storage, tree, fileId, signal);
-        const name = branch.getName();
+        await resolveFile(storage, tree, fileId, signal);
+        const name = await storage.getFileName(tree.id, fileId, { signal });
         let mimetype = null;
         let size = null;
         let createdAt = null;
         let updatedAt = null;
         try {
             ensureOperationActive(signal);
-            const event = await branch.getFileEvent();
+            const event = await storage.getOriginalFileEvent(tree.id, fileId);
             const metadata = readFileEventMetadata(event.getContent());
             mimetype = metadata.mimetype;
             size = metadata.size;
@@ -1250,7 +1282,7 @@ export async function getFileDetails(storage, treeId, fileId, options) {
     });
 }
 async function getTreeDetails(storage, treeId, signal) {
-    const tree = await resolveTree(storage, treeId, signal);
+    await resolveTree(storage, treeId, signal);
     if (signal?.aborted)
         throw new StorageError("operation cancelled");
     const client = storage.getClient();
@@ -1268,7 +1300,7 @@ async function getTreeDetails(storage, treeId, signal) {
         }
     }
     return {
-        name: tree.room.name || roomDisplayName(storage, treeId),
+        name: await storage.getTreeName(treeId, { signal }),
         id: treeId,
         createdAt,
         memberCount,

package/package.json

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