@telecrypt-io/storage 0.1.3 → 0.2.0

package/README.md

@@ -8,7 +8,9 @@ Files are encrypted on the client before upload. The server stores only opaque c
 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.
+**Status:** library source only. The current public npm release is
+`@telecrypt-io/storage@0.1.3`; no version has been released from this
+repository yet.
 
 ## Install
 
@@ -16,7 +18,7 @@ Recovery Key restores your files on a new device — even if you lose the origin
 npm install @telecrypt-io/storage
 ```
 
-This gives you both the `TeleCryptIOStorage` library and the `telecrypt-io` CLI.
+This gives you the `TeleCryptIOStorage` library and its browser-safe `core` API.
 
 ## Quick start
 
@@ -33,17 +35,10 @@ 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
-```
-
-**Web UI:** a React app lives in [`ui/`](./ui) (`cd ui && npm install && npm run dev`).
+The command-line client is sourced by
+[`TeleCrypt-io/storage-cli`](https://github.com/TeleCrypt-io/storage-cli). The static web
+application is sourced by
+[`TeleCrypt-io/storage.telecrypt.io`](https://github.com/TeleCrypt-io/storage.telecrypt.io).
 
 ## How it works
 
@@ -74,8 +69,7 @@ npm run synapse:down
 
 Tests run against a real local Synapse in podman, never against a production server.
 
-See [CLI.md](./CLI.md) for command reference and [RELEASING.md](./RELEASING.md) for release
-instructions.
+See [RELEASING.md](./RELEASING.md) for the guarded npm release procedure.
 
 ## Licence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telecrypt-io/storage",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "license": "BUSL-1.1",
   "type": "module",
   "main": "dist/index.js",
@@ -15,9 +15,6 @@
       "import": "./dist/core/index.js"
     }
   },
-  "bin": {
-    "telecrypt-io": "dist/cli/index.js"
-  },
   "files": [
     "dist",
     "README.md",
@@ -37,10 +34,9 @@
     "synapse:down": "./throwaway_synapse/down.sh"
   },
   "dependencies": {
-    "commander": "15.0.0",
-    "fake-indexeddb": "6.2.5",
     "matrix-encrypt-attachment": "1.0.3",
-    "matrix-js-sdk": "41.9.0"
+    "matrix-js-sdk": "41.9.0",
+    "oidc-client-ts": "3.5.0"
   },
   "devDependencies": {
     "@playwright/test": "1.61.1",
@@ -54,10 +50,10 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/TeleCrypt-io/secure-storage.git"
+    "url": "git+https://github.com/TeleCrypt-io/storage-sdk.git"
   },
-  "homepage": "https://github.com/TeleCrypt-io/secure-storage#readme",
+  "homepage": "https://github.com/TeleCrypt-io/storage-sdk#readme",
   "bugs": {
-    "url": "https://github.com/TeleCrypt-io/secure-storage/issues"
+    "url": "https://github.com/TeleCrypt-io/storage-sdk/issues"
   }
 }

package/dist/cli/cryptoSnapshot.d.ts

@@ -1,37 +0,0 @@
-interface IndexSpec {
-    name: string;
-    keyPath: string | string[];
-    unique: boolean;
-    multiEntry: boolean;
-}
-interface StoreSpec {
-    name: string;
-    keyPath: string | string[] | null;
-    autoIncrement: boolean;
-    indexes: IndexSpec[];
-}
-interface StoreRecord {
-    key?: unknown;
-    value: unknown;
-}
-interface DbSnapshot {
-    name: string;
-    version: number;
-    stores: StoreSpec[];
-    records: Record<string, StoreRecord[]>;
-}
-export interface CryptoSnapshot {
-    dbs: DbSnapshot[];
-}
-/** Dumps every IndexedDB database currently visible to this process. */
-export declare function exportIndexedDB(): Promise<CryptoSnapshot>;
-/** Recreates every database/store/index/record from a snapshot into the
- * current (assumed empty) IndexedDB factory. */
-export declare function importIndexedDB(snapshot: CryptoSnapshot): Promise<void>;
-export declare function loadSnapshotFromDisk(path: string): CryptoSnapshot | null;
-export declare function saveSnapshotToDisk(path: string, snapshot: CryptoSnapshot): void;
-/** Loads the on-disk snapshot (if any) into the current process's fake-indexeddb. */
-export declare function restoreCryptoStore(path: string): Promise<void>;
-/** Dumps the current process's fake-indexeddb to disk for the next process. */
-export declare function persistCryptoStore(path: string): Promise<void>;
-export {};

