@telecrypt-io/storage 0.1.0

package/dist/cli/cryptoSnapshot.d.ts

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

@@ -0,0 +1,187 @@
+/**
+ * Cross-process crypto persistence (THE central challenge — see docs/CLI_SPEC.md).
+ *
+ * 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

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

package/dist/cli/errors.js

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

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

package/dist/cli/index.js

@@ -0,0 +1,415 @@
+#!/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";
+// 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")
+    .requiredOption("--user <localpart>", "Username (localpart or full MXID)")
+    .requiredOption("--password <pw>", "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);
+        }
+        catch (err) {
+            throw new CliError(`login failed: ${err.message}`);
+        }
+        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
+        // 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/output.d.ts

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