@telecrypt-io/storage 0.7.0 → 0.7.1

package/README.md

@@ -5,7 +5,7 @@
 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
+[telecrypt-io.github.io/llms-authority/llms.txt](https://telecrypt-io.github.io/llms-authority/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

package/dist/core/constants.d.ts

@@ -9,6 +9,8 @@ export declare const MAX_MATRIX_IDENTIFIER_BYTES = 255;
  * backend hostname that differs from the user-visible Matrix server name.
  */
 export declare function validateCanonicalMatrixUserId(value: unknown, serverName: unknown): string;
+/** Validates a Matrix user ID without binding it to a particular homeserver. */
+export declare function validateMatrixUserId(value: unknown): string;
 export declare function validateMatrixDeviceId(value: unknown): string;
 export declare function validateMatrixRoomId(value: unknown, name?: string): string;
 export declare function validateMatrixEventId(value: unknown, name?: string): string;

package/dist/core/constants.js

@@ -15,17 +15,25 @@ const MATRIX_EVENT_ID_PATTERN = /^\$[A-Za-z0-9._~:/+\-]+$/;
  * backend hostname that differs from the user-visible Matrix server name.
  */
 export function validateCanonicalMatrixUserId(value, serverName) {
-    if (typeof value !== "string" ||
-        new TextEncoder().encode(value).byteLength > MAX_MATRIX_IDENTIFIER_BYTES) {
-        throw new Error("invalid Matrix user ID");
-    }
+    const userId = validateMatrixUserId(value);
     if (typeof serverName !== "string" || !MATRIX_SERVER_NAME_REGEXP.test(serverName)) {
         throw new Error("invalid Matrix server name");
     }
-    const match = value.match(MATRIX_USER_ID_PATTERN);
+    const match = userId.match(MATRIX_USER_ID_PATTERN);
     if (!match || match[2].toLowerCase() !== serverName.toLowerCase()) {
         throw new Error("invalid Matrix user ID for this homeserver");
     }
+    return userId;
+}
+/** Validates a Matrix user ID without binding it to a particular homeserver. */
+export function validateMatrixUserId(value) {
+    if (typeof value !== "string" ||
+        new TextEncoder().encode(value).byteLength > MAX_MATRIX_IDENTIFIER_BYTES) {
+        throw new Error("invalid Matrix user ID");
+    }
+    if (!MATRIX_USER_ID_PATTERN.test(value)) {
+        throw new Error("invalid Matrix user ID");
+    }
     return value;
 }
 export function validateMatrixDeviceId(value) {

package/dist/core/index.d.ts

@@ -4,4 +4,6 @@ export * from "./operations.js";
 export * from "./errors.js";
 export * from "./oidc.js";
 export * from "./constants.js";
+export { cancelResponseBody, readResponseBody, ResponseBodyReadError } from "./http.js";
+export type { ResponseBody, ResponseBodyOptions } from "./http.js";
 export { isValidName, validateName } from "./validation.js";

package/dist/core/index.js

@@ -4,4 +4,5 @@ export * from "./operations.js";
 export * from "./errors.js";
 export * from "./oidc.js";
 export * from "./constants.js";
+export { cancelResponseBody, readResponseBody, ResponseBodyReadError } from "./http.js";
 export { isValidName, validateName } from "./validation.js";

package/dist/core/oidc.d.ts

@@ -34,6 +34,8 @@ export type OidcTokenEndpointMetadata = Pick<OidcClientConfig, "issuer" | "token
  * identifiers, or control characters from an untrusted response to cross the
  * SDK boundary. */
 export declare function sanitizeDiagnosticText(value: string): string;
+/** Validates an endpoint against the configured homeserver and optional issuer path. */
+export declare function assertOidcEndpoint(value: unknown, trustedHomeserver: string, name: string, issuer?: URL, allowQuery?: boolean): string;
 /**
  * Discovers the OIDC/MAS issuer and endpoints for a homeserver via the
  * Matrix client's stable `/auth_metadata` endpoint. Matrix 42 performs this

package/dist/core/oidc.js

@@ -382,7 +382,7 @@ function abortableDelay(milliseconds, signal) {
         schedule();
     });
 }
-function parseHttpUrl(value, name) {
+function parseHttpUrl(value, name, allowQuery = false) {
     const text = requireOpaqueString(value, name);
     let parsed;
     try {
@@ -396,7 +396,7 @@ function parseHttpUrl(value, name) {
         (parsed.protocol === "http:" && !isLoopbackHostname(parsed.hostname)) ||
         parsed.username !== "" ||
         parsed.password !== "" ||
-        parsed.search !== "" ||
+        (!allowQuery && parsed.search !== "") ||
         parsed.hash !== "" ||
         (parsed.toString() !== text && !isRootWithoutSlash)) {
         throw new StorageError(`OIDC authorization context has an invalid ${name}`);
@@ -409,6 +409,15 @@ function isWithinIssuerPath(issuer, endpoint) {
     const prefix = issuer.pathname.endsWith("/") ? issuer.pathname : `${issuer.pathname}/`;
     return endpoint.pathname === issuer.pathname || endpoint.pathname.startsWith(prefix);
 }
+/** Validates an endpoint against the configured homeserver and optional issuer path. */
+export function assertOidcEndpoint(value, trustedHomeserver, name, issuer, allowQuery = false) {
+    const homeserver = parseHttpUrl(trustedHomeserver, "homeserver URL");
+    const endpoint = parseHttpUrl(value, name, allowQuery);
+    if (endpoint.origin !== homeserver.origin || (issuer && !isWithinIssuerPath(issuer, endpoint))) {
+        throw new StorageError(`${name} must remain on the configured OIDC origin and issuer path`);
+    }
+    return endpoint.toString();
+}
 function matrixAuthMetadataEndpoint(homeserver) {
     const basePath = homeserver.pathname.replace(/\/+$/u, "");
     return new URL(`${basePath}/_matrix/client/v1/auth_metadata`, homeserver.origin).toString();
@@ -640,7 +649,12 @@ export async function discoverOidcIssuer(homeserverBaseUrl, signal) {
             throw failure;
         }
         ensureOidcNotCancelled(signal, "discovery");
-        return validateTrustedAuthMetadata(body);
+        try {
+            return validateTrustedAuthMetadata(body);
+        }
+        catch (error) {
+            throw responseValidationFailure("discovery", response, responseText ?? "", error);
+        }
     }
     catch (err) {
         if (err instanceof AggregateError)
@@ -1100,14 +1114,20 @@ export async function whoAmI(homeserverUrl, accessToken, serverName, signal) {
         if (!isRecord(body)) {
             throw responseValidationFailure("identity confirmation", response, responseText ?? "", new StorageError("OIDC identity confirmation returned an invalid response"));
         }
-        const userId = validateMatrixUserId(body.user_id, serverName);
+        let userId;
+        try {
+            userId = validateMatrixUserId(body.user_id, serverName);
+        }
+        catch (error) {
+            throw responseValidationFailure("identity confirmation", response, responseText ?? "", error);
+        }
         let deviceId = null;
         if (body.device_id !== undefined && body.device_id !== null) {
             try {
                 deviceId = validateMatrixDeviceId(body.device_id);
             }
             catch (error) {
-                throw new StorageError("OIDC identity confirmation returned an invalid device ID", { cause: error });
+                throw responseValidationFailure("identity confirmation", response, responseText ?? "", new StorageError("OIDC identity confirmation returned an invalid device ID", { cause: error }));
             }
         }
         if (signal?.aborted)

package/dist/core/operations.js

@@ -17,7 +17,7 @@ import { Method } from "matrix-js-sdk/lib/http-api/method.js";
 import { FileTooLargeError, MutationPartialError, MutationOutcomeUnknownError, NonEmptyTreeError, RoomCreationAmbiguousError, RoomCleanupIncompleteError, StorageError, } from "./errors.js";
 import { ConditionTimeoutError, waitForCondition } from "./poll.js";
 import { validateName } from "./validation.js";
-import { getDeletedTreeIds, isFileDeleted, isTreeDeleted, markFileDeleted, markTreeDeleted, } from "../deletion-markers.js";
+import { isFileDeleted, isTreeDeleted, markFileDeleted, markTreeDeleted, } from "../deletion-markers.js";
 /**
  * Production Synapse enforces the built-in rc_messages budget (per-account
  * burst 10, refill 1/5s) on every room/state mutation the tree operations
@@ -204,9 +204,7 @@ async function resolveFile(storage, tree, fileId, signal) {
  * room. This also prevents a folder/vault delete from silently deleting a
  * nested shared tree.
  */
-function assertTreeEmptyForDeletion(storage, tree, spaces) {
-    if (spaces.length !== 1)
-        throw new NonEmptyTreeError(tree.id);
+function assertTreeEmptyForDeletion(storage, tree) {
     let files;
     try {
         files = tree.listFiles().filter((file) => !isMarkedFileDeleted(storage, tree.id, file.id));
@@ -216,40 +214,74 @@ function assertTreeEmptyForDeletion(storage, tree, spaces) {
     }
     if (files.length > 0)
         throw new NonEmptyTreeError(tree.id);
+    const childEvents = readRelationEvents(storage.getClient(), tree.id, EventType.SpaceChild);
+    if (childEvents === null)
+        throw new StorageError("could not enumerate storage folders safely");
+    for (const event of childEvents) {
+        if (!isActiveRelationEvent(event))
+            continue;
+        const childId = relationStateKey(event);
+        if (!childId)
+            throw new StorageError("could not enumerate storage folders safely");
+        if (!isTreeDeleted(storage.getClient(), childId))
+            throw new NonEmptyTreeError(tree.id);
+    }
 }
 async function refreshDeletionRooms(storage, rootId, signal) {
     const client = storage.getClient();
-    const http = client.http;
-    // A real MatrixClient always exposes its authenticated HTTP transport. A
-    // client without one cannot prove that its local relation graph is current.
-    if (typeof http?.authedRequest !== "function") {
-        throw new StorageError("delete graph refresh is unavailable");
-    }
     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");
+        throw new StorageError("could not enumerate storage parent safely");
     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");
+            throw new StorageError("could not enumerate storage parent safely");
         if (parentId !== rootId)
             parentIds.add(parentId);
     }
     if (parentIds.size > 1)
-        throw new StorageError("delete graph is unsafe");
-    const parentId = parentIds.values().next().value;
-    if (parentId)
-        await storage.refreshRoomState(parentId, { signal });
+        throw new StorageError("storage room has multiple parents");
+    const parents = [...parentIds];
+    if (parents[0]) {
+        await storage.refreshRoomState(parents[0], { signal });
+        const childEvents = readRelationEvents(client, parents[0], EventType.SpaceChild, rootId);
+        if (childEvents === null ||
+            !childEvents.some((event) => isActiveRelationEvent(event) && relationStateKey(event, rootId) === rootId)) {
+            throw new StorageError("storage parent relation is inconsistent");
+        }
+    }
     if (signal?.aborted)
         throw new StorageError("operation cancelled");
+    return parents;
+}
+function snapshotTreeSpaces(root) {
+    const spaces = [];
+    const seen = new Set();
+    const pending = [root];
+    while (pending.length > 0) {
+        const tree = pending.pop();
+        if (!tree || seen.has(tree.id))
+            continue;
+        seen.add(tree.id);
+        spaces.push(tree);
+        let children;
+        try {
+            children = tree.getDirectories();
+        }
+        catch (error) {
+            if (error instanceof StorageError)
+                throw error;
+            throw new StorageError("could not enumerate storage folders", { cause: error });
+        }
+        pending.push(...children);
+    }
+    return spaces;
 }
 async function refreshTreeSpaces(storage, spaces, signal) {
     for (const space of spaces) {
@@ -280,126 +312,24 @@ function isActiveRelationEvent(event) {
 function activeTreeDirectories(client, tree) {
     const childEvents = readRelationEvents(client, tree.id, EventType.SpaceChild);
     if (childEvents === null)
-        throw new StorageError("delete graph is unsafe");
+        throw new StorageError("storage folder state is unavailable");
     const activeChildIds = new Set();
     for (const event of childEvents) {
         if (!isActiveRelationEvent(event))
             continue;
         const childId = relationStateKey(event);
         if (!childId)
-            throw new StorageError("delete graph is unsafe");
+            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("delete graph is unsafe");
+            throw new StorageError("storage folder state is inconsistent");
         return child;
     });
 }
-function snapshotTreeSpaces(root, activeRelationClient) {
-    const spaces = [];
-    const seen = new Set();
-    const pending = [root];
-    while (pending.length > 0) {
-        const tree = pending.pop();
-        if (!tree)
-            continue;
-        if (seen.has(tree.id))
-            continue;
-        seen.add(tree.id);
-        spaces.push(tree);
-        let children;
-        try {
-            children = activeRelationClient
-                ? activeTreeDirectories(activeRelationClient, tree)
-                : tree.getDirectories();
-        }
-        catch (error) {
-            if (error instanceof StorageError)
-                throw error;
-            throw new StorageError("could not enumerate storage space descendants safely", { cause: error });
-        }
-        for (const child of children)
-            pending.push(child);
-    }
-    return spaces;
-}
-/**
- * Deletion is intentionally narrower than MSC3089TreeSpace.delete(): a local
- * child graph is not proof that the rooms are exclusively owned by this tree.
- * Validate every observed edge in both directions and reject any parent or
- * child edge outside the exact deletion set before the first mutation.
- */
-function validateDeletionGraph(client, root, ids, deletedRooms) {
-    const edges = new Set();
-    const externalParents = [];
-    const addEdge = (parentId, childId) => {
-        if (deletedRooms.has(childId))
-            return;
-        if (!ids.has(childId))
-            throw new StorageError("delete graph is unsafe");
-        edges.add(`${parentId}\u0000${childId}`);
-    };
-    for (const id of ids) {
-        const tree = client.unstableGetFileTreeSpace(id);
-        if (!tree)
-            throw new StorageError("delete graph is unsafe");
-        const directories = activeTreeDirectories(client, tree);
-        for (const child of directories)
-            addEdge(id, child.id);
-        const childEvents = readRelationEvents(client, id, 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");
-            addEdge(id, childId);
-        }
-    }
-    for (const edge of edges) {
-        const separator = edge.indexOf("\u0000");
-        const parentId = edge.slice(0, separator);
-        const childId = edge.slice(separator + 1);
-        const childLink = readRelationEvents(client, parentId, EventType.SpaceChild, childId);
-        const parentLink = readRelationEvents(client, childId, EventType.SpaceParent, parentId);
-        if (!childLink?.some((event) => isActiveRelationEvent(event) && relationStateKey(event, childId) === childId) ||
-            !parentLink?.some((event) => isActiveRelationEvent(event) && relationStateKey(event, parentId) === parentId)) {
-            throw new StorageError("delete graph is unsafe");
-        }
-    }
-    for (const id of ids) {
-        const parentEvents = readRelationEvents(client, id, EventType.SpaceParent);
-        if (parentEvents === null)
-            throw new StorageError("delete graph is unsafe");
-        for (const event of parentEvents) {
-            if (!isActiveRelationEvent(event))
-                continue;
-            const parentId = relationStateKey(event);
-            if (!parentId)
-                throw new StorageError("delete graph is unsafe");
-            if (!ids.has(parentId)) {
-                if (id !== root.id || externalParents.includes(parentId)) {
-                    throw new StorageError("delete graph is unsafe");
-                }
-                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");
-                }
-                externalParents.push(parentId);
-            }
-        }
-    }
-    if (!ids.has(root.id))
-        throw new StorageError("delete graph is unsafe");
-    if (externalParents.length > 1)
-        throw new StorageError("delete graph is unsafe");
-    return { externalParents };
-}
 async function unlinkExternalParents(storage, rootId, externalParents, signal) {
     const client = storage.getClient();
     let mutationAttempted = false;
@@ -481,10 +411,10 @@ async function deleteRoomDeterministically(storage, roomId, signal) {
         const client = storage.getClient();
         const tree = storage.getTree(roomId);
         if (!tree)
-            throw new StorageError("delete graph is unsafe");
+            throw new StorageError("storage room is unavailable for deletion");
         const self = client.getUserId();
         if (!self)
-            throw new StorageError("delete graph is unsafe");
+            throw new StorageError("Matrix user identity is unavailable");
         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"))) {
@@ -1062,38 +992,20 @@ async function deleteTree(storage, treeId, options) {
             if (isTreeDeleted(client, treeId))
                 return { id: treeId, deleted: true };
             const tree = await resolveTree(storage, treeId, operation.signal);
-            // Read reconciliation state after this operation reaches the single
-            // client queue; a preceding delete may have populated the set while we
-            // were waiting for its turn.
-            const removedRooms = getDeletedTreeIds(client);
-            let graph;
+            let externalParents;
             try {
-                // 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, client);
-                const activeSpaces = spaces.filter((space) => !removedRooms.has(space.id));
-                const ids = new Set(activeSpaces.map((space) => space.id));
-                if (!ids.has(tree.id)) {
-                    if (removedRooms.has(tree.id)) {
-                        return { id: treeId, deleted: true };
-                    }
-                    throw new StorageError("delete graph is unsafe");
-                }
-                assertTreeEmptyForDeletion(storage, tree, activeSpaces);
-                graph = validateDeletionGraph(client, tree, ids, removedRooms);
+                // Deletion owns one room. Refresh its current state and its one
+                // supported parent before checking files/folders or changing links.
+                externalParents = await refreshDeletionRooms(storage, tree.id, operation.signal);
+                assertTreeEmptyForDeletion(storage, tree);
             }
             catch (error) {
                 if (error instanceof StorageError)
                     throw error;
                 throw new StorageError("delete failed", { cause: error });
             }
-            // Keep external parent links intact until the room deletion succeeds.
-            // Unlinking first would silently detach a live vault on failure.
             try {
-                await unlinkExternalParents(storage, tree.id, graph.externalParents, operation.signal);
+                await unlinkExternalParents(storage, tree.id, externalParents, operation.signal);
             }
             catch (error) {
                 if (error instanceof StorageError)
@@ -1104,11 +1016,8 @@ async function deleteTree(storage, treeId, options) {
                 await deleteRoomDeterministically(storage, tree.id, operation.signal);
             }
             catch (error) {
-                // The root is still live when its relation is removed. If deletion then
-                // fails, restore both sides before reporting failure; otherwise a live
-                // vault would be silently detached from its external parent.
                 try {
-                    await relinkExternalParents(storage, tree.id, graph.externalParents, new AbortController().signal);
+                    await relinkExternalParents(storage, tree.id, externalParents, new AbortController().signal);
                 }
                 catch (cleanupError) {
                     throw new StorageError("delete cleanup is incomplete", {

package/package.json

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