package/dist/cli/cryptoSnapshot.js

@@ -1,187 +0,0 @@
-/**
- * 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
- * IndexedDB available is `fake-indexeddb`, which is a pure in-memory
- * implementation — it evaporates when the process exits. Left alone, every
- * CLI invocation would start with an empty crypto store and be unable to
- * decrypt anything a previous invocation wrote (including its own device's
- * megolm sessions), which also breaks cross-user sharing: userB's upload
- * process sends userA an olm-encrypted room key addressed to userA's device
- * identity; if that identity is regenerated every run, the key is
- * undecryptable and userA can never read userB's file no matter what backup
- * scheme is layered on top.
- *
- * Fix: snapshot fake-indexeddb's databases to disk after each command and
- * reload them before the next one runs, keyed to the profile directory. This
- * is Option 1 from the spec (disk-persistent crypto store) implemented via
- * generic export/import over the *public* IndexedDB API (databases(), cursors,
- * transactions) rather than poking fake-indexeddb's internals — so it isn't
- * coupled to fake-indexeddb's private representation and would keep working
- * against any spec-compliant IndexedDB implementation. Runtime crypto
- * behaviour is otherwise unchanged from what the library's own tests already
- * exercise (keys.test.ts, tree.test.ts 4.6 both run rust-crypto on
- * fake-indexeddb).
- *
- * Binary values (megolm session keys etc.) don't survive JSON, so the
- * snapshot is serialised with Node's structured-clone-capable `node:v8`
- * (de)serialize rather than JSON.
- */
-import * as fs from "node:fs";
-import * as v8 from "node:v8";
-function getIndexedDB() {
-    const idb = globalThis.indexedDB;
-    if (!idb) {
-        throw new Error("cryptoSnapshot: globalThis.indexedDB is not set — import 'fake-indexeddb/auto' before calling exportIndexedDB/importIndexedDB");
-    }
-    return idb;
-}
-function promisifyRequest(req) {
-    return new Promise((resolve, reject) => {
-        req.onsuccess = () => resolve(req.result);
-        req.onerror = () => reject(req.error);
-    });
-}
-function promisifyTxDone(tx) {
-    return new Promise((resolve, reject) => {
-        tx.oncomplete = () => resolve();
-        tx.onerror = () => reject(tx.error);
-        tx.onabort = () => reject(tx.error ?? new Error("IndexedDB transaction aborted"));
-    });
-}
-function readAllRecords(store) {
-    return new Promise((resolve, reject) => {
-        const out = [];
-        const outOfLine = store.keyPath === null;
-        const req = store.openCursor();
-        req.onerror = () => reject(req.error);
-        req.onsuccess = () => {
-            const cursor = req.result;
-            if (cursor) {
-                out.push(outOfLine
-                    ? { key: cursor.primaryKey, value: cursor.value }
-                    : { value: cursor.value });
-                cursor.continue();
-            }
-            else {
-                resolve(out);
-            }
-        };
-    });
-}
-/** Dumps every IndexedDB database currently visible to this process. */
-export async function exportIndexedDB() {
-    const idb = getIndexedDB();
-    const infos = await idb.databases();
-    const dbs = [];
-    for (const info of infos) {
-        if (!info.name)
-            continue;
-        const db = await promisifyRequest(idb.open(info.name, info.version));
-        try {
-            const storeNames = Array.from(db.objectStoreNames);
-            const stores = [];
-            const records = {};
-            if (storeNames.length > 0) {
-                const tx = db.transaction(storeNames, "readonly");
-                for (const storeName of storeNames) {
-                    const store = tx.objectStore(storeName);
-                    const indexes = Array.from(store.indexNames).map((iname) => {
-                        const idx = store.index(iname);
-                        return {
-                            name: idx.name,
-                            keyPath: idx.keyPath,
-                            unique: idx.unique,
-                            multiEntry: idx.multiEntry,
-                        };
-                    });
-                    stores.push({
-                        name: storeName,
-                        keyPath: store.keyPath,
-                        autoIncrement: store.autoIncrement,
-                        indexes,
-                    });
-                    records[storeName] = await readAllRecords(store);
-                }
-                await promisifyTxDone(tx);
-            }
-            dbs.push({ name: info.name, version: db.version, stores, records });
-        }
-        finally {
-            db.close();
-        }
-    }
-    return { dbs };
-}
-/** Recreates every database/store/index/record from a snapshot into the
- * current (assumed empty) IndexedDB factory. */
-export async function importIndexedDB(snapshot) {
-    const idb = getIndexedDB();
-    for (const dbSnap of snapshot.dbs) {
-        const db = await new Promise((resolve, reject) => {
-            const req = idb.open(dbSnap.name, Math.max(dbSnap.version, 1));
-            req.onupgradeneeded = () => {
-                const database = req.result;
-                for (const store of dbSnap.stores) {
-                    const os = database.createObjectStore(store.name, {
-                        keyPath: store.keyPath ?? undefined,
-                        autoIncrement: store.autoIncrement,
-                    });
-                    for (const idx of store.indexes) {
-                        os.createIndex(idx.name, idx.keyPath, {
-                            unique: idx.unique,
-                            multiEntry: idx.multiEntry,
-                        });
-                    }
-                }
-            };
-            req.onsuccess = () => resolve(req.result);
-            req.onerror = () => reject(req.error);
-        });
-        try {
-            const storeNames = dbSnap.stores.map((s) => s.name);
-            if (storeNames.length > 0) {
-                const tx = db.transaction(storeNames, "readwrite");
-                for (const store of dbSnap.stores) {
-                    const os = tx.objectStore(store.name);
-                    for (const rec of dbSnap.records[store.name] ?? []) {
-                        if (store.keyPath === null) {
-                            os.put(rec.value, rec.key);
-                        }
-                        else {
-                            os.put(rec.value);
-                        }
-                    }
-                }
-                await promisifyTxDone(tx);
-            }
-        }
-        finally {
-            db.close();
-        }
-    }
-}
-export function loadSnapshotFromDisk(path) {
-    if (!fs.existsSync(path))
-        return null;
-    const buf = fs.readFileSync(path);
-    if (buf.length === 0)
-        return null;
-    return v8.deserialize(buf);
-}
-export function saveSnapshotToDisk(path, snapshot) {
-    fs.writeFileSync(path, v8.serialize(snapshot), { mode: 0o600 });
-}
-/** Loads the on-disk snapshot (if any) into the current process's fake-indexeddb. */
-export async function restoreCryptoStore(path) {
-    const snapshot = loadSnapshotFromDisk(path);
-    if (snapshot) {
-        await importIndexedDB(snapshot);
-    }
-}
-/** Dumps the current process's fake-indexeddb to disk for the next process. */
-export async function persistCryptoStore(path) {
-    const snapshot = await exportIndexedDB();
-    saveSnapshotToDisk(path, snapshot);
-}

