@telecrypt-io/storage 0.7.1 → 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.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
-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/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

@@ -728,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();
@@ -754,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, {
@@ -778,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)
@@ -805,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");
     }
@@ -1110,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.1",
+  "version": "0.7.2",
   "license": "BUSL-1.1",
   "type": "module",
   "packageManager": "npm@11.19.0",