@telecrypt-io/storage 0.3.0 → 0.5.7

package/README.md

@@ -5,16 +5,17 @@
 End-to-end encrypted file storage and sharing, built on Matrix.
 
 Files are encrypted on the client before upload. The server stores only opaque ciphertext and
-never holds the decryption keys. Shared folders let multiple people add and read files, and a
+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 protected exact-version tags with NPM Trusted
-Publishing/OIDC provenance. The command-line client is maintained in its own repository.
+This repository publishes the library package from annotated exact-version tags whose resulting
+GitHub Release is immutable, with NPM Trusted Publishing/OIDC provenance. The command-line client
+is maintained in its own repository.
 
 ## Install
 
 ```bash
-npm install @telecrypt-io/storage@0.3.0
+npm install @telecrypt-io/storage@0.5.7
 ```
 
 This gives you the `TeleCryptIOStorage` library and its browser-safe `core` API.
@@ -30,40 +31,86 @@ import * as core from "@telecrypt-io/storage/core";
 const storage = await TeleCryptIOStorage.create({
   baseUrl, userId, accessToken, deviceId,
 });
-const folder = await core.createFolder(storage, "Photos");
-await core.uploadFile(storage, folder.id, "cat.jpg", bytes, "image/jpeg");
+const vault = await core.createVault(storage, "Photos");
+await core.uploadFile(storage, vault.id, "cat.jpg", bytes, "image/jpeg");
 ```
 
+The recommended constructors configure the Matrix client with the SDK's bounded, 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 response bodies are validated and bounded 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:
 
-| File-system concept | Matrix concept |
+| Storage concept | Matrix concept |
 |---|---|
-| Folder | A Space (room marked as a file tree) |
-| Subfolder | A child Space |
+| Vault | A Space (room marked as a file tree) |
+| Folder | A child Space |
 | File | An event pointing at encrypted uploaded content |
 | Version | A newer event superseding the old |
 | 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 complete Matrix version chain and reports a typed partial result if cleanup stops
+after some versions. 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). Requires no server-side changes — it runs against
-stock Synapse.
+distributed via the room's Megolm session). File deletion uses TeleCrypt's authenticated Synapse
+storage extension to remove the local media and thumbnail objects before Matrix redaction; stock
+Synapse without that extension cannot provide the SDK deletion contract.
 
 ## Development
 
 ```bash
-npm ci
+npm ci --ignore-scripts --no-fund --no-audit
 npm run synapse:up     # disposable local Synapse/MAS fixture
 npm test
 npm run synapse:down