package/dist/cli/errors.d.ts

@@ -1 +0,0 @@
-export { CliError } from "../core/errors.js";

package/dist/cli/errors.js

@@ -1,3 +0,0 @@
-// Re-homed under src/core/errors.ts (platform-agnostic — no Node/CLI
-// dependencies), re-exported here so existing CLI imports keep working.
-export { CliError } from "../core/errors.js";

package/dist/cli/index.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import "fake-indexeddb/auto";

package/dist/cli/index.js

@@ -1,443 +0,0 @@
-#!/usr/bin/env node
-import "fake-indexeddb/auto";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { Command } from "commander";
-import { createClient } from "matrix-js-sdk";
-import { clearProfile, readSession, writeSession } from "./profile.js";
-import { initStorageForNewSession, openStorage, waitForBackupSettled } from "./storage.js";
-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
-// and background-request warnings fire on totally successful runs. Left
-// alone, that corrupts BOTH halves of the CLI's output contract: stdout must
-// be exactly one line (human text or --json payload), and stderr under
-// --json must be exactly one `{"error": "..."}` line for a test (or script)
-// to parse. Silence all of them here, before TeleCryptIOStorage.create() ever
-// triggers rust-crypto initialisation; the CLI's own output always goes
-// through process.stdout.write/process.stderr.write directly (see
-// output.ts), never console.*, so this can't swallow anything we emit
-// ourselves. Set TELECRYPT_IO_STORAGE_DEBUG=1 to see the SDK's logs again
-// (all routed to stderr, labelled) when troubleshooting.
-if (!process.env.TELECRYPT_IO_STORAGE_DEBUG) {
-    console.log = () => { };
-    console.debug = () => { };
-    console.info = () => { };
-    console.trace = () => { };
-    console.warn = () => { };
-    console.error = () => { };
-}
-else {
-    const toStderr = (label) => (...args) => process.stderr.write(`[${label}] ${args.map(String).join(" ")}\n`);
-    console.log = toStderr("log");
-    console.debug = toStderr("debug");
-    console.info = toStderr("info");
-    console.trace = toStderr("trace");
-    console.warn = toStderr("warn");
-    console.error = toStderr("error");
-}
-const EXT_MIMETYPES = {
-    ".txt": "text/plain",
-    ".json": "application/json",
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".pdf": "application/pdf",
-    ".md": "text/markdown",
-};
-function guessMimetype(filePath) {
-    return EXT_MIMETYPES[path.extname(filePath).toLowerCase()] ?? "application/octet-stream";
-}
-const program = new Command();
-program
-    .name("telecrypt-io")
-    .description("TeleCrypt.io CLI")
-    .option("--json", "machine-readable JSON output")
-    .showHelpAfterError();
-const storage = program
-    .command("storage")
-    .description("End-to-end encrypted file storage on Matrix");
-// ---------------------------------------------------------------------------
-// Session
-// ---------------------------------------------------------------------------
-storage
-    .command("login")
-    .description("Log in and persist the session + crypto store to the profile")
-    .requiredOption("--homeserver <url>", "Matrix homeserver base URL")
-    .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 () => {
-        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");
-                },
-            });
-        }
-        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,
-            };
-        }
-        writeSession(session);
-        // Establishes this device's crypto identity and does a first sync
-        // (proves connectivity end-to-end), and writes the initial crypto
-        // store snapshot so later commands have something to load.
-        const opened = await initStorageForNewSession(session);
-        await opened.close();
-        return {
-            json: { userId: session.userId, deviceId: session.deviceId, homeserver: session.homeserver },
-            text: `Logged in as ${session.userId} (device ${session.deviceId})`,
-        };
-    });
-});
-storage
-    .command("register")
-    .description("Register a new account (dev/test convenience), then log in")
-    .requiredOption("--homeserver <url>", "Matrix homeserver base URL")
-    .requiredOption("--user <localpart>", "Username (localpart)")
-    .requiredOption("--password <pw>", "Password")
-    .action(async (opts, command) => {
-    await runAction(command, async () => {
-        const res = await fetch(`${opts.homeserver}/_matrix/client/v3/register`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({
-                username: opts.user,
-                password: opts.password,
-                auth: { type: "m.login.dummy" },
-                inhibit_login: false,
-            }),
-        });
-        if (!res.ok) {
-            const body = await res.text();
-            throw new CliError(`registration failed (${res.status}): ${body}`);
-        }
-        const data = (await res.json());
-        const session = {
-            homeserver: opts.homeserver,
-            userId: data.user_id,
-            deviceId: data.device_id,
-            accessToken: data.access_token,
-        };
-        writeSession(session);
-        const opened = await initStorageForNewSession(session);
-        await opened.close();
-        return {
-            json: { userId: session.userId, deviceId: session.deviceId, homeserver: session.homeserver },
-            text: `Registered and logged in as ${session.userId} (device ${session.deviceId})`,
-        };
-    });
-});
-storage
-    .command("whoami")
-    .description("Print the current session identity")
-    .action(async (_opts, command) => {
-    await runAction(command, async () => {
-        const session = readSession();
-        if (!session)
-            throw new CliError("not logged in");
-        return {
-            json: { userId: session.userId, deviceId: session.deviceId, homeserver: session.homeserver },
-            text: `${session.userId} (device ${session.deviceId}) @ ${session.homeserver}`,
-        };
-    });
-});
-storage
-    .command("logout")
-    .description("Clear the local profile (session + crypto store)")
-    .action(async (_opts, command) => {
-    await runAction(command, async () => {
-        const session = readSession();
-        if (session) {
-            // Best-effort server-side logout; local profile is cleared either way.
-            await fetch(`${session.homeserver}/_matrix/client/v3/logout`, {
-                method: "POST",
-                headers: { Authorization: `Bearer ${session.accessToken}` },
-            }).catch(() => undefined);
-        }
-        clearProfile();
-        return { json: { loggedOut: true }, text: "Logged out." };
-    });
-});
-// ---------------------------------------------------------------------------
-// Recovery (Layer 2)
-// ---------------------------------------------------------------------------
-const recovery = storage.command("recovery").description("Server-side key backup / recovery");
-recovery
-    .command("setup")
-    .description("Set up recovery (cross-signing + key backup) and print the Recovery Key")
-    .action(async (_opts, command) => {
-    await runAction(command, async () => {
-        const opened = await openStorage();
-        try {
-            const result = await core.setupRecovery(opened.storage);
-            // Give any already-known megolm sessions a chance to actually reach
-            // the server backup before this short-lived process exits — see
-            // waitForBackupSettled's doc comment.
-            await waitForBackupSettled(opened.storage);
-            return {
-                json: { ...result },
-                text: [
-                    "Recovery Key (SAVE THIS — it is the only way to recover your files on a new device):",
-                    "",
-                    result.recoveryKey,
-                ].join("\n"),
-            };
-        }
-        finally {
-            await opened.close();
-        }
-    });
-});
-recovery
-    .command("restore <recoveryKey>")
-    .description("Restore keys on this device from a Recovery Key")
-    .action(async (recoveryKey, _opts, command) => {
-    await runAction(command, async () => {
-        const opened = await openStorage();
-        try {
-            const result = await core.restoreRecovery(opened.storage, recoveryKey);
-            return {
-                json: { ...result },
-                text: `Restored ${result.imported}/${result.total} keys.`,
-            };
-        }
-        finally {
-            await opened.close();
-        }
-    });
-});
-// ---------------------------------------------------------------------------
-// Folders
-// ---------------------------------------------------------------------------
-const folder = storage.command("folder").description("Shared folder operations");
-folder
-    .command("create <name>")
-    .description("Create a new shared folder")
-    .action(async (name, _opts, command) => {
-    await runAction(command, async () => {
-        const opened = await openStorage();
-        try {
-            const result = await core.createFolder(opened.storage, name);
-            return {
-                json: { folderId: result.id, name: result.name },
-                text: `Created folder "${result.name}" (${result.id})`,
-            };
-        }
-        finally {
-            await opened.close();
-        }
-    });
-});
-folder
-    .command("list")
-    .description("List folders visible to the current user")
-    .action(async (_opts, command) => {
-    await runAction(command, async () => {
-        const opened = await openStorage();
-        try {
-            const folders = await core.listFolders(opened.storage);
-            return {
-                json: { folders },
-                text: folders.length === 0
-                    ? "(no folders)"
-                    : folders.map((f) => `${f.id}\t${f.name}`).join("\n"),
-            };
-        }
-        finally {
-            await opened.close();
-        }
-    });
-});
-folder
-    .command("join <folderId>")
-    .description("Accept a pending folder invitation (join the room)")
-    .action(async (folderId, _opts, command) => {
-    await runAction(command, async () => {
-        const opened = await openStorage();
-        try {
-            const result = await core.joinFolder(opened.storage, folderId);
-            return { json: { ...result }, text: `Joined folder ${result.folderId}` };
-        }
-        finally {
-            await opened.close();
-        }
-    });
-});
-folder
-    .command("share <folderId> <userId>")
-    .description("Invite a participant to a shared folder at a given role")
-    .option("--role <role>", "viewer or editor", "viewer")
-    .action(async (folderId, userId, opts, command) => {
-    await runAction(command, async () => {
-        // Validated here too (before openStorage/login is even attempted) so
-        // a bad --role fails fast exactly as before; core.shareFolder repeats
-        // the same check so it's still safe to call standalone (e.g. from a
-        // future UI) without this CLI-side pre-check.
-        if (opts.role !== "viewer" && opts.role !== "editor") {
-            throw new CliError(`invalid --role "${opts.role}" (must be viewer or editor)`);
-        }
-        const opened = await openStorage();
-        try {
-            const result = await core.shareFolder(opened.storage, folderId, userId, opts.role);
-            return {
-                json: { ...result },
-                text: `Invited ${result.userId} to ${result.folderId} as ${result.role}`,
-            };
-        }
-        finally {
-            await opened.close();
-        }
-    });
-});
-folder
-    .command("members <folderId>")
-    .description("List participants and their roles")
-    .action(async (folderId, _opts, command) => {
-    await runAction(command, async () => {
-        const opened = await openStorage();
-        try {
-            const members = await core.listMembers(opened.storage, folderId);
-            return {
-                json: { members },
-                text: members.map((m) => `${m.userId}\t${m.role}\t${m.membership}`).join("\n"),
-            };
-        }
-        finally {
-            await opened.close();
-        }
-    });
-});
-folder
-    .command("unshare <folderId> <userId>")
-    .description("Remove a participant from a shared folder")
-    .action(async (folderId, userId, _opts, command) => {
-    await runAction(command, async () => {
-        const opened = await openStorage();
-        try {
-            const result = await core.unshareFolder(opened.storage, folderId, userId);
-            return { json: { ...result }, text: `Removed ${result.userId} from ${result.folderId}` };
-        }
-        finally {
-            await opened.close();
-        }
-    });
-});
-// ---------------------------------------------------------------------------
-// Files
-// ---------------------------------------------------------------------------
-const file = storage.command("file").description("File operations within a folder");
-file
-    .command("upload <folderId> <path>")
-    .description("Encrypt and upload a local file into a folder")
-    .option("--name <name>", "Name to store the file as (default: basename of path)")
-    .action(async (folderId, filePath, opts, command) => {
-    await runAction(command, async () => {
-        if (!fs.existsSync(filePath)) {
-            throw new CliError(`file not found: ${filePath}`);
-        }
-        const opened = await openStorage();
-        try {
-            const name = opts.name ?? path.basename(filePath);
-            const data = fs.readFileSync(filePath);
-            const result = await core.uploadFile(opened.storage, folderId, name, data, guessMimetype(filePath));
-            // If recovery/backup is already active for this account, give the
-            // new session's key a chance to actually reach the server backup
-            // before this short-lived process exits.
-            await waitForBackupSettled(opened.storage);
-            return {
-                json: { fileId: result.id, name: result.name },
-                text: `Uploaded "${result.name}" as ${result.id}`,
-            };
-        }
-        finally {
-            await opened.close();
-        }
-    });
-});
-file
-    .command("list <folderId>")
-    .description("List files in a folder")
-    .action(async (folderId, _opts, command) => {
-    await runAction(command, async () => {
-        const opened = await openStorage();
-        try {
-            const files = await core.listFiles(opened.storage, folderId);
-            return {
-                json: { files },
-                text: files.length === 0 ? "(no files)" : files.map((f) => `${f.id}\t${f.name}`).join("\n"),
-            };
-        }
-        finally {
-            await opened.close();
-        }
-    });
-});
-file
-    .command("download <folderId> <fileId> <destPath>")
-    .description("Download and decrypt a file to a local path")
-    .action(async (folderId, fileId, destPath, _opts, command) => {
-    await runAction(command, async () => {
-        const opened = await openStorage();
-        try {
-            const result = await core.downloadFile(opened.storage, folderId, fileId);
-            fs.writeFileSync(destPath, Buffer.from(result.bytes));
-            return {
-                json: { path: destPath, bytes: result.bytes.byteLength, mimetype: result.mimetype },
-                text: `Downloaded ${result.bytes.byteLength} bytes to ${destPath}`,
-            };
-        }
-        finally {
-            await opened.close();
-        }
-    });
-});
-// ---------------------------------------------------------------------------
-program
-    .parseAsync(process.argv)
-    .catch((err) => {
-    process.stderr.write(`Error: ${err.message}\n`);
-    process.exitCode = 1;
-})
-    .finally(() => {
-    // Every action closes its own storage (stopClient()), but Node's global
-    // fetch (undici) can keep a keep-alive socket open past that, leaving
-    // the process hanging instead of exiting on its own. Exit explicitly
-    // once the command has fully finished and printed its output.
-    process.exit(process.exitCode ?? 0);
-});

