@telecrypt-io/storage 0.7.2 → 0.9.0

package/README.md

@@ -46,6 +46,13 @@ by default. Browser persistence uses IndexedDB and the Matrix Rust crypto WASM r
 example assumes a browser environment. OIDC discovery, login, refresh, and the corresponding
 `createFromOidc` inputs are exported from `@telecrypt-io/storage/core`.
 
+Applications that require the Decryption Key Safe before downloading room history can create the
+client with `startClient: false`. Check its status and restore room keys first; `restore()` starts
+sync after importing them so Matrix can publish this login's device keys and complete account
+signing. For an already-ready safe, call `await storage.startSync()` after the status check. Keep
+Storage operations locked until the Safe reports ready. The default is to start sync during
+creation.
+
 The example creates retained Matrix rooms and encrypted media. Delete its file and then its empty
 vault when finished; cleanup is part of the operation, not an automatic consequence of stopping
 the client.
@@ -62,14 +69,41 @@ The SDK maps the file tree to Matrix primitives defined by MSC3089:
 Vault, folder, and file IDs are opaque Matrix room and event IDs. Names are display labels: two
 objects with the same name are still distinct, and a name is not an idempotency key.
 
+Vault and folder names, and file names, are stored in encrypted room messages. Matrix room names
+remain the generic `Encrypted storage`; file-listing state stores only an event pointer, and media
+uploads omit the original filename. Use the asynchronous operations in `@telecrypt-io/storage/core`
+to read names. The synchronous Matrix SDK tree helper cannot decrypt on demand and exposes a generic
+file label until an async operation resolves the name. This is a TeleCrypt metadata format: standard
+MSC3089 clients will not display the private names or understand these file indexes. SDK 0.8 starts
+this format without a reader or migration for trees written by older SDK versions; those old trees
+may be ignored or removed.
+
 File bytes are encrypted in the client before upload with Matrix attachment encryption (AES-CTR
 and a per-file key distributed through the room's Megolm session). The server stores encrypted
 media and Matrix events, but encryption does not hide all room, event, or other metadata from the
 server or users who can read the room.
 
-Recovery is explicit. Use `core.setupRecovery(storage)` to create a recovery key and keep that key
-securely; use `core.restoreRecovery(storage, recoveryKey)` on a new device. Losing the recovery key
-can prevent encrypted keys from being restored.
+The Decryption Key Safe is mandatory before the public core storage operations. Inspect
+`storage.keySafe.getStatus(signal?)`. For `setup-required`, call `setup(signal?)`, offer the returned
+`recoveryKey` for copying/saving, explain that losing both this key and local decryption keys can
+make files permanently unreadable, and require an explicit saved-key acknowledgement before
+`confirmSaved(signal?)`. `confirmation-required` returns the same pending key after interruption.
+For `restore-required`, call `restore(recoveryKey, signal?)` with the existing key; this restores
+room keys and signs the current login using the existing account keys. Normal use requires `ready`.
+Setup and restore never replace an existing safe or account signing identity. Resetting the account
+password cannot recover encrypted files.
+
+Pending setup state is kept beside the login's IndexedDB crypto data. A platform that snapshots
+IndexedDB to disk, such as the CLI, must supply `onKeySafeStateChanged` at creation and durably flush
+its snapshot before resolving that callback. Key Safe methods accept an optional `AbortSignal`.
+The safe, signing keys, and saved-key acknowledgement are shared SDK behavior rather than separate
+Web/CLI implementations.
+
+Sharing uses Matrix's native encrypted-history bundle exchange. Both users must have completed
+their account signing setup. An invitation alone does not establish successful history sharing:
+the SDK checks native recipient-device eligibility afterward and reports partial completion if
+keys could not be shared. An upload restriction can reject the encrypted history bundle upload;
+the error is preserved, including when retrying an existing invitation.
 
 Deletion has strict ordering. Delete files before their folders or vaults because folders and
 vaults must be empty. File deletion removes the encrypted media object before redacting its Matrix

package/dist/TeleCryptIOStorage.d.ts

@@ -2,6 +2,7 @@ import { MatrixClient, MatrixEvent } from "matrix-js-sdk";
 import type { CryptoCallbacks } from "matrix-js-sdk/lib/crypto-api/index.js";
 import type { TokenRefreshFunction } from "matrix-js-sdk/lib/http-api/index.js";
 import type { RecoveryStatus } from "./core/types.js";
+import { DecryptionKeySafe, type KeySafePersistenceOptions } from "./key-safe.js";
 export interface TreeSpace {
     readonly id: string;
     readonly room: {
@@ -26,8 +27,9 @@ export interface TreeSpace {
 }
 export interface FileBranch {
     readonly id: string;
+    readonly roomId: string;
     /** Current MSC3089 branch/listing event. Its event ID is distinct from `id` (the state key). */
-    readonly indexEvent?: Pick<MatrixEvent, "getId">;
+    readonly indexEvent?: Pick<MatrixEvent, "getId" | "getContent" | "getSender" | "isRedacted">;
     /** Matrix SDK keeps a redacted branch in state as an inactive object. */
     readonly isActive?: boolean;
     getName(): string;
@@ -63,8 +65,12 @@ export interface CreateTeleCryptIOStorageOptions {
      * Node/tests, where `fake-indexeddb` is process-global).
      */
     cryptoDatabasePrefix?: string;
+    /** Persist local Key Safe state before server-side setup continues (CLI snapshots). */
+    onKeySafeStateChanged?: () => Promise<void>;
     /** initialSyncLimit passed to startClient(); default 10. */
     initialSyncLimit?: number;
+    /** Start Matrix sync after crypto initializes; default true. */
+    startClient?: boolean;
     /** How long to wait for the first sync before giving up; default 15000ms. */
     syncTimeoutMs?: number;
     /** How long to wait for rust-crypto WASM + IndexedDB init; default 60000ms. */
@@ -106,7 +112,10 @@ export interface CreateFromOidcOptions {
     tokenRefreshFunction?: TokenRefreshFunction;
     persistentCryptoStore?: boolean;
     cryptoDatabasePrefix?: string;
+    /** Persist local Key Safe state before server-side setup continues (CLI snapshots). */
+    onKeySafeStateChanged?: () => Promise<void>;
     initialSyncLimit?: number;
+    startClient?: boolean;
     syncTimeoutMs?: number;
     initTimeoutMs?: number;
     onProgress?: (message: string) => void;
@@ -143,10 +152,40 @@ export declare function readFileEventMetadata(content: unknown): FileEventMetada
 export declare function withTreeMutation<T>(client: MatrixClient, operation: (signal?: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<T>;
 export declare class TeleCryptIOStorage {
     private client;
+    private readonly syncOptions;
     private readonly decoratedTreeSpaces;
-    constructor(client: MatrixClient);
+    private readonly decoratedFileBranches;
+    private readonly treeNames;
+    private readonly fileNames;
+    readonly keySafe: DecryptionKeySafe;
+    private syncStarted;
+    private syncInFlight;
+    constructor(client: MatrixClient, options?: KeySafePersistenceOptions, syncOptions?: Pick<CreateTeleCryptIOStorageOptions, "initialSyncLimit" | "syncTimeoutMs" | "onProgress">);
     /** The underlying matrix-js-sdk client (e.g. to stop it, or for advanced/interop use). */
     getClient(): MatrixClient;
+    /** Start Matrix room sync after crypto setup, for example after the current
+     * login has checked or restored its Decryption Key Safe. */
+    startSync(signal?: AbortSignal): Promise<void>;
+    private fileNameKey;
+    private getStateEvent;
+    private getTreeOwnerId;
+    private sendEncryptedMetadataMessage;
+    private readEncryptedMetadataMessage;
+    private writeTreeName;
+    /** Resolves an encrypted vault/folder name through its pointer state event. */
+    getTreeName(roomId: string, options?: MatrixRequestOptions): Promise<string>;
+    private writeFileName;
+    /** Resolves an encrypted file name from the MSC3089 index pointer. */
+    getFileName(treeId: string, fileId: string, options?: MatrixRequestOptions & {
+        refreshState?: boolean;
+    }): Promise<string>;
+    /** Returns the current file metadata pointer, including on inactive branches. */
+    getFileMetadataEventId(treeId: string, fileId: string, options?: MatrixRequestOptions): Promise<string | null>;
+    /** Fetches and validates a current encrypted rename event, allowing retries after redaction. */
+    getFileRenameMetadataEvent(treeId: string, fileId: string, metadataEventId: string): Promise<MatrixEvent>;
+    /** Fetches the original encrypted file message directly by event ID. */
+    getOriginalFileEvent(treeId: string, fileId: string, allowRedacted?: boolean): Promise<MatrixEvent>;
+    private createEncryptedFile;
     /**
      * Refreshes a room's current state from the homeserver. The background sync
      * loop is intentionally asynchronous, so a short-lived CLI process can
@@ -177,7 +216,7 @@ export declare class TeleCryptIOStorage {
     */
     static createFromOidc(opts: CreateFromOidcOptions): Promise<TeleCryptIOStorage>;
     /** Shared post-construction bootstrap for `create()`/`createFromOidc()`:
-     * persistent crypto store, first sync, wrap in a `TeleCryptIOStorage`. */
+     * persistent crypto store, optional first sync, wrap in a `TeleCryptIOStorage`. */
     private static bootstrap;
     private static throwIfAborted;
     private static withTimeout;
@@ -249,6 +288,7 @@ export declare class TeleCryptIOStorage {
      * which refreshes the exact parent/child state before reporting success.
      */
     private decorateTreeSpace;
+    private decorateFileBranch;
     /** Cleans up only a room created by this operation and reports incomplete cleanup. */
     private cleanupCreatedRoom;
     private removeRelationLink;