@telecrypt-io/storage 0.9.0 → 0.9.3

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

@@ -12,6 +12,9 @@ unmerged Matrix proposal.
 npm install @telecrypt-io/storage
 ```
 
+The SDK supports Node.js `24.21.0` as its exact engine version. Its release tooling uses the
+bundled npm `11.19.0`.
+
 ## Browser quick start
 
 The example below starts with an authenticated OIDC session. Obtain `userId`, `accessToken`, and
@@ -83,6 +86,18 @@ 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.
 
+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
@@ -93,6 +108,12 @@ room keys and signs the current login using the existing account keys. Normal us
 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`.
@@ -105,6 +126,17 @@ the SDK checks native recipient-device eligibility afterward and reports partial
 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
 event and requires TeleCrypt's Synapse storage extension; stock Synapse cannot provide that

package/dist/TeleCryptIOStorage.d.ts

@@ -21,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;
     }>;
 }
@@ -170,10 +170,18 @@ export declare class TeleCryptIOStorage {
     private getStateEvent;
     private getTreeOwnerId;
     private sendEncryptedMetadataMessage;
+    private requireEncryptedStorageRoom;
     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 & {
@@ -186,6 +194,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
@@ -193,6 +207,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