package/dist/cli/oidc.d.ts

@@ -1,19 +0,0 @@
-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

@@ -1,97 +0,0 @@
-/**
- * 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

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

package/dist/cli/oidcWindowPolyfill.js

@@ -1,76 +0,0 @@
-/**
- * `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/output.d.ts

@@ -1,16 +0,0 @@
-import type { Command } from "commander";
-export interface CommandResult {
-    /** Machine-readable payload for --json. */
-    json: Record<string, unknown>;
-    /** Human-readable text for the default (non --json) output. */
-    text: string;
-}
-/**
- * Runs a command action: executes `fn`, prints its result (JSON or human
- * text) to stdout on success, or a clean `{ "error": "..." }` (JSON mode) /
- * `Error: ...` (text mode) to stderr on failure — never a raw stack trace.
- * Sets process.exitCode accordingly (0 on success, 1 on failure) rather than
- * calling process.exit() directly, so callers can do any final cleanup
- * first.
- */
-export declare function runAction(command: Command, fn: () => Promise<CommandResult>): Promise<void>;

package/dist/cli/output.js

@@ -1,24 +0,0 @@
-function isJsonMode(command) {
-    return Boolean(command.optsWithGlobals().json);
-}
-/**
- * Runs a command action: executes `fn`, prints its result (JSON or human
- * text) to stdout on success, or a clean `{ "error": "..." }` (JSON mode) /
- * `Error: ...` (text mode) to stderr on failure — never a raw stack trace.
- * Sets process.exitCode accordingly (0 on success, 1 on failure) rather than
- * calling process.exit() directly, so callers can do any final cleanup
- * first.
- */
-export async function runAction(command, fn) {
-    const json = isJsonMode(command);
-    try {
-        const result = await fn();
-        process.stdout.write((json ? JSON.stringify(result.json) : result.text) + "\n");
-        process.exitCode = 0;
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        process.stderr.write((json ? JSON.stringify({ error: message }) : `Error: ${message}`) + "\n");
-        process.exitCode = 1;
-    }
-}

