@telecrypt-io/storage 0.5.26 → 0.5.28

package/README.md

@@ -4,6 +4,10 @@
 
 End-to-end encrypted file storage and sharing, built on Matrix.
 
+The current public TeleCrypt architecture, responsibilities, and product limits are authoritative at
+[telecrypt.io/llms.txt](https://telecrypt.io/llms.txt). This README documents this SDK's package API
+and development workflow.
+
 Files are encrypted on the client before upload. The server stores only opaque ciphertext and
 never holds the decryption keys. Shared vaults let multiple people add and read files, and a
 Recovery Key restores your files on a new device — even if you lose the original.
@@ -15,7 +19,7 @@ is maintained in its own repository.
 ## Install
 
 ```bash
-npm install @telecrypt-io/storage@0.5.10
+npm install @telecrypt-io/storage@0.5.28
 ```
 
 This gives you the `TeleCryptIOStorage` library and its browser-safe `core` API.

package/dist/TeleCryptIOStorage.d.ts

@@ -285,12 +285,6 @@ export declare class TeleCryptIOStorage {
         role: string;
         membership: string;
     }[]>;
-    /**
-     * Returns the homeserver's complete joined-room inventory. Local sync room
-     * lists can be truncated by initialSyncLimit and are not an authoritative
-     * basis for deletion safety.
-     */
-    listJoinedRoomIds(options?: MatrixRequestOptions): Promise<string[]>;
     /** Reads one room membership from the homeserver, not the lagging local sync store. */
     getRoomMembership(roomId: string, userId?: string | null, options?: MatrixRequestOptions): Promise<string | null>;
     uploadFile(tree: TreeSpace, name: string, data: ArrayBuffer, mimetype: string, signal?: AbortSignal): Promise<string>;

package/dist/TeleCryptIOStorage.js

@@ -375,21 +375,6 @@ function parseMatrixPowerLevels(value) {
     }
     return value;
 }
-function parseJoinedRoomsResponse(value) {
-    if (!isRecord(value) ||
-        !Array.isArray(value.joined_rooms) ||
-        value.joined_rooms.length > MAX_MATRIX_JOINED_ROOMS) {
-        throw new Error("invalid Matrix joined-room response");
-    }
-    return value.joined_rooms.map((roomId) => {
-        try {
-            return validateMatrixRoomId(roomId, "joined-room response");
-        }
-        catch {
-            throw new Error("invalid Matrix joined-room response");
-        }
-    });
-}
 function isGoneRoomError(error) {
     return (error instanceof MatrixError &&
         (error.errcode === "M_NOT_FOUND" || error.errcode === "M_UNKNOWN"));
@@ -1435,19 +1420,6 @@ export class TeleCryptIOStorage {
             role: roleFor(e.state_key),
         }));
     }
