@telecrypt-io/storage 0.1.0

package/LICENSE

@@ -0,0 +1,109 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:              TeleCrypt.io
+Licensed Work:         TeleCrypt.io Storage
+                        The Licensed Work is (c) 2026 TeleCrypt.io
+Additional Use Grant:  You may use, copy, modify, and create derivative
+                        works of the Licensed Work for any non-commercial
+                        purpose, including personal, educational, research,
+                        and experimentation use. You may not use the
+                        Licensed Work, or any derivative work thereof, to
+                        provide a commercial product or service to third
+                        parties, or for any purpose intended for or
+                        directed toward commercial advantage or monetary
+                        compensation.
+
+Change Date:            2030-07-20
+
+Change License:         Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact TeleCrypt.io.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an
+Open Source license. However, the Licensed Work will eventually be made
+available under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified
+copy of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant, or (b) insert the text "None" to specify a Change
+   Date of no more than four years from the date the Licensed Work is
+   published.
+
+3. To not modify this License in any other way.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/README.md

@@ -0,0 +1,53 @@
+# TeleCrypt.io Storage
+
+End-to-end encrypted file storage and sharing, built on Matrix.
+
+Files are encrypted on the client before upload. The server stores only opaque ciphertext and
+never holds the decryption keys.
+
+**Status:** early development. Not yet usable.
+
+## How it works
+
+Built on [MSC3089](https://github.com/matrix-org/matrix-spec-proposals/pull/3089), which models
+a file tree using Matrix primitives:
+
+| File-system concept | Matrix concept |
+|---|---|
+| Folder | A Space (room marked as a file tree) |
+| Subfolder | A child Space |
+| File | An event pointing at encrypted uploaded content |
+| Version | A newer event superseding the old |
+| Sharing | Room invitation |
+| Permissions | Power levels |
+
+Encryption uses the same scheme as Matrix attachments (AES-CTR with a per-file key, keys
+distributed via the room's Megolm session). Requires no server-side changes — it runs against
+stock Synapse.
+
+## Development
+
+```bash
+npm install
+npm run synapse:up     # disposable local Synapse for tests
+npm test
+npm run synapse:down
+```
+
+Tests run against a real local Synapse in Docker, never against a production server.
+
+See [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md) for the phased build plan.
+
+## Licence
+
+[Business Source License 1.1](./LICENSE). Non-commercial use is permitted; converts to
+Apache License 2.0 on 2030-07-20.
+
+For commercial licensing, contact TeleCrypt.io.
+
+## Third-party code
+
+- [`matrix-js-sdk`](https://github.com/matrix-org/matrix-js-sdk) — Apache-2.0 — dependency
+- [`matrix-files-sdk`](https://github.com/matrix-org/matrix-files-sdk) — Apache-2.0 — reference
+- [`files-sdk-demo`](https://github.com/vector-im/files-sdk-demo) — AGPL-3.0 — **not used**;
+  incompatible with this project's licence

package/dist/TeleCryptIOStorage.d.ts

@@ -0,0 +1,185 @@
+import { MatrixClient } from "matrix-js-sdk";
+import type { CryptoCallbacks } from "matrix-js-sdk/lib/crypto-api/index.js";
+export interface TreeSpace {
+    readonly id: string;
+    readonly room: {
+        name: string;
+    };
+    readonly isTopLevel: boolean;
+    setName(name: string): Promise<void>;
+    createDirectory(name: string): Promise<TreeSpace>;
+    getDirectories(): TreeSpace[];
+    getDirectory(roomId: string): TreeSpace | undefined;
+    invite(userId: string, andSubspaces?: boolean): Promise<void>;
+    delete(): Promise<void>;
+    getOrder(): number;
+    setOrder(index: number): Promise<void>;
+    getPermissions(userId: string): string;
+    setPermissions(userId: string, role: string): Promise<void>;
+    getFile(fileEventId: string): FileBranch | null;
+    listFiles(): FileBranch[];
+    listAllFiles(): FileBranch[];
+    createFile(name: string, encryptedContents: Buffer | ArrayBuffer | Uint8Array, info: Record<string, unknown>, additionalContent?: Record<string, unknown>): Promise<{
+        event_id: string;
+    }>;
+}
+export interface FileBranch {
+    readonly id: string;
+    readonly version: number;
+    readonly isActive: boolean;
+    getName(): string;
+    setName(name: string): Promise<void>;
+    delete(): Promise<void>;
+    getFileInfo(): Promise<{
+        info: Record<string, unknown>;
+        httpUrl: string;
+    }>;
+    getFileEvent(): Promise<{
+        getContent: () => Record<string, unknown>;
+    }>;
+    getVersionHistory(): Promise<FileBranch[]>;
+    createNewVersion(name: string, encryptedContents: Buffer | ArrayBuffer | Uint8Array, info: Record<string, unknown>, additionalContent?: Record<string, unknown>): Promise<{
+        event_id: string;
+    }>;
+}
+export interface CreateTeleCryptIOStorageOptions {
+    /** Matrix homeserver base URL, e.g. "https://matrix.example.com". */
+    baseUrl: string;
+    userId: string;
+    accessToken: string;
+    deviceId: string;
+    /**
+     * Use a persistent crypto store (IndexedDB) so keys survive a restart on this
+     * device. This is the default (`true`) — it is what makes both same-device
+     * restart recovery and (via `keys.setupRecovery`/`restoreFromRecoveryKey`)
+     * new-device recovery possible. Set explicitly to `false` to opt into an
+     * in-memory, amnesiac store; this must be a deliberate choice, e.g. for a
+     * short-lived process that should never persist secrets to disk.
+     */
+    persistentCryptoStore?: boolean;
+    /**
+     * Overrides the IndexedDB name prefix used for the crypto store. Defaults to
+     * a value scoped to (userId, deviceId) so that multiple devices/users never
+     * collide when they happen to share a single IndexedDB origin (e.g. in
+     * Node/tests, where `fake-indexeddb` is process-global).
+     */
+    cryptoDatabasePrefix?: string;
+    /** initialSyncLimit passed to startClient(); default 10. */
+    initialSyncLimit?: number;
+    /** How long to wait for the first sync before giving up; default 15000ms. */
+    syncTimeoutMs?: number;
+    /**
+     * Optional platform-supplied crypto callbacks (e.g. to source the secret
+     * storage key from an OS keychain instead of prompting). `keys.setupRecovery`
+     * and `keys.restoreFromRecoveryKey` temporarily override
+     * `getSecretStorageKey`/`cacheSecretStorageKey` on this object for the
+     * duration of the call, then restore whatever was here before.
+     */
+    cryptoCallbacks?: CryptoCallbacks;
+}
+export declare class TeleCryptIOStorage {
+    private client;
+    constructor(client: MatrixClient);
+    /** The underlying matrix-js-sdk client (e.g. to stop it, or for advanced/interop use). */
+    getClient(): MatrixClient;
+    /**
+     * Recommended entry point: builds the MatrixClient with a persistent crypto
+     * store and the secret-storage callback wiring `keys.*` needs, starts the
+     * client, waits for the first sync, and returns a ready TeleCryptIOStorage.
+     *
+     * The plain constructor remains available for advanced callers who need to
+     * build/configure the MatrixClient themselves; in that case `keys.*` only
+     * works if the caller wires equivalent cryptoCallbacks onto the client at
+     * construction time (see `cryptoCallbacks` above for why: matrix-js-sdk
+     * captures a single callbacks object at MatrixClient construction, so it
+     * must exist before `initRustCrypto` runs, not be added afterwards).
+     */
+    static create(opts: CreateTeleCryptIOStorageOptions): Promise<TeleCryptIOStorage>;
+    private requireCrypto;
+    /**
+     * Temporarily wires `getSecretStorageKey`/`cacheSecretStorageKey` on the
+     * client's cryptoCallbacks to hand back `privateKey`, runs `fn`, then
+     * restores whatever callbacks were there before — regardless of success or
+     * failure. Requires that the client was constructed with a cryptoCallbacks
+     * object in the first place (see `create()`'s doc comment).
+     */
+    private withSecretStorageKey;
+    /**
+     * Bootstraps cross-signing and secret storage with a brand-new server-side
+     * key backup, and returns the Recovery Key for the caller to show the user.
+     * This is what makes `restoreFromRecoveryKey` on another device possible.
+     */
+    private keysSetupRecovery;
+    /** Is there an active key backup and a ready secret storage right now? */
+    private keysIsRecoverySetup;
+    /**
+     * On a new device: unlocks secret storage with the Recovery Key, loads the
+     * key-backup decryption key out of secret storage, and restores the key
+     * backup so previously-uploaded files become decryptable again.
+     *
+     * Throws a clear error (never silently "succeeds" with zero keys) if the
+     * recovery key is malformed or does not unlock this account's secret
+     * storage / key backup.
+     */
+    private keysRestoreFromRecoveryKey;
+    /** Key-management API: setup, status, and restore for server-side Secure Backup. */
+    get keys(): {
+        setupRecovery: () => Promise<{
+            recoveryKey: string;
+        }>;
+        isRecoverySetup: () => Promise<boolean>;
+        restoreFromRecoveryKey: (recoveryKey: string) => Promise<{
+            imported: number;
+            total: number;
+        }>;
+    };
+    /**
+     * Creates a new top-level shared folder (tree space).
+     *
+     * Works around a genuine race in matrix-js-sdk's own
+     * `unstableCreateFileTree()`: it creates the room via a plain
+     * `createRoom()` HTTP call, then immediately wraps the result by looking
+     * the room up in the *local* client store (`new MSC3089TreeSpace(this,
+     * roomId)` calls `client.getRoom(roomId)` and throws `Error("Unknown
+     * room")` if it's not there yet). The local store is only populated by
+     * the client's background sync processing, which is asynchronous and can
+     * easily not have caught up in the few milliseconds between the HTTP
+     * response and that lookup — especially right after a client has just
+     * started. The room really was created server-side by that point (that's
+     * how we get "Unknown room" at all); this method waits for the client's
+     * own ongoing sync loop to surface it, then wraps it directly via
+     * `unstableGetFileTreeSpace`, instead of surfacing a spurious failure for
+     * a folder that in fact exists.
+     */
+    createTree(name: string): Promise<TreeSpace>;
+    listTrees(): Promise<TreeSpace[]>;
+    getTree(roomId: string): TreeSpace | null;
+    /**
+     * Lists the participants of a shared folder (tree space) and their role,
+     * derived from room membership (join/invite state) + power levels.
+     * Includes invited-but-not-yet-joined members as well as joined ones;
+     * excludes anyone who has left/been kicked/banned.
+     *
+     * Deliberately reads directly from the server's authoritative REST state
+     * endpoints (`GET .../members`, `GET .../state/m.room.power_levels/`)
+     * rather than from the client's locally synced `tree.room`/`currentState`.
+     * On a freshly-started client (as every CLI command is — see
+     * docs/CLI_SPEC.md and src/cli/cryptoSnapshot.ts), room membership and
+     * power-level state can take several more `/sync` round trips to fully
+     * converge locally after a change, even though the room itself is already
+     * visible — reading the same data straight from the server sidesteps that
+     * sync-convergence lag entirely. The role thresholds mirror
+     * `MSC3089TreeSpace.getPermissions()` exactly (userLevel >= adminLevel ->
+     * owner, >= editLevel -> editor, else viewer).
+     */
+    listMembers(tree: TreeSpace): Promise<{
+        userId: string;
+        role: string;
+        membership: string;
+    }[]>;
+    uploadFile(tree: TreeSpace, name: string, data: ArrayBuffer, mimetype: string): Promise<string>;
+    downloadFile(branch: FileBranch): Promise<{
+        data: ArrayBuffer;
+        mimetype: string;
+    }>;
+}

package/dist/TeleCryptIOStorage.js

@@ -0,0 +1,323 @@
+import { ClientEvent, createClient, SyncState } from "matrix-js-sdk";
+import { encryptAttachment, decryptAttachment } from "matrix-encrypt-attachment";
+import { decodeRecoveryKey } from "matrix-js-sdk/lib/crypto-api/recovery-key.js";
+export class TeleCryptIOStorage {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** The underlying matrix-js-sdk client (e.g. to stop it, or for advanced/interop use). */
+    getClient() {
+        return this.client;
+    }
+    /**
+     * Recommended entry point: builds the MatrixClient with a persistent crypto
+     * store and the secret-storage callback wiring `keys.*` needs, starts the
+     * client, waits for the first sync, and returns a ready TeleCryptIOStorage.
+     *
+     * The plain constructor remains available for advanced callers who need to
+     * build/configure the MatrixClient themselves; in that case `keys.*` only
+     * works if the caller wires equivalent cryptoCallbacks onto the client at
+     * construction time (see `cryptoCallbacks` above for why: matrix-js-sdk
+     * captures a single callbacks object at MatrixClient construction, so it
+     * must exist before `initRustCrypto` runs, not be added afterwards).
+     */
+    static async create(opts) {
+        const client = createClient({
+            baseUrl: opts.baseUrl,
+            userId: opts.userId,
+            accessToken: opts.accessToken,
+            deviceId: opts.deviceId,
+            cryptoCallbacks: opts.cryptoCallbacks ?? {},
+        });
+        const persistent = opts.persistentCryptoStore ?? true;
+        await client.initRustCrypto({
+            useIndexedDB: persistent,
+            cryptoDatabasePrefix: opts.cryptoDatabasePrefix ?? `telecrypt-io-storage::${opts.userId}::${opts.deviceId}`,
+        });
+        await client.startClient({ initialSyncLimit: opts.initialSyncLimit ?? 10 });
+        await new Promise((resolve, reject) => {
+            const timeoutMs = opts.syncTimeoutMs ?? 15000;
+            const timeout = setTimeout(() => reject(new Error("sync timeout")), timeoutMs);
+            client.once(ClientEvent.Sync, (state) => {
+                clearTimeout(timeout);
+                if (state === SyncState.Prepared || state === SyncState.Syncing) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`unexpected sync state: ${state}`));
+                }
+            });
+        });
+        return new TeleCryptIOStorage(client);
+    }
+    requireCrypto() {
+        const crypto = this.client.getCrypto();
+        if (!crypto) {
+            throw new Error("TeleCryptIOStorage: this client's crypto was never initialised (call client.initRustCrypto() first, or use TeleCryptIOStorage.create())");
+        }
+        return crypto;
+    }
+    /**
+     * Temporarily wires `getSecretStorageKey`/`cacheSecretStorageKey` on the
+     * client's cryptoCallbacks to hand back `privateKey`, runs `fn`, then
+     * restores whatever callbacks were there before — regardless of success or
+     * failure. Requires that the client was constructed with a cryptoCallbacks
+     * object in the first place (see `create()`'s doc comment).
+     */
+    async withSecretStorageKey(privateKey, fn) {
+        const callbacks = this.client.cryptoCallbacks;
+        const prevGetKey = callbacks.getSecretStorageKey;
+        const prevCache = callbacks.cacheSecretStorageKey;
+        callbacks.getSecretStorageKey = async ({ keys }) => {
+            const keyId = Object.keys(keys)[0];
+            return [keyId, privateKey];
+        };
+        callbacks.cacheSecretStorageKey = () => { };
+        try {
+            return await fn();
+        }
+        finally {
+            callbacks.getSecretStorageKey = prevGetKey;
+            callbacks.cacheSecretStorageKey = prevCache;
+        }
+    }
+    /**
+     * Bootstraps cross-signing and secret storage with a brand-new server-side
+     * key backup, and returns the Recovery Key for the caller to show the user.
+     * This is what makes `restoreFromRecoveryKey` on another device possible.
+     */
+    async keysSetupRecovery() {
+        const crypto = this.requireCrypto();
+        await crypto.bootstrapCrossSigning({
+            // No existing verified device to interactively re-authenticate against
+            // for this account, so there is nothing to feed into `makeRequest`;
+            // matches the working pattern already proven in keys.test.ts.
+            authUploadDeviceSigningKeys: async () => undefined,
+        });
+        const generated = await crypto.createRecoveryKeyFromPassphrase();
+        if (!generated.encodedPrivateKey) {
+            throw new Error("setupRecovery: matrix-js-sdk did not return an encoded recovery key");
+        }
+        await this.withSecretStorageKey(generated.privateKey, async () => {
+            await crypto.bootstrapSecretStorage({
+                setupNewSecretStorage: true,
+                setupNewKeyBackup: true,
+                createSecretStorageKey: async () => generated,
+            });
+            await crypto.checkKeyBackupAndEnable();
+        });
+        return { recoveryKey: generated.encodedPrivateKey };
+    }
+    /** Is there an active key backup and a ready secret storage right now? */
+    async keysIsRecoverySetup() {
+        const crypto = this.client.getCrypto();
+        if (!crypto)
+            return false;
+        const [storageStatus, backupVersion] = await Promise.all([
+            crypto.getSecretStorageStatus(),
+            crypto.getActiveSessionBackupVersion(),
+        ]);
+        return storageStatus.ready && backupVersion !== null;
+    }
+    /**
+     * On a new device: unlocks secret storage with the Recovery Key, loads the
+     * key-backup decryption key out of secret storage, and restores the key
+     * backup so previously-uploaded files become decryptable again.
+     *
+     * Throws a clear error (never silently "succeeds" with zero keys) if the
+     * recovery key is malformed or does not unlock this account's secret
+     * storage / key backup.
+     */
+    async keysRestoreFromRecoveryKey(recoveryKey) {
+        const crypto = this.requireCrypto();
+        let privateKey;
+        try {
+            privateKey = decodeRecoveryKey(recoveryKey);
+        }
+        catch (err) {
+            throw new Error(`restoreFromRecoveryKey: not a valid recovery key (${err.message})`);
+        }
+        return this.withSecretStorageKey(privateKey, async () => {
+            try {
+                await crypto.loadSessionBackupPrivateKeyFromSecretStorage();
+            }
+            catch (err) {
+                throw new Error(`restoreFromRecoveryKey: recovery key did not unlock secret storage / key backup (${err.message})`);
+            }
+            try {
+                const result = await crypto.restoreKeyBackup();
+                return { imported: result.imported, total: result.total };
+            }
+            catch (err) {
+                throw new Error(`restoreFromRecoveryKey: failed to restore key backup (${err.message})`);
+            }
+        });
+    }
+    /** Key-management API: setup, status, and restore for server-side Secure Backup. */
+    get keys() {
+        return {
+            setupRecovery: () => this.keysSetupRecovery(),
+            isRecoverySetup: () => this.keysIsRecoverySetup(),
+            restoreFromRecoveryKey: (recoveryKey) => this.keysRestoreFromRecoveryKey(recoveryKey),
+        };
+    }
+    /**
+     * Creates a new top-level shared folder (tree space).
+     *
+     * Works around a genuine race in matrix-js-sdk's own
+     * `unstableCreateFileTree()`: it creates the room via a plain
+     * `createRoom()` HTTP call, then immediately wraps the result by looking
+     * the room up in the *local* client store (`new MSC3089TreeSpace(this,
+     * roomId)` calls `client.getRoom(roomId)` and throws `Error("Unknown
+     * room")` if it's not there yet). The local store is only populated by
+     * the client's background sync processing, which is asynchronous and can
+     * easily not have caught up in the few milliseconds between the HTTP
+     * response and that lookup — especially right after a client has just
+     * started. The room really was created server-side by that point (that's
+     * how we get "Unknown room" at all); this method waits for the client's
+     * own ongoing sync loop to surface it, then wraps it directly via
+     * `unstableGetFileTreeSpace`, instead of surfacing a spurious failure for
+     * a folder that in fact exists.
+     */
+    async createTree(name) {
+        const knownRoomIdsBefore = new Set(this.client.getRooms().map((r) => r.roomId));
+        try {
+            // The `await` here is load-bearing: without it, the promise's
+            // eventual rejection would happen after this try/catch has already
+            // returned, bypassing the recovery logic below entirely.
+            return (await this.client.unstableCreateFileTree(name));
+        }
+        catch (err) {
+            if (!(err instanceof Error) || err.message !== "Unknown room")
+                throw err;
+            const newRoomId = await new Promise((resolve, reject) => {
+                const deadline = Date.now() + 15000;
+                const poll = () => {
+                    const found = this.client.getRooms().find((r) => !knownRoomIdsBefore.has(r.roomId));
+                    if (found) {
+                        resolve(found.roomId);
+                        return;
+                    }
+                    if (Date.now() >= deadline) {
+                        reject(new Error("createTree: room was created server-side but never appeared in this client's local sync state"));
+                        return;
+                    }
+                    setTimeout(poll, 200);
+                };
+                poll();
+            });
+            const tree = this.client.unstableGetFileTreeSpace(newRoomId);
+            if (!tree) {
+                throw new Error(`createTree: room ${newRoomId} appeared but is not a valid file tree space`);
+            }
+            return tree;
+        }
+    }
+    async listTrees() {
+        const rooms = this.client.getRooms();
+        const trees = [];
+        for (const room of rooms) {
+            const tree = this.client.unstableGetFileTreeSpace(room.roomId);
+            if (tree) {
+                trees.push(tree);
+            }
+        }
+        return trees;
+    }
+    getTree(roomId) {
+        return this.client.unstableGetFileTreeSpace(roomId);
+    }
+    /**
+     * Lists the participants of a shared folder (tree space) and their role,
+     * derived from room membership (join/invite state) + power levels.
+     * Includes invited-but-not-yet-joined members as well as joined ones;
+     * excludes anyone who has left/been kicked/banned.
+     *
+     * Deliberately reads directly from the server's authoritative REST state
+     * endpoints (`GET .../members`, `GET .../state/m.room.power_levels/`)
+     * rather than from the client's locally synced `tree.room`/`currentState`.
+     * On a freshly-started client (as every CLI command is — see
+     * docs/CLI_SPEC.md and src/cli/cryptoSnapshot.ts), room membership and
+     * power-level state can take several more `/sync` round trips to fully
+     * converge locally after a change, even though the room itself is already
+     * visible — reading the same data straight from the server sidesteps that
+     * sync-convergence lag entirely. The role thresholds mirror
+     * `MSC3089TreeSpace.getPermissions()` exactly (userLevel >= adminLevel ->
+     * owner, >= editLevel -> editor, else viewer).
+     */
+    async listMembers(tree) {
+        const clientAny = this.client;
+        const baseUrl = clientAny.getHomeserverUrl();
+        const token = clientAny.getAccessToken();
+        const authHeaders = { Authorization: `Bearer ${token}` };
+        const roomPath = `${baseUrl}/_matrix/client/v3/rooms/${encodeURIComponent(tree.id)}`;
+        const [membersRes, powerLevelsRes] = await Promise.all([
+            fetch(`${roomPath}/members`, { headers: authHeaders }),
+            fetch(`${roomPath}/state/m.room.power_levels/`, { headers: authHeaders }),
+        ]);
+        if (!membersRes.ok) {
+            throw new Error(`listMembers: failed to fetch room members (${membersRes.status})`);
+        }
+        const membersBody = (await membersRes.json());
+        const pls = powerLevelsRes.ok
+            ? (await powerLevelsRes.json())
+            : {};
+        const viewLevel = pls.users_default ?? 0;
+        const editLevel = pls.events_default ?? 50;
+        const adminLevel = pls.events?.["m.room.power_levels"] ?? 100;
+        const roleFor = (userId) => {
+            const userLevel = pls.users?.[userId] ?? viewLevel;
+            if (userLevel >= adminLevel)
+                return "owner";
+            if (userLevel >= editLevel)
+                return "editor";
+            return "viewer";
+        };
+        return membersBody.chunk
+            .filter((e) => e.content.membership === "join" || e.content.membership === "invite")
+            .map((e) => ({
+            userId: e.state_key,
+            membership: e.content.membership,
+            role: roleFor(e.state_key),
+        }));
+    }
+    async uploadFile(tree, name, data, mimetype) {
+        const encrypted = await encryptAttachment(data);
+        const { event_id } = await tree.createFile(name, Buffer.from(encrypted.data), encrypted.info, { info: { mimetype, size: data.byteLength } });
+        return event_id;
+    }
+    async downloadFile(branch) {
+        const { info } = await branch.getFileInfo();
+        // If the underlying room event couldn't be decrypted (e.g. this device
+        // never received/recovered the megolm session for it), matrix-js-sdk
+        // hands back a placeholder with no usable `info` rather than throwing —
+        // so without this check, callers would hit an opaque
+        // "Cannot read properties of undefined" a few lines down instead of a
+        // clear, actionable error.
+        if (!info || typeof info.url !== "string") {
+            throw new Error("downloadFile: could not read file info from the event — it is likely undecryptable on this device (missing megolm session; try restoring from a Recovery Key)");
+        }
+        const mxcUrl = info.url;
+        const clientAny = this.client;
+        const downloadUrl = clientAny.mxcUrlToHttp(mxcUrl, undefined, undefined, undefined, false, true, true);
+        if (!downloadUrl)
+            throw new Error("failed to build media URL");
+        const res = await fetch(downloadUrl, {
+            headers: {
+                Authorization: `Bearer ${clientAny.getAccessToken()}`,
+            },
+        });
+        if (!res.ok) {
+            throw new Error(`media download failed: ${res.status}`);
+        }
+        const ciphertext = await res.arrayBuffer();
+        const data = await decryptAttachment(ciphertext, info);
+        const eventContent = (await branch.getFileEvent()).getContent();
+        const infoBlock = eventContent["info"];
+        const mimetype = typeof infoBlock?.["mimetype"] === "string"
+            ? infoBlock["mimetype"]
+            : "application/octet-stream";
+        return { data, mimetype };
+    }
+}