package/dist/cli/poll.d.ts

@@ -1 +0,0 @@
-export { waitForCondition } from "../core/poll.js";

package/dist/cli/poll.js

@@ -1,3 +0,0 @@
-// Re-homed under src/core/poll.ts (platform-agnostic — no Node/CLI
-// dependencies), re-exported here so existing CLI imports keep working.
-export { waitForCondition } from "../core/poll.js";

package/dist/cli/profile.d.ts

@@ -1,33 +0,0 @@
-export interface Session {
-    homeserver: string;
-    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,
- * crypto store) lives here. Overridable via TELECRYPT_IO_STORAGE_HOME so
- * tests can give each simulated user/device its own isolated profile.
- * Defaults to ~/.telecrypt-io/storage for normal interactive use.
- */
-export declare function profileDir(): string;
-export declare function sessionPath(dir?: string): string;
-export declare function cryptoSnapshotPath(dir?: string): string;
-export declare function ensureProfileDir(dir?: string): void;
-export declare function readSession(dir?: string): Session | null;
-export declare function writeSession(session: Session, dir?: string): void;
-/** Clears all local state for this profile (session + crypto store). */
-export declare function clearProfile(dir?: string): void;

package/dist/cli/profile.js

@@ -1,46 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
-/**
- * Resolves the profile directory: everything this CLI persists (session,
- * crypto store) lives here. Overridable via TELECRYPT_IO_STORAGE_HOME so
- * tests can give each simulated user/device its own isolated profile.
- * Defaults to ~/.telecrypt-io/storage for normal interactive use.
- */
-export function profileDir() {
-    const home = process.env.TELECRYPT_IO_STORAGE_HOME;
-    if (home && home.trim() !== "")
-        return home;
-    return path.join(os.homedir(), ".telecrypt-io", "storage");
-}
-export function sessionPath(dir = profileDir()) {
-    return path.join(dir, "session.json");
-}
-export function cryptoSnapshotPath(dir = profileDir()) {
-    return path.join(dir, "crypto.snapshot");
-}
-export function ensureProfileDir(dir = profileDir()) {
-    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-}
-export function readSession(dir = profileDir()) {
-    const p = sessionPath(dir);
-    if (!fs.existsSync(p))
-        return null;
-    const raw = fs.readFileSync(p, "utf8");
-    return JSON.parse(raw);
-}
-export function writeSession(session, dir = profileDir()) {
-    ensureProfileDir(dir);
-    fs.writeFileSync(sessionPath(dir), JSON.stringify(session, null, 2), {
-        mode: 0o600,
-    });
-}
-/** Clears all local state for this profile (session + crypto store). */
-export function clearProfile(dir = profileDir()) {
-    const sp = sessionPath(dir);
-    const cp = cryptoSnapshotPath(dir);
-    if (fs.existsSync(sp))
-        fs.rmSync(sp);
-    if (fs.existsSync(cp))
-        fs.rmSync(cp);
-}

