@telecrypt-io/storage 0.9.0 → 0.9.3

package/dist/core/oidc.js

@@ -64,10 +64,8 @@ const DIAGNOSTIC_SECRET_FIELD = /(?:access[_-]?token|refresh[_-]?token|id[_-]?to
 const DIAGNOSTIC_EMAIL = /[A-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Z0-9-]+(?:\.[A-Z0-9-]+)+/giu;
 const DIAGNOSTIC_MXID = /@[A-Z0-9._=+\-/]+:[A-Z0-9.-]+/giu;
 const DIAGNOSTIC_ULID = /\b[0-9A-HJKMNP-TV-Z]{26}\b/giu;
-/** Keep provider diagnostics useful without allowing credentials, customer
- * identifiers, or control characters from an untrusted response to cross the
- * SDK boundary. */
-export function sanitizeDiagnosticText(value) {
+/** Existing fallback for plain or malformed provider diagnostics. */
+function sanitizeUnstructuredDiagnosticText(value) {
     const quotedValue = `"(?:\\\\.|[^"\\\\])*"|'(?:\\\\.|[^'\\\\])*'|[^\\s,};\\]]+`;
     return value
         .replace(/(Bearer\s+)(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s"',}]+)/giu, "$1<redacted>")
@@ -81,6 +79,21 @@ export function sanitizeDiagnosticText(value) {
         .replace(/[\r\n\u0000-\u001f\u007f-\u009f\u2028\u2029]/gu, " ")
         .trim();
 }
+/** Redact recognized secret fields and identifiers in provider diagnostics.
+ * Structured JSON uses decoded property names at every depth; the text fallback
+ * is limited to patterns recognized in unstructured input. */
+export function sanitizeDiagnosticText(value) {
+    try {
+        return JSON.stringify(JSON.parse(value), (key, item) => {
+            if (DIAGNOSTIC_SECRET_FIELD.test(key))
+                return "<redacted>";
+            return typeof item === "string" ? sanitizeUnstructuredDiagnosticText(item) : item;
+        });
+    }
+    catch {
+        return sanitizeUnstructuredDiagnosticText(value);
+    }
+}
 class OidcResponseError extends Error {
     status;
     constructor(operation, status, body, cause) {

package/dist/core/operations.d.ts

@@ -50,6 +50,8 @@ export declare function deleteFolder(storage: TeleCryptIOStorage, folderId: stri
 export declare function renameFile(storage: TeleCryptIOStorage, treeId: string, fileId: string, name: string, options?: OperationOptions): Promise<RenameResult>;
 export declare function deleteFile(storage: TeleCryptIOStorage, treeId: string, fileId: string, options?: OperationOptions): Promise<DeleteResult>;
 export declare function uploadFile(storage: TeleCryptIOStorage, treeId: string, name: string, bytes: Uint8Array, mimetype: string, options?: OperationOptions): Promise<FileInfo>;
+/** Discard the acknowledged stages of a failed upload using its retained IDs. */
+export declare function cleanupFileUpload(storage: TeleCryptIOStorage, treeId: string, mediaId: string, fileId?: string, options?: OperationOptions): Promise<void>;
 export declare function downloadFile(storage: TeleCryptIOStorage, treeId: string, fileId: string, options?: OperationOptions): Promise<DownloadedFile>;
 export declare function setupRecovery(storage: TeleCryptIOStorage, options?: OperationOptions): Promise<RecoverySetup>;
 export declare function restoreRecovery(storage: TeleCryptIOStorage, recoveryKey: string, options?: OperationOptions): Promise<RecoveryRestore>;

package/dist/core/operations.js

@@ -11,13 +11,13 @@
  * platform-specific and stays with the caller.
  */
 import { readFileEventMetadata, withMatrixMutationAbort, withTreeMutation, } from "../TeleCryptIOStorage.js";
-import { EventType, MatrixError, RoomCreateTypeField, RoomType, UNSTABLE_MSC3088_ENABLED, UNSTABLE_MSC3088_PURPOSE, UNSTABLE_MSC3089_TREE_SUBTYPE, } from "matrix-js-sdk";
-import { ClientPrefix } from "matrix-js-sdk/lib/http-api/prefix.js";
-import { Method } from "matrix-js-sdk/lib/http-api/method.js";
+import { EventType, MatrixError, } from "matrix-js-sdk";
+import { deleteOwnedMedia } from "../media.js";
 import { validateMatrixEventId } from "./constants.js";
 import { FileTooLargeError, MutationPartialError, MutationOutcomeUnknownError, NonEmptyTreeError, RoomCreationAmbiguousError, RoomCleanupIncompleteError, StorageError, } from "./errors.js";
 import { ConditionTimeoutError, waitForCondition } from "./poll.js";
-import { validateName } from "./validation.js";
+import { hasStorageTreeMarkersRoom, isStorageTreeRoom, validateName } from "./validation.js";
+import { prepareReaderHistorySharing } from "../sharing.js";
 import { isFileDeleted, isTreeDeleted, markFileDeleted, markTreeDeleted, } from "../deletion-markers.js";
 /**
  * Production Synapse enforces the built-in rc_messages budget (per-account
@@ -100,6 +100,7 @@ function isRateLimited(error) {
 }
 function requiresMutationReconciliation(error) {
     return (error instanceof MutationOutcomeUnknownError ||
+        error instanceof MutationPartialError ||
         error instanceof RoomCreationAmbiguousError ||
         error instanceof RoomCleanupIncompleteError);
 }
@@ -325,7 +326,17 @@ async function activeTreeDirectories(storage, tree, signal) {
             // 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 });
+            let joined = false;
+            return await waitForCondition(async () => {
+                const directory = storage.getTree(childId);
+                if (directory)
+                    return directory;
+                if (!joined && client.getRoom?.(childId)?.getMyMembership?.() === "invite") {
+                    await joinTreeRoom(storage, childId, signal ?? new AbortController().signal);
+                    joined = true;
+                }
+                return null;
+            }, { timeoutMs: 15000, signal });
         }
         catch (error) {
             if (signal?.aborted)
@@ -546,64 +557,98 @@ export function getMyVaultRole(storage, vaultId) {
         return null;
     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;
+async function joinTreeRoom(storage, vaultId, signal) {
+    let membership;
+    try {
+        membership = await storage.getRoomMembership(vaultId, undefined, { signal });
+    }
+    catch (err) {
+        if (signal.aborted)
+            throw new StorageError("operation cancelled");
+        // Synapse refuses GET /rooms/:room/members for an invited user with
+        // M_FORBIDDEN. That response means the membership preflight cannot
+        // inspect the room yet; it is not evidence that joining is forbidden.
+        // Attempt the idempotent join and let its own response decide access.
+        if (err instanceof MatrixError && err.errcode === "M_FORBIDDEN") {
+            membership = null;
+        }
+        else {
+            throw new StorageError("join failed", { cause: err });
+        }
+    }
+    if (membership === "join")
+        return;
+    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 {
-            membership = await storage.getRoomMembership(vaultId, undefined, { signal });
+            await waitForCondition(() => client.getRoom(vaultId)?.getMember(userId)?.membership === "invite" ? true : null, { timeoutMs: 15000, signal });
         }
         catch (err) {
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
-            // Synapse refuses GET /rooms/:room/members for an invited user with
-            // M_FORBIDDEN. That response means the membership preflight cannot
-            // inspect the room yet; it is not evidence that joining is forbidden.
-            // Attempt the idempotent join and let its own response decide access.
-            if (err instanceof MatrixError && err.errcode === "M_FORBIDDEN") {
-                membership = null;
-            }
-            else {
-                throw new StorageError("join failed", { cause: err });
+            if (err instanceof ConditionTimeoutError) {
+                throw new StorageError("the room invitation has not reached this login yet; retry joining", { cause: err });
             }
+            throw err;
         }
-        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(() => client.joinRoom(vaultId), signal), signal);
+    }
+    catch (err) {
+        if (err instanceof MutationOutcomeUnknownError)
+            throw err;
+        if (err instanceof MatrixError && err.errcode === "M_FORBIDDEN") {
+            const afterForbidden = await storage.getRoomMembership(vaultId, undefined, { signal });
+            if (afterForbidden === "join")
+                return;
         }
+        if (signal.aborted)
+            throw new StorageError("operation cancelled");
+        throw new StorageError("join failed", { cause: err });
+    }
+}
+export async function joinVault(storage, vaultId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
+    return withOperationDeadline(options, async (signal) => {
+        const joined = new Set();
+        const pending = [vaultId];
         try {
-            await withRateLimitRetry(() => withMatrixMutationAbort(() => client.joinRoom(vaultId), signal), signal);
+            while (pending.length > 0) {
+                ensureOperationActive(signal);
+                const roomId = pending.shift();
+                if (joined.has(roomId) || isMarkedTreeDeleted(storage, roomId))
+                    continue;
+                // Keep native joinRoom's inviter/history-bundle handling for every
+                // child. Merely joining the root does not accept its child invites.
+                await joinTreeRoom(storage, roomId, signal);
+                joined.add(roomId);
+                await resolveTree(storage, roomId, signal);
+                await storage.refreshRoomState(roomId, { signal });
+                const children = readRelationEvents(storage.getClient(), roomId, EventType.SpaceChild);
+                if (children === null)
+                    throw new StorageError("storage folder state is unavailable");
+                for (const child of children) {
+                    if (!isActiveRelationEvent(child))
+                        continue;
+                    const childId = relationStateKey(child);
+                    if (!childId)
+                        throw new StorageError("storage folder state is inconsistent");
+                    pending.push(childId);
+                }
+            }
         }
-        catch (err) {
-            if (err instanceof MutationOutcomeUnknownError)
-                throw err;
-            if (err instanceof MatrixError && err.errcode === "M_FORBIDDEN") {
-                const afterForbidden = await storage.getRoomMembership(vaultId, undefined, { signal });
-                if (afterForbidden === "join")
-                    return { vaultId, joined: true };
+        catch (error) {
+            if (joined.size > 0) {
+                throw new MutationPartialError("join", [...joined], "some folders were joined; retry accepting the same vault to finish", { cause: error });
             }
-            if (signal.aborted)
-                throw new StorageError("operation cancelled");
-            throw new StorageError("join failed", { cause: err });
+            throw error;
         }
-        ensureOperationActive(signal);
         return { vaultId, joined: true };
     }, "mutation");
 }
@@ -615,14 +660,6 @@ function hasActiveSpaceParent(room) {
     const events = result == null ? [] : Array.isArray(result) ? result : [result];
     return events.some((event) => isActiveRelationEvent(event));
 }
-function isReviewedStorageTreeRoom(room) {
-    const createEvent = room?.currentState?.getStateEvents?.(EventType.RoomCreate, "");
-    const createContent = createEvent?.getContent?.();
-    const purposeEvent = room?.currentState?.getStateEvents?.(UNSTABLE_MSC3088_PURPOSE.name, UNSTABLE_MSC3089_TREE_SUBTYPE.name);
-    const purposeContent = purposeEvent?.getContent?.();
-    return (createContent?.[RoomCreateTypeField] === RoomType.Space &&
-        purposeContent?.[UNSTABLE_MSC3088_ENABLED.name] === true);
-}
 /** 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 });
@@ -650,7 +687,7 @@ export async function listPendingInvites(storage, options) {
             }
             // Invite state may not have MSC3089 tree metadata yet — accept rooms whose
             // create event marks them as a file tree space.
-            if (isReviewedStorageTreeRoom(room)) {
+            if (isStorageTreeRoom(room)) {
                 invites.push({
                     id: room.roomId,
                     name: roomDisplayName(storage, room.roomId),
@@ -689,7 +726,7 @@ export async function declineInvite(storage, vaultId, options) {
             // requiring a joined TreeSpace object.
             if (!currentRoom ||
                 hasActiveSpaceParent(currentRoom) ||
-                !isReviewedStorageTreeRoom(currentRoom)) {
+                !hasStorageTreeMarkersRoom(currentRoom)) {
                 throw new StorageError("decline failed");
             }
             let membership;
@@ -780,14 +817,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                     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");
-                }
+                const verifyHistorySharing = await prepareReaderHistorySharing(client, userId);
                 for (const [index, space] of spaces.entries()) {
                     ensureOperationActive(operation.signal);
                     const members = index === 0
@@ -807,12 +837,9 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                     // 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);
+                    await withRateLimitRetry(() => withMatrixMutationAbort(() => space.invite(userId, false), 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");
-                    }
+                    await verifyHistorySharing();
                 }
                 // Storage rooms have one immutable owner power level and readers use
                 // the room's default user level. Changing per-user power levels would create editors and
@@ -1121,18 +1148,10 @@ export async function renameFile(storage, treeId, fileId, name, options) {
         return { id: fileId, name };
     }, "mutation");
 }
-function requireFileDeletionTransport(client) {
-    const http = client.http;
-    if (!http || typeof http.authedRequest !== "function") {
-        throw new StorageError("Matrix HTTP transport unavailable");
-    }
-    return http;
-}
 async function deleteFileMedia(storage, mediaIds, signal) {
     const client = storage.getClient();
-    const http = requireFileDeletionTransport(client);
     try {
-        await withRateLimitRetry(() => withMatrixMutationAbort(() => http.authedRequest(Method.Post, "/io.telecrypt.storage/delete_media", undefined, { media_ids: [...mediaIds] }, { prefix: ClientPrefix.Unstable, rawResponseBody: true, abortSignal: signal }), signal, "delete file media"), signal);
+        await withRateLimitRetry(() => withMatrixMutationAbort(() => deleteOwnedMedia(client, mediaIds, signal), signal, "delete file media"), signal);
     }
     catch (error) {
         if (error instanceof MutationOutcomeUnknownError)
@@ -1150,8 +1169,6 @@ export async function deleteFile(storage, treeId, fileId, options) {
             return { id: fileId, deleted: true };
         await storage.refreshRoomState(treeId, { signal });
         const branch = tree.getFile(fileId);
-        if (!branch)
-            throw new StorageError("file not found");
         let originalEvent;
         try {
             originalEvent = await storage.getOriginalFileEvent(tree.id, fileId, true);
@@ -1160,7 +1177,7 @@ export async function deleteFile(storage, treeId, fileId, options) {
             throw new StorageError("could not resolve encrypted file safely", { cause: error });
         }
         if (originalEvent.isRedacted()) {
-            if (branch.isActive === false) {
+            if (!branch || branch.isActive === false) {
                 markFileDeleted(storage.getClient(), tree.id, fileId);
                 return { id: fileId, deleted: true };
             }
@@ -1184,7 +1201,9 @@ export async function deleteFile(storage, treeId, fileId, options) {
         const completedIds = [mediaId];
         try {
             const client = storage.getClient();
-            const metadataEventId = await storage.getFileMetadataEventId(tree.id, fileId, { signal });
+            const metadataEventId = branch
+                ? await storage.getFileMetadataEventId(tree.id, fileId, { signal })
+                : null;
             if (metadataEventId && metadataEventId !== fileId) {
                 const metadataEvent = await storage.getFileRenameMetadataEvent(tree.id, fileId, metadataEventId);
                 if (!metadataEvent.isRedacted()) {
@@ -1195,16 +1214,17 @@ export async function deleteFile(storage, treeId, fileId, options) {
             const currentBranch = tree.getFile(fileId);
             const indexEvent = currentBranch?.indexEvent;
             const listingEventId = indexEvent?.getId();
-            if (!indexEvent || typeof listingEventId !== "string" || listingEventId.length === 0) {
+            if (currentBranch && (!indexEvent || typeof listingEventId !== "string" || listingEventId.length === 0)) {
                 throw new StorageError("encrypted file has no listing event identifier");
             }
-            if (!indexEvent.isRedacted()) {
+            if (indexEvent && !indexEvent.isRedacted()) {
                 if (indexEvent.getSender() !== client.getUserId()) {
                     throw new StorageError("file listing was not authored by the owner");
                 }
                 await withRateLimitRetry(() => withMatrixMutationAbort(() => client.redactEvent(tree.id, listingEventId), signal, "delete file listing"), signal);
             }
-            completedIds.push(listingEventId);
+            if (listingEventId)
+                completedIds.push(listingEventId);
             await withRateLimitRetry(() => withMatrixMutationAbort(() => client.redactEvent(tree.id, fileId), signal, "delete file attachment event"), signal);
             completedIds.push(fileId);
         }
@@ -1235,12 +1255,18 @@ export async function deleteFile(storage, treeId, fileId, options) {
 }
 export async function uploadFile(storage, treeId, name, bytes, mimetype, options) {
     await storage.keySafe.requireReady({ signal: options?.signal });
-    return withOperationDeadline(options, async (signal) => {
+    const deadline = createOperationDeadline(options);
+    try {
+        const signal = deadline.signal;
+        ensureOperationActive(signal);
+        // Unlike a read, an upload must retain a receipt returned by an in-flight
+        // mutation after cancellation. Native HTTP requests remain time-bounded;
+        // the uploader stops before starting another write when this signal aborts.
         const tree = await resolveTree(storage, treeId, signal);
         const fileId = await withRateLimitRetry(() => storage.uploadFile(tree, name, toArrayBuffer(bytes), mimetype, signal), signal).catch((error) => {
             if (error instanceof FileTooLargeError)
                 throw error;
-            if (error instanceof MutationOutcomeUnknownError)
+            if (error instanceof MutationOutcomeUnknownError || error instanceof MutationPartialError)
                 throw error;
             if (signal.aborted)
                 throw new StorageError("operation cancelled");
@@ -1263,10 +1289,20 @@ export async function uploadFile(storage, treeId, name, bytes, mimetype, options
         catch (error) {
             if (error instanceof MutationOutcomeUnknownError)
                 throw error;
-            throw new MutationPartialError("upload file", [fileId], "upload completed but the file could not be observed locally", { cause: error });
+            throw new MutationPartialError("upload file", [fileId], "upload completed but the file could not be observed locally", { cause: error, treeId });
         }
         ensureOperationActive(signal);
         return { id: fileId, name, mimetype };
+    }
+    finally {
+        deadline.close();
+    }
+}
+/** Discard the acknowledged stages of a failed upload using its retained IDs. */
+export async function cleanupFileUpload(storage, treeId, mediaId, fileId, options) {
+    await storage.keySafe.requireReady({ signal: options?.signal });
+    return withOperationDeadline(options, async (signal) => {
+        await storage.cleanupFileUpload(treeId, mediaId, fileId, { signal });
     }, "mutation");
 }
 export async function downloadFile(storage, treeId, fileId, options) {

package/dist/core/validation.d.ts

@@ -1,3 +1,18 @@
 /** Shared name contract used by SDK inputs and remote projections. */
 export declare function isValidName(value: unknown): value is string;
 export declare function validateName(value: unknown, label: string): asserts value is string;
+export declare const STORAGE_ROOM_ENCRYPTION_ALGORITHM = "m.megolm.v1.aes-sha2";
+interface StorageTreeRoomLike {
+    currentState?: {
+        getStateEvents?: (eventType: string, stateKey?: string) => unknown;
+    };
+}
+/** The shared Storage-room contract for both synced rooms and refreshed state. */
+export declare function isStorageTreeState(createContent: unknown, purposeContent: unknown, encryptionContent: unknown): boolean;
+/** The room markers needed for explicit invite cleanup before encryption is available. */
+export declare function hasStorageTreeMarkers(createContent: unknown, purposeContent: unknown): boolean;
+/** Checks the existing Storage markers and Megolm room encryption together. */
+export declare function isStorageTreeRoom(room: StorageTreeRoomLike | null | undefined): boolean;
+/** Checks only the room markers for explicit cleanup paths such as declining an invite. */
+export declare function hasStorageTreeMarkersRoom(room: StorageTreeRoomLike | null | undefined): boolean;
+export {};

package/dist/core/validation.js

@@ -1,3 +1,4 @@
+import { EventType, RoomCreateTypeField, RoomType, UNSTABLE_MSC3088_ENABLED, UNSTABLE_MSC3088_PURPOSE, UNSTABLE_MSC3089_TREE_SUBTYPE, } from "matrix-js-sdk";
 /** Shared name contract used by SDK inputs and remote projections. */
 export function isValidName(value) {
     return (typeof value === "string" &&
@@ -9,3 +10,47 @@ export function validateName(value, label) {
         throw new Error(`invalid ${label}`);
     }
 }
+export const STORAGE_ROOM_ENCRYPTION_ALGORITHM = "m.megolm.v1.aes-sha2";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The shared Storage-room contract for both synced rooms and refreshed state. */
+export function isStorageTreeState(createContent, purposeContent, encryptionContent) {
+    return hasStorageTreeMarkers(createContent, purposeContent) &&
+        isRecord(encryptionContent) &&
+        encryptionContent.algorithm === STORAGE_ROOM_ENCRYPTION_ALGORITHM;
+}
+/** The room markers needed for explicit invite cleanup before encryption is available. */
+export function hasStorageTreeMarkers(createContent, purposeContent) {
+    return (isRecord(createContent) &&
+        createContent[RoomCreateTypeField] === RoomType.Space &&
+        isRecord(purposeContent) &&
+        purposeContent[UNSTABLE_MSC3088_ENABLED.name] === true);
+}
+function getStorageTreeState(room) {
+    const getContent = (eventType, stateKey) => {
+        const raw = room?.currentState?.getStateEvents?.(eventType, stateKey);
+        const event = Array.isArray(raw) ? raw[0] : raw;
+        if (typeof event !== "object" || event === null)
+            return undefined;
+        const getEventContent = event.getContent;
+        return typeof getEventContent === "function"
+            ? getEventContent.call(event)
+            : undefined;
+    };
+    return {
+        createContent: getContent(EventType.RoomCreate, ""),
+        purposeContent: getContent(UNSTABLE_MSC3088_PURPOSE.name, UNSTABLE_MSC3089_TREE_SUBTYPE.name),
+        encryptionContent: getContent(EventType.RoomEncryption, ""),
+    };
+}
+/** Checks the existing Storage markers and Megolm room encryption together. */
+export function isStorageTreeRoom(room) {
+    const state = getStorageTreeState(room);
+    return isStorageTreeState(state.createContent, state.purposeContent, state.encryptionContent);
+}
+/** Checks only the room markers for explicit cleanup paths such as declining an invite. */
+export function hasStorageTreeMarkersRoom(room) {
+    const state = getStorageTreeState(room);
+    return hasStorageTreeMarkers(state.createContent, state.purposeContent);
+}

package/dist/media.d.ts

@@ -0,0 +1,3 @@
+import type { MatrixClient } from "matrix-js-sdk";
+/** The policy endpoint authorizes deletion against the uploading user. */
+export declare function deleteOwnedMedia(client: MatrixClient, mediaIds: readonly string[], signal?: AbortSignal): Promise<void>;

package/dist/media.js

@@ -0,0 +1,10 @@
+import { Method } from "matrix-js-sdk/lib/http-api/method.js";
+import { ClientPrefix } from "matrix-js-sdk/lib/http-api/prefix.js";
+import { StorageError } from "./core/errors.js";
+/** The policy endpoint authorizes deletion against the uploading user. */
+export async function deleteOwnedMedia(client, mediaIds, signal) {
+    if (!client.http || typeof client.http.authedRequest !== "function") {
+        throw new StorageError("Matrix HTTP transport unavailable");
+    }
+    await client.http.authedRequest(Method.Post, "/io.telecrypt.storage/delete_media", undefined, { media_ids: [...mediaIds] }, { prefix: ClientPrefix.Unstable, rawResponseBody: true, abortSignal: signal });
+}

package/dist/sharing.d.ts

@@ -0,0 +1,3 @@
+import type { MatrixClient } from "matrix-js-sdk";
+/** Use the same account/device requirements for explicit and inherited sharing. */
+export declare function prepareReaderHistorySharing(client: MatrixClient, userId: string): Promise<() => Promise<void>>;

package/dist/sharing.js

@@ -0,0 +1,18 @@
+import { StorageError } from "./core/errors.js";
+/** Use the same account/device requirements for explicit and inherited sharing. */
+export async function prepareReaderHistorySharing(client, userId) {
+    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");
+    }
+    return async () => {
+        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");
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telecrypt-io/storage",
-  "version": "0.9.0",
+  "version": "0.9.3",
   "license": "BUSL-1.1",
   "type": "module",
   "packageManager": "npm@11.19.0",
@@ -22,7 +22,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": "24.20.0"
+    "node": "24.21.0"
   },
   "publishConfig": {
     "access": "public"
@@ -48,7 +48,7 @@
     "eslint": "10.9.0",
     "fake-indexeddb": "6.2.5",
     "typescript": "5.9.3",
-    "vitest": "4.1.11"
+    "vitest": "4.1.12"
   },
   "repository": {
     "type": "git",