@telecrypt-io/storage 0.1.0 → 0.1.2

package/README.md

@@ -1,11 +1,49 @@
 # TeleCrypt.io Storage
 
+[![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.
 
 Files are encrypted on the client before upload. The server stores only opaque ciphertext and
-never holds the decryption keys.
+never holds the decryption keys. Shared folders let multiple people add and read files, and a
+Recovery Key restores your files on a new device — even if you lose the original.
+
+**Status:** published and usable — library, CLI, and a React web UI.
+
+## Install
+
+```bash
+npm install @telecrypt-io/storage
+```
+
+This gives you both the `TeleCryptIOStorage` library and the `telecrypt-io` CLI.
+
+## Quick start
+
+**Library:**
+
+```ts
+import { TeleCryptIOStorage } from "@telecrypt-io/storage";
+import * as core from "@telecrypt-io/storage/core";
+
+const storage = await TeleCryptIOStorage.create({
+  baseUrl, userId, accessToken, deviceId,
+});
+const folder = await core.createFolder(storage, "Photos");
+await core.uploadFile(storage, folder.id, "cat.jpg", bytes, "image/jpeg");
+```
+
+**CLI:**
+
+```bash
+telecrypt-io storage login --homeserver https://your.server --user alice --password ...
+telecrypt-io storage folder create Photos
+telecrypt-io storage file upload <folderId> ./cat.jpg
+telecrypt-io storage folder share <folderId> @bob:your.server --role editor
+telecrypt-io storage recovery setup     # prints your Recovery Key — save it
+```
 
-**Status:** early development. Not yet usable.
+**Web UI:** a React app lives in [`ui/`](./ui) (`cd ui && npm install && npm run dev`).
 
 ## How it works
 
@@ -34,9 +72,10 @@ npm test
 npm run synapse:down
 ```
 
-Tests run against a real local Synapse in Docker, never against a production server.
+Tests run against a real local Synapse in podman, never against a production server.
 
-See [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md) for the phased build plan.
+See [CLI.md](./CLI.md) for command reference and [RELEASING.md](./RELEASING.md) for release
+instructions.
 
 ## Licence
 

package/dist/TeleCryptIOStorage.d.ts

@@ -1,5 +1,6 @@
 import { MatrixClient } from "matrix-js-sdk";
 import type { CryptoCallbacks } from "matrix-js-sdk/lib/crypto-api/index.js";
+import type { TokenRefreshFunction } from "matrix-js-sdk/lib/http-api/index.js";
 export interface TreeSpace {
     readonly id: string;
     readonly room: {
@@ -68,6 +69,10 @@ export interface CreateTeleCryptIOStorageOptions {
     initialSyncLimit?: number;
     /** How long to wait for the first sync before giving up; default 15000ms. */
     syncTimeoutMs?: number;
+    /** How long to wait for rust-crypto WASM + IndexedDB init; default 60000ms. */
+    initTimeoutMs?: number;
+    /** Optional progress reporter for UI/CLI status lines during bootstrap. */
+    onProgress?: (message: string) => void;
     /**
      * Optional platform-supplied crypto callbacks (e.g. to source the secret
      * storage key from an OS keychain instead of prompting). `keys.setupRecovery`
@@ -77,6 +82,36 @@ export interface CreateTeleCryptIOStorageOptions {
      */
     cryptoCallbacks?: CryptoCallbacks;
 }
+/**
+ * Options for `TeleCryptIOStorage.createFromOidc` — mirrors
+ * `CreateTeleCryptIOStorageOptions` but sourced from an OIDC/MAS login
+ * (device-code or authorization-code+PKCE, see `src/core/oidc.ts`) instead
+ * of a password login. Same resulting shape either way: a ready
+ * `TeleCryptIOStorage` with a persistent crypto store.
+ */
+export interface CreateFromOidcOptions {
+    baseUrl: string;
+    userId: string;
+    accessToken: string;
+    deviceId: string;
+    /** If provided (together with `tokenRefreshFunction`), wires the
+     * underlying MatrixClient so an expired access token is transparently
+     * refreshed mid-request. */
+    refreshToken?: string;
+    /** See `src/core/oidc.ts`'s `buildTokenRefreshFunction` — a plain
+     * `(refreshToken) => Promise<AccessTokens>`, deliberately NOT
+     * matrix-js-sdk's `OidcTokenRefresher` (see that file's doc comment for
+     * why: it requires `window.sessionStorage`, which doesn't exist under
+     * Node). */
+    tokenRefreshFunction?: TokenRefreshFunction;
+    persistentCryptoStore?: boolean;
+    cryptoDatabasePrefix?: string;
+    initialSyncLimit?: number;
+    syncTimeoutMs?: number;
+    initTimeoutMs?: number;
+    onProgress?: (message: string) => void;
+    cryptoCallbacks?: CryptoCallbacks;
+}
 export declare class TeleCryptIOStorage {
     private client;
     constructor(client: MatrixClient);
@@ -95,6 +130,24 @@ export declare class TeleCryptIOStorage {
      * must exist before `initRustCrypto` runs, not be added afterwards).
      */
     static create(opts: CreateTeleCryptIOStorageOptions): Promise<TeleCryptIOStorage>;
+    /**
+     * As `create()`, but the resulting `MatrixClient` was authenticated via
+     * OIDC/MAS (device-code or authorization-code+PKCE — see
+     * `src/core/oidc.ts`) rather than `m.login.password`. If `refreshToken` +
+     * `tokenRefresher` are both given, the client's `tokenRefreshFunction` is
+     * wired so an expired access token is transparently refreshed mid-request
+     * — same mechanism matrix-js-sdk uses for any refresh-token-capable login.
+     */
+    static createFromOidc(opts: CreateFromOidcOptions): Promise<TeleCryptIOStorage>;
+    /** Shared post-construction bootstrap for `create()`/`createFromOidc()`:
+     * persistent crypto store, first sync, wrap in a `TeleCryptIOStorage`. */
+    private static bootstrap;
+    private static withTimeout;
+    /** Wait until the client reaches Prepared/Syncing. Ignores transient
+     * pre-sync states instead of rejecting on the first Sync event (which can
+     * race `startClient`), and handles the case where sync already completed
+     * before the listener was attached. */
+    private static waitForFirstSync;
     private requireCrypto;
     /**
      * Temporarily wires `getSecretStorageKey`/`cacheSecretStorageKey` on the
@@ -163,8 +216,7 @@ export declare class TeleCryptIOStorage {
      * 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
+     * On a freshly-started client (as every CLI command is), 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

package/dist/TeleCryptIOStorage.js

@@ -1,4 +1,6 @@
 import { ClientEvent, createClient, SyncState } 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";
 import { decodeRecoveryKey } from "matrix-js-sdk/lib/crypto-api/recovery-key.js";
 export class TeleCryptIOStorage {
@@ -30,26 +32,80 @@ export class TeleCryptIOStorage {
             deviceId: opts.deviceId,
             cryptoCallbacks: opts.cryptoCallbacks ?? {},
         });
+        return TeleCryptIOStorage.bootstrap(client, opts);
+    }
+    /**
+     * As `create()`, but the resulting `MatrixClient` was authenticated via
+     * OIDC/MAS (device-code or authorization-code+PKCE — see
+     * `src/core/oidc.ts`) rather than `m.login.password`. If `refreshToken` +
+     * `tokenRefresher` are both given, the client's `tokenRefreshFunction` is
+     * wired so an expired access token is transparently refreshed mid-request
+     * — same mechanism matrix-js-sdk uses for any refresh-token-capable login.
+     */
+    static async createFromOidc(opts) {
+        const client = createClient({
+            baseUrl: opts.baseUrl,
+            userId: opts.userId,
+            accessToken: opts.accessToken,
+            deviceId: opts.deviceId,
+            refreshToken: opts.refreshToken,
+            tokenRefreshFunction: opts.refreshToken && opts.tokenRefreshFunction ? opts.tokenRefreshFunction : undefined,
+            cryptoCallbacks: opts.cryptoCallbacks ?? {},
+        });
+        return TeleCryptIOStorage.bootstrap(client, opts);
+    }
+    /** Shared post-construction bootstrap for `create()`/`createFromOidc()`:
+     * persistent crypto store, first sync, wrap in a `TeleCryptIOStorage`. */
+    static async bootstrap(client, opts) {
+        const progress = opts.onProgress ?? (() => { });
         const persistent = opts.persistentCryptoStore ?? true;
-        await client.initRustCrypto({
+        progress("Loading encryption engine (WASM)…");
+        await TeleCryptIOStorage.withTimeout(client.initRustCrypto({
             useIndexedDB: persistent,
             cryptoDatabasePrefix: opts.cryptoDatabasePrefix ?? `telecrypt-io-storage::${opts.userId}::${opts.deviceId}`,
-        });
+        }), opts.initTimeoutMs ?? 60000, "crypto init");
+        progress("Encryption ready — opening secure store…");
+        progress("Starting Matrix client…");
         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) {
+        progress("Waiting for first sync with homeserver…");
+        await TeleCryptIOStorage.waitForFirstSync(client, opts.syncTimeoutMs ?? 15000);
+        progress("Sync complete.");
+        return new TeleCryptIOStorage(client);
+    }
+    static withTimeout(promise, ms, label) {
+        return Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                setTimeout(() => reject(new Error(`${label} timeout after ${ms}ms`)), ms);
+            }),
+        ]);
+    }
+    /** Wait until the client reaches Prepared/Syncing. Ignores transient
+     * pre-sync states instead of rejecting on the first Sync event (which can
+     * race `startClient`), and handles the case where sync already completed
+     * before the listener was attached. */
+    static waitForFirstSync(client, timeoutMs) {
+        const ready = (state) => state === SyncState.Prepared || state === SyncState.Syncing;
+        if (ready(client.getSyncState())) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const onSync = (state) => {
+                if (ready(state)) {
+                    cleanup();
                     resolve();
                 }
-                else {
-                    reject(new Error(`unexpected sync state: ${state}`));
-                }
-            });
+            };
+            const cleanup = () => {
+                clearTimeout(timeout);
+                client.removeListener(ClientEvent.Sync, onSync);
+            };
+            const timeout = setTimeout(() => {
+                cleanup();
+                reject(new Error("sync timeout"));
+            }, timeoutMs);
+            client.on(ClientEvent.Sync, onSync);
         });
-        return new TeleCryptIOStorage(client);
     }
     requireCrypto() {
         const crypto = this.client.getCrypto();
@@ -237,8 +293,7 @@ export class TeleCryptIOStorage {
      * 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
+     * On a freshly-started client (as every CLI command is), 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
@@ -247,22 +302,17 @@ export class TeleCryptIOStorage {
      * 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 }),
+        const roomId = encodeURIComponent(tree.id);
+        const membersPath = `/rooms/${roomId}/members`;
+        const powerLevelsPath = `/rooms/${roomId}/state/m.room.power_levels/`;
+        const reqOpts = { prefix: ClientPrefix.V3 };
+        const [membersBody, plsRaw] = await Promise.all([
+            this.client.http.authedRequest(Method.Get, membersPath, undefined, undefined, reqOpts),
+            this.client.http
+                .authedRequest(Method.Get, powerLevelsPath, undefined, undefined, reqOpts)
+                .catch(() => ({})),
         ]);
-        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 pls = plsRaw;
         const viewLevel = pls.users_default ?? 0;
         const editLevel = pls.events_default ?? 50;
         const adminLevel = pls.events?.["m.room.power_levels"] ?? 100;

package/dist/cli/cryptoSnapshot.js

@@ -1,5 +1,5 @@
 /**
- * Cross-process crypto persistence (THE central challenge — see docs/CLI_SPEC.md).
+ * Cross-process crypto persistence for the process-per-command CLI.
  *
  * A CLI runs each command as a separate OS process. `TeleCryptIOStorage.create()`
  * initialises rust-crypto with `useIndexedDB: true`, but in Node the only

package/dist/cli/index.js

@@ -9,6 +9,7 @@ import { initStorageForNewSession, openStorage, waitForBackupSettled } from "./s
 import { CliError } from "./errors.js";
 import { runAction } from "./output.js";
 import * as core from "../core/operations.js";
+import { runDeviceCodeLogin } from "./oidc.js";
 // matrix-js-sdk (loglevel) and the rust-crypto WASM tracing layer write
 // verbose logs straight to console.log/debug/info/trace (stdout by default)
 // AND console.warn/error (stderr by default) — e.g. push-rule setup notices
@@ -67,24 +68,51 @@ storage
     .command("login")
     .description("Log in and persist the session + crypto store to the profile")
     .requiredOption("--homeserver <url>", "Matrix homeserver base URL")
-    .requiredOption("--user <localpart>", "Username (localpart or full MXID)")
-    .requiredOption("--password <pw>", "Password")
+    .option("--user <localpart>", "Username (localpart or full MXID) — password login")
+    .option("--password <pw>", "Password — password login")
+    .option("--oidc", "Log in via OIDC/MAS device-code grant instead of password")
     .action(async (opts, command) => {
     await runAction(command, async () => {
-        const client = createClient({ baseUrl: opts.homeserver });
-        let res;
-        try {
-            res = await client.loginWithPassword(opts.user, opts.password);
+        let session;
+        if (opts.oidc) {
+            session = await runDeviceCodeLogin(opts.homeserver, {
+                onVerification: ({ verificationUri, verificationUriComplete, userCode }) => {
+                    // Progress output — stderr only, so it never corrupts the
+                    // stdout contract (--json's single JSON line / text mode's
+                    // single line), same convention as TELECRYPT_IO_STORAGE_DEBUG
+                    // SDK logging below.
+                    process.stderr.write([
+                        "",
+                        `To finish logging in, visit: ${verificationUriComplete ?? verificationUri}`,
+                        verificationUriComplete ? "" : `and enter code: ${userCode}`,
+                        "Attempting to open your browser…",
+                        "Waiting for approval…",
+                        "",
+                    ]
+                        .filter((l) => l !== "")
+                        .join("\n") + "\n");
+                },
+            });
         }
-        catch (err) {
-            throw new CliError(`login failed: ${err.message}`);
+        else {
+            if (!opts.user || !opts.password) {
+                throw new CliError("--user and --password are required for password login (or pass --oidc)");
+            }
+            const client = createClient({ baseUrl: opts.homeserver });
+            let res;
+            try {
+                res = await client.loginWithPassword(opts.user, opts.password);
+            }
+            catch (err) {
+                throw new CliError(`login failed: ${err.message}`);
+            }
+            session = {
+                homeserver: opts.homeserver,
+                userId: res.user_id,
+                deviceId: res.device_id,
+                accessToken: res.access_token,
+            };
         }
-        const session = {
-            homeserver: opts.homeserver,
-            userId: res.user_id,
-            deviceId: res.device_id,
-            accessToken: res.access_token,
-        };
         writeSession(session);
         // Establishes this device's crypto identity and does a first sync
         // (proves connectivity end-to-end), and writes the initial crypto

package/dist/cli/oidc.d.ts

@@ -0,0 +1,19 @@
+import type { Session } from "./profile.js";
+export interface DeviceCodeLoginHooks {
+    /** Called once the device+user code is known, before polling begins —
+     * the caller (CLI command) prints it and attempts to open the browser. */
+    onVerification: (info: {
+        verificationUri: string;
+        verificationUriComplete?: string;
+        userCode: string;
+    }) => void;
+}
+/**
+ * Runs the full device-code login flow against `homeserver`: discovery, DCR,
+ * start device authorization, print verification info + try to open the
+ * browser, poll until approved, confirm identity via `/whoami`. Returns a
+ * `Session` ready to `writeSession()` — includes the OIDC token set fields
+ * (`refreshToken`, `oidcIssuer`, `oidcClientId`, `oidcIdToken`) so later CLI
+ * invocations can reuse + refresh it.
+ */
+export declare function runDeviceCodeLogin(homeserver: string, hooks: DeviceCodeLoginHooks): Promise<Session>;

package/dist/cli/oidc.js

@@ -0,0 +1,97 @@
+/**
+ * CLI-only OIDC/MAS adapter: device-code login (RFC 8628) against a
+ * homeserver's delegated auth service (MAS). Node-only (child_process for
+ * best-effort browser open). Platform-specific behavior stays out of `src/core/`; the actual
+ * OIDC protocol calls all live in `src/core/oidc.ts` and are shared with the
+ * UI's PKCE adapter.
+ */
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { discoverOidcIssuer, registerClient, startDeviceCodeLogin, waitForDeviceCodeLogin, isDeviceAccessTokenError, whoAmI, } from "../core/oidc.js";
+import { CliError } from "./errors.js";
+import { withOidcWindowShim } from "./oidcWindowPolyfill.js";
+/** Generates a device ID the same shape matrix-js-sdk itself would (short
+ * uppercase alphanumeric) — this CLI process chooses it upfront (unlike the
+ * UI's authorization-code flow, where the SDK picks a random one) so it's
+ * available immediately for logging/display and is guaranteed to match the
+ * resulting Matrix device_id (embedded in the requested scope, see
+ * `core/oidc.ts`'s `startDeviceCodeLogin`). */
+function generateDeviceId() {
+    return randomBytes(5).toString("hex").toUpperCase();
+}
+/** Best-effort: try to open the verification URL in the user's default
+ * browser. Never throws — if it fails (headless box, no display, unknown
+ * platform), the caller already printed the URL for the user to open by
+ * hand. */
+function tryOpenBrowser(url) {
+    const platform = process.platform;
+    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "start" : "xdg-open";
+    try {
+        const child = spawn(cmd, platform === "win32" ? ["", url] : [url], {
+            detached: true,
+            stdio: "ignore",
+            shell: platform === "win32",
+        });
+        child.unref();
+    }
+    catch {
+        // best-effort only
+    }
+}
+/**
+ * Runs the full device-code login flow against `homeserver`: discovery, DCR,
+ * start device authorization, print verification info + try to open the
+ * browser, poll until approved, confirm identity via `/whoami`. Returns a
+ * `Session` ready to `writeSession()` — includes the OIDC token set fields
+ * (`refreshToken`, `oidcIssuer`, `oidcClientId`, `oidcIdToken`) so later CLI
+ * invocations can reuse + refresh it.
+ */
+export async function runDeviceCodeLogin(homeserver, hooks) {
+    // See src/cli/oidcWindowPolyfill.ts: discovery is the one OIDC call that
+    // needs a `window` stub under Node, and the only place in the CLI it's
+    // safe to install one — nothing crypto/WASM-related exists yet in this
+    // process.
+    const authMetadata = await withOidcWindowShim(() => discoverOidcIssuer(homeserver));
+    if (!authMetadata.device_authorization_endpoint) {
+        throw new CliError(`${homeserver} does not advertise OIDC device-code support (no device_authorization_endpoint) — try password login instead.`);
+    }
+    const clientId = await registerClient(authMetadata, {
+        clientName: "TeleCrypt.io CLI",
+        clientUri: "https://telecrypt.io/",
+        applicationType: "native",
+        // Device-code flow never redirects a browser back to us, so this URI is
+        // never actually dereferenced — it's a DCR-schema placeholder only.
+        // Unverified against production MAS's DCR policy (only exercised here
+        // against the local dev/test MAS, which allows insecure/mismatched URIs).
+        redirectUris: ["http://localhost:0/"],
+        contacts: undefined,
+        tosUri: undefined,
+        policyUri: undefined,
+    });
+    const deviceId = generateDeviceId();
+    const session = await startDeviceCodeLogin(authMetadata, clientId, deviceId);
+    hooks.onVerification({
+        verificationUri: session.verification_uri,
+        verificationUriComplete: session.verification_uri_complete,
+        userCode: session.user_code,
+    });
+    tryOpenBrowser(session.verification_uri_complete ?? session.verification_uri);
+    const result = await waitForDeviceCodeLogin(authMetadata, clientId, session);
+    if (isDeviceAccessTokenError(result)) {
+        throw new CliError(`device login was not approved: ${result.error_description ?? result.error}`);
+    }
+    const who = await whoAmI(homeserver, result.access_token);
+    if (who.deviceId && who.deviceId !== deviceId) {
+        throw new CliError(`device_id mismatch after OIDC login: requested ${deviceId}, server confirmed ${who.deviceId}`);
+    }
+    return {
+        homeserver,
+        userId: who.userId,
+        deviceId,
+        accessToken: result.access_token,
+        refreshToken: result.refresh_token,
+        oidcIssuer: authMetadata.issuer,
+        oidcClientId: clientId,
+        oidcTokenEndpoint: authMetadata.token_endpoint,
+    };
+}

package/dist/cli/oidcWindowPolyfill.d.ts

@@ -0,0 +1 @@
+export declare function withOidcWindowShim<T>(fn: () => Promise<T>): Promise<T>;

package/dist/cli/oidcWindowPolyfill.js

@@ -0,0 +1,76 @@
+/**
+ * `src/core/oidc.ts`'s `discoverOidcIssuer()` calls matrix-js-sdk's
+ * `MatrixClient.getAuthMetadata()`, which internally constructs
+ * oidc-client-ts state requiring `window.sessionStorage`/`window.
+ * localStorage` to exist — a real browser has both natively; plain Node does
+ * not, so under Node it throws `ReferenceError: window is not defined`
+ * before ever making the HTTP request. Confirmed by direct testing — this is
+ * a genuine gap in matrix-js-sdk's OIDC helpers for non-browser consumers,
+ * not a misconfiguration on our side. (The same root cause is why we
+ * deliberately do NOT use matrix-js-sdk's `OidcTokenRefresher` for token
+ * refresh — see `core/oidc.ts`'s `refreshOidcToken`/`buildTokenRefreshFunction`,
+ * a plain hand-rolled `fetch` instead, which needs no `window` at all and so
+ * has no such gap, no matter when a refresh happens to fire.)
+ *
+ * `withOidcWindowShim()` installs a minimal in-memory `Storage`-shaped
+ * `window` stub, runs `fn`, then removes it again — DELIBERATELY SCOPED, not
+ * a permanent global assignment:
+ *
+ * A permanent `globalThis.window` breaks something unrelated —
+ * `@matrix-org/matrix-sdk-crypto-wasm`'s own environment detection
+ * (`typeof window !== "undefined"` → assumes a real browser IndexedDB is
+ * available) fails with "Unsupported environment" once `window` exists at
+ * all, even as an empty-ish stub, since CLI crypto persistence depends on Node being detected as Node
+ * (`fake-indexeddb`), not as a browser. Confirmed by direct testing:
+ * `initRustCrypto()` broke the moment `globalThis.window` was defined
+ * unconditionally at module load.
+ *
+ * This is safe to use ONLY around `discoverOidcIssuer()`, and ONLY at OIDC
+ * login time (`src/cli/oidc.ts`'s `runDeviceCodeLogin`) — the one call site
+ * where it runs before any `TeleCryptIOStorage`/`MatrixClient`/rust-crypto
+ * WASM exists in the process, so there is no concurrent WASM environment
+ * check for the temporary stub to corrupt. Never wrap anything that runs
+ * concurrently with, or after, crypto initialisation.
+ */
+class MemoryStorage {
+    map = new Map();
+    get length() {
+        return this.map.size;
+    }
+    clear() {
+        this.map.clear();
+    }
+    getItem(key) {
+        return this.map.has(key) ? this.map.get(key) : null;
+    }
+    key(index) {
+        return [...this.map.keys()][index] ?? null;
+    }
+    removeItem(key) {
+        this.map.delete(key);
+    }
+    setItem(key, value) {
+        this.map.set(key, value);
+    }
+}
+export async function withOidcWindowShim(fn) {
+    const hadWindow = "window" in globalThis;
+    const previous = globalThis.window;
+    if (!hadWindow) {
+        globalThis.window = {
+            sessionStorage: new MemoryStorage(),
+            localStorage: new MemoryStorage(),
+        };
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        if (!hadWindow) {
+            delete globalThis.window;
+        }
+        else {
+            globalThis.window = previous;
+        }
+    }
+}

package/dist/cli/profile.d.ts

@@ -3,6 +3,19 @@ export interface Session {
     userId: string;
     deviceId: string;
     accessToken: string;
+    /**
+     * Present only when logged in via `storage login --oidc` (device-code
+     * grant against MAS; see src/cli/oidc.ts).
+     * Absent for a plain password login. `oidcTokenEndpoint` is persisted
+     * directly (rather than re-discovered from `oidcIssuer` on every command)
+     * so reusing/refreshing the session never needs OIDC discovery again —
+     * discovery is Node-hostile (see src/cli/oidcWindowPolyfill.ts) and this
+     * avoids needing it more than once, at login time.
+     */
+    refreshToken?: string;
+    oidcIssuer?: string;
+    oidcClientId?: string;
+    oidcTokenEndpoint?: string;
 }
 /**
  * Resolves the profile directory: everything this CLI persists (session,

package/dist/cli/storage.js

@@ -1,9 +1,46 @@
 import "fake-indexeddb/auto";
 import { CryptoEvent } from "matrix-js-sdk/lib/crypto-api/index.js";
 import { TeleCryptIOStorage } from "../TeleCryptIOStorage.js";
-import { cryptoSnapshotPath, ensureProfileDir, profileDir, readSession } from "./profile.js";
+import { cryptoSnapshotPath, ensureProfileDir, profileDir, readSession, writeSession } from "./profile.js";
 import { persistCryptoStore, restoreCryptoStore } from "./cryptoSnapshot.js";
 import { CliError } from "./errors.js";
+import { buildTokenRefreshFunction } from "../core/oidc.js";
+/**
+ * Builds a TeleCryptIOStorage for the given session — plain password/access-
+ * token sessions go through `create()`; sessions with an OIDC token set
+ * (persisted by `storage login --oidc`, see src/cli/oidc.ts) go through
+ * `createFromOidc()` with a token refresh function wired to persist
+ * refreshed tokens straight back to this profile's session.json, so a later
+ * CLI invocation picks up the refreshed access token rather than the
+ * (possibly now-expired) one this process started with. Needs no OIDC
+ * discovery / `window` shim here — `oidcTokenEndpoint` was already resolved
+ * and persisted at login time (see src/cli/oidc.ts).
+ */
+async function buildStorageForSession(session, dir) {
+    if (!session.refreshToken || !session.oidcClientId || !session.oidcTokenEndpoint) {
+        return TeleCryptIOStorage.create({
+            baseUrl: session.homeserver,
+            userId: session.userId,
+            accessToken: session.accessToken,
+            deviceId: session.deviceId,
+        });
+    }
+    const tokenRefreshFunction = buildTokenRefreshFunction(session.oidcTokenEndpoint, session.oidcClientId, async (tokens) => {
+        writeSession({
+            ...session,
+            accessToken: tokens.accessToken,
+            refreshToken: tokens.refreshToken ?? session.refreshToken,
+        }, dir);
+    });
+    return TeleCryptIOStorage.createFromOidc({
+        baseUrl: session.homeserver,
+        userId: session.userId,
+        accessToken: session.accessToken,
+        deviceId: session.deviceId,
+        refreshToken: session.refreshToken,
+        tokenRefreshFunction,
+    });
+}
 /**
  * Opens a TeleCryptIOStorage bound to the current profile's session, having first
  * restored the crypto store snapshot (if any) from a previous CLI
@@ -16,12 +53,7 @@ export async function openStorage(dir = profileDir()) {
     }
     const snapshotPath = cryptoSnapshotPath(dir);
     await restoreCryptoStore(snapshotPath);
-    const storage = await TeleCryptIOStorage.create({
-        baseUrl: session.homeserver,
-        userId: session.userId,
-        accessToken: session.accessToken,
-        deviceId: session.deviceId,
-    });
+    const storage = await buildStorageForSession(session, dir);
     let closed = false;
     const close = async () => {
         if (closed)
@@ -77,12 +109,7 @@ export async function waitForBackupSettled(storage, timeoutMs = 20000) {
 export async function initStorageForNewSession(session, dir = profileDir()) {
     ensureProfileDir(dir);
     const snapshotPath = cryptoSnapshotPath(dir);
-    const storage = await TeleCryptIOStorage.create({
-        baseUrl: session.homeserver,
-        userId: session.userId,
-        accessToken: session.accessToken,
-        deviceId: session.deviceId,
-    });
+    const storage = await buildStorageForSession(session, dir);
     let closed = false;
     const close = async () => {
         if (closed)

package/dist/core/index.d.ts

@@ -3,3 +3,4 @@
 export * from "./types.js";
 export * from "./operations.js";
 export * from "./errors.js";
+export * from "./oidc.js";

package/dist/core/index.js

@@ -3,3 +3,4 @@
 export * from "./types.js";
 export * from "./operations.js";
 export * from "./errors.js";
+export * from "./oidc.js";

package/dist/core/oidc.d.ts

@@ -0,0 +1,119 @@
+import { type OidcClientConfig, type OidcRegistrationClientMetadata, type DeviceAuthorizationResponse, type DeviceAccessTokenResponse, type DeviceAccessTokenError, type BearerTokenResponse } from "matrix-js-sdk/lib/oidc/index.js";
+import type { AccessTokens, TokenRefreshFunction } from "matrix-js-sdk/lib/http-api/index.js";
+import type { IdTokenClaims } from "oidc-client-ts";
+export type { OidcClientConfig, DeviceAuthorizationResponse, DeviceAccessTokenResponse, DeviceAccessTokenError, BearerTokenResponse, AccessTokens, TokenRefreshFunction, };
+/**
+ * The full result of a completed OIDC login (device-code or authorization
+ * code) — enough for a caller to build a ready `TeleCryptIOStorage` via
+ * `TeleCryptIOStorage.createFromOidc(...)` AND to persist for reuse/refresh
+ * across restarts (CLI: profile file; UI: localStorage).
+ */
+export interface OidcTokenSet {
+    homeserverUrl: string;
+    issuer: string;
+    clientId: string;
+    userId: string;
+    deviceId: string;
+    accessToken: string;
+    refreshToken?: string;
+    idToken: string;
+    /** epoch ms, if the token response included an expiry. */
+    expiresAt?: number;
+}
+/**
+ * Discovers the OIDC/MAS issuer + endpoints for a homeserver, via
+ * `MatrixClient.getAuthMetadata()` (MSC2965 `/auth_metadata`, falling back to
+ * the legacy `/auth_issuer` + issuer well-known) — the non-deprecated path
+ * recommended over `discoverAndValidateOIDCIssuerWellKnown`.
+ *
+ * NODE CALLERS: this internally constructs oidc-client-ts state that
+ * requires `window.sessionStorage`/`window.localStorage` to exist (a real
+ * browser has both natively). Under plain Node, wrap this ONE call in
+ * `src/cli/oidcWindowPolyfill.ts`'s `withOidcWindowShim()` — see that file's
+ * doc comment for why it must be scoped narrowly (a permanent global
+ * `window` breaks the rust-crypto WASM's own environment detection) and why
+ * it's safe here specifically (called once, before any crypto/WASM exists).
+ */
+export declare function discoverOidcIssuer(homeserverBaseUrl: string): Promise<OidcClientConfig>;
+/**
+ * Dynamic client registration (DCR). `clientUri`/`redirectUris` must share a
+ * host unless the issuer's policy allows a mismatch (our local dev/test MAS
+ * does; a production issuer may not).
+ */
+export declare function registerClient(authMetadata: OidcClientConfig, metadata: OidcRegistrationClientMetadata): Promise<string>;
+/**
+ * Starts a device-code authorization session. `deviceId` is caller-chosen
+ * (unlike the authorization-code flow, where the SDK picks a random one) so
+ * it can be reused as this Matrix device's `device_id` throughout —
+ * `generateScope(deviceId)` embeds it in the requested scope per MSC2967.
+ */
+export declare function startDeviceCodeLogin(authMetadata: OidcClientConfig, clientId: string, deviceId: string): Promise<DeviceAuthorizationResponse>;
+/**
+ * Polls the token endpoint until the device-code session is approved (or
+ * denied/expired) — see matrix-js-sdk's `waitForDeviceAuthorization` for the
+ * RFC 8628 polling semantics (honours `interval`/`expires_in`,
+ * `authorization_pending`/`slow_down`).
+ */
+export declare function waitForDeviceCodeLogin(authMetadata: OidcClientConfig, clientId: string, session: DeviceAuthorizationResponse): Promise<DeviceAccessTokenResponse | DeviceAccessTokenError>;
+export declare function isDeviceAccessTokenError(result: DeviceAccessTokenResponse | DeviceAccessTokenError): result is DeviceAccessTokenError;
+/**
+ * Builds the authorization URL to redirect the browser to. PKCE
+ * verifier/state/nonce are generated and persisted to `window.sessionStorage`
+ * internally by matrix-js-sdk/oidc-client-ts (`mx_oidc_`-prefixed keys) — the
+ * caller does not need to manage them; `completeAuthorizationCodeFlow` reads
+ * them back after the redirect.
+ */
+export declare function beginAuthorizationCodeFlow(opts: {
+    authMetadata: OidcClientConfig;
+    clientId: string;
+    homeserverUrl: string;
+    redirectUri: string;
+}): Promise<string>;
+/** Completes the authorization-code exchange after the `?code&state` redirect. */
+export declare function completeAuthorizationCodeFlow(code: string, state: string): Promise<{
+    tokenResponse: BearerTokenResponse;
+    oidcClientSettings: {
+        clientId: string;
+        issuer: string;
+    };
+    homeserverUrl: string;
+    idTokenClaims: IdTokenClaims;
+}>;
+/** The device_id granted is embedded in the token response's `scope`
+ * (`urn:matrix:org.matrix.msc2967.client:device:<id>`), per MSC2967 — the
+ * authorization-code flow doesn't return it any other way (the SDK
+ * auto-generates it when the caller doesn't request a specific one). */
+export declare function extractDeviceIdFromScope(scope: string): string | null;
+/** Confirms {userId, deviceId} for a freshly-obtained access token via
+ * `GET /_matrix/client/v3/account/whoami` — needed because neither the
+ * device-code nor authorization-code token response includes the Matrix
+ * user ID. */
+export declare function whoAmI(homeserverUrl: string, accessToken: string): Promise<{
+    userId: string;
+    deviceId: string | null;
+}>;
+/**
+ * Refreshes an access token via a plain RFC 6749 `grant_type=refresh_token`
+ * POST to the token endpoint — deliberately NOT matrix-js-sdk's
+ * `OidcTokenRefresher`/oidc-client-ts, which unconditionally construct an
+ * internal `OidcClient` requiring `window.sessionStorage`/`window.
+ * localStorage` even though a plain refresh never actually reads or writes
+ * them (confirmed by direct testing: `ReferenceError: window is not
+ * defined` under plain Node; see test/functional/oidc.test.ts O.2). A public client (`token_endpoint_auth_method:
+ * "none"`, what `registerClient` above registers) authenticates a refresh
+ * with just `client_id` in the body, no secret — this is the whole request.
+ * Works identically in Node and the browser (plain `fetch`), so both
+ * adapters share it with zero platform-specific code.
+ */
+export declare function refreshOidcToken(tokenEndpoint: string, clientId: string, refreshToken: string): Promise<AccessTokens>;
+/**
+ * Builds the `tokenRefreshFunction` `TeleCryptIOStorage.createFromOidc`
+ * expects: refreshes via `refreshOidcToken`, then calls `onPersist` with the
+ * new tokens before returning them — so a caller's adapter-specific
+ * persistence (CLI: profile file; UI: localStorage) always sees a refresh
+ * that just happened, not just ones it initiated itself.
+ */
+export declare function buildTokenRefreshFunction(tokenEndpoint: string, clientId: string, onPersist: (tokens: {
+    accessToken: string;
+    refreshToken?: string;
+}) => Promise<void>): TokenRefreshFunction;

package/dist/core/oidc.js

@@ -0,0 +1,170 @@
+/**
+ * Shared OIDC/MAS login building blocks — used by BOTH the CLI (device-code
+ * grant) and the web UI (authorization-code + PKCE). Browser-safe (no
+ * node:fs/path/v8/process/commander/fake-indexeddb): the functions here only
+ * ever call browser-only matrix-js-sdk OIDC helpers (window.crypto for PKCE)
+ * when actually invoked from the browser adapter — importing this module
+ * under Node is safe (nothing here touches `window` at import time), calling
+ * the PKCE-only functions from Node is not (by design: the CLI never calls
+ * them, only the device-code functions, which are plain `fetch` calls).
+ */
+import { createClient } from "matrix-js-sdk";
+import { registerOidcClient, generateScope, generateOidcAuthorizationUrl, completeAuthorizationCodeGrant, startDeviceAuthorization, waitForDeviceAuthorization, } from "matrix-js-sdk/lib/oidc/index.js";
+import { CliError } from "./errors.js";
+/**
+ * Discovers the OIDC/MAS issuer + endpoints for a homeserver, via
+ * `MatrixClient.getAuthMetadata()` (MSC2965 `/auth_metadata`, falling back to
+ * the legacy `/auth_issuer` + issuer well-known) — the non-deprecated path
+ * recommended over `discoverAndValidateOIDCIssuerWellKnown`.
+ *
+ * NODE CALLERS: this internally constructs oidc-client-ts state that
+ * requires `window.sessionStorage`/`window.localStorage` to exist (a real
+ * browser has both natively). Under plain Node, wrap this ONE call in
+ * `src/cli/oidcWindowPolyfill.ts`'s `withOidcWindowShim()` — see that file's
+ * doc comment for why it must be scoped narrowly (a permanent global
+ * `window` breaks the rust-crypto WASM's own environment detection) and why
+ * it's safe here specifically (called once, before any crypto/WASM exists).
+ */
+export async function discoverOidcIssuer(homeserverBaseUrl) {
+    const client = createClient({ baseUrl: homeserverBaseUrl });
+    try {
+        return await client.getAuthMetadata();
+    }
+    catch (err) {
+        throw new CliError(`OIDC discovery failed: ${err.message}`);
+    }
+}
+/**
+ * Dynamic client registration (DCR). `clientUri`/`redirectUris` must share a
+ * host unless the issuer's policy allows a mismatch (our local dev/test MAS
+ * does; a production issuer may not).
+ */
+export async function registerClient(authMetadata, metadata) {
+    try {
+        return await registerOidcClient(authMetadata, metadata);
+    }
+    catch (err) {
+        throw new CliError(`OIDC dynamic client registration failed: ${err.message}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Device-code grant (RFC 8628) — the CLI's login flow. Plain `fetch` calls
+// under the hood (matrix-js-sdk's `startDeviceAuthorization` /
+// `waitForDeviceAuthorization`), nothing browser-only.
+// ---------------------------------------------------------------------------
+/**
+ * Starts a device-code authorization session. `deviceId` is caller-chosen
+ * (unlike the authorization-code flow, where the SDK picks a random one) so
+ * it can be reused as this Matrix device's `device_id` throughout —
+ * `generateScope(deviceId)` embeds it in the requested scope per MSC2967.
+ */
+export async function startDeviceCodeLogin(authMetadata, clientId, deviceId) {
+    const scope = generateScope(deviceId);
+    return startDeviceAuthorization({ clientId, scope, metadata: authMetadata });
+}
+/**
+ * Polls the token endpoint until the device-code session is approved (or
+ * denied/expired) — see matrix-js-sdk's `waitForDeviceAuthorization` for the
+ * RFC 8628 polling semantics (honours `interval`/`expires_in`,
+ * `authorization_pending`/`slow_down`).
+ */
+export async function waitForDeviceCodeLogin(authMetadata, clientId, session) {
+    return waitForDeviceAuthorization({ session, metadata: authMetadata, clientId });
+}
+export function isDeviceAccessTokenError(result) {
+    return typeof result.error === "string";
+}
+// ---------------------------------------------------------------------------
+// Authorization code + PKCE — the web UI's login flow. Browser-only when
+// actually called (uses window.crypto/window.sessionStorage internally via
+// oidc-client-ts) — never called from the CLI.
+// ---------------------------------------------------------------------------
+/**
+ * Builds the authorization URL to redirect the browser to. PKCE
+ * verifier/state/nonce are generated and persisted to `window.sessionStorage`
+ * internally by matrix-js-sdk/oidc-client-ts (`mx_oidc_`-prefixed keys) — the
+ * caller does not need to manage them; `completeAuthorizationCodeFlow` reads
+ * them back after the redirect.
+ */
+export async function beginAuthorizationCodeFlow(opts) {
+    const nonce = crypto.randomUUID();
+    return generateOidcAuthorizationUrl({
+        metadata: opts.authMetadata,
+        clientId: opts.clientId,
+        homeserverUrl: opts.homeserverUrl,
+        redirectUri: opts.redirectUri,
+        nonce,
+    });
+}
+/** Completes the authorization-code exchange after the `?code&state` redirect. */
+export async function completeAuthorizationCodeFlow(code, state) {
+    return completeAuthorizationCodeGrant(code, state);
+}
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+/** The device_id granted is embedded in the token response's `scope`
+ * (`urn:matrix:org.matrix.msc2967.client:device:<id>`), per MSC2967 — the
+ * authorization-code flow doesn't return it any other way (the SDK
+ * auto-generates it when the caller doesn't request a specific one). */
+export function extractDeviceIdFromScope(scope) {
+    const match = scope.match(/urn:matrix:org\.matrix\.msc2967\.client:device:(\S+)/);
+    return match ? match[1] : null;
+}
+/** Confirms {userId, deviceId} for a freshly-obtained access token via
+ * `GET /_matrix/client/v3/account/whoami` — needed because neither the
+ * device-code nor authorization-code token response includes the Matrix
+ * user ID. */
+export async function whoAmI(homeserverUrl, accessToken) {
+    const client = createClient({ baseUrl: homeserverUrl, accessToken });
+    const res = await client.whoami();
+    return { userId: res.user_id, deviceId: res.device_id ?? null };
+}
+/**
+ * Refreshes an access token via a plain RFC 6749 `grant_type=refresh_token`
+ * POST to the token endpoint — deliberately NOT matrix-js-sdk's
+ * `OidcTokenRefresher`/oidc-client-ts, which unconditionally construct an
+ * internal `OidcClient` requiring `window.sessionStorage`/`window.
+ * localStorage` even though a plain refresh never actually reads or writes
+ * them (confirmed by direct testing: `ReferenceError: window is not
+ * defined` under plain Node; see test/functional/oidc.test.ts O.2). A public client (`token_endpoint_auth_method:
+ * "none"`, what `registerClient` above registers) authenticates a refresh
+ * with just `client_id` in the body, no secret — this is the whole request.
+ * Works identically in Node and the browser (plain `fetch`), so both
+ * adapters share it with zero platform-specific code.
+ */
+export async function refreshOidcToken(tokenEndpoint, clientId, refreshToken) {
+    const res = await fetch(tokenEndpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            client_id: clientId,
+        }).toString(),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new CliError(`OIDC token refresh failed (${res.status}): ${body}`);
+    }
+    const data = (await res.json());
+    return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        expiry: data.expires_in ? new Date(Date.now() + data.expires_in * 1000) : undefined,
+    };
+}
+/**
+ * Builds the `tokenRefreshFunction` `TeleCryptIOStorage.createFromOidc`
+ * expects: refreshes via `refreshOidcToken`, then calls `onPersist` with the
+ * new tokens before returning them — so a caller's adapter-specific
+ * persistence (CLI: profile file; UI: localStorage) always sees a refresh
+ * that just happened, not just ones it initiated itself.
+ */
+export function buildTokenRefreshFunction(tokenEndpoint, clientId, onPersist) {
+    return async (refreshToken) => {
+        const tokens = await refreshOidcToken(tokenEndpoint, clientId, refreshToken);
+        await onPersist({ accessToken: tokens.accessToken, refreshToken: tokens.refreshToken });
+        return tokens;
+    };
+}