package/dist/cli/storage.d.ts

@@ -1,36 +0,0 @@
-import "fake-indexeddb/auto";
-import { TeleCryptIOStorage } from "../TeleCryptIOStorage.js";
-import { Session } from "./profile.js";
-export interface OpenedStorage {
-    storage: TeleCryptIOStorage;
-    session: Session;
-    /** Persists the crypto store back to disk and stops the client. Call this
-     * in a `finally` block around every command that opens storage, so the
-     * next CLI invocation sees whatever this one learned (new megolm sessions,
-     * device keys, etc.) — this is what makes decryption survive across
-     * separate processes. */
-    close: () => Promise<void>;
-}
-/**
- * Opens a TeleCryptIOStorage bound to the current profile's session, having first
- * restored the crypto store snapshot (if any) from a previous CLI
- * invocation. Throws CliError("not logged in") if there is no session.
- */
-export declare function openStorage(dir?: string): Promise<OpenedStorage>;
-/**
- * If server-side key backup is active for this account, waits (best-effort,
- * bounded) for the SDK's backup engine to report zero sessions remaining to
- * upload. This matters specifically because a CLI command is a *short-lived
- * process*: the backup engine deliberately fire-and-forgets its upload loop
- * with a randomised 0-10s startup jitter (to avoid a multi-device thundering
- * herd), so a command that creates a new megolm session (recovery setup,
- * or a file upload once recovery is already set up) and then exits
- * immediately can easily outrun that loop, leaving the new key silently
- * absent from the backup — recoverable-looking but not actually recoverable.
- * Never throws: this is a best-effort settle grace period, not a
- * correctness gate on the command's primary result.
- */
-export declare function waitForBackupSettled(storage: TeleCryptIOStorage, timeoutMs?: number): Promise<void>;
-/** Used by login/register: builds storage for a brand-new session and
- * establishes the initial (empty) crypto store snapshot on disk. */
-export declare function initStorageForNewSession(session: Session, dir?: string): Promise<OpenedStorage>;

