@telecrypt-io/storage 0.1.0

package/dist/cli/output.js

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

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

package/dist/cli/poll.js

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

@@ -0,0 +1,20 @@
+export interface Session {
+    homeserver: string;
+    userId: string;
+    deviceId: string;
+    accessToken: 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

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

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

@@ -0,0 +1,99 @@
+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 { persistCryptoStore, restoreCryptoStore } from "./cryptoSnapshot.js";
+import { CliError } from "./errors.js";
+/**
+ * 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 TeleCryptIOStorage.create({
+        baseUrl: session.homeserver,
+        userId: session.userId,
+        accessToken: session.accessToken,
+        deviceId: session.deviceId,
+    });
+    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 TeleCryptIOStorage.create({
+        baseUrl: session.homeserver,
+        userId: session.userId,
+        accessToken: session.accessToken,
+        deviceId: session.deviceId,
+    });
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        try {
+            await persistCryptoStore(snapshotPath);
+        }
+        finally {
+            storage.getClient().stopClient();
+        }
+    };
+    return { storage, session, close };
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,8 @@
+/** A user-facing operation error: a clean, prefix-free message meant to be
+ * shown directly to a user (CLI stderr today, a future UI's error toast
+ * tomorrow) — never a raw stack trace. Thrown for expected failure
+ * conditions (bad login, wrong recovery key, missing file/folder, not
+ * logged in, ...). Platform-agnostic: no Node/CLI dependencies. */
+export declare class CliError extends Error {
+    constructor(message: string);
+}

package/dist/core/errors.js

@@ -0,0 +1,11 @@
+/** A user-facing operation error: a clean, prefix-free message meant to be
+ * shown directly to a user (CLI stderr today, a future UI's error toast
+ * tomorrow) — never a raw stack trace. Thrown for expected failure
+ * conditions (bad login, wrong recovery key, missing file/folder, not
+ * logged in, ...). Platform-agnostic: no Node/CLI dependencies. */
+export class CliError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CliError";
+    }
+}

package/dist/core/index.d.ts

@@ -0,0 +1,5 @@
+/** Barrel: the full platform-agnostic surface a UI (or any non-CLI caller)
+ * needs — the typed result contract plus every operation. */
+export * from "./types.js";
+export * from "./operations.js";
+export * from "./errors.js";

package/dist/core/index.js

@@ -0,0 +1,5 @@
+/** Barrel: the full platform-agnostic surface a UI (or any non-CLI caller)
+ * needs — the typed result contract plus every operation. */
+export * from "./types.js";
+export * from "./operations.js";
+export * from "./errors.js";

package/dist/core/operations.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Platform-agnostic operations: one function per user-facing action, each
+ * taking an already-created `TeleCryptIOStorage` plus plain inputs and returning
+ * one of the typed results in `./types.ts`. No I/O beyond the Matrix client
+ * itself, no stdout, no `process`, no file paths — bytes in/out are always
+ * `Uint8Array`. This is what the CLI's command actions call today and what
+ * a future React UI calls directly, so both run the exact same tested logic
+ * and share the exact same result shapes.
+ *
+ * `core/` never creates the `TeleCryptIOStorage`/`MatrixClient` itself — store
+ * config (persistent crypto store, session credentials, etc.) is
+ * 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";
+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[]>;
+export declare function joinFolder(storage: TeleCryptIOStorage, folderId: string): Promise<JoinResult>;
+/**
+ * Invites `userId` to the folder at `role` and applies the role's
+ * permissions. Doubles as "change an existing participant's role" (call
+ * again with a different role): inviting someone who's already a member is
+ * a 403 from the server, not a real failure — that specific error is
+ * swallowed and the role change still applies. Any other invite failure
+ * (e.g. unknown user) propagates.
+ */
+export declare function shareFolder(storage: TeleCryptIOStorage, folderId: string, userId: string, role: string): Promise<ShareResult>;
+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 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>;

package/dist/core/operations.js

