@telecrypt-io/storage 0.8.0 → 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.
@@ -76,9 +83,27 @@ 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.
+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: {
@@ -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,13 +152,20 @@ 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;
@@ -201,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;

package/dist/TeleCryptIOStorage.js

@@ -9,6 +9,7 @@ import { cancelResponseBody, raceWithAbort, readMediaResponseBody, readResponseB
 import { sanitizeDiagnosticText } from "./core/oidc.js";
 import { validateName } from "./core/validation.js";
 import { isTreeDeleted } from "./deletion-markers.js";
+import { DecryptionKeySafe } from "./key-safe.js";
 const STORAGE_METADATA_EVENT_TYPE = "io.telecrypt.storage.metadata";
 const STORAGE_METADATA_MSGTYPE = "io.telecrypt.storage.metadata";
 const GENERIC_TREE_NAME = "Encrypted storage";
@@ -406,12 +407,18 @@ export async function withTreeMutation(client, operation, signal) {
 }
 export class TeleCryptIOStorage {
     client;
+    syncOptions;
     decoratedTreeSpaces = new WeakSet();
     decoratedFileBranches = new WeakMap();
     treeNames = new Map();
     fileNames = new Map();
-    constructor(client) {
+    keySafe;
+    syncStarted = false;
+    syncInFlight;
+    constructor(client, options = {}, syncOptions = {}) {
         this.client = client;
+        this.syncOptions = syncOptions;
+        this.keySafe = new DecryptionKeySafe(client, (key, operation, signal) => this.withSecretStorageKey(key, operation, signal), options, (signal) => this.startSync(signal));
         // Advanced callers may construct a MatrixClient themselves. The SDK does
         // not mutate matrix-js-sdk internals: configure that client with the
         // supported createClient({ fetchFn, localTimeoutMs }) options, or use
@@ -421,6 +428,41 @@ export class TeleCryptIOStorage {
     getClient() {
         return this.client;
     }
+    /** Start Matrix room sync after crypto setup, for example after the current
+     * login has checked or restored its Decryption Key Safe. */
+    async startSync(signal) {
+        if (this.syncStarted)
+            return;
+        if (this.syncInFlight)
+            return this.syncInFlight;
+        const start = (async () => {
+            try {
+                TeleCryptIOStorage.throwIfAborted(signal);
+                const timeoutMs = this.syncOptions.syncTimeoutMs ?? 15000;
+                this.syncOptions.onProgress?.("Starting Matrix client…");
+                await TeleCryptIOStorage.withTimeout(this.client.startClient({ initialSyncLimit: this.syncOptions.initialSyncLimit ?? 10 }), timeoutMs, "client start", signal);
+                this.syncOptions.onProgress?.("Waiting for first sync with homeserver…");
+                await TeleCryptIOStorage.waitForFirstSync(this.client, timeoutMs, signal);
+                TeleCryptIOStorage.throwIfAborted(signal);
+                this.syncStarted = true;
+                this.syncOptions.onProgress?.("Sync complete.");
+            }
+            catch (error) {
+                try {
+                    this.client.stopClient();
+                }
+                catch (stopError) {
+                    throw new AggregateError([error, stopError], "Matrix sync startup and cleanup failed");
+                }
+                throw error;
+            }
+            finally {
+                this.syncInFlight = undefined;
+            }
+        })();
+        this.syncInFlight = start;
+        return start;
+    }
     fileNameKey(treeId, fileId) {
         return `${treeId}\u0000${fileId}`;
     }
@@ -747,10 +789,11 @@ export class TeleCryptIOStorage {
         return TeleCryptIOStorage.bootstrap(client, opts);
     }
     /** 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`. */
     static async bootstrap(client, opts) {
         const progress = opts.onProgress ?? (() => { });
         const persistent = opts.persistentCryptoStore ?? true;
+        let storage;
         try {
             progress("Loading encryption engine (WASM)…");
             await TeleCryptIOStorage.withTimeout(client.initRustCrypto({
@@ -758,27 +801,35 @@ export class TeleCryptIOStorage {
                 cryptoDatabasePrefix: opts.cryptoDatabasePrefix ?? `telecrypt-io-storage::${opts.userId}::${opts.deviceId}`,
             }), opts.initTimeoutMs ?? 60000, "crypto init", opts.signal);
             progress("Encryption ready — opening secure store…");
-            progress("Starting Matrix client…");
-            // Mark this before awaiting: startClient can start its sync loop and then
-            // reject while reporting an error from the initial request.
-            await TeleCryptIOStorage.withTimeout(client.startClient({ initialSyncLimit: opts.initialSyncLimit ?? 10 }), opts.syncTimeoutMs ?? 15000, "client start", opts.signal);
-            progress("Waiting for first sync with homeserver…");
-            await TeleCryptIOStorage.waitForFirstSync(client, opts.syncTimeoutMs ?? 15000, opts.signal);
-            TeleCryptIOStorage.throwIfAborted(opts.signal);
-            progress("Sync complete.");
-            return new TeleCryptIOStorage(client);
+            storage = new TeleCryptIOStorage(client, opts, opts);
+            if (opts.startClient === false) {
+                // Rust Crypto starts checking server-side backup state during init. A
+                // short-lived caller (the CLI login transaction) may close this
+                // client before that background check finishes, so drain it before
+                // returning the sync-deferred client.
+                const crypto = client.getCrypto();
+                if (crypto) {
+                    await TeleCryptIOStorage.withTimeout(crypto.checkKeyBackupAndEnable(), opts.syncTimeoutMs ?? 15000, "crypto backup check", opts.signal);
+                }
+            }
+            else {
+                await storage.startSync(opts.signal);
+            }
+            return storage;
         }
         catch (error) {
             // stopClient is idempotent in matrix-js-sdk and is also required after
             // init/timeout failures: crypto startup can have installed listeners or
             // a sync task before the awaited operation rejects.
-            try {
-                client.stopClient();
-            }
-            catch (cleanupError) {
-                throw new AggregateError([error, cleanupError], "storage bootstrap and client cleanup failed", {
-                    cause: error,
-                });
+            if (!storage) {
+                try {
+                    client.stopClient();
+                }
+                catch (cleanupError) {
+                    throw new AggregateError([error, cleanupError], "storage bootstrap and client cleanup failed", {
+                        cause: error,
+                    });
+                }
             }
             throw error;
         }
@@ -992,12 +1043,7 @@ export class TeleCryptIOStorage {
         if (signal?.aborted)
             throw new StorageError("operation cancelled");
         try {
-            await withRecoveryCryptoDeadline(() => crypto.bootstrapCrossSigning({
-                // No existing verified device to interactively re-authenticate against
-                // for this account, so there is nothing to feed into `makeRequest`;
-                // matches the working pattern already proven in keys.test.ts.
-                authUploadDeviceSigningKeys: async () => undefined,
-            }), signal, "cross-signing bootstrap");
+            await withRecoveryCryptoDeadline(() => crypto.bootstrapCrossSigning({}), signal, "cross-signing bootstrap");
         }
         catch (error) {
             // Cross-signing setup can commit server-side state before a transport

package/dist/core/operations.js

@@ -303,7 +303,8 @@ function isActiveRelationEvent(event) {
         !Array.isArray(content) &&
         Object.keys(content).length > 0);
 }
-function activeTreeDirectories(client, tree) {
+async function activeTreeDirectories(storage, tree, signal) {
+    const client = storage.getClient();
     const childEvents = readRelationEvents(client, tree.id, EventType.SpaceChild);
     if (childEvents === null)
         throw new StorageError("storage folder state is unavailable");
@@ -316,13 +317,26 @@ function activeTreeDirectories(client, tree) {
             throw new StorageError("storage folder state is inconsistent");
         activeChildIds.add(childId);
     }
-    const knownChildren = new Map(tree.getDirectories().map((child) => [child.id, child]));
-    return [...activeChildIds].map((childId) => {
-        const child = knownChildren.get(childId);
-        if (!child)
-            throw new StorageError("storage folder state is inconsistent");
-        return child;
-    });
+    const directories = await Promise.all([...activeChildIds].map(async (childId) => {
+        if (isMarkedTreeDeleted(storage, childId))
+            return null;
+        try {
+            // The parent room's relationship state can arrive before Matrix SDK's
+            // MSC3089 TreeSpace projection includes that child. Resolve the exact
+            // room named by the active relation instead of treating that brief
+            // projection lag as corrupt folder state.
+            return await waitForCondition(() => storage.getTree(childId), { timeoutMs: 15000, signal });
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new StorageError("operation cancelled");
+            if (error instanceof ConditionTimeoutError) {
+                throw new StorageError("storage folder state is inconsistent");
+            }
+            throw new StorageError("storage folder state lookup failed", { cause: error });
+        }
+    }));
+    return directories.filter((directory) => directory !== null);
 }
 async function unlinkExternalParents(storage, rootId, externalParents, signal) {
     const client = storage.getClient();
@@ -479,9 +493,6 @@ async function deleteRoomDeterministically(storage, roomId, signal) {
 function removeRoomFromLocalStore(client, roomId) {
     client.store?.removeRoom(roomId);
 }
-function isActiveMembership(membership) {
-    return membership === "join" || membership === "invite";
-}
 function isRevocableMembership(membership) {
     return membership === "join" || membership === "invite" || membership === "knock";
 }
@@ -497,6 +508,7 @@ function toArrayBuffer(bytes) {
     return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
 }
 export async function createVault(storage, name, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         let tree;
         try {
@@ -516,6 +528,7 @@ export async function createVault(storage, name, options) {
 }
 /** Top-level vaults only — excludes subdirectories of an existing tree. */
 export async function listVaults(storage, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const trees = await storage.listTrees(signal);
         const topLevel = trees.filter((tree) => tree.isTopLevel);
@@ -534,6 +547,7 @@ export function getMyVaultRole(storage, vaultId) {
     return tree.getPermissions(userId);
 }
 export async function joinVault(storage, vaultId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         let membership;
         try {
@@ -555,8 +569,27 @@ export async function joinVault(storage, vaultId, options) {
         }
         if (membership === "join")
             return { vaultId, joined: true };
+        const client = storage.getClient();
+        const userId = client.getUserId();
+        if (userId && client.getRoom(vaultId)?.getMember(userId)?.membership !== "invite") {
+            // MatrixClient.joinRoom reads the inviter from its local invite-room
+            // state. A to-device history bundle can arrive first in the initial
+            // sync, before that stripped invite state has reached the room store;
+            // joining without it skips Matrix JS SDK's pending-bundle acceptance.
+            try {
+                await waitForCondition(() => client.getRoom(vaultId)?.getMember(userId)?.membership === "invite" ? true : null, { timeoutMs: 15000, signal });
+            }
+            catch (err) {
+                if (signal.aborted)
+                    throw new StorageError("operation cancelled");
+                if (err instanceof ConditionTimeoutError) {
+                    throw new StorageError("the room invitation has not reached this login yet; retry joining", { cause: err });
+                }
+                throw err;
+            }
+        }
         try {
-            await withRateLimitRetry(() => withMatrixMutationAbort(() => storage.getClient().joinRoom(vaultId), signal), signal);
+            await withRateLimitRetry(() => withMatrixMutationAbort(() => client.joinRoom(vaultId), signal), signal);
         }
         catch (err) {
             if (err instanceof MutationOutcomeUnknownError)
@@ -592,6 +625,7 @@ function isReviewedStorageTreeRoom(room) {
 }
 /** Rooms where this account is invited and the room looks like a file tree. */
 export async function listPendingInvites(storage, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const client = storage.getClient();
         const rooms = client.getRooms();
@@ -628,6 +662,7 @@ export async function listPendingInvites(storage, options) {
 }
 /** Decline a vault invite (same as leaving before join). */
 export async function declineInvite(storage, vaultId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const client = storage.getClient();
         try {
@@ -721,6 +756,7 @@ export async function declineInvite(storage, vaultId, options) {
 }
 /** Invites `userId` to the vault as a reader. */
 export async function shareVault(storage, vaultId, userId, role, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     if (role !== "viewer") {
         throw new StorageError("storage sharing supports viewers only");
     }
@@ -743,6 +779,15 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                 if (currentMembers.some((member) => member.userId === userId && member.role === "owner")) {
                     throw new StorageError("share will not demote an existing owner");
                 }
+                const client = storage.getClient();
+                const crypto = client.getCrypto();
+                if (!crypto)
+                    throw new StorageError("sharing requires initialized encryption");
+                const recipient = await client.downloadKeysForUsers([userId]);
+                const devices = Object.keys(recipient.device_keys?.[userId] ?? {});
+                if (!recipient.master_keys?.[userId] || !recipient.self_signing_keys?.[userId] || devices.length === 0) {
+                    throw new StorageError("The reader must set up or unlock their Decryption Key Safe before sharing");
+                }
                 for (const [index, space] of spaces.entries()) {
                     ensureOperationActive(operation.signal);
                     const members = index === 0
@@ -756,28 +801,21 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                         : await storage.getRoomMembership(space.id, userId, {
                             signal: operation.signal,
                         });
-                    if (isActiveMembership(currentMembership ?? ""))
+                    if (currentMembership === "join")
                         continue;
-                    try {
-                        await withRateLimitRetry(() => withMatrixMutationAbort(() => space.invite(userId), operation.signal), operation.signal);
-                        completedRoomIds.add(space.id);
-                    }
-                    catch (error) {
-                        if (!(error instanceof MatrixError) || error.errcode !== "M_FORBIDDEN")
-                            throw error;
-                        // Synapse may race another invite/join and answer M_FORBIDDEN. Only
-                        // suppress that typed condition after re-reading authoritative
-                        // membership; never infer it from provider-controlled error text.
-                        const membership = await storage.getRoomMembership(space.id, userId, {
-                            signal: operation.signal,
-                        });
-                        if (!isActiveMembership(membership ?? ""))
-                            throw new StorageError("share failed");
+                    // Native invite shares the encrypted history before inviting. Retry
+                    // pending invitations too: an earlier attempt may have sent only an
+                    // invitation. In particular, never swallow a media-upload 403 merely
+                    // because an invitation already exists.
+                    await withRateLimitRetry(() => withMatrixMutationAbort(() => space.invite(userId), operation.signal), operation.signal);
+                    completedRoomIds.add(space.id);
+                    const statuses = await Promise.all(devices.map((id) => crypto.getDeviceVerificationStatus(userId, id)));
+                    if (!statuses.some((status) => status?.signedByOwner)) {
+                        throw new StorageError("The invitation was sent, but history keys could not be shared; the reader must unlock their Decryption Key Safe, then retry sharing");
                     }
                 }
                 // Storage rooms have one immutable owner power level and readers use
-                // the room's default user level. Inviting is the complete sharing
-                // operation; changing per-user power levels would create editors and
+                // the room's default user level. Changing per-user power levels would create editors and
                 // let metadata authorship drift away from the owner.
             }
             catch (error) {
@@ -790,6 +828,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                     (error.message === "share failed" ||
                         error.message.includes("owner") ||
                         error.message.includes("current user") ||
+                        error.message.includes("Decryption Key Safe") ||
                         error.message === "operation cancelled")) {
                     throw error;
                 }
@@ -804,6 +843,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
     }
 }
 export async function unshareVault(storage, vaultId, userId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     const operation = createOperationDeadline(options);
     const completedRoomIds = new Set();
     try {
@@ -878,6 +918,7 @@ export async function unshareVault(storage, vaultId, userId, options) {
     }
 }
 export async function listMembers(storage, vaultId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, vaultId, signal);
         try {
@@ -891,6 +932,7 @@ export async function listMembers(storage, vaultId, options) {
     });
 }
 export async function listFiles(storage, treeId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, treeId, signal);
         try {
@@ -913,11 +955,12 @@ export async function listFiles(storage, treeId, options) {
 }
 /** Lists the direct child folders of a vault or folder. */
 export async function listSubfolders(storage, parentId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, parentId, signal);
         await storage.refreshRoomState(parentId, { signal });
         ensureOperationActive(signal);
-        const directories = activeTreeDirectories(storage.getClient(), tree)
+        const directories = (await activeTreeDirectories(storage, tree, signal))
             .filter((directory) => !isMarkedTreeDeleted(storage, directory.id));
         return Promise.all(directories.map(async (directory) => ({
             id: directory.id,
@@ -926,6 +969,7 @@ export async function listSubfolders(storage, parentId, options) {
     });
 }
 export async function createSubfolder(storage, parentId, name, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     validateName(name, "name");
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, parentId, signal);
@@ -971,10 +1015,12 @@ async function renameTree(storage, treeId, name, options) {
 }
 /** Renames a top-level Vault. */
 export async function renameVault(storage, vaultId, name, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return renameTree(storage, vaultId, name, options);
 }
 /** Renames a nested folder. */
 export async function renameFolder(storage, folderId, name, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return renameTree(storage, folderId, name, options);
 }
 async function deleteTree(storage, treeId, options) {
@@ -1038,13 +1084,16 @@ async function deleteTree(storage, treeId, options) {
 }
 /** Deletes a top-level Vault. */
 export async function deleteVault(storage, vaultId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return deleteTree(storage, vaultId, options);
 }
 /** Deletes a nested folder. */
 export async function deleteFolder(storage, folderId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return deleteTree(storage, folderId, options);
 }
 export async function renameFile(storage, treeId, fileId, name, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     validateName(name, "file name");
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, treeId, signal);
@@ -1094,6 +1143,7 @@ async function deleteFileMedia(storage, mediaIds, signal) {
     }
 }
 export async function deleteFile(storage, treeId, fileId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, treeId, signal);
         if (isMarkedFileDeleted(storage, tree.id, fileId))
@@ -1184,6 +1234,7 @@ export async function deleteFile(storage, treeId, fileId, options) {
     }, "mutation");
 }
 export async function uploadFile(storage, treeId, name, bytes, mimetype, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, treeId, signal);
         const fileId = await withRateLimitRetry(() => storage.uploadFile(tree, name, toArrayBuffer(bytes), mimetype, signal), signal).catch((error) => {
@@ -1219,6 +1270,7 @@ export async function uploadFile(storage, treeId, name, bytes, mimetype, options
     }, "mutation");
 }
 export async function downloadFile(storage, treeId, fileId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, treeId, signal);
         const branch = await resolveFile(storage, tree, fileId, signal);
@@ -1253,6 +1305,7 @@ function tsToIso(ts) {
     return new Date(ts).toISOString();
 }
 export async function getFileDetails(storage, treeId, fileId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, async (signal) => {
         const tree = await resolveTree(storage, treeId, signal);
         await resolveFile(storage, tree, fileId, signal);
@@ -1308,9 +1361,11 @@ async function getTreeDetails(storage, treeId, signal) {
 }
 /** Returns details for a top-level Vault. */
 export async function getVaultDetails(storage, vaultId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, (signal) => getTreeDetails(storage, vaultId, signal));
 }
 /** Returns details for a nested folder. */
 export async function getFolderDetails(storage, folderId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
     return withOperationDeadline(options, (signal) => getTreeDetails(storage, folderId, signal));
 }

package/dist/core/types.d.ts

@@ -87,3 +87,4 @@ export interface FolderDetails {
     createdAt: string | null;
     memberCount: number | null;
 }
+export type { KeySafeStatus, KeySafeOptions } from "../key-safe.js";

package/dist/key-safe.d.ts

@@ -0,0 +1,62 @@
+import { type MatrixClient } from "matrix-js-sdk";
+export interface KeySafeOptions {
+    signal?: AbortSignal;
+}
+export interface KeySafeStatus {
+    state: "setup-required" | "confirmation-required" | "restore-required" | "ready";
+    recoveryKey?: string;
+}
+export interface KeySafePersistenceOptions {
+    persistentCryptoStore?: boolean;
+    cryptoDatabasePrefix?: string;
+    /** Flush platform crypto persistence before continuing a setup mutation. */
+    onKeySafeStateChanged?: () => Promise<void>;
+}
+type WithKey = <T>(key: Uint8Array<ArrayBuffer>, fn: () => Promise<T>, signal?: AbortSignal) => Promise<T>;
+/** The local saved-key acknowledgement and Matrix's existing encryption setup. */
+export declare class DecryptionKeySafe {
+    private client;
+    private withKey;
+    private options;
+    private startSync?;
+    private memory;
+    private tail;
+    private secretRecordsRefreshed;
+    private refreshedKeyDescriptorId;
+    constructor(client: MatrixClient, withKey: WithKey, options?: KeySafePersistenceOptions, startSync?: ((signal?: AbortSignal) => Promise<void>) | undefined);
+    private active;
+    private crypto;
+    private local;
+    private save;
+    private serial;
+    private refreshAccountData;
+    /**
+     * MatrixClient.getAccountDataFromServer reads its local store after initial
+     * sync. A resumed sync can complete before account-data events reach that
+     * store, so refresh the existing Safe records from the authenticated server
+     * API before native secret-storage code reads them. Seed those exact records
+     * through the public Store API used by Matrix sync itself.
+     */
+    private refreshSecretStorageAccountData;
+    private topology;
+    private serverBackup;
+    private signingReady;
+    getStatus(signal?: AbortSignal): Promise<KeySafeStatus>;
+    requireReady(options?: KeySafeOptions): Promise<void>;
+    /** Re-publish the same native signed records after an interrupted upload. */
+    private publishSigning;
+    private checkSigningCanResume;
+    private configure;
+    setup(signal?: AbortSignal): Promise<{
+        recoveryKey: string;
+    }>;
+    confirmSaved(signal?: AbortSignal): Promise<{
+        state: "ready";
+    }>;
+    restore(recoveryKey: string, signal?: AbortSignal): Promise<{
+        imported: number;
+        total: number;
+        state: "ready";
+    }>;
+}
+export {};

package/dist/key-safe.js

@@ -0,0 +1,349 @@
+import { MatrixError, MatrixEvent } from "matrix-js-sdk";
+import { Method } from "matrix-js-sdk/lib/http-api/method.js";
+import { ClientPrefix } from "matrix-js-sdk/lib/http-api/prefix.js";
+import { decodeRecoveryKey } from "matrix-js-sdk/lib/crypto-api/recovery-key.js";
+import { encodeUri } from "matrix-js-sdk/lib/utils.js";
+import { StorageError } from "./core/errors.js";
+/** The local saved-key acknowledgement and Matrix's existing encryption setup. */
+export class DecryptionKeySafe {
+    client;
+    withKey;
+    options;
+    startSync;
+    memory = {};
+    tail = Promise.resolve();
+    secretRecordsRefreshed = false;
+    refreshedKeyDescriptorId = null;
+    constructor(client, withKey, options = {}, startSync) {
+        this.client = client;
+        this.withKey = withKey;
+        this.options = options;
+        this.startSync = startSync;
+    }
+    active(signal) {
+        if (signal?.aborted)
+            throw new StorageError("operation cancelled");
+    }
+    crypto() {
+        const crypto = this.client.getCrypto();
+        if (!crypto)
+            throw new StorageError("encryption is not initialized");
+        return crypto;
+    }
+    async local(write) {
+        if (this.options.persistentCryptoStore === false) {
+            if (write)
+                this.memory = write;
+            return this.memory;
+        }
+        const prefix = this.options.cryptoDatabasePrefix ?? `telecrypt-io-storage::${this.client.getUserId()}::${this.client.getDeviceId()}`;
+        const database = await new Promise((resolve, reject) => {
+            const request = indexedDB.open(`${prefix}::key-safe`, 1);
+            request.onupgradeneeded = () => request.result.createObjectStore("state");
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+        try {
+            return await new Promise((resolve, reject) => {
+                const transaction = database.transaction("state", write ? "readwrite" : "readonly");
+                const store = transaction.objectStore("state");
+                const request = write ? store.put(write, "setup") : store.get("setup");
+                transaction.oncomplete = () => resolve(write ?? request.result ?? {});
+                transaction.onerror = () => reject(transaction.error);
+                transaction.onabort = () => reject(transaction.error ?? new Error("key safe persistence aborted"));
+            });
+        }
+        finally {
+            database.close();
+        }
+    }
+    async save(value) {
+        const previous = await this.local();
+        await this.local(value);
+        try {
+            await this.options.onKeySafeStateChanged?.();
+        }
+        catch (error) {
+            await this.local(previous);
+            throw error;
+        }
+    }
+    serial(operation) {
+        const result = this.tail.then(operation);
+        this.tail = result.catch(() => undefined);
+        return result;
+    }
+    async refreshAccountData(type) {
+        const user = this.client.getUserId();
+        if (!user)
+            throw new StorageError("Matrix login is not initialized");
+        const path = encodeUri("/user/$userId/account_data/$type", { $userId: user, $type: type });
+        let content;
+        try {
+            content = await this.client.http.authedRequest(Method.Get, path, undefined, undefined, { prefix: ClientPrefix.V3 });
+        }
+        catch (error) {
+            if (!(error instanceof MatrixError) || error.errcode !== "M_NOT_FOUND")
+                throw error;
+            content = null;
+        }
+        // An absent account-data event is not itself an event to cache. In
+        // particular, MatrixEvent normalizes null content to {}, which would make
+        // SecretStorage treat an absent secret as malformed content.
+        if (content !== null) {
+            this.client.store.storeAccountDataEvents([new MatrixEvent({ type, sender: user, content })]);
+        }
+        return content;
+    }
+    /**
+     * MatrixClient.getAccountDataFromServer reads its local store after initial
+     * sync. A resumed sync can complete before account-data events reach that
+     * store, so refresh the existing Safe records from the authenticated server
+     * API before native secret-storage code reads them. Seed those exact records
+     * through the public Store API used by Matrix sync itself.
+     */
+    async refreshSecretStorageAccountData(force = false) {
+        const defaultKey = await this.refreshAccountData("m.secret_storage.default_key");
+        const keyId = typeof defaultKey?.key === "string" ? defaultKey.key : null;
+        if (keyId && (force || this.refreshedKeyDescriptorId !== keyId)) {
+            await this.refreshAccountData(`m.secret_storage.key.${keyId}`);
+            this.refreshedKeyDescriptorId = keyId;
+        }
+        if (force || !this.secretRecordsRefreshed) {
+            await Promise.all([
+                this.refreshAccountData("m.cross_signing.master"),
+                this.refreshAccountData("m.cross_signing.self_signing"),
+                this.refreshAccountData("m.cross_signing.user_signing"),
+                this.refreshAccountData("m.megolm_backup.v1"),
+            ]);
+            this.secretRecordsRefreshed = true;
+        }
+        return keyId;
+    }
+    async topology(forceAccountDataRefresh = false) {
+        const [defaultKeyId, backup] = await Promise.all([
+            this.refreshSecretStorageAccountData(forceAccountDataRefresh), this.serverBackup(),
+        ]);
+        const key = await this.client.secretStorage.getKey();
+        return { key, defaultKeyId, backup };
+    }
+    async serverBackup() {
+        // CryptoApi.getKeyBackupInfo caches absence and maps request failures to
+        // null. Neither can authorize creating a new server backup on retry.
+        try {
+            return await this.client.http.authedRequest(Method.Get, "/room_keys/version", undefined, undefined, { prefix: ClientPrefix.V3 });
+        }
+        catch (error) {
+            if (error instanceof MatrixError && error.errcode === "M_NOT_FOUND")
+                return null;
+            throw error;
+        }
+    }
+    async signingReady() {
+        const crypto = this.crypto();
+        const user = this.client.getUserId();
+        await crypto.userHasCrossSigningKeys(user, true);
+        const [account, device, ready] = await Promise.all([
+            crypto.getUserVerificationStatus(user),
+            crypto.getDeviceVerificationStatus(user, this.client.getDeviceId()),
+            crypto.isCrossSigningReady(),
+        ]);
+        return ready && account.isVerified() && device?.signedByOwner === true;
+    }
+    getStatus(signal) {
+        const options = { signal };
+        return this.serial(async () => {
+            this.active(options.signal);
+            const local = await this.local();
+            if (local.recoveryKey)
+                return { state: "confirmation-required", recoveryKey: local.recoveryKey };
+            const { key, defaultKeyId, backup } = await this.topology();
+            if (!key && !defaultKeyId && !backup)
+                return { state: "setup-required" };
+            if (local.confirmed && key?.[0] === local.keyId && backup?.version === local.backupVersion && await this.signingReady()) {
+                await this.crypto().checkKeyBackupAndEnable();
+                if (await this.crypto().getActiveSessionBackupVersion() === backup?.version) {
+                    this.active(options.signal);
+                    return { state: "ready" };
+                }
+            }
+            this.active(options.signal);
+            return { state: "restore-required" };
+        });
+    }
+    async requireReady(options = {}) {
+        const status = await this.getStatus(options.signal);
+        if (status.state !== "ready")
+            throw new StorageError("Set up or unlock the Decryption Key Safe before using storage");
+    }
+    /** Re-publish the same native signed records after an interrupted upload. */
+    async publishSigning(signal) {
+        const crypto = this.crypto();
+        const user = this.client.getUserId();
+        const cached = await crypto.getUserCrossSigningKeys(user);
+        const server = await this.client.downloadKeysForUsers([user]);
+        if (!cached?.master_key || !cached.self_signing_key || !cached.user_signing_key) {
+            throw new StorageError("account signing setup is incomplete; unlock the existing Decryption Key Safe");
+        }
+        for (const [remote, local] of [
+            [server.master_keys?.[user], cached.master_key],
+            [server.self_signing_keys?.[user], cached.self_signing_key],
+            [server.user_signing_keys?.[user], cached.user_signing_key],
+        ]) {
+            if (remote && JSON.stringify(remote.keys) !== JSON.stringify(local.keys)) {
+                throw new StorageError("account signing keys changed; unlock the existing Decryption Key Safe");
+            }
+        }
+        this.active(signal);
+        await this.client.http.authedRequest(Method.Post, "/keys/device_signing/upload", undefined, cached, { prefix: ClientPrefix.V3 });
+        this.active(signal);
+        await crypto.crossSignDevice(this.client.getDeviceId());
+        await crypto.userHasCrossSigningKeys(user, true);
+    }
+    async checkSigningCanResume() {
+        const user = this.client.getUserId();
+        const [cached, server, status] = await Promise.all([
+            this.crypto().getUserCrossSigningKeys(user),
+            this.client.downloadKeysForUsers([user]),
+            this.crypto().getCrossSigningStatus(),
+        ]);
+        // A new login may defer room sync until the Safe is restored. Ensure the
+        // Rust crypto store has the account's public signing keys before importing
+        // their private copies from secret storage; the HTTP download above alone
+        // does not populate that native identity cache.
+        await this.crypto().userHasCrossSigningKeys(user, true);
+        const remote = server.master_keys?.[user];
+        const hasPrivateKeys = Object.values(status.privateKeysCachedLocally).every(Boolean);
+        if (remote && !status.privateKeysInSecretStorage && !hasPrivateKeys) {
+            throw new StorageError("Use the existing account signing keys; automatic replacement is not allowed");
+        }
+        if (remote && hasPrivateKeys && cached?.master_key && JSON.stringify(remote.keys) !== JSON.stringify(cached.master_key.keys)) {
+            throw new StorageError("Account signing keys changed; this login must unlock the existing Decryption Key Safe");
+        }
+    }
+    async configure(encoded, signal) {
+        const crypto = this.crypto();
+        const privateKey = decodeRecoveryKey(encoded);
+        const { key, defaultKeyId, backup } = await this.topology(true);
+        if (!key && defaultKeyId)
+            throw new StorageError("The existing Decryption Key Safe is incomplete; it will not be replaced");
+        if (key && !(await this.client.secretStorage.checkKey(privateKey, key[1]))) {
+            throw new StorageError("This key does not unlock the existing Decryption Key Safe");
+        }
+        await this.withKey(privateKey, async () => {
+            await this.checkSigningCanResume();
+            this.active(signal);
+            // Establish the encrypted account-data store first. Native cross-signing
+            // then saves its private keys there BEFORE publishing public keys. This
+            // keeps a CLI crash between native requests recoverable with the pending
+            // saved key, even before its next IndexedDB snapshot reaches disk.
+            if (!key) {
+                await crypto.bootstrapSecretStorage({
+                    createSecretStorageKey: async () => ({ privateKey, encodedPrivateKey: encoded, keyInfo: {} }),
+                    setupNewKeyBackup: false,
+                });
+            }
+            this.active(signal);
+            // Omitting authUploadDeviceSigningKeys sends the real initial upload.
+            await crypto.bootstrapCrossSigning({});
+            await this.publishSigning(signal);
+            this.active(signal);
+            await crypto.bootstrapSecretStorage({
+                createSecretStorageKey: async () => ({ privateKey, encodedPrivateKey: encoded, keyInfo: {} }),
+                setupNewKeyBackup: backup === null,
+            });
+            this.active(signal);
+            await crypto.loadSessionBackupPrivateKeyFromSecretStorage();
+            await crypto.checkKeyBackupAndEnable();
+            if (!(await this.signingReady()) || !(await crypto.getActiveSessionBackupVersion())) {
+                throw new StorageError("Decryption Key Safe setup has not finished; retry with the same saved key");
+            }
+        }, signal);
+    }
+    setup(signal) {
+        const options = { signal };
+        return this.serial(async () => {
+            this.active(options.signal);
+            let local = await this.local();
+            if (!local.recoveryKey) {
+                const { key, defaultKeyId, backup } = await this.topology(true);
+                if (key || defaultKeyId || backup)
+                    throw new StorageError("A Decryption Key Safe already exists; enter its saved key to unlock it");
+                const generated = await this.crypto().createRecoveryKeyFromPassphrase();
+                if (!generated.encodedPrivateKey)
+                    throw new StorageError("Could not create the Decryption Key Safe key");
+                local = { recoveryKey: generated.encodedPrivateKey };
+                await this.save(local);
+            }
+            this.active(options.signal);
+            await this.configure(local.recoveryKey, options.signal);
+            return { recoveryKey: local.recoveryKey };
+        });
+    }
+    confirmSaved(signal) {
+        const options = { signal };
+        return this.serial(async () => {
+            this.active(options.signal);
+            const local = await this.local();
+            if (!local.recoveryKey)
+                throw new StorageError("Set up the Decryption Key Safe and save its key before confirming");
+            await this.configure(local.recoveryKey, options.signal);
+            const { key, defaultKeyId, backup } = await this.topology(true);
+            if (!key && defaultKeyId)
+                throw new StorageError("The existing Decryption Key Safe is incomplete; it will not be replaced");
+            if (!key || !backup?.version)
+                throw new StorageError("Decryption Key Safe setup is incomplete");
+            this.active(options.signal);
+            await this.save({ confirmed: true, keyId: key[0], backupVersion: backup.version });
+            return { state: "ready" };
+        });
+    }
+    restore(recoveryKey, signal) {
+        const options = { signal };
+        return this.serial(async () => {
+            this.active(options.signal);
+            let privateKey;
+            try {
+                privateKey = decodeRecoveryKey(recoveryKey);
+            }
+            catch (cause) {
+                throw new StorageError("Invalid Decryption Key Safe key", { cause });
+            }
+            const { key, defaultKeyId, backup } = await this.topology(true);
+            if (!key && defaultKeyId)
+                throw new StorageError("The existing Decryption Key Safe is incomplete; it will not be replaced");
+            if (!key || !(await this.client.secretStorage.checkKey(privateKey, key[1]))) {
+                throw new StorageError("This key does not unlock the existing Decryption Key Safe");
+            }
+            // An interrupted first setup may have saved secret storage before it
+            // created the backup. Complete those missing steps using this same key.
+            if (!backup)
+                await this.configure(recoveryKey, options.signal);
+            return this.withKey(privateKey, async () => {
+                const status = await this.crypto().getCrossSigningStatus();
+                if (!status.privateKeysInSecretStorage && !Object.values(status.privateKeysCachedLocally).every(Boolean)) {
+                    throw new StorageError("Account signing keys are missing from the Decryption Key Safe; they will not be replaced");
+                }
+                await this.checkSigningCanResume();
+                this.active(options.signal);
+                await this.crypto().bootstrapCrossSigning({});
+                await this.publishSigning(options.signal);
+                await this.crypto().loadSessionBackupPrivateKeyFromSecretStorage();
+                await this.crypto().checkKeyBackupAndEnable();
+                const result = await this.crypto().restoreKeyBackup();
+                // Restore room keys before starting history sync. That first sync also
+                // publishes this login's device keys so Matrix can complete its
+                // account-signing check.
+                await this.startSync?.(options.signal);
+                if (!(await this.signingReady()))
+                    throw new StorageError("This login's account signing setup is incomplete");
+                this.active(options.signal);
+                const currentBackup = await this.serverBackup();
+                if (!currentBackup?.version)
+                    throw new StorageError("Decryption Key Safe backup is unavailable");
+                await this.save({ confirmed: true, keyId: key[0], backupVersion: currentBackup.version });
+                return { imported: result.imported, total: result.total, state: "ready" };
+            }, options.signal);
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telecrypt-io/storage",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "license": "BUSL-1.1",
   "type": "module",
   "packageManager": "npm@11.19.0",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "matrix-encrypt-attachment": "1.0.3",
-    "matrix-js-sdk": "42.2.0"
+    "matrix-js-sdk": "42.4.0"
   },
   "devDependencies": {
     "@types/node": "24.13.3",