@telecrypt-io/storage 0.7.0 → 0.7.2

package/README.md

@@ -2,19 +2,9 @@
 
 [![npm](https://img.shields.io/npm/v/@telecrypt-io/storage)](https://www.npmjs.com/package/@telecrypt-io/storage)
 
-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.
-
-This repository publishes the library package from annotated version tags using npm Trusted
-Publishing. GitHub Releases identify the corresponding source version. The command-line client is
-maintained in its own repository.
+A JavaScript/TypeScript SDK for encrypted Matrix file trees, based on
+[MSC3089](https://github.com/matrix-org/matrix-spec-proposals/pull/3089), an open and currently
+unmerged Matrix proposal.
 
 ## Install
 
@@ -22,119 +12,79 @@ maintained in its own repository.
 npm install @telecrypt-io/storage
 ```
 
-This gives you the `TeleCryptIOStorage` library and its browser-safe `core` API.
-
-## Quick start
+## Browser quick start
 
-**Library:**
+The example below starts with an authenticated OIDC session. Obtain `userId`, `accessToken`, and
+`deviceId` from that completed session. `baseUrl` and `serverName` must come from trusted
+application configuration for the same Matrix deployment; do not accept them from an untrusted
+request.
 
 ```ts
 import { TeleCryptIOStorage } from "@telecrypt-io/storage";
 import * as core from "@telecrypt-io/storage/core";
 
+// baseUrl/serverName come from trusted application configuration.
+// userId/accessToken/deviceId come from completed OIDC authentication.
 const storage = await TeleCryptIOStorage.create({
-  baseUrl, userId, accessToken, deviceId,
+  baseUrl, serverName, userId, accessToken, deviceId,
 });
-const vault = await core.createVault(storage, "Photos");
-await core.uploadFile(storage, vault.id, "cat.jpg", bytes, "image/jpeg");
+try {
+  const vault = await core.createVault(storage, "Example");
+  const file = await core.uploadFile(
+    storage, vault.id, "hello.txt",
+    new TextEncoder().encode("Hello"), "text/plain",
+  );
+  const downloaded = await core.downloadFile(storage, vault.id, file.id);
+  console.log(new TextDecoder().decode(downloaded.bytes));
+} finally {
+  storage.getClient().stopClient();
+}
 ```
 
-The recommended constructors configure the Matrix client with the SDK's manual-redirect transport
-and finite request deadline. The public `new TeleCryptIOStorage(client)` constructor is
-an advanced escape hatch: it does not rewrite matrix-js-sdk internals. Callers using it must build
-the client through matrix-js-sdk's supported `createClient` options (`fetchFn` and
-`localTimeoutMs`) and remain responsible for the safety of other Matrix SDK requests. SDK methods
-that need the authenticated transport fail closed when it is unavailable; they do not silently
-install a private transport configuration.
-
-Same-name vault/folder creation is serialized within one `TeleCryptIOStorage` instance, but
-each call creates a distinct room. Display names are labels, not identities, and Matrix
-provides no server-side room-creation idempotency key.
-
-## OIDC API
-
-The SDK owns the browser authorization-code PKCE context in `sessionStorage` and provides device-code,
-discovery, dynamic registration, identity confirmation, and refresh helpers. OAuth metadata, token
-scopes, Matrix user/device identities, redirects, and complete response bodies are validated before
-they are returned. Network-bound helpers accept `AbortSignal` where cancellation is meaningful; token
-refresh uses a public client and persists the resulting token pair through the caller's callback.
-
-The command-line client is sourced by
-[`TeleCrypt-io/storage-cli`](https://github.com/TeleCrypt-io/storage-cli). The static web
-application is sourced by
-[`TeleCrypt-io/storage.telecrypt.io`](https://github.com/TeleCrypt-io/storage.telecrypt.io).
-
-### 0.5 OIDC migration
-
-Version 0.5 targets Matrix JS SDK 42 and the stable Matrix OAuth metadata endpoint. Existing
-integrations must use the current `createFromOidc` options and pass the confirmed Matrix user ID,
-device ID, and access token returned by the login flow. Replace old Matrix SDK OIDC imports and
-private HTTP discovery with `discoverOidcIssuer`, `registerClient`, the device-code or PKCE flow
-helpers, and `whoAmI` from `core/oidc`; the discovery URL is the stable
-`/_matrix/client/v1/auth_metadata` endpoint. Refresh integration uses
-`buildTokenRefreshFunction` as the current `tokenRefreshFunction` callback and must persist the
-returned token pair before reporting success. The SDK no longer carries pre-0.5 compatibility
-paths, so no adapter-side shim is required or supported. Discovery accepts providers that omit
-`revocation_endpoint`; revocation is only an opportunistic cleanup path after refresh persistence
-fails. Device-code sessions retain their requested device ID in-process; callers that reconstruct a
-session must pass its expected device ID to `waitForDeviceCodeLogin`. `buildTokenRefreshFunction`
-always requires the expected device ID because a reconstructed refresh callback has no safe implicit
-binding. Returned OAuth scopes are rejected unless they match that intended Matrix device exactly.
-
-## How it works
-
-Built on [MSC3089](https://github.com/matrix-org/matrix-spec-proposals/pull/3089), which models
-a file tree using Matrix primitives:
-
-| Storage concept | Matrix concept |
-|---|---|
-| Vault | A Space (room marked as a file tree) |
-| Folder | A child Space |
-| File | An event pointing at encrypted uploaded content |
-| Sharing | Room invitation |
-| Permissions | Power levels |
-
-### Deletion
-
-Vaults and folders are deleted only when they are empty. Delete each file first; deleting a file
-also removes its encrypted media object before redacting its Matrix event. Delete empty child
-folders before deleting their parent. A nonempty delete
-fails with `NonEmptyTreeError`, so a shared or nested tree is never removed implicitly.
-
-Encryption uses the same scheme as Matrix attachments (AES-CTR with a per-file key, keys
-distributed via the room's Megolm session). File deletion uses TeleCrypt's authenticated Synapse
-storage extension to remove the local media object before Matrix redaction; stock
-Synapse without that extension cannot provide the SDK deletion contract.
-
-## Development
+`TeleCryptIOStorage.create` initializes the Matrix client and its persistent browser crypto store
+by default. Browser persistence uses IndexedDB and the Matrix Rust crypto WASM runtime, so this
+example assumes a browser environment. OIDC discovery, login, refresh, and the corresponding
+`createFromOidc` inputs are exported from `@telecrypt-io/storage/core`.
 
-```bash
-npm ci --ignore-scripts --no-fund --no-audit
-npm run test:unit      # unit-only checks; does not start Podman
-npm run synapse:up     # disposable local Synapse/MAS fixture
-npm test               # full SDK suite, including fixture-backed functional tests
-```
+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.
+
+## Storage model and behavior
+
+The SDK maps the file tree to Matrix primitives defined by MSC3089:
 
-The full suite uses the real local Synapse/MAS/Postgres fixture in Podman at `localhost:8008`, never
-a production server. This is the shared fixture for the SDK, CLI, and Web functional/e2e suites;
-start it from this checkout and reuse it for the sibling repositories. Unit tests may use mocks for
-isolated boundaries, but they do not replace the real-stack checks.
+- A vault is a Matrix Space room marked as a file tree.
+- A folder is a child Space in that tree.
+- A file is a Matrix event referring to encrypted uploaded content.
+- Sharing uses Matrix room invitations and permissions use Matrix power levels.
 
-If setup or tests fail, inspect the relevant logs, then run `npm run synapse:down` when finished.
+Vault, folder, and file IDs are opaque Matrix room and event IDs. Names are display labels: two
+objects with the same name are still distinct, and a name is not an idempotency key.
 
-After a successful run, use `npm run synapse:down` for scoped teardown. Use
-`./throwaway_synapse/down.sh --wipe` only when a complete fixture reset is explicitly required.
+File bytes are encrypted in the client before upload with Matrix attachment encryption (AES-CTR
+and a per-file key distributed through the room's Megolm session). The server stores encrypted
+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.
 
-See [RELEASING.md](./RELEASING.md) for the npm release procedure.
+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.
 
-## Licence
+Deletion has strict ordering. Delete files before their folders or vaults because folders and
+vaults must be empty. File deletion removes the encrypted media object before redacting its Matrix
+event and requires TeleCrypt's Synapse storage extension; stock Synapse cannot provide that
+deletion contract.
 
-[Business Source License 1.1](./LICENSE). Non-commercial use is permitted; converts to
-Apache License 2.0 on 2030-07-20.
+## Source repositories
 
-For commercial licensing, contact TeleCrypt.io.
+- Web application: [`TeleCrypt-io/storage`](https://github.com/TeleCrypt-io/storage)
+- Command-line client: [`cli/`](https://github.com/TeleCrypt-io/storage/tree/main/cli)
 
-## Third-party code
+## License
 
-- [`matrix-js-sdk`](https://github.com/matrix-org/matrix-js-sdk) — Apache-2.0 — dependency
-- [`matrix-encrypt-attachment`](https://github.com/matrix-org/matrix-encrypt-attachment) — Apache-2.0 — dependency
+See [`LICENSE`](./LICENSE) for the complete terms. The current license is Business Source License
+1.1 with an additional grant for non-commercial use; it is not an open-source license. The stated
+Change Date is 2030-07-20, and the Change License is Apache License 2.0. The license also changes
+on the fourth anniversary of the first public distribution of a specific version if that occurs
+before its stated Change Date. The full license controls in case of any discrepancy.

package/dist/TeleCryptIOStorage.d.ts

@@ -26,6 +26,8 @@ export interface TreeSpace {
 }
 export interface FileBranch {
     readonly id: string;
+    /** Current MSC3089 branch/listing event. Its event ID is distinct from `id` (the state key). */
+    readonly indexEvent?: Pick<MatrixEvent, "getId">;
     /** Matrix SDK keeps a redacted branch in state as an inactive object. */
     readonly isActive?: boolean;
     getName(): string;

package/dist/TeleCryptIOStorage.js

@@ -1,4 +1,4 @@
-import { ClientEvent, createClient, EventType, MatrixEvent, MatrixError, Preset, RoomCreateTypeField, RoomType, SyncState, UNSTABLE_MSC3088_ENABLED, UNSTABLE_MSC3088_PURPOSE, UNSTABLE_MSC3089_TREE_SUBTYPE, } from "matrix-js-sdk";
+import { ClientEvent, createClient, EventType, MatrixEvent, MatrixError, Preset, RoomCreateTypeField, RoomType, SyncState, UNSTABLE_MSC3088_ENABLED, UNSTABLE_MSC3088_PURPOSE, UNSTABLE_MSC3089_BRANCH, UNSTABLE_MSC3089_TREE_SUBTYPE, } 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 { encryptAttachment, decryptAttachment } from "matrix-encrypt-attachment";
@@ -1036,19 +1036,22 @@ export class TeleCryptIOStorage {
                 invite: 100,
                 kick: 100,
                 ban: 100,
-                redact: 50,
-                state_default: 50,
-                events_default: 50,
+                redact: 100,
+                state_default: 0,
+                events_default: 0,
                 users_default: 0,
                 events: {
                     [EventType.RoomPowerLevels]: 100,
                     [EventType.RoomHistoryVisibility]: 100,
                     [EventType.RoomTombstone]: 100,
                     [EventType.RoomEncryption]: 100,
-                    [EventType.RoomName]: 50,
-                    [EventType.RoomMessage]: 50,
-                    [EventType.RoomMessageEncrypted]: 50,
-                    [EventType.Sticker]: 50,
+                    [EventType.RoomName]: 100,
+                    [EventType.RoomMessage]: 0,
+                    [EventType.RoomMessageEncrypted]: 0,
+                    [EventType.Sticker]: 0,
+                    [EventType.SpaceChild]: 100,
+                    [EventType.SpaceParent]: 100,
+                    [UNSTABLE_MSC3089_BRANCH.name]: 100,
                 },
                 users: { [userId]: 100 },
             },

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.d.ts

@@ -31,7 +31,7 @@ export declare function declineInvite(storage: TeleCryptIOStorage, vaultId: stri
     vaultId: string;
     declined: boolean;
 }>;
-/** Invites `userId` to the vault and applies the requested role. */
+/** Invites `userId` to the vault as a reader. */
 export declare function shareVault(storage: TeleCryptIOStorage, vaultId: string, userId: string, role: string, options?: OperationOptions): Promise<ShareResult>;
 export declare function unshareVault(storage: TeleCryptIOStorage, vaultId: string, userId: string, options?: OperationOptions): Promise<UnshareResult>;
 export declare function listMembers(storage: TeleCryptIOStorage, vaultId: string, options?: OperationOptions): Promise<Member[]>;

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"))) {
@@ -798,10 +728,10 @@ export async function declineInvite(storage, vaultId, options) {
         return { vaultId, declined: true };
     }, "mutation");
 }
-/** Invites `userId` to the vault and applies the requested role. */
+/** Invites `userId` to the vault as a reader. */
 export async function shareVault(storage, vaultId, userId, role, options) {
-    if (role !== "viewer" && role !== "editor") {
-        throw new StorageError("invalid --role (must be viewer or editor)");
+    if (role !== "viewer") {
+        throw new StorageError("storage sharing supports viewers only");
     }
     const operation = createOperationDeadline(options);
     const completedRoomIds = new Set();
@@ -824,6 +754,12 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                 }
                 for (const [index, space] of spaces.entries()) {
                     ensureOperationActive(operation.signal);
+                    const members = index === 0
+                        ? currentMembers
+                        : await withRateLimitRetry(() => storage.listMembers(space, { signal: operation.signal }), operation.signal);
+                    if (members.some((member) => member.userId === userId && member.role === "owner")) {
+                        throw new StorageError("share will not demote an existing owner");
+                    }
                     const currentMembership = index === 0
                         ? currentMembers.find((member) => member.userId === userId)?.membership
                         : await storage.getRoomMembership(space.id, userId, {
@@ -848,17 +784,10 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                             throw new StorageError("share failed");
                     }
                 }
-                for (const space of spaces) {
-                    ensureOperationActive(operation.signal);
-                    const members = space.id === tree.id
-                        ? currentMembers
-                        : await withRateLimitRetry(() => storage.listMembers(space, { signal: operation.signal }), operation.signal);
-                    if (members.some((member) => member.userId === userId && member.role === "owner")) {
-                        throw new StorageError("share will not demote an existing owner");
-                    }
-                    await withRateLimitRetry(() => withMatrixMutationAbort(() => space.setPermissions(userId, role), operation.signal), operation.signal);
-                    completedRoomIds.add(space.id);
-                }
+                // 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
+                // let metadata authorship drift away from the owner.
             }
             catch (error) {
                 if (error instanceof MutationOutcomeUnknownError)
@@ -875,7 +804,7 @@ export async function shareVault(storage, vaultId, userId, role, options) {
                 }
                 throw new StorageError("share failed", { cause: error });
             }
-            return { vaultId, userId, role };
+            return { vaultId, userId, role: "viewer" };
         }, operation.signal);
         return await raceOperationDeadline(operation, pending, "mutation");
     }
@@ -1062,38 +991,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 +1015,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", {
@@ -1201,9 +1109,17 @@ export async function deleteFile(storage, treeId, fileId, options) {
         const completedIds = [];
         try {
             const client = storage.getClient();
+            // MSC3089 uses the file event ID as the branch state key, but the current
+            // listing is a separate state event. Redact that current listing after
+            // clearing the branch state; redacting only the file event leaves the
+            // listing visible and is especially harmful when a user is suspended.
+            const listingEventId = branch.indexEvent?.getId?.() ?? branch.id;
+            if (typeof listingEventId !== "string" || listingEventId.length === 0) {
+                throw new StorageError("encrypted file has no listing event identifier");
+            }
             await withRateLimitRetry(() => withMatrixMutationAbort(() => client.sendStateEvent(tree.id, UNSTABLE_MSC3089_BRANCH.name, {}, branch.id), signal, "delete file state"), signal);
-            await withRateLimitRetry(() => withMatrixMutationAbort(() => client.redactEvent(tree.id, branch.id), signal, "delete file event"), signal);
-            completedIds.push(branch.id);
+            await withRateLimitRetry(() => withMatrixMutationAbort(() => client.redactEvent(tree.id, listingEventId), signal, "delete file event"), signal);
+            completedIds.push(listingEventId);
         }
         catch (error) {
             if (error instanceof MutationOutcomeUnknownError)

package/package.json

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