@@ -0,0 +1,120 @@
+import { CliError } from "./errors.js";
+import { waitForCondition } from "./poll.js";
+/**
+ * Resolves a folder by ID, polling briefly: a room this same account just
+ * created (or was just invited to, by another process/session) can be
+ * momentarily absent from a from-scratch `/sync` before showing up moments
+ * later — real async settling, not an instant "not found". Throws a clean
+ * error if the folder still isn't visible once the poll times out.
+ */
+async function resolveTree(storage, folderId) {
+    try {
+        return await waitForCondition(() => storage.getTree(folderId), {
+            timeoutMs: 15000,
+        });
+    }
+    catch {
+        throw new CliError(`folder not found: ${folderId}`);
+    }
+}
+/** As `resolveTree`, but for a specific file within an already-resolved
+ * folder — covers the same settling window for a file another
+ * process/session just uploaded. */
+async function resolveFile(tree, fileId) {
+    try {
+        return await waitForCondition(() => tree.getFile(fileId), { timeoutMs: 15000 });
+    }
+    catch {
+        throw new CliError(`file not found: ${fileId}`);
+    }
+}
+function toArrayBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+export async function createFolder(storage, name) {
+    const tree = await storage.createTree(name);
+    return { id: tree.id, name };
+}
+/** Top-level folders only — excludes subdirectories of an existing tree. */
+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 }));
+}
+export async function joinFolder(storage, folderId) {
+    try {
+        await storage.getClient().joinRoom(folderId);
+    }
+    catch (err) {
+        throw new CliError(`join failed: ${err.message}`);
+    }
+    return { folderId, joined: true };
+}
+/**
+ * Invites `userId` to the folder at `role` and applies the role's
+ * permissions. Doubles as "change an existing participant's role" (call
+ * again with a different role): inviting someone who's already a member is
+ * a 403 from the server, not a real failure — that specific error is
+ * swallowed and the role change still applies. Any other invite failure
+ * (e.g. unknown user) propagates.
+ */
+export async function shareFolder(storage, folderId, userId, role) {
+    if (role !== "viewer" && role !== "editor") {
+        throw new CliError(`invalid --role "${role}" (must be viewer or editor)`);
+    }
+    const tree = await resolveTree(storage, folderId);
+    try {
+        await tree.invite(userId);
+    }
+    catch (err) {
+        if (!/already in the room/i.test(err.message)) {
+            throw err;
+        }
+    }
+    await tree.setPermissions(userId, role);
+    return { folderId, userId, role };
+}
+export async function unshareFolder(storage, folderId, userId) {
+    await resolveTree(storage, folderId);
+    try {
+        await storage.getClient().kick(folderId, userId, "unshared");
+    }
+    catch (err) {
+        throw new CliError(`unshare failed: ${err.message}`);
+    }
+    return { folderId, userId, removed: true };
+}
+export async function listMembers(storage, folderId) {
+    const tree = await resolveTree(storage, folderId);
+    return storage.listMembers(tree);
+}
+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 uploadFile(storage, folderId, name, bytes, mimetype) {
+    const tree = await resolveTree(storage, folderId);
+    const fileId = await storage.uploadFile(tree, name, toArrayBuffer(bytes), mimetype);
+    return { id: fileId, name, mimetype };
+}
+export async function downloadFile(storage, folderId, fileId) {
+    const tree = await resolveTree(storage, folderId);
+    const branch = await resolveFile(tree, fileId);
+    let result;
+    try {
+        result = await storage.downloadFile(branch);
+    }
+    catch (err) {
+        throw new CliError(`download failed: ${err.message}`);
+    }
+    return {
+        bytes: new Uint8Array(result.data),
+        mimetype: result.mimetype,
+        name: branch.getName(),
+    };
+}
+export async function setupRecovery(storage) {
+    return storage.keys.setupRecovery();
+}
+export async function restoreRecovery(storage, recoveryKey) {
+    return storage.keys.restoreFromRecoveryKey(recoveryKey);
+}

