@telecrypt-io/storage 0.7.1 → 0.8.0

package/README.md

@@ -2,19 +2,9 @@
 
 [![npm](https://img.shields.io/npm/v/@telecrypt-io/storage)](https://www.npmjs.com/package/@telecrypt-io/storage)
 
-End-to-end encrypted file storage and sharing, built on Matrix.
-
-The current public TeleCrypt architecture, responsibilities, and product limits are authoritative at
-[telecrypt-io.github.io/llms-authority/llms.txt](https://telecrypt-io.github.io/llms-authority/llms.txt). This README documents this SDK's package API
-and development workflow.
-
-Files are encrypted on the client before upload. The server stores only opaque ciphertext and
-never holds the decryption keys. Shared vaults let multiple people add and read files, and a
-Recovery Key restores your files on a new device — even if you lose the original.
-
-This repository publishes the library package from annotated version tags using npm Trusted
-Publishing. GitHub Releases identify the corresponding source version. The command-line client is
-maintained in its own repository.
+A JavaScript/TypeScript SDK for encrypted Matrix file trees, based on
+[MSC3089](https://github.com/matrix-org/matrix-spec-proposals/pull/3089), an open and currently
+unmerged Matrix proposal.
 
 ## Install
 
@@ -22,119 +12,88 @@ maintained in its own repository.
 npm install @telecrypt-io/storage
 ```
 
-This gives you the `TeleCryptIOStorage` library and its browser-safe `core` API.
+## Browser quick start
 
-## Quick start
-
-**Library:**
+The example below starts with an authenticated OIDC session. Obtain `userId`, `accessToken`, and
+`deviceId` from that completed session. `baseUrl` and `serverName` must come from trusted
+application configuration for the same Matrix deployment; do not accept them from an untrusted
+request.
 
 ```ts
 import { TeleCryptIOStorage } from "@telecrypt-io/storage";
 import * as core from "@telecrypt-io/storage/core";
 
+// baseUrl/serverName come from trusted application configuration.
+// userId/accessToken/deviceId come from completed OIDC authentication.
 const storage = await TeleCryptIOStorage.create({
-  baseUrl, userId, accessToken, deviceId,
+  baseUrl, serverName, userId, accessToken, deviceId,
 });
-const vault = await core.createVault(storage, "Photos");
-await core.uploadFile(storage, vault.id, "cat.jpg", bytes, "image/jpeg");
+try {
+  const vault = await core.createVault(storage, "Example");
+  const file = await core.uploadFile(
+    storage, vault.id, "hello.txt",
+    new TextEncoder().encode("Hello"), "text/plain",
+  );
+  const downloaded = await core.downloadFile(storage, vault.id, file.id);
+  console.log(new TextDecoder().decode(downloaded.bytes));
+} finally {
+  storage.getClient().stopClient();
+}
 ```
 
-The recommended constructors configure the Matrix client with the SDK's manual-redirect transport
-and finite request deadline. The public `new TeleCryptIOStorage(client)` constructor is
-an advanced escape hatch: it does not rewrite matrix-js-sdk internals. Callers using it must build
-the client through matrix-js-sdk's supported `createClient` options (`fetchFn` and
-`localTimeoutMs`) and remain responsible for the safety of other Matrix SDK requests. SDK methods
-that need the authenticated transport fail closed when it is unavailable; they do not silently
-install a private transport configuration.
-
-Same-name vault/folder creation is serialized within one `TeleCryptIOStorage` instance, but
-each call creates a distinct room. Display names are labels, not identities, and Matrix
-provides no server-side room-creation idempotency key.
-
-## OIDC API
-
-The SDK owns the browser authorization-code PKCE context in `sessionStorage` and provides device-code,
-discovery, dynamic registration, identity confirmation, and refresh helpers. OAuth metadata, token
-scopes, Matrix user/device identities, redirects, and complete response bodies are validated before
-they are returned. Network-bound helpers accept `AbortSignal` where cancellation is meaningful; token
-refresh uses a public client and persists the resulting token pair through the caller's callback.
-
-The command-line client is sourced by
-[`TeleCrypt-io/storage-cli`](https://github.com/TeleCrypt-io/storage-cli). The static web
-application is sourced by
-[`TeleCrypt-io/storage.telecrypt.io`](https://github.com/TeleCrypt-io/storage.telecrypt.io).
-
-### 0.5 OIDC migration
-
-Version 0.5 targets Matrix JS SDK 42 and the stable Matrix OAuth metadata endpoint. Existing
-integrations must use the current `createFromOidc` options and pass the confirmed Matrix user ID,
-device ID, and access token returned by the login flow. Replace old Matrix SDK OIDC imports and
-private HTTP discovery with `discoverOidcIssuer`, `registerClient`, the device-code or PKCE flow
-helpers, and `whoAmI` from `core/oidc`; the discovery URL is the stable
-`/_matrix/client/v1/auth_metadata` endpoint. Refresh integration uses
-`buildTokenRefreshFunction` as the current `tokenRefreshFunction` callback and must persist the
-returned token pair before reporting success. The SDK no longer carries pre-0.5 compatibility
-paths, so no adapter-side shim is required or supported. Discovery accepts providers that omit
-`revocation_endpoint`; revocation is only an opportunistic cleanup path after refresh persistence
-fails. Device-code sessions retain their requested device ID in-process; callers that reconstruct a
-session must pass its expected device ID to `waitForDeviceCodeLogin`. `buildTokenRefreshFunction`
-always requires the expected device ID because a reconstructed refresh callback has no safe implicit
-binding. Returned OAuth scopes are rejected unless they match that intended Matrix device exactly.
-
-## How it works
-
-Built on [MSC3089](https://github.com/matrix-org/matrix-spec-proposals/pull/3089), which models
-a file tree using Matrix primitives:
-
-| Storage concept | Matrix concept |
-|---|---|
-| Vault | A Space (room marked as a file tree) |
-| Folder | A child Space |
-| File | An event pointing at encrypted uploaded content |
-| Sharing | Room invitation |
-| Permissions | Power levels |
-
-### Deletion
-
-Vaults and folders are deleted only when they are empty. Delete each file first; deleting a file
-also removes its encrypted media object before redacting its Matrix event. Delete empty child
-folders before deleting their parent. A nonempty delete
-fails with `NonEmptyTreeError`, so a shared or nested tree is never removed implicitly.
-
-Encryption uses the same scheme as Matrix attachments (AES-CTR with a per-file key, keys
-distributed via the room's Megolm session). File deletion uses TeleCrypt's authenticated Synapse
-storage extension to remove the local media object before Matrix redaction; stock
-Synapse without that extension cannot provide the SDK deletion contract.
-
-## Development
+`TeleCryptIOStorage.create` initializes the Matrix client and its persistent browser crypto store
+by default. Browser persistence uses IndexedDB and the Matrix Rust crypto WASM runtime, so this
+example assumes a browser environment. OIDC discovery, login, refresh, and the corresponding
+`createFromOidc` inputs are exported from `@telecrypt-io/storage/core`.
 
-```bash
-npm ci --ignore-scripts --no-fund --no-audit
-npm run test:unit      # unit-only checks; does not start Podman
-npm run synapse:up     # disposable local Synapse/MAS fixture
-npm test               # full SDK suite, including fixture-backed functional tests
-```
+The example creates retained Matrix rooms and encrypted media. Delete its file and then its empty
+vault when finished; cleanup is part of the operation, not an automatic consequence of stopping
+the client.
+
+## Storage model and behavior
+
+The SDK maps the file tree to Matrix primitives defined by MSC3089:
+
+- A vault is a Matrix Space room marked as a file tree.
+- A folder is a child Space in that tree.
+- A file is a Matrix event referring to encrypted uploaded content.
+- Sharing uses Matrix room invitations and permissions use Matrix power levels.
 
-The full suite uses the real local Synapse/MAS/Postgres fixture in Podman at `localhost:8008`, never
-a production server. This is the shared fixture for the SDK, CLI, and Web functional/e2e suites;
-start it from this checkout and reuse it for the sibling repositories. Unit tests may use mocks for
-isolated boundaries, but they do not replace the real-stack checks.
+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.
 
-If setup or tests fail, inspect the relevant logs, then run `npm run synapse:down` when finished.
+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.
 
-After a successful run, use `npm run synapse:down` for scoped teardown. Use
-`./throwaway_synapse/down.sh --wipe` only when a complete fixture reset is explicitly required.
+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
+server or users who can read the room.
 
-See [RELEASING.md](./RELEASING.md) for the npm release procedure.
+Recovery is explicit. Use `core.setupRecovery(storage)` to create a recovery key and keep that key
+securely; use `core.restoreRecovery(storage, recoveryKey)` on a new device. Losing the recovery key
+can prevent encrypted keys from being restored.
 
-## Licence
+Deletion has strict ordering. Delete files before their folders or vaults because folders and
+vaults must be empty. File deletion removes the encrypted media object before redacting its Matrix
+event and requires TeleCrypt's Synapse storage extension; stock Synapse cannot provide that
+deletion contract.
 
-[Business Source License 1.1](./LICENSE). Non-commercial use is permitted; converts to
-Apache License 2.0 on 2030-07-20.
+## Source repositories
 
-For commercial licensing, contact TeleCrypt.io.
+- Web application: [`TeleCrypt-io/storage`](https://github.com/TeleCrypt-io/storage)
+- Command-line client: [`cli/`](https://github.com/TeleCrypt-io/storage/tree/main/cli)
 
-## Third-party code
+## License
 
-- [`matrix-js-sdk`](https://github.com/matrix-org/matrix-js-sdk) — Apache-2.0 — dependency
-- [`matrix-encrypt-attachment`](https://github.com/matrix-org/matrix-encrypt-attachment) — Apache-2.0 — dependency
+See [`LICENSE`](./LICENSE) for the complete terms. The current license is Business Source License
+1.1 with an additional grant for non-commercial use; it is not an open-source license. The stated
+Change Date is 2030-07-20, and the Change License is Apache License 2.0. The license also changes
+on the fourth anniversary of the first public distribution of a specific version if that occurs
+before its stated Change Date. The full license controls in case of any discrepancy.

package/dist/TeleCryptIOStorage.d.ts

@@ -26,6 +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" | "getContent" | "getSender" | "isRedacted">;
     /** Matrix SDK keeps a redacted branch in state as an inactive object. */
     readonly isActive?: boolean;
     getName(): string;
@@ -142,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
@@ -247,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_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,25 +1254,29 @@ 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,
                 kick: 100,
                 ban: 100,
-                redact: 50,
-                state_default: 50,
-                events_default: 50,
+                redact: 100,
+                state_default: 0,
+                events_default: 0,
                 users_default: 0,
                 events: {
                     [EventType.RoomPowerLevels]: 100,
                     [EventType.RoomHistoryVisibility]: 100,
                     [EventType.RoomTombstone]: 100,
                     [EventType.RoomEncryption]: 100,
-                    [EventType.RoomName]: 50,
-                    [EventType.RoomMessage]: 50,
-                    [EventType.RoomMessageEncrypted]: 50,
-                    [EventType.Sticker]: 50,
+                    [EventType.RoomName]: 100,
+                    [EventType.RoomMessage]: 0,
+                    [EventType.RoomMessageEncrypted]: 0,
+                    [EventType.Sticker]: 0,
+                    [EventType.SpaceChild]: 100,
+                    [EventType.SpaceParent]: 100,
+                    [UNSTABLE_MSC3089_BRANCH.name]: 100,
+                    [STORAGE_METADATA_EVENT_TYPE]: 100,
                 },
                 users: { [userId]: 100 },
             },
@@ -1116,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
@@ -1200,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);
             }
@@ -1406,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;
@@ -1476,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.
@@ -1506,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.d.ts

@@ -31,7 +31,7 @@ export declare function declineInvite(storage: TeleCryptIOStorage, vaultId: stri
     vaultId: string;
     declined: boolean;
 }>;
-/** Invites `userId` to the vault and applies the requested role. */
+/** Invites `userId` to the vault as a reader. */
 export declare function shareVault(storage: TeleCryptIOStorage, vaultId: string, userId: string, role: string, options?: OperationOptions): Promise<ShareResult>;
 export declare function unshareVault(storage: TeleCryptIOStorage, vaultId: string, userId: string, options?: OperationOptions): Promise<UnshareResult>;
 export declare function listMembers(storage: TeleCryptIOStorage, vaultId: string, options?: OperationOptions): Promise<Member[]>;

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);
@@ -728,10 +719,10 @@ export async function declineInvite(storage, vaultId, options) {
         return { vaultId, declined: true };
     }, "mutation");
 }
-/** Invites `userId` to the vault and applies the requested role. */
+/** Invites `userId` to the vault as a reader. */
 export async function shareVault(storage, vaultId, userId, role, options) {
-    if (role !== "viewer" && role !== "editor") {
-        throw new StorageError("invalid --role (must be viewer or editor)");
+    if (role !== "viewer") {
+        throw new StorageError("storage sharing supports viewers only");
     }
     const operation = createOperationDeadline(options);
     const completedRoomIds = new Set();
@@ -754,6 +745,12 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                 }
                 for (const [index, space] of spaces.entries()) {
                     ensureOperationActive(operation.signal);
+                    const members = index === 0
+                        ? 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");
+                    }
                     const currentMembership = index === 0
                         ? currentMembers.find((member) => member.userId === userId)?.membership
                         : await storage.getRoomMembership(space.id, userId, {
@@ -778,17 +775,10 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                             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(() => space.setPermissions(userId, role), operation.signal), operation.signal);
-                    completedRoomIds.add(space.id);
-                }
+                // Storage rooms have one immutable owner power level and readers use
+                // the room's default user level. Inviting is the complete sharing
+                // operation; changing per-user power levels would create editors and
+                // let metadata authorship drift away from the owner.
             }
             catch (error) {
                 if (error instanceof MutationOutcomeUnknownError)
@@ -805,7 +795,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                 }
                 throw new StorageError("share failed", { cause: error });
             }
-            return { vaultId, userId, role };
+            return { vaultId, userId, role: "viewer" };
         }, operation.signal);
         return await raceOperationDeadline(operation, pending, "mutation");
     }
@@ -909,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)
@@ -926,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) {
@@ -958,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) {
@@ -991,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 {
@@ -1016,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 });
@@ -1055,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) {
@@ -1094,43 +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();
-            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, branch.id), signal, "delete file event"), signal);
-            completedIds.push(branch.id);
+            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");
+            }
+            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) {
@@ -1139,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");
@@ -1198,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 }),
         };
     });
 }
@@ -1216,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;
@@ -1243,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();
@@ -1261,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.1",
+  "version": "0.8.0",
   "license": "BUSL-1.1",
   "type": "module",
   "packageManager": "npm@11.19.0",