@telecrypt-io/storage 0.8.0 → 0.9.2

package/LICENSE

@@ -2,7 +2,7 @@ Business Source License 1.1
 
 Parameters
 
-Licensor:              TeleCrypt.io
+Licensor:              Alexander Potemkin
 Licensed Work:         TeleCrypt.io Storage
                         The Licensed Work is (c) 2026 TeleCrypt.io
 Additional Use Grant:  You may use, copy, modify, and create derivative

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.
@@ -76,9 +83,56 @@ and a per-file key distributed through the room's Megolm session). The server st
 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.
+If an upload is rejected after media was accepted, the SDK removes that media and any acknowledged
+attachment. A transport failure leaves accepted work intact. An upload `MutationPartialError`
+retains `treeId` and `completedIds` in the order `[mediaId, attachmentEventId?]`. Keep those IDs;
+do not repeat the upload blindly. To discard the partial upload, call
+`core.cleanupFileUpload(storage, error.treeId, error.completedIds[0], error.completedIds[1])`.
+Retry cleanup with the same IDs if it fails. A known attachment ID can also be passed to ordinary
+`core.deleteFile` even when its listing was never committed. An initial media response lost before
+the server returns any identifier still has an unknown outcome and cannot provide cleanup IDs.
+Upload cancellation stops before the next write and waits for the current request's bounded
+settlement so returned media/event IDs are retained. Keep observing the upload promise after
+cancelling a UI wait or closing a view; persist any partial receipt for the originating account.
+
+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.
+
+Short-lived clients should call `storage.waitForKeyBackup(treeId, fileId?, options?)` after creating
+or renaming encrypted metadata and before closing. Omit `fileId` for a vault or folder. This checks
+the exact encryption session in the active server backup, including reused keys that produce no
+new backup-progress event. If verification fails, retain the local profile and retry backup;
+the metadata mutation has already committed.
+
+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.
+
+`joinVault` accepts the vault and its linked folder invitations, including their history keys.
+New folders inherit the parent's joined and invited readers; browsing accepts their folder
+invitations. If reader access fails after folder creation, the partial-completion error retains
+the created folder ID. Retry sharing the parent vault to complete access to that folder.
+
+Storage spaces are private and only their creator changes room state. Loading owned trees or
+refreshing their state repairs the permissive defaults emitted by older SDKs and restores
+invite-only joining. The repair preserves membership, unrelated power settings and encryption
+keys; readers do not write it. Owners must use an updated client for their existing trees to be
+repaired. Disabled Storage markers and deleted trees are not restored automatically.
 
 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: {
@@ -20,7 +21,7 @@ export interface TreeSpace {
     setPermissions(userId: string, role: string): Promise<void>;
     getFile(fileEventId: string): FileBranch | null;
     listFiles(): FileBranch[];
-    createFile(name: string, encryptedContents: ArrayBuffer | Uint8Array, info: Record<string, unknown>, additionalContent?: Record<string, unknown>): Promise<{
+    createFile(name: string, encryptedContents: ArrayBuffer | Uint8Array, info: Record<string, unknown>, additionalContent?: Record<string, unknown>, signal?: AbortSignal): Promise<{
         event_id: string;
     }>;
 }
@@ -64,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. */
@@ -107,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;
@@ -144,21 +152,35 @@ 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;
     private readonly decoratedFileBranches;
     private readonly treeNames;
     private readonly fileNames;
-    constructor(client: MatrixClient);
+    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;
+    private getTreeMetadataEvent;
     /** Resolves an encrypted vault/folder name through its pointer state event. */
     getTreeName(roomId: string, options?: MatrixRequestOptions): Promise<string>;
+    /**
+     * Waits for the current encrypted vault/folder name, or file metadata, to
+     * have its session in the active native key backup. Checks the exact session
+     * even when encryption reuses a key and the backup engine emits no new event.
+     */
+    waitForKeyBackup(treeId: string, fileId?: string, options?: MatrixRequestOptions): Promise<void>;
     private writeFileName;
     /** Resolves an encrypted file name from the MSC3089 index pointer. */
     getFileName(treeId: string, fileId: string, options?: MatrixRequestOptions & {
@@ -171,6 +193,12 @@ export declare class TeleCryptIOStorage {
     /** Fetches the original encrypted file message directly by event ID. */
     getOriginalFileEvent(treeId: string, fileId: string, allowRedacted?: boolean): Promise<MatrixEvent>;
     private createEncryptedFile;
+    /**
+     * Discards a partial upload using its MutationPartialError.completedIds:
+     * [mediaId, fileId?]. Explicit cleanup also covers an unacknowledged listing.
+     * Keep the same IDs after failure and retry this operation, not the upload.
+     */
+    cleanupFileUpload(treeId: string, mediaId: string, fileId?: string, options?: MatrixRequestOptions): Promise<void>;
     /**
      * Refreshes a room's current state from the homeserver. The background sync
      * loop is intentionally asynchronous, so a short-lived CLI process can
@@ -178,6 +206,7 @@ export declare class TeleCryptIOStorage {
      * changed a file name or branch.
      */
     refreshRoomState(roomId: string, options?: MatrixRequestOptions): Promise<void>;
+    private repairOwnedTreePermissions;
     /**
      * Recommended entry point: builds the MatrixClient with a persistent crypto
      * store and the secret-storage callback wiring `keys.*` needs, starts the
@@ -201,7 +230,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;