+# For a complete reset, use ./throwaway_synapse/down.sh --wipe.
 ```
 
 Tests run against a real local Synapse/MAS fixture in Podman, never against a production server.
@@ -80,6 +127,4 @@ For commercial licensing, contact TeleCrypt.io.
 ## Third-party code
 
 - [`matrix-js-sdk`](https://github.com/matrix-org/matrix-js-sdk) — Apache-2.0 — dependency
-- [`matrix-files-sdk`](https://github.com/matrix-org/matrix-files-sdk) — Apache-2.0 — reference
-- [`files-sdk-demo`](https://github.com/vector-im/files-sdk-demo) — AGPL-3.0 — **not used**;
-  incompatible with this project's licence
+- [`matrix-encrypt-attachment`](https://github.com/matrix-org/matrix-encrypt-attachment) — Apache-2.0 — dependency

package/dist/TeleCryptIOStorage.d.ts

@@ -1,6 +1,7 @@
 import { MatrixClient } from "matrix-js-sdk";
 import type { CryptoCallbacks } from "matrix-js-sdk/lib/crypto-api/index.js";
 import type { TokenRefreshFunction } from "matrix-js-sdk/lib/http-api/index.js";
+import type { RecoveryStatus } from "./core/types.js";
 export interface TreeSpace {
     readonly id: string;
     readonly room: {
@@ -20,7 +21,7 @@ export interface TreeSpace {
     getFile(fileEventId: string): FileBranch | null;
     listFiles(): FileBranch[];
     listAllFiles(): FileBranch[];
-    createFile(name: string, encryptedContents: Buffer | ArrayBuffer | Uint8Array, info: Record<string, unknown>, additionalContent?: Record<string, unknown>): Promise<{
+    createFile(name: string, encryptedContents: ArrayBuffer | Uint8Array, info: Record<string, unknown>, additionalContent?: Record<string, unknown>): Promise<{
         event_id: string;
     }>;
 }
@@ -39,13 +40,15 @@ export interface FileBranch {
         getContent: () => Record<string, unknown>;
     }>;
     getVersionHistory(): Promise<FileBranch[]>;
-    createNewVersion(name: string, encryptedContents: Buffer | ArrayBuffer | Uint8Array, info: Record<string, unknown>, additionalContent?: Record<string, unknown>): Promise<{
+    createNewVersion(name: string, encryptedContents: ArrayBuffer | Uint8Array, info: Record<string, unknown>, additionalContent?: Record<string, unknown>): Promise<{
         event_id: string;
     }>;
 }
 export interface CreateTeleCryptIOStorageOptions {
     /** Matrix homeserver base URL, e.g. "https://matrix.example.com". */
     baseUrl: string;
+    /** Independently trusted Matrix server name for this deployment. */
+    serverName: string;
     userId: string;
     accessToken: string;
     deviceId: string;
@@ -73,6 +76,8 @@ export interface CreateTeleCryptIOStorageOptions {
     initTimeoutMs?: number;
     /** Optional progress reporter for UI/CLI status lines during bootstrap. */
     onProgress?: (message: string) => void;
+    /** Cancels bootstrap and stops the owned MatrixClient before rejecting. */
+    signal?: AbortSignal;
     /**
      * Optional platform-supplied crypto callbacks (e.g. to source the secret
      * storage key from an OS keychain instead of prompting). `keys.setupRecovery`
@@ -91,6 +96,8 @@ export interface CreateTeleCryptIOStorageOptions {
  */
 export interface CreateFromOidcOptions {
     baseUrl: string;
+    /** Independently trusted Matrix server name for this deployment. */
+    serverName: string;
     userId: string;
     accessToken: string;
     deviceId: string;
@@ -99,10 +106,8 @@ export interface CreateFromOidcOptions {
      * refreshed mid-request. */
     refreshToken?: string;
     /** See `src/core/oidc.ts`'s `buildTokenRefreshFunction` — a plain
-     * `(refreshToken) => Promise<AccessTokens>`, deliberately NOT
-     * matrix-js-sdk's `OidcTokenRefresher` (see that file's doc comment for
-     * why: it requires `window.sessionStorage`, which doesn't exist under
-     * Node). */
+     * `(refreshToken) => Promise<AccessTokens>` that keeps token response
+     * validation and adapter-specific persistence in the shared core. */
     tokenRefreshFunction?: TokenRefreshFunction;
     persistentCryptoStore?: boolean;
     cryptoDatabasePrefix?: string;
@@ -110,10 +115,33 @@ export interface CreateFromOidcOptions {
     syncTimeoutMs?: number;
     initTimeoutMs?: number;
     onProgress?: (message: string) => void;
+    /** Cancels bootstrap and stops the owned MatrixClient before rejecting. */
+    signal?: AbortSignal;
     cryptoCallbacks?: CryptoCallbacks;
 }
+/** Waits for one Matrix mutation to settle without aborting the shared client.
+ * If cancellation arrives after the mutation starts, the outcome is explicitly
+ * unknown: the caller must reconcile and may safely retry idempotent work. */
+export declare function withMatrixMutationAbort<T>(_client: MatrixClient, operation: () => Promise<T>, signal?: AbortSignal, operationName?: string): Promise<T>;
+export interface MatrixRequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    /** Matrix SDK transport deadline, when making a direct authenticated request. */
+    localTimeoutMs?: number;
+    /** Internal Matrix SDK spelling used by `authedRequest`. */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Serializes all tree mutations for one MatrixClient. A single queue is
+ * intentional: separate per-room locks can deadlock when a parent mutation
+ * needs to inspect or update a child while another operation does the inverse.
+ * Each invocation still creates its own room; Matrix has no server-side
+ * room-creation idempotency key for MSC3089.
+ */
+export declare function withTreeMutation<T>(client: MatrixClient, operation: (signal?: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<T>;
 export declare class TeleCryptIOStorage {
     private client;
+    private readonly decoratedTreeSpaces;
     constructor(client: MatrixClient);
     /** The underlying matrix-js-sdk client (e.g. to stop it, or for advanced/interop use). */
     getClient(): MatrixClient;
@@ -123,7 +151,7 @@ export declare class TeleCryptIOStorage {
      * otherwise list a stale state snapshot immediately after another process
      * changed a file name or branch.
      */
-    refreshRoomState(roomId: string): Promise<void>;
+    refreshRoomState(roomId: string, options?: MatrixRequestOptions): Promise<void>;
     /**
      * Recommended entry point: builds the MatrixClient with a persistent crypto
      * store and the secret-storage callback wiring `keys.*` needs, starts the
@@ -135,21 +163,25 @@ export declare class TeleCryptIOStorage {
      * construction time (see `cryptoCallbacks` above for why: matrix-js-sdk
      * captures a single callbacks object at MatrixClient construction, so it
      * must exist before `initRustCrypto` runs, not be added afterwards).
-     */
+    */
     static create(opts: CreateTeleCryptIOStorageOptions): Promise<TeleCryptIOStorage>;
     /**
      * As `create()`, but the resulting `MatrixClient` was authenticated via
      * OIDC/MAS (device-code or authorization-code+PKCE — see
      * `src/core/oidc.ts`) rather than `m.login.password`. If `refreshToken` +
-     * `tokenRefresher` are both given, the client's `tokenRefreshFunction` is
+     * `tokenRefreshFunction` are both given, the client's `tokenRefreshFunction` is
      * wired so an expired access token is transparently refreshed mid-request
      * — same mechanism matrix-js-sdk uses for any refresh-token-capable login.
-     */
+    */
     static createFromOidc(opts: CreateFromOidcOptions): Promise<TeleCryptIOStorage>;
     /** Shared post-construction bootstrap for `create()`/`createFromOidc()`:
      * persistent crypto store, first sync, wrap in a `TeleCryptIOStorage`. */
     private static bootstrap;
+    private static throwIfAborted;
     private static withTimeout;
+    /** Bounds a Matrix mutation without cancelling a shared client's other
+     * requests. A timeout means the server may have committed the mutation. */
+    private static withMutationTimeout;
     /** Wait until the client reaches Prepared/Syncing. Ignores transient
      * pre-sync states instead of rejecting on the first Sync event (which can
      * race `startClient`), and handles the case where sync already completed
@@ -164,14 +196,19 @@ export declare class TeleCryptIOStorage {
      * object in the first place (see `create()`'s doc comment).
      */
     private withSecretStorageKey;
+    private withRecoveryMutation;
     /**
      * Bootstraps cross-signing and secret storage with a brand-new server-side
      * key backup, and returns the Recovery Key for the caller to show the user.
      * This is what makes `restoreFromRecoveryKey` on another device possible.
      */
     private keysSetupRecovery;
+    private performKeysSetupRecovery;
     /** Is there an active key backup and a ready secret storage right now? */
     private keysIsRecoverySetup;
+    private performKeysIsRecoverySetup;
+    /** Returns one consistent recovery topology snapshot without exposing raw crypto callbacks. */
+    private keysGetRecoveryStatus;
     /**
      * On a new device: unlocks secret storage with the Recovery Key, loads the
      * key-backup decryption key out of secret storage, and restores the key
@@ -182,55 +219,51 @@ export declare class TeleCryptIOStorage {
      * storage / key backup.
      */
     private keysRestoreFromRecoveryKey;
+    private performKeysRestoreFromRecoveryKey;
     /** Key-management API: setup, status, and restore for server-side Secure Backup. */
     get keys(): {
-        setupRecovery: () => Promise<{
+        setupRecovery: (signal?: AbortSignal) => Promise<{
             recoveryKey: string;
         }>;
-        isRecoverySetup: () => Promise<boolean>;
-        restoreFromRecoveryKey: (recoveryKey: string) => Promise<{
+        isRecoverySetup: (signal?: AbortSignal) => Promise<boolean>;
+        getStatus: (signal?: AbortSignal) => Promise<RecoveryStatus>;
+        restoreFromRecoveryKey: (recoveryKey: string, signal?: AbortSignal) => Promise<{
             imported: number;
             total: number;
         }>;
     };
     /**
-     * Creates a new top-level shared folder (tree space).
+     * Creates a new top-level shared vault (tree space).
      *
-     * Works around a genuine race in matrix-js-sdk's own
-     * `unstableCreateFileTree()`: it creates the room via a plain
-     * `createRoom()` HTTP call, then immediately wraps the result by looking
-     * the room up in the *local* client store (`new MSC3089TreeSpace(this,
-     * roomId)` calls `client.getRoom(roomId)` and throws `Error("Unknown
-     * room")` if it's not there yet). The local store is only populated by
-     * the client's background sync processing, which is asynchronous and can
-     * easily not have caught up in the few milliseconds between the HTTP
-     * response and that lookup — especially right after a client has just
-     * started. The room really was created server-side by that point (that's
-     * how we get "Unknown room" at all); this method waits for the client's
-     * own ongoing sync loop to surface it, then wraps it directly via
-     * `unstableGetFileTreeSpace`, instead of surfacing a spurious failure for
-     * a folder that in fact exists.
+     * Uses Matrix's public `createRoom()` response as the authoritative room
+     * identity, then waits for that exact room to appear in local sync state.
      */
-    createTree(name: string): Promise<TreeSpace>;
-    listTrees(): Promise<TreeSpace[]>;
+    private treeRoomOptions;
+    private waitForTreeSpace;
     /**
-     * Creates a subdirectory (nested tree space) under `parent` and links it
-     * with the parent's space.child / the child's space.parent state events.
-     *
-     * Mirrors `createTree`'s workaround for the same matrix-js-sdk race:
-     * `MSC3089TreeSpace.createDirectory()` calls `unstableCreateFileTree()`,
-     * which creates the room via a plain `createRoom()` HTTP call and then
-     * immediately wraps the result by looking the room up in the *local*
-     * client store — throwing `Error("Unknown room")` when the background
-     * sync loop hasn't surfaced the new room yet. Without the workaround the
-     * subfolder room is created server-side but never linked (no space.child
-     * event), leaving an orphaned room and a spurious failure for a folder
-     * that in fact exists.
+     * MSC3089's built-in createDirectory only sends the two relationship events;
+     * it does not update either room's local state after the homeserver accepts
+     * them. Wrap returned spaces so child creation goes through createSubtree,
+     * which refreshes the exact parent/child state before reporting success.
+     */
+    private decorateTreeSpace;
+    /** Cleans up only a room created by this operation and reports incomplete cleanup. */
+    private cleanupCreatedRoom;
+    private removeRelationLink;
+    private removeChildLink;
+    private removeParentLink;
+    private createTreeSpace;
+    /**
+     * Creates one top-level shared vault per invocation. Same-name calls are
+     * serialized for this MatrixClient, but display names are not identities.
      */
-    createSubtree(parent: TreeSpace, name: string): Promise<TreeSpace>;
+    createTree(name: string, signal?: AbortSignal): Promise<TreeSpace>;
+    listTrees(signal?: AbortSignal): Promise<TreeSpace[]>;
+    /** Creates and links a child tree space using the exact Matrix room ID. */
+    createSubtree(parent: TreeSpace, name: string, signal?: AbortSignal): Promise<TreeSpace>;
     getTree(roomId: string): TreeSpace | null;
     /**
-     * Lists the participants of a shared folder (tree space) and their role,
+     * Lists the participants of a shared vault (tree space) and their role,
      * derived from room membership (join/invite state) + power levels.
      * Includes invited-but-not-yet-joined members as well as joined ones;
      * excludes anyone who has left/been kicked/banned.
@@ -246,13 +279,21 @@ export declare class TeleCryptIOStorage {
      * `MSC3089TreeSpace.getPermissions()` exactly (userLevel >= adminLevel ->
      * owner, >= editLevel -> editor, else viewer).
      */
-    listMembers(tree: TreeSpace): Promise<{
+    listMembers(tree: TreeSpace, options?: MatrixRequestOptions): Promise<{
         userId: string;
         role: string;
         membership: string;
     }[]>;
-    uploadFile(tree: TreeSpace, name: string, data: ArrayBuffer, mimetype: string): Promise<string>;
-    downloadFile(branch: FileBranch): Promise<{
+    /**
+     * 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>;
+    downloadFile(branch: FileBranch, signal?: AbortSignal): Promise<{
         data: ArrayBuffer;
         mimetype: string;
     }>;