package/dist/cli/storage.js

@@ -1,126 +0,0 @@
-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, 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
- * invocation. Throws CliError("not logged in") if there is no session.
- */
-export async function openStorage(dir = profileDir()) {
-    const session = readSession(dir);
-    if (!session) {
-        throw new CliError("not logged in — run `telecrypt-io storage login` first");
-    }
-    const snapshotPath = cryptoSnapshotPath(dir);
-    await restoreCryptoStore(snapshotPath);
-    const storage = await buildStorageForSession(session, dir);
-    let closed = false;
-    const close = async () => {
-        if (closed)
-            return;
-        closed = true;
-        try {
-            await persistCryptoStore(snapshotPath);
-        }
-        finally {
-            storage.getClient().stopClient();
-        }
-    };
-    return { storage, session, close };
-}
-/**
- * If server-side key backup is active for this account, waits (best-effort,
- * bounded) for the SDK's backup engine to report zero sessions remaining to
- * upload. This matters specifically because a CLI command is a *short-lived
- * process*: the backup engine deliberately fire-and-forgets its upload loop
- * with a randomised 0-10s startup jitter (to avoid a multi-device thundering
- * herd), so a command that creates a new megolm session (recovery setup,
- * or a file upload once recovery is already set up) and then exits
- * immediately can easily outrun that loop, leaving the new key silently
- * absent from the backup — recoverable-looking but not actually recoverable.
- * Never throws: this is a best-effort settle grace period, not a
- * correctness gate on the command's primary result.
- */
-export async function waitForBackupSettled(storage, timeoutMs = 20000) {
-    const active = await storage.keys.isRecoverySetup();
-    if (!active)
-        return;
-    const client = storage.getClient();
-    await new Promise((resolve) => {
-        let settled = false;
-        const finish = () => {
-            if (settled)
-                return;
-            settled = true;
-            client.removeListener(CryptoEvent.KeyBackupSessionsRemaining, onRemaining);
-            clearTimeout(timer);
-            resolve();
-        };
-        const onRemaining = (remaining) => {
-            if (remaining === 0)
-                finish();
-        };
-        client.on(CryptoEvent.KeyBackupSessionsRemaining, onRemaining);
-        const timer = setTimeout(finish, timeoutMs);
-    });
-}
-/** Used by login/register: builds storage for a brand-new session and
- * establishes the initial (empty) crypto store snapshot on disk. */
-export async function initStorageForNewSession(session, dir = profileDir()) {
-    ensureProfileDir(dir);
-    const snapshotPath = cryptoSnapshotPath(dir);
-    const storage = await buildStorageForSession(session, dir);
-    let closed = false;
-    const close = async () => {
-        if (closed)
-            return;
-        closed = true;
-        try {
-            await persistCryptoStore(snapshotPath);
-        }
-        finally {
-            storage.getClient().stopClient();
-        }
-    };
-    return { storage, session, close };
-}