package/dist/core/poll.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A freshly-synced client doesn't always see a room/event the *instant* the
+ * server has committed it — e.g. a room this same session just created can
+ * briefly be absent from the very next from-scratch `/sync` a later process
+ * performs, before showing up moments later. That's real async settling
+ * (Matrix eventual-consistency-on-fresh-sync), not a bug to paper over with
+ * a fixed delay: poll the actual condition, bounded by a timeout, leveraging
+ * the client's own live background sync loop (already running in this
+ * process since TeleCryptIOStorage.create() started it).
+ */
+export declare function waitForCondition<T>(check: () => T | null | undefined, opts?: {
+    timeoutMs?: number;
+    intervalMs?: number;
+}): Promise<T>;

package/dist/core/poll.js

@@ -0,0 +1,24 @@
+/**
+ * A freshly-synced client doesn't always see a room/event the *instant* the
+ * server has committed it — e.g. a room this same session just created can
+ * briefly be absent from the very next from-scratch `/sync` a later process
+ * performs, before showing up moments later. That's real async settling
+ * (Matrix eventual-consistency-on-fresh-sync), not a bug to paper over with
+ * a fixed delay: poll the actual condition, bounded by a timeout, leveraging
+ * the client's own live background sync loop (already running in this
+ * process since TeleCryptIOStorage.create() started it).
+ */
+export async function waitForCondition(check, opts) {
+    const timeoutMs = opts?.timeoutMs ?? 15000;
+    const intervalMs = opts?.intervalMs ?? 300;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const result = check();
+        if (result !== null && result !== undefined)
+            return result;
+        if (Date.now() >= deadline) {
+            throw new Error(`timed out after ${timeoutMs}ms waiting for condition`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The shared typed result contract for every `core/operations.ts` function.
+ * This is deliberately the ONE definition of these shapes: the CLI's
+ * `--json` schema is these types (or a trivial projection of them, e.g.
+ * `FolderInfo.id` -> the CLI's `folderId` key for backwards-compatible
+ * command output), and the future React UI's data model is these types
+ * directly. Keeping it here means the CLI and the UI can never drift apart
+ * on what an operation returns.
+ */
+export interface FolderInfo {
+    id: string;
+    name: string;
+}
+export interface FileInfo {
+    id: string;
+    name: string;
+    mimetype?: string;
+}
+export interface Member {
+    userId: string;
+    role: string;
+    membership: string;
+}
+export interface ShareResult {
+    folderId: string;
+    userId: string;
+    role: string;
+}
+export interface UnshareResult {
+    folderId: string;
+    userId: string;
+    removed: boolean;
+}
+export interface JoinResult {
+    folderId: string;
+    joined: boolean;
+}
+/** Bytes in/out are always `Uint8Array` — never a file path. */
+export interface DownloadedFile {
+    bytes: Uint8Array;
+    mimetype: string;
+    name: string;
+}
+export interface RecoverySetup {
+    recoveryKey: string;
+}
+export interface RecoveryRestore {
+    imported: number;
+    total: number;
+}

package/dist/core/types.js

@@ -0,0 +1,10 @@
+/**
+ * The shared typed result contract for every `core/operations.ts` function.
+ * This is deliberately the ONE definition of these shapes: the CLI's
+ * `--json` schema is these types (or a trivial projection of them, e.g.
+ * `FolderInfo.id` -> the CLI's `folderId` key for backwards-compatible
+ * command output), and the future React UI's data model is these types
+ * directly. Keeping it here means the CLI and the UI can never drift apart
+ * on what an operation returns.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { TeleCryptIOStorage } from "./TeleCryptIOStorage.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { TeleCryptIOStorage } from "./TeleCryptIOStorage.js";

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@telecrypt-io/storage",
+  "version": "0.1.0",
+  "license": "BUSL-1.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "telecrypt-io": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src test --ext .ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "synapse:up": "./throwaway_synapse/up.sh",
+    "synapse:fresh": "./throwaway_synapse/up.sh --fresh",
+    "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"
+  },
+  "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"
+  }
+}