package/dist/core/operations.d.ts

@@ -12,11 +12,20 @@
  * platform-specific and stays with the caller (see `src/cli/storage.ts`).
  */
 import { TeleCryptIOStorage } from "../TeleCryptIOStorage.js";
-import type { DownloadedFile, FileInfo, FolderInfo, JoinResult, Member, RecoveryRestore, RecoverySetup, ShareResult, UnshareResult } from "./types.js";
+import type { DownloadedFile, FileDetails, FileInfo, FolderDetails, FolderInfo, DeleteResult, JoinResult, Member, RecoveryRestore, RecoverySetup, RenameResult, ShareResult, UnshareResult } from "./types.js";
 export declare function createFolder(storage: TeleCryptIOStorage, name: string): Promise<FolderInfo>;
 /** Top-level folders only — excludes subdirectories of an existing tree. */
 export declare function listFolders(storage: TeleCryptIOStorage): Promise<FolderInfo[]>;
+/** Current account's effective role for a folder, or null while it is unavailable. */
+export declare function getMyFolderRole(storage: TeleCryptIOStorage, folderId: string): string | null;
 export declare function joinFolder(storage: TeleCryptIOStorage, folderId: string): Promise<JoinResult>;
+/** Rooms where this account is invited and the room looks like a file tree. */
+export declare function listPendingInvites(storage: TeleCryptIOStorage): Promise<FolderInfo[]>;
+/** Decline a folder invite (same as leaving before join). */
+export declare function declineInvite(storage: TeleCryptIOStorage, folderId: string): Promise<{
+    folderId: string;
+    declined: boolean;
+}>;
 /**
  * Invites `userId` to the folder at `role` and applies the role's
  * permissions. Doubles as "change an existing participant's role" (call
@@ -29,7 +38,15 @@ export declare function shareFolder(storage: TeleCryptIOStorage, folderId: strin
 export declare function unshareFolder(storage: TeleCryptIOStorage, folderId: string, userId: string): Promise<UnshareResult>;
 export declare function listMembers(storage: TeleCryptIOStorage, folderId: string): Promise<Member[]>;
 export declare function listFiles(storage: TeleCryptIOStorage, folderId: string): Promise<FileInfo[]>;
+export declare function listSubfolders(storage: TeleCryptIOStorage, folderId: string): Promise<FolderInfo[]>;
+export declare function createSubfolder(storage: TeleCryptIOStorage, folderId: string, name: string): Promise<FolderInfo>;
+export declare function renameFolder(storage: TeleCryptIOStorage, folderId: string, name: string): Promise<RenameResult>;
+export declare function deleteFolder(storage: TeleCryptIOStorage, folderId: string): Promise<DeleteResult>;
+export declare function renameFile(storage: TeleCryptIOStorage, folderId: string, fileId: string, name: string): Promise<RenameResult>;
+export declare function deleteFile(storage: TeleCryptIOStorage, folderId: string, fileId: string): Promise<DeleteResult>;
 export declare function uploadFile(storage: TeleCryptIOStorage, folderId: string, name: string, bytes: Uint8Array, mimetype: string): Promise<FileInfo>;
 export declare function downloadFile(storage: TeleCryptIOStorage, folderId: string, fileId: string): Promise<DownloadedFile>;
 export declare function setupRecovery(storage: TeleCryptIOStorage): Promise<RecoverySetup>;
 export declare function restoreRecovery(storage: TeleCryptIOStorage, recoveryKey: string): Promise<RecoveryRestore>;
+export declare function getFileDetails(storage: TeleCryptIOStorage, folderId: string, fileId: string): Promise<FileDetails>;
+export declare function getFolderDetails(storage: TeleCryptIOStorage, folderId: string): Promise<FolderDetails>;

package/dist/core/operations.js

@@ -40,6 +40,14 @@ export async function listFolders(storage) {
     const trees = await storage.listTrees();
     return trees.filter((t) => t.isTopLevel).map((t) => ({ id: t.id, name: t.room.name }));
 }
+/** Current account's effective role for a folder, or null while it is unavailable. */
+export function getMyFolderRole(storage, folderId) {
+    const userId = storage.getClient().getUserId();
+    const tree = storage.getTree(folderId);
+    if (!userId || !tree)
+        return null;
+    return tree.getPermissions(userId);
+}
 export async function joinFolder(storage, folderId) {
     try {
         await storage.getClient().joinRoom(folderId);
@@ -49,6 +57,57 @@ export async function joinFolder(storage, folderId) {
     }
     return { folderId, joined: true };
 }
+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;
+}
+/** Rooms where this account is invited and the room looks like a file tree. */
+export async function listPendingInvites(storage) {
+    const client = storage.getClient();
+    const invites = [];
+    for (const room of client.getRooms()) {
+        if (room.getMyMembership() !== "invite")
+            continue;
+        const tree = storage.getTree(room.roomId);
+        if (tree) {
+            invites.push({
+                id: tree.id,
+                name: roomDisplayName(storage, room.roomId, tree.room.name),
+            });
+            continue;
+        }
+        // Invite state may not have MSC3089 tree metadata yet — accept rooms whose
+        // create event marks them as a file tree space.
+        const createEvent = room.currentState?.getStateEvents("m.room.create", "");
+        const createContent = createEvent?.getContent();
+        const roomType = createContent?.["type"];
+        if (roomType === "org.matrix.msc3088.file" || roomType === "m.space") {
+            invites.push({
+                id: room.roomId,
+                name: roomDisplayName(storage, room.roomId),
+            });
+        }
+    }
+    return invites;
+}
+/** Decline a folder invite (same as leaving before join). */
+export async function declineInvite(storage, folderId) {
+    try {
+        await storage.getClient().leave(folderId);
+    }
+    catch (err) {
+        throw new CliError(`decline failed: ${err.message}`);
+    }
+    return { folderId, declined: true };
+}
 /**
  * Invites `userId` to the folder at `role` and applies the role's
  * permissions. Doubles as "change an existing participant's role" (call
@@ -91,6 +150,37 @@ export async function listFiles(storage, folderId) {
     const tree = await resolveTree(storage, folderId);
     return tree.listFiles().map((f) => ({ id: f.id, name: f.getName() }));
 }
+export async function listSubfolders(storage, folderId) {
+    const tree = await resolveTree(storage, folderId);
+    return tree.getDirectories().map((d) => ({ id: d.id, name: d.room.name }));
+}
+export async function createSubfolder(storage, folderId, name) {
+    const tree = await resolveTree(storage, folderId);
+    const sub = await tree.createDirectory(name);
+    return { id: sub.id, name };
+}
+export async function renameFolder(storage, folderId, name) {
+    const tree = await resolveTree(storage, folderId);
+    await tree.setName(name);
+    return { id: folderId, name };
+}
+export async function deleteFolder(storage, folderId) {
+    const tree = await resolveTree(storage, folderId);
+    await tree.delete();
+    return { id: folderId, deleted: true };
+}
+export async function renameFile(storage, folderId, fileId, name) {
+    const tree = await resolveTree(storage, folderId);
+    const branch = await resolveFile(tree, fileId);
+    await branch.setName(name);
+    return { id: fileId, name };
+}
+export async function deleteFile(storage, folderId, fileId) {
+    const tree = await resolveTree(storage, folderId);
+    const branch = await resolveFile(tree, fileId);
+    await branch.delete();
+    return { id: fileId, deleted: true };
+}
 export async function uploadFile(storage, folderId, name, bytes, mimetype) {
     const tree = await resolveTree(storage, folderId);
     const fileId = await storage.uploadFile(tree, name, toArrayBuffer(bytes), mimetype);
@@ -118,3 +208,71 @@ export async function setupRecovery(storage) {
 export async function restoreRecovery(storage, recoveryKey) {
     return storage.keys.restoreFromRecoveryKey(recoveryKey);
 }
+function tsToIso(ts) {
+    if (ts == null || !Number.isFinite(ts))
+        return null;
+    return new Date(ts).toISOString();
+}
+export async function getFileDetails(storage, folderId, fileId) {
+    const tree = await resolveTree(storage, folderId);
+    const branch = await resolveFile(tree, fileId);
+    const name = branch.getName();
+    let mimetype = null;
+    let size = null;
+    let createdAt = null;
+    let updatedAt = null;
+    try {
+        const { info } = await branch.getFileInfo();
+        if (info) {
+            if (typeof info["mimetype"] === "string")
+                mimetype = info["mimetype"];
+            if (typeof info["size"] === "number")
+                size = info["size"];
+        }
+    }
+    catch {
+        // Partial metadata is fine — UI shows "—" for unknown fields.
+    }
+    try {
+        const event = await branch.getFileEvent();
+        const content = event.getContent();
+        const infoBlock = content["info"];
+        if (!mimetype && typeof infoBlock?.["mimetype"] === "string") {
+            mimetype = infoBlock["mimetype"];
+        }
+        if (size == null && typeof infoBlock?.["size"] === "number") {
+            size = infoBlock["size"];
+        }
+        const eventAny = event;
+        const ts = eventAny.getTs?.() ?? eventAny.origin_server_ts;
+        createdAt = tsToIso(ts);
+        updatedAt = createdAt;
+    }
+    catch {
+        // Same as above.
+    }
+    return { name, mimetype, size, createdAt, updatedAt };
+}
+export async function getFolderDetails(storage, folderId) {
+    const tree = await resolveTree(storage, folderId);
+    const client = storage.getClient();
+    const room = client.getRoom(folderId);
+    let createdAt = null;
+    let memberCount = null;
+    if (room) {
+        const createEvent = room.currentState?.getStateEvents("m.room.create", "");
+        createdAt = tsToIso(createEvent?.getTs());
+        try {
+            memberCount = room.getJoinedMemberCount();
+        }
+        catch {
+            memberCount = null;
+        }
+    }
+    return {
+        name: tree.room.name || roomDisplayName(storage, folderId),
+        id: folderId,
+        createdAt,
+        memberCount,
+    };
+}

package/dist/core/types.d.ts

@@ -35,6 +35,14 @@ export interface JoinResult {
     folderId: string;
     joined: boolean;
 }
+export interface DeleteResult {
+    id: string;
+    deleted: boolean;
+}
+export interface RenameResult {
+    id: string;
+    name: string;
+}
 /** Bytes in/out are always `Uint8Array` — never a file path. */
 export interface DownloadedFile {
     bytes: Uint8Array;
@@ -48,3 +56,16 @@ export interface RecoveryRestore {
     imported: number;
     total: number;
 }
+export interface FileDetails {
+    name: string;
+    mimetype: string | null;
+    size: number | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+export interface FolderDetails {
+    name: string;
+    id: string;
+    createdAt: string | null;
+    memberCount: number | null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telecrypt-io/storage",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "BUSL-1.1",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
     }
   },
   "bin": {
@@ -33,18 +37,27 @@
     "synapse:down": "./throwaway_synapse/down.sh"
   },
   "dependencies": {
-    "commander": "^15.0.0",
-    "fake-indexeddb": "^6.2.5",
+    "commander": "15.0.0",
+    "fake-indexeddb": "6.2.5",
     "matrix-encrypt-attachment": "1.0.3",
     "matrix-js-sdk": "41.9.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "eslint": "^9.0.0",
-    "tsx": "^4.23.1",
-    "typescript": "^5.6.0",
-    "vitest": "^2.0.0"
+    "@playwright/test": "1.61.1",
+    "@types/node": "22.20.1",
+    "@typescript-eslint/eslint-plugin": "8.64.0",
+    "@typescript-eslint/parser": "8.64.0",
+    "eslint": "9.39.5",
+    "tsx": "4.23.1",
+    "typescript": "5.9.3",
+    "vitest": "2.1.9"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TeleCrypt-io/secure-storage.git"
+  },
+  "homepage": "https://github.com/TeleCrypt-io/secure-storage#readme",
+  "bugs": {
+    "url": "https://github.com/TeleCrypt-io/secure-storage/issues"
   }
 }