-    /**
-     * Returns the homeserver's complete joined-room inventory. Local sync room
-     * lists can be truncated by initialSyncLimit and are not an authoritative
-     * basis for deletion safety.
-     */
-    async listJoinedRoomIds(options) {
-        const body = await requireMatrixHttpTransport(this.client).authedRequest(Method.Get, "/joined_rooms", undefined, undefined, {
-            prefix: ClientPrefix.V3,
-            localTimeoutMs: matrixRequestTimeout(options),
-            abortSignal: matrixRequestSignal(options),
-        });
-        return parseJoinedRoomsResponse(body);
-    }
     /** Reads one room membership from the homeserver, not the lagging local sync store. */
     async getRoomMembership(roomId, userId = this.client.getUserId(), options) {
         if (!userId)

package/dist/core/index.d.ts

@@ -4,3 +4,4 @@ export * from "./operations.js";
 export * from "./errors.js";
 export * from "./oidc.js";
 export * from "./constants.js";
+export { isValidName, MAX_NAME_LENGTH, validateName } from "./validation.js";

package/dist/core/index.js

@@ -4,3 +4,4 @@ export * from "./operations.js";
 export * from "./errors.js";
 export * from "./oidc.js";
 export * from "./constants.js";
+export { isValidName, MAX_NAME_LENGTH, validateName } from "./validation.js";

package/dist/core/oidc.js

@@ -35,6 +35,9 @@ const MAX_OIDC_TOKEN_LENGTH = 8192;
 const MAX_OIDC_SCOPE_LENGTH = 4096;
 const MAX_OIDC_CONTACTS = 16;
 const MAX_OIDC_REDIRECT_URIS = 8;
+const LEGACY_MATRIX_SCOPE_PREFIX = "urn:matrix:client:";
+const MSC2967_MATRIX_SCOPE_PREFIX = "urn:matrix:org.matrix.msc2967.client:";
+const MATRIX_SCOPE_PREFIXES = [LEGACY_MATRIX_SCOPE_PREFIX, MSC2967_MATRIX_SCOPE_PREFIX];
 // MAS advertises a 20-minute device-code lifetime. Keep that provider window
 // as the hard upper bound while retaining a finite polling budget.
 const MAX_DEVICE_EXPIRES_IN_SECONDS = 20 * 60;
@@ -791,7 +794,9 @@ export async function waitForDeviceCodeLogin(authMetadata, clientId, session, si
             }, Math.min(OIDC_REQUEST_TIMEOUT_MS, remaining), signal);
             if (response.ok && isValidDeviceAccessTokenResponse(body)) {
                 const tokenResponse = validateDeviceAccessTokenResponse(body);
-                if (!requestedDeviceId || tokenResponse.scope !== generateScope(requestedDeviceId)) {
+                if (!requestedDeviceId ||
+                    typeof tokenResponse.scope !== "string" ||
+                    !scopeMatchesDevice(tokenResponse.scope, requestedDeviceId)) {
                     throw new OidcValidationError("OIDC device authorization returned an unexpected granted scope");
                 }
                 ensureOidcNotCancelled(signal, "device authorization");
@@ -940,9 +945,8 @@ export async function completeAuthorizationCodeFlow(code, state, signal) {
         validateBearerTokenResponse(body);
         validateTokenBounds(body, "authorization code exchange");
         const normalized = normalizeBearerTokenResponseTokenType(body);
-        const expectedScope = generateScope(context.deviceId);
         const grantedScope = normalized.scope;
-        if (typeof grantedScope !== "string" || grantedScope !== expectedScope) {
+        if (typeof grantedScope !== "string" || !scopeMatchesDevice(grantedScope, context.deviceId)) {
             throw new StorageError("OIDC authorization code exchange returned an unexpected granted scope");
         }
         const tokenResponse = {
@@ -975,12 +979,52 @@ export function extractDeviceIdFromScope(scope) {
         return null;
     }
     const tokens = scope.split(/\s+/);
-    const deviceTokens = tokens.filter((token) => token.startsWith("urn:matrix:client:device:"));
+    const deviceTokens = tokens.filter((token) => MATRIX_SCOPE_PREFIXES.some((prefix) => token.startsWith(`${prefix}device:`)));
     if (deviceTokens.length !== 1)
         return null;
-    const deviceId = deviceTokens[0].slice("urn:matrix:client:device:".length);
+    const deviceToken = deviceTokens[0];
+    const prefix = MATRIX_SCOPE_PREFIXES.find((candidate) => deviceToken.startsWith(`${candidate}device:`));
+    if (!prefix)
+        return null;
+    const deviceId = deviceToken.slice(`${prefix}device:`.length);
     return DEVICE_ID_PATTERN.test(deviceId) ? deviceId : null;
 }
+/**
+ * Accepts the legacy Matrix OAuth scope and the current MSC2967 namespace
+ * returned by MAS. The provider may add the standard `openid` scope, but the
+ * API and device grants must remain one exact namespace pair bound to the
+ * device that this client requested.
+ */
+function scopeMatchesDevice(scope, expectedDeviceId) {
+    if (typeof scope !== "string" ||
+        typeof expectedDeviceId !== "string" ||
+        !DEVICE_ID_PATTERN.test(expectedDeviceId) ||
+        scope.length === 0 ||
+        scope.length > MAX_OIDC_SCOPE_LENGTH ||
+        /[\u0000-\u001f\u007f]/.test(scope) ||
+        scope.trim() !== scope ||
+        /\s{2,}/.test(scope)) {
+        return false;
+    }
+    const tokens = scope.split(/\s+/);
+    if (new Set(tokens).size !== tokens.length)
+        return false;
+    return MATRIX_SCOPE_PREFIXES.some((prefix) => {
+        const expected = new Set([
+            `${prefix}api:*`,
+            `${prefix}device:${expectedDeviceId}`,
+            "openid",
+        ]);
+        const required = new Set([
+            `${prefix}api:*`,
+            `${prefix}device:${expectedDeviceId}`,
+        ]);
+        return (tokens.length >= required.size &&
+            tokens.length <= expected.size &&
+            tokens.every((token) => expected.has(token)) &&
+            [...required].every((token) => tokens.includes(token)));
+    });
+}
 function validateMatrixUserId(userId, serverName) {
     try {
         return validateCanonicalMatrixUserId(userId, serverName);
@@ -1120,8 +1164,7 @@ async function refreshOidcToken(tokenEndpoint, clientId, refreshToken, expectedD
             catch {
                 throw new StorageError("OIDC token refresh returned an invalid scope");
             }
-            if (extractDeviceIdFromScope(grantedScope) === null ||
-                grantedScope !== generateScope(expectedDeviceId)) {
+            if (!scopeMatchesDevice(grantedScope, expectedDeviceId)) {
                 throw new StorageError("OIDC token refresh returned an unexpected granted scope");
             }
         }

package/dist/core/operations.js

@@ -32,7 +32,6 @@ const RATE_LIMIT_DEFAULT_DELAY_MS = 15_000;
 const RATE_LIMIT_MAX_DELAY_MS = 30_000;
 const RATE_LIMIT_MAX_TOTAL_DELAY_MS = 90_000;
 const MAX_DELETION_ROOMS = 4096;
-const DELETION_REFRESH_CONCURRENCY = 8;
 const MAX_DELETION_DEPTH = 128;
 const MAX_FILE_VERSION_CHAIN = 128;
 const MAX_LIST_ITEMS = 10000;
@@ -257,7 +256,7 @@ function assertTreeEmptyForDeletion(storage, tree, spaces) {
     if (files.length > 0)
         throw new NonEmptyTreeError(tree.id);
 }
-async function refreshDeletionRooms(storage, signal) {
+async function refreshDeletionRooms(storage, rootId, signal) {
     const client = storage.getClient();
     const http = client.http;
     // A real MatrixClient always exposes its authenticated HTTP transport. A
@@ -265,48 +264,31 @@ async function refreshDeletionRooms(storage, signal) {
     if (typeof http?.authedRequest !== "function") {
         throw new StorageError("delete graph refresh is unavailable");
     }
-    const roomIds = await storage.listJoinedRoomIds({ signal });
-    if (roomIds.length > MAX_DELETION_ROOMS)
-        throw new StorageError("delete graph is too large");
-    const joined = new Set(roomIds);
-    const roomIdsToRefresh = [];
-    // Matrix has no bounded endpoint that enumerates every invited/non-joined
-    // room carrying a space relation. Refresh every locally visible room and
-    // fail closed for an invite/knock/unknown membership; a joined external
-    // parent remains inspectable and is validated by validateDeletionGraph.
-    for (const room of client.getRooms()) {
-        if (!joined.has(room.roomId)) {
-            const membership = room.getMyMembership?.();
-            if (membership !== "join")
-                throw new StorageError("delete graph inventory is incomplete");
-            roomIdsToRefresh.push(room.roomId);
-        }
+    await storage.refreshRoomState(rootId, { signal });
+    if (signal?.aborted)
+        throw new StorageError("operation cancelled");
+    // The refreshed root owns its parent relation. Verify its one supported
+    // external parent directly; unrelated local rooms are outside this deletion.
+    const parentEvents = readRelationEvents(client, rootId, EventType.SpaceParent);
+    if (parentEvents === null)
+        throw new StorageError("delete graph is unsafe");
+    const parentIds = new Set();
+    for (const event of parentEvents) {
+        if (!isActiveRelationEvent(event))
+            continue;
+        const parentId = relationStateKey(event);
+        if (!parentId)
+            throw new StorageError("delete graph is unsafe");
+        if (parentId !== rootId)
+            parentIds.add(parentId);
     }
-    roomIdsToRefresh.push(...roomIds);
-    let nextRoom = 0;
-    let failed = false;
-    let firstError;
-    const refreshWorker = async () => {
-        while (!failed && !signal?.aborted) {
-            const roomId = roomIdsToRefresh[nextRoom++];
-            if (roomId === undefined)
-                return;
-            try {
-                await storage.refreshRoomState(roomId, { signal });
-            }
-            catch (error) {
-                failed = true;
-                firstError = error;
-                return;
-            }
-        }
-    };
-    const workerCount = Math.min(DELETION_REFRESH_CONCURRENCY, roomIdsToRefresh.length);
-    await Promise.all(Array.from({ length: workerCount }, () => refreshWorker()));
+    if (parentIds.size > 1)
+        throw new StorageError("delete graph is unsafe");
+    const parentId = parentIds.values().next().value;
+    if (parentId)
+        await storage.refreshRoomState(parentId, { signal });
     if (signal?.aborted)
         throw new StorageError("operation cancelled");
-    if (failed)
-        throw firstError;
 }
 async function refreshTreeSpaces(storage, spaces, signal) {
     for (const space of spaces) {
@@ -420,31 +402,11 @@ function validateDeletionGraph(client, root, ids, deletedRooms) {
                 if (id !== root.id || externalParents.includes(parentId)) {
                     throw new StorageError("delete graph is unsafe");
                 }
-                externalParents.push(parentId);
-            }
-        }
-    }
-    const rooms = client.getRooms();
-    if (rooms.length > MAX_DELETION_ROOMS)
-        throw new StorageError("delete graph is too large");
-    for (const room of rooms) {
-        const parentId = room.roomId;
-        const childEvents = readRelationEvents(client, parentId, EventType.SpaceChild);
-        if (childEvents === null)
-            throw new StorageError("delete graph is unsafe");
-        for (const event of childEvents) {
-            if (!isActiveRelationEvent(event))
-                continue;
-            const childId = relationStateKey(event);
-            if (!childId)
-                throw new StorageError("delete graph is unsafe");
-            if (ids.has(childId) && !ids.has(parentId)) {
-                if (childId === root.id) {
-                    if (!externalParents.includes(parentId))
-                        externalParents.push(parentId);
-                    continue;
+                const childLink = readRelationEvents(client, parentId, EventType.SpaceChild, id);
+                if (!childLink?.some((candidate) => isActiveRelationEvent(candidate) && relationStateKey(candidate, id) === id)) {
+                    throw new StorageError("delete graph is unsafe");
                 }
-                throw new StorageError("delete graph is unsafe");
+                externalParents.push(parentId);
             }
         }
     }
@@ -524,60 +486,78 @@ function isGoneError(error) {
         (error.errcode === "M_NOT_FOUND" || error.errcode === "M_UNKNOWN"));
 }
 async function deleteRoomDeterministically(storage, roomId, signal) {
-    const client = storage.getClient();
-    const tree = storage.getTree(roomId);
-    if (!tree)
-        throw new StorageError("delete graph is unsafe");
-    const self = client.getUserId();
-    if (!self)
-        throw new StorageError("delete graph is unsafe");
-    const members = await storage.listMembers(tree, { signal });
-    if (members.some((member) => member.userId !== self && member.role === "owner" &&
-        (member.membership === "join" || member.membership === "invite" || member.membership === "knock"))) {
-        throw new StorageError("delete will not kick another room owner");
-    }
-    for (const member of members) {
-        const membership = member.membership;
-        if (member.userId === self ||
-            (membership !== "join" && membership !== "invite" && membership !== "knock")) {
-            continue;
-        }
-        try {
-            await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.kick(roomId, member.userId, "Room deleted"), signal), signal);
-        }
-        catch (error) {
-            if (isGoneError(error))
+    const completedRoomIds = [];
+    const markRoomMutationComplete = () => {
+        if (!completedRoomIds.includes(roomId))
+            completedRoomIds.push(roomId);
+    };
+    try {
+        const client = storage.getClient();
+        const tree = storage.getTree(roomId);
+        if (!tree)
+            throw new StorageError("delete graph is unsafe");
+        const self = client.getUserId();
+        if (!self)
+            throw new StorageError("delete graph is unsafe");
+        const members = await storage.listMembers(tree, { signal });
+        if (members.some((member) => member.userId !== self && member.role === "owner" &&
+            (member.membership === "join" || member.membership === "invite" || member.membership === "knock"))) {
+            throw new StorageError("delete will not kick another room owner");
+        }
+        for (const member of members) {
+            const membership = member.membership;
+            if (member.userId === self ||
+                (membership !== "join" && membership !== "invite" && membership !== "knock")) {
                 continue;
-            if (error instanceof MatrixError && error.errcode === "M_FORBIDDEN") {
-                const currentMembership = await storage.getRoomMembership(roomId, member.userId, { signal });
-                if (currentMembership === "leave" ||
-                    currentMembership === "ban" ||
-                    !currentMembership) {
+            }
+            try {
+                await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.kick(roomId, member.userId, "Room deleted"), signal), signal);
+                markRoomMutationComplete();
+            }
+            catch (error) {
+                if (isGoneError(error))
                     continue;
+                if (error instanceof MatrixError && error.errcode === "M_FORBIDDEN") {
+                    const currentMembership = await storage.getRoomMembership(roomId, member.userId, { signal });
+                    if (currentMembership === "leave" ||
+                        currentMembership === "ban" ||
+                        !currentMembership) {
+                        continue;
+                    }
                 }
+                throw error;
+            }
+        }
+        const ownMembership = await storage.getRoomMembership(roomId, undefined, { signal });
+        if (ownMembership === "join" || ownMembership === "invite" || ownMembership === "knock") {
+            try {
+                await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.leave(roomId), signal), signal);
+                markRoomMutationComplete();
+            }
+            catch (error) {
+                if (!isGoneError(error))
+                    throw error;
             }
-            throw error;
         }
-    }
-    const ownMembership = await storage.getRoomMembership(roomId, undefined, { signal });
-    if (ownMembership === "join" || ownMembership === "invite" || ownMembership === "knock") {
         try {
-            await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.leave(roomId), signal), signal);
+            await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.forget(roomId), signal), signal);
+            markRoomMutationComplete();
         }
         catch (error) {
             if (!isGoneError(error))
                 throw error;
         }
-    }
-    try {
-        await withRateLimitRetry(() => withMatrixMutationAbort(client, () => client.forget(roomId), signal), signal);
+        removeRoomFromLocalStore(client, roomId);
+        markTreeDeleted(client, roomId);
     }
     catch (error) {
-        if (!isGoneError(error))
+        if (error instanceof MutationOutcomeUnknownError || error instanceof MutationPartialError)
             throw error;
+        if (completedRoomIds.length > 0) {
+            throw new MutationPartialError("delete", completedRoomIds, "room cleanup stopped");
+        }
+        throw error;
     }
-    removeRoomFromLocalStore(client, roomId);
-    markTreeDeleted(client, roomId);
 }
 /**
  * The SDK normally evicts a room as part of forget(). Keep the local-store
@@ -1134,10 +1114,11 @@ async function deleteTree(storage, treeId, options) {
             const removedRooms = getDeletedTreeIds(client);
             let graph;
             try {
-                // Re-read every locally visible room before taking the immutable graph
-                // snapshot. Local MSC3089 relations and memberships can lag another
-                // session; deleting from that stale view can orphan shared descendants.
-                await refreshDeletionRooms(storage, operation.signal);
+                // Re-read the candidate graph and any external parents it identifies
+                // before taking the immutable graph snapshot. Unrelated rooms are not
+                // part of this operation and must not block deletion merely because
+                // their membership is not joined.
+                await refreshDeletionRooms(storage, tree.id, operation.signal);
                 const spaces = snapshotTreeSpaces(tree, "delete graph is too large");
                 const activeSpaces = spaces.filter((space) => !removedRooms.has(space.id));
                 const ids = new Set(activeSpaces.map((space) => space.id));
@@ -1155,7 +1136,7 @@ async function deleteTree(storage, treeId, options) {
                     error instanceof MutationPartialError ||
                     error instanceof NonEmptyTreeError)
                     throw error;
-                if (error instanceof StorageError && error.message === "operation cancelled")
+                if (error instanceof StorageError)
                     throw error;
                 throw new StorageError("delete failed");
             }
@@ -1172,7 +1153,7 @@ async function deleteTree(storage, treeId, options) {
                 if (error instanceof StorageError && error.message === "delete graph unlink cleanup is incomplete") {
                     throw error;
                 }
-                if (error instanceof StorageError && error.message === "operation cancelled")
+                if (error instanceof StorageError)
                     throw error;
                 throw new StorageError("delete failed");
             }
@@ -1193,7 +1174,7 @@ async function deleteTree(storage, treeId, options) {
                     throw error;
                 if (error instanceof MutationPartialError)
                     throw error;
-                if (error instanceof StorageError && error.message === "operation cancelled")
+                if (error instanceof StorageError)
                     throw error;
                 throw new StorageError("delete failed");
             }

package/dist/core/validation.d.ts

@@ -1,3 +1,4 @@
-/** Small shared input validators kept out of the public core barrel. */
+/** Shared name contract used by SDK inputs and remote projections. */
 export declare const MAX_NAME_LENGTH = 512;
+export declare function isValidName(value: unknown): value is string;
 export declare function validateName(value: unknown, label: string): asserts value is string;

package/dist/core/validation.js

@@ -1,10 +1,13 @@
-/** Small shared input validators kept out of the public core barrel. */
+/** Shared name contract used by SDK inputs and remote projections. */
 export const MAX_NAME_LENGTH = 512;
+export function isValidName(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= MAX_NAME_LENGTH &&
+        !/[\u0000-\u001f\u007f]/.test(value));
+}
 export function validateName(value, label) {
-    if (typeof value !== "string" ||
-        value.length === 0 ||
-        value.length > MAX_NAME_LENGTH ||
-        /[\u0000-\u001f\u007f]/.test(value)) {
+    if (!isValidName(value)) {
         throw new Error(`invalid ${label}`);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telecrypt-io/storage",
-  "version": "0.5.26",
+  "version": "0.5.28",
   "license": "BUSL-1.1",
   "type": "module",
   "packageManager": "npm@11.19.0",