@telecrypt-io/storage 0.5.27 → 0.5.29

package/dist/core/errors.d.ts

@@ -3,7 +3,7 @@
  * conditions (bad login, wrong recovery key, missing file, vault, or folder, not
  * logged in, ...). Platform-agnostic: no Node/CLI dependencies. */
 export declare class StorageError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
 /** Setup would replace account recovery state, which this SDK never does. */
 export declare class RecoveryAlreadyConfiguredError extends StorageError {
@@ -13,35 +13,35 @@ export declare class RecoveryAlreadyConfiguredError extends StorageError {
 /** Restore failed without exposing provider or crypto-library error details. */
 export declare class RecoveryRestoreError extends StorageError {
     readonly code: "RECOVERY_RESTORE_FAILED";
-    constructor();
+    constructor(cause?: unknown);
 }
 /** Setup failed before the generated Recovery Key could be safely returned. */
 export declare class RecoverySetupError extends StorageError {
     readonly code: "RECOVERY_SETUP_FAILED";
-    constructor();
+    constructor(cause?: unknown);
 }
 /** The recovery setup transport result is ambiguous; state must be checked before retrying. */
 export declare class RecoverySetupAmbiguousError extends StorageError {
     readonly code: "RECOVERY_SETUP_AMBIGUOUS";
-    constructor();
+    constructor(cause?: unknown);
 }
 /** Recovery restore was cancelled after the provider may have changed state. */
 export declare class RecoveryRestoreAmbiguousError extends StorageError {
     readonly code: "RECOVERY_RESTORE_AMBIGUOUS";
-    constructor();
+    constructor(cause?: unknown);
 }
 /** A Matrix mutation was cancelled after its request started. */
 export declare class MutationOutcomeUnknownError extends StorageError {
     readonly code: "MUTATION_OUTCOME_UNKNOWN";
     readonly operation: string;
-    constructor(operation?: string);
+    constructor(operation?: string, options?: ErrorOptions);
 }
 /** A multi-room mutation committed some work before a later step failed. */
 export declare class MutationPartialError extends StorageError {
     readonly code: "MUTATION_PARTIAL";
     readonly operation: string;
     readonly completedIds: readonly string[];
-    constructor(operation: string, completedIds: readonly string[], detail?: string);
+    constructor(operation: string, completedIds: readonly string[], detail?: string, options?: ErrorOptions);
 }
 /** A vault or folder still contains files or child folders. */
 export declare class NonEmptyTreeError extends StorageError {
@@ -53,13 +53,13 @@ export declare class NonEmptyTreeError extends StorageError {
 export declare class RoomCreationAmbiguousError extends StorageError {
     readonly code: "ROOM_CREATION_AMBIGUOUS";
     readonly operation: string;
-    constructor(operation?: string);
+    constructor(operation?: string, cause?: unknown);
 }
 /** A newly-created room could not be fully rolled back. */
 export declare class RoomCleanupIncompleteError extends StorageError {
     readonly code: "ROOM_CLEANUP_INCOMPLETE";
     readonly roomId: string;
-    constructor(roomId: string);
+    constructor(roomId: string, cause?: unknown);
 }
 /** The SDK's single product file-size limit was exceeded. */
 export declare class FileTooLargeError extends StorageError {

package/dist/core/errors.js

@@ -3,8 +3,8 @@
  * conditions (bad login, wrong recovery key, missing file, vault, or folder, not
  * logged in, ...). Platform-agnostic: no Node/CLI dependencies. */
 export class StorageError extends Error {
-    constructor(message) {
-        super(message);
+    constructor(message, options) {
+        super(message, options);
         this.name = "StorageError";
     }
 }
@@ -19,32 +19,32 @@ export class RecoveryAlreadyConfiguredError extends StorageError {
 /** Restore failed without exposing provider or crypto-library error details. */
 export class RecoveryRestoreError extends StorageError {
     code = "RECOVERY_RESTORE_FAILED";
-    constructor() {
-        super("recovery restore failed; verify the Recovery Key and account");
+    constructor(cause) {
+        super("recovery restore failed; verify the Recovery Key and account", cause === undefined ? undefined : { cause });
         this.name = "RecoveryRestoreError";
     }
 }
 /** Setup failed before the generated Recovery Key could be safely returned. */
 export class RecoverySetupError extends StorageError {
     code = "RECOVERY_SETUP_FAILED";
-    constructor() {
-        super("recovery setup did not complete; check recovery status before retrying");
+    constructor(cause) {
+        super("recovery setup did not complete; check recovery status before retrying", cause === undefined ? undefined : { cause });
         this.name = "RecoverySetupError";
     }
 }
 /** The recovery setup transport result is ambiguous; state must be checked before retrying. */
 export class RecoverySetupAmbiguousError extends StorageError {
     code = "RECOVERY_SETUP_AMBIGUOUS";
-    constructor() {
-        super("recovery setup may have completed; check recovery status before retrying");
+    constructor(cause) {
+        super("recovery setup may have completed; check recovery status before retrying", cause === undefined ? undefined : { cause });
         this.name = "RecoverySetupAmbiguousError";
     }
 }
 /** Recovery restore was cancelled after the provider may have changed state. */
 export class RecoveryRestoreAmbiguousError extends StorageError {
     code = "RECOVERY_RESTORE_AMBIGUOUS";
-    constructor() {
-        super("recovery restore may have completed; check recovery status before retrying");
+    constructor(cause) {
+        super("recovery restore may have completed; check recovery status before retrying", cause === undefined ? undefined : { cause });
         this.name = "RecoveryRestoreAmbiguousError";
     }
 }
@@ -52,8 +52,8 @@ export class RecoveryRestoreAmbiguousError extends StorageError {
 export class MutationOutcomeUnknownError extends StorageError {
     code = "MUTATION_OUTCOME_UNKNOWN";
     operation;
-    constructor(operation = "operation") {
-        super(`${operation} outcome is unknown; reconcile current state before retrying`);
+    constructor(operation = "operation", options) {
+        super(`${operation} outcome is unknown; reconcile current state before retrying`, options);
         this.name = "MutationOutcomeUnknownError";
         this.operation = operation;
     }
@@ -63,8 +63,8 @@ export class MutationPartialError extends StorageError {
     code = "MUTATION_PARTIAL";
     operation;
     completedIds;
-    constructor(operation, completedIds, detail) {
-        super(`${operation} failed after partial completion${detail ? `: ${detail}` : ""}; retry to reconcile current state`);
+    constructor(operation, completedIds, detail, options) {
+        super(`${operation} failed after partial completion${detail ? `: ${detail}` : ""}; retry to reconcile current state`, options);
         this.name = "MutationPartialError";
         this.operation = operation;
         this.completedIds = [...completedIds];
@@ -84,8 +84,8 @@ export class NonEmptyTreeError extends StorageError {
 export class RoomCreationAmbiguousError extends StorageError {
     code = "ROOM_CREATION_AMBIGUOUS";
     operation;
-    constructor(operation = "room creation") {
-        super(`${operation} outcome is unknown; reconcile newly-created rooms before retrying`);
+    constructor(operation = "room creation", cause) {
+        super(`${operation} outcome is unknown; reconcile newly-created rooms before retrying`, cause === undefined ? undefined : { cause });
         this.name = "RoomCreationAmbiguousError";
         this.operation = operation;
     }
@@ -94,8 +94,8 @@ export class RoomCreationAmbiguousError extends StorageError {
 export class RoomCleanupIncompleteError extends StorageError {
     code = "ROOM_CLEANUP_INCOMPLETE";
     roomId;
-    constructor(roomId) {
-        super("created room cleanup is incomplete; retry cleanup for the created room");
+    constructor(roomId, cause) {
+        super("created room cleanup is incomplete; retry cleanup for the created room", cause === undefined ? undefined : { cause });
         this.name = "RoomCleanupIncompleteError";
         this.roomId = roomId;
     }

package/dist/core/http.d.ts

@@ -1,24 +1,30 @@
+/** Read a complete response body while preserving the caller's cancellation contract. */
+export interface ResponseBody {
+    bytes: Uint8Array<ArrayBuffer>;
+}
 /**
- * Read a response body without allowing an untrusted peer to control the
- * amount of memory consumed. Callers decide whether a truncated body is an
- * error and retain the response status when they need provider-error mapping.
+ * A response stream failed after producing some bytes. The bytes are kept for
+ * diagnostic callers; product-media callers must unwrap only the cause and
+ * never expose this raw buffer in a public error.
  */
-export interface BoundedResponseBody {
-    bytes: Uint8Array<ArrayBuffer>;
-    truncated: boolean;
+export declare class ResponseBodyReadError extends Error {
+    readonly bytes: Uint8Array<ArrayBuffer>;
+    constructor(bytes: Uint8Array<ArrayBuffer>, cause: unknown);
 }
-export interface BoundedResponseOptions {
+export interface ResponseBodyOptions {
     /** Error returned when the body signal aborts. */
     abortError?: () => Error;
-    /** Keep a stream reader locked until its asynchronous cancellation settles. */
-    deferReaderRelease?: boolean;
 }
 /**
  * Reject a caller-facing operation as soon as a signal aborts. The underlying
  * operation is deliberately not awaited after that point: browser/network
- * implementations are allowed to ignore AbortSignal, but a bounded SDK API
- * must still settle at its deadline. Its promise remains observed so a late
- * rejection cannot become an unhandled rejection.
+ * implementations are allowed to ignore AbortSignal, but the SDK API must
+ * still settle at its deadline. A deadline rejection is the complete public
+ * outcome; the late operation has no second result channel.
  */
-export declare function raceWithAbort<T>(operation: PromiseLike<T>, signal: AbortSignal, onAbort: () => void, error: () => Error): Promise<T>;
-export declare function readBoundedResponseBody(response: Response, maxBytes: number, signal?: AbortSignal, options?: BoundedResponseOptions): Promise<BoundedResponseBody>;
+export declare function raceWithAbort<T>(operation: PromiseLike<T>, signal: AbortSignal, error: () => Error): Promise<T>;
+/** Await cleanup for a response that is being rejected before its body is read. */
+export declare function cancelResponseBody(response: Response, operation: string, primaryError?: unknown): Promise<void>;
+export declare function readResponseBody(response: Response, signal?: AbortSignal, options?: ResponseBodyOptions): Promise<ResponseBody>;
+/** Read successful product media with the SDK's single plaintext-size ceiling. */
+export declare function readMediaResponseBody(response: Response, maxBytes: number, signal?: AbortSignal, options?: ResponseBodyOptions): Promise<ResponseBody>;

package/dist/core/http.js

@@ -1,26 +1,32 @@
+import { FileTooLargeError } from "./errors.js";
+/**
+ * A response stream failed after producing some bytes. The bytes are kept for
+ * diagnostic callers; product-media callers must unwrap only the cause and
+ * never expose this raw buffer in a public error.
+ */
+export class ResponseBodyReadError extends Error {
+    bytes;
+    constructor(bytes, cause) {
+        super("response body read failed", { cause });
+        this.name = "ResponseBodyReadError";
+        this.bytes = bytes;
+    }
+}
+const RESPONSE_CLEANUP_TIMEOUT_MS = 5_000;
 function abortError() {
     return new DOMException("The operation was aborted", "AbortError");
 }
 /**
  * Reject a caller-facing operation as soon as a signal aborts. The underlying
  * operation is deliberately not awaited after that point: browser/network
- * implementations are allowed to ignore AbortSignal, but a bounded SDK API
- * must still settle at its deadline. Its promise remains observed so a late
- * rejection cannot become an unhandled rejection.
+ * implementations are allowed to ignore AbortSignal, but the SDK API must
+ * still settle at its deadline. A deadline rejection is the complete public
+ * outcome; the late operation has no second result channel.
  */
-export function raceWithAbort(operation, signal, onAbort, error) {
-    if (signal.aborted) {
-        try {
-            onAbort();
-        }
-        catch {
-            // Cleanup is best effort; the caller-facing abort error remains stable.
-        }
-        // The operation may already have been started by the caller. Observe its
-        // eventual rejection even though the public operation is already aborted.
-        void Promise.resolve(operation).catch(() => undefined);
-        return Promise.reject(error());
-    }
+export function raceWithAbort(operation, signal, error) {
+    // Attach the rejection observer before checking an already-aborted signal;
+    // the caller may have started this operation before entering the race.
+    const observedOperation = Promise.resolve(operation);
     return new Promise((resolve, reject) => {
         let settled = false;
         const cleanup = () => signal.removeEventListener("abort", abort);
@@ -32,98 +38,127 @@ export function raceWithAbort(operation, signal, onAbort, error) {
             callback();
         };
         const abort = () => {
-            // A resolved fetch can still have its abort event delivered first when a
-            // caller aborts immediately after starting it. Let an already-resolved
-            // operation hand its response to the bounded body reader, which can then
-            // cancel that reader instead of losing it in the fetch race.
-            queueMicrotask(() => {
-                finish(() => {
-                    try {
-                        onAbort();
-                    }
-                    catch {
-                        // Cleanup is best effort; the caller-facing abort error remains stable.
-                    }
+            finish(() => {
+                try {
                     reject(error());
-                });
+                }
+                catch (abortError) {
+                    reject(abortError);
+                }
             });
         };
         signal.addEventListener("abort", abort, { once: true });
-        Promise.resolve(operation).then((value) => finish(() => resolve(value)), (reason) => finish(() => reject(reason)));
+        observedOperation.then((value) => finish(() => resolve(value)), (reason) => finish(() => reject(reason)));
         if (signal.aborted)
             abort();
     });
 }
-function cancelWithoutWaiting(cancel) {
+function combineCleanupFailures(primaryError, cleanupFailures, message) {
+    const errors = primaryError === undefined ? [...cleanupFailures] : [primaryError, ...cleanupFailures];
+    return new AggregateError(errors, message, {
+        cause: primaryError ?? cleanupFailures[0],
+    });
+}
+async function runBoundedCleanup(cleanup, operation) {
+    const pending = Promise.resolve().then(cleanup);
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`${operation} cleanup timed out`));
+        }, RESPONSE_CLEANUP_TIMEOUT_MS);
+    });
+    try {
+        await Promise.race([pending, deadline]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** Await cleanup for a response that is being rejected before its body is read. */
+export async function cancelResponseBody(response, operation, primaryError) {
+    if (!response.body)
+        return;
     try {
-        return Promise.resolve(cancel()).catch(() => undefined);
+        await runBoundedCleanup(() => response.body.cancel(), `${operation} response`);
     }
-    catch {
-        // A stream may reject cancellation synchronously; the caller is already
-        // rejecting or returning a bounded result, so cleanup remains best effort.
-        return Promise.resolve();
+    catch (error) {
+        throw combineCleanupFailures(primaryError, [error], primaryError === undefined
+            ? `${operation} response cleanup was incomplete`
+            : `${operation} failed and response cleanup was incomplete`);
     }
 }
-function releaseReaderWithoutThrowing(reader) {
+async function cancelReaderAndRelease(reader, operation, primaryError) {
+    const cleanupFailures = [];
+    try {
+        await runBoundedCleanup(() => reader.cancel(), `${operation} reader cancellation`);
+    }
+    catch (error) {
+        cleanupFailures.push(error);
+    }
+    // Cancellation is awaited before releasing the reader, so cleanup failures
+    // stay part of the current operation instead of mutating a later error.
     try {
         reader.releaseLock();
     }
-    catch {
-        // A reader with a still-pending read can reject lock release. The bounded
-        // caller must retain its abort/size result rather than waiting for or
-        // replacing it with stream cleanup failure.
+    catch (error) {
+        cleanupFailures.push(error);
     }
-}
-export async function readBoundedResponseBody(response, maxBytes, signal, options = {}) {
-    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
-        throw new Error("invalid response body limit");
+    if (cleanupFailures.length > 0) {
+        throw combineCleanupFailures(primaryError, cleanupFailures, primaryError === undefined
+            ? `${operation} reader cleanup was incomplete`
+            : `${operation} failed and reader cleanup was incomplete`);
     }
-    const cancelBody = () => {
-        if (response.body)
-            cancelWithoutWaiting(() => response.body.cancel());
-    };
-    const cancelAbortedResponse = () => {
-        if (!response.body) {
-            cancelBody();
+}
+async function readResponseBodyInternal(response, signal, options = {}, maxBytes) {
+    const cancelAbortedResponse = async (failure) => {
+        if (!response.body)
             return;
-        }
         let reader;
         try {
             reader = response.body.getReader();
         }
-        catch {
-            cancelBody();
-            return;
+        catch (error) {
+            throw combineCleanupFailures(failure, [error], "response reader setup failed after abort");
         }
-        const cancellation = cancelWithoutWaiting(() => reader.cancel());
-        if (options.deferReaderRelease)
-            void cancellation.then(() => releaseReaderWithoutThrowing(reader));
-        else
-            releaseReaderWithoutThrowing(reader);
+        await cancelReaderAndRelease(reader, "response body", failure);
     };
     if (signal?.aborted) {
-        cancelAbortedResponse();
-        throw options.abortError?.() ?? abortError();
+        const failure = options.abortError?.() ?? abortError();
+        await cancelAbortedResponse(failure);
+        throw failure;
     }
-    const contentLength = response.headers.get("content-length");
-    if (contentLength !== null && (!/^\d+$/.test(contentLength) || Number(contentLength) > maxBytes)) {
-        cancelBody();
-        return { bytes: new Uint8Array(), truncated: true };
+    if (maxBytes !== undefined &&
+        (!Number.isSafeInteger(maxBytes) || maxBytes < 0)) {
+        throw new Error("invalid media response body limit");
+    }
+    if (maxBytes !== undefined) {
+        const contentLength = response.headers.get("content-length");
+        if (contentLength !== null && /^\d+$/u.test(contentLength) && Number(contentLength) > maxBytes) {
+            const tooLarge = new FileTooLargeError();
+            await cancelResponseBody(response, "media response", tooLarge);
+            throw tooLarge;
+        }
     }
     if (!response.body)
-        return { bytes: new Uint8Array(), truncated: false };
-    const reader = response.body.getReader();
-    let cancellation;
-    const cancelReader = () => {
-        cancellation ??= cancelWithoutWaiting(() => reader.cancel());
-    };
-    const releaseReader = () => {
-        if (options.deferReaderRelease && cancellation) {
-            void cancellation.then(() => releaseReaderWithoutThrowing(reader));
+        return { bytes: new Uint8Array() };
+    let reader;
+    try {
+        reader = response.body.getReader();
+    }
+    catch (error) {
+        let failure = error;
+        try {
+            await cancelResponseBody(response, "response body reader setup", error);
         }
-        else {
-            releaseReaderWithoutThrowing(reader);
+        catch (cleanupError) {
+            failure = cleanupError;
         }
+        throw new ResponseBodyReadError(new Uint8Array(), failure);
+    }
+    let abortCancellation;
+    const cancelReader = () => {
+        abortCancellation ??= runBoundedCleanup(() => reader.cancel(), "response body reader");
     };
     const chunks = [];
     let bytesRead = 0;
@@ -166,16 +201,8 @@ export async function readBoundedResponseBody(response, maxBytes, signal, option
             const { done, value } = await readChunk();
             if (done)
                 break;
-            const remaining = maxBytes - bytesRead;
-            if (value.byteLength > remaining) {
-                if (remaining > 0) {
-                    const chunk = new Uint8Array(remaining);
-                    chunk.set(value.subarray(0, remaining));
-                    chunks.push(chunk);
-                    bytesRead += remaining;
-                }
-                cancelReader();
-                return { bytes: joinBytes(chunks, bytesRead), truncated: true };
+            if (maxBytes !== undefined && value.byteLength > maxBytes - bytesRead) {
+                throw new FileTooLargeError();
             }
             const chunk = new Uint8Array(value.byteLength);
             chunk.set(value);
@@ -183,10 +210,57 @@ export async function readBoundedResponseBody(response, maxBytes, signal, option
             bytesRead += value.byteLength;
         }
     }
-    finally {
-        releaseReader();
+    catch (error) {
+        if (signal?.aborted) {
+            const failure = new ResponseBodyReadError(joinBytes(chunks, bytesRead), error);
+            const cleanupFailures = [];
+            if (abortCancellation) {
+                try {
+                    await abortCancellation;
+                }
+                catch (cleanupError) {
+                    cleanupFailures.push(cleanupError);
+                }
+            }
+            try {
+                reader.releaseLock();
+            }
+            catch (cleanupError) {
+                cleanupFailures.push(cleanupError);
+            }
+            if (cleanupFailures.length > 0) {
+                throw combineCleanupFailures(failure, cleanupFailures, "response body read failed and reader cleanup was incomplete");
+            }
+            throw failure;
+        }
+        try {
+            await cancelReaderAndRelease(reader, "response body", error);
+        }
+        catch (cleanupError) {
+            if (error instanceof FileTooLargeError)
+                throw cleanupError;
+            throw new ResponseBodyReadError(joinBytes(chunks, bytesRead), cleanupError);
+        }
+        if (error instanceof FileTooLargeError)
+            throw error;
+        throw new ResponseBodyReadError(joinBytes(chunks, bytesRead), error);
     }
-    return { bytes: joinBytes(chunks, bytesRead), truncated: false };
+    // A settled normal read has no pending read request, so Web Streams
+    // guarantees that this synchronous release cannot throw.
+    try {
+        reader.releaseLock();
+    }
+    catch (error) {
+        throw new ResponseBodyReadError(joinBytes(chunks, bytesRead), error);
+    }
+    return { bytes: joinBytes(chunks, bytesRead) };
+}
+export function readResponseBody(response, signal, options = {}) {
+    return readResponseBodyInternal(response, signal, options);
+}
+/** Read successful product media with the SDK's single plaintext-size ceiling. */
+export function readMediaResponseBody(response, maxBytes, signal, options = {}) {
+    return readResponseBodyInternal(response, signal, options, maxBytes);
 }
 function joinBytes(chunks, total) {
     const bytes = new Uint8Array(total);

package/dist/core/index.d.ts

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

package/dist/core/index.js

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

package/dist/core/oidc.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Shared OIDC/MAS login building blocks — used by BOTH the CLI (device-code
+ * grant) and the web UI (authorization-code + PKCE). Browser-safe (no
+ * node:fs/path/v8/process/commander/fake-indexeddb): browser state is only
+ * touched when the PKCE functions are called by the web adapter. Importing
+ * this module under Node is safe; the CLI uses the device-code functions,
+ * which are plain fetch calls.
+ */
 import { type DeviceAuthorizationResponse, type DeviceAccessTokenResponse, type DeviceAccessTokenError, type BearerTokenResponse as OAuthBearerTokenResponse, type ValidatedAuthMetadata } from "matrix-js-sdk/lib/oauth/index.js";
 import type { AccessTokens, TokenRefreshFunction } from "matrix-js-sdk/lib/http-api/index.js";
 /** Matrix 1.18 OAuth metadata returned by `/auth_metadata`. */
@@ -22,6 +30,13 @@ export interface OidcRegistrationClientMetadata {
 }
 /** The issuer-bound endpoints accepted by the token refresh adapter. */
 export type OidcTokenEndpointMetadata = Pick<OidcClientConfig, "issuer" | "token_endpoint" | "revocation_endpoint">;
+/** Keep provider diagnostics useful without allowing credentials, customer
+ * identifiers, or control characters from an untrusted response to cross the
+ * SDK boundary. */
+export declare function sanitizeDiagnosticText(value: string): string;
+/** Copy a transport error's useful details across the SDK boundary after the
+ * same secret/control-character sanitization used for provider responses. */
+export declare function diagnosticCause(error: unknown, seen?: WeakSet<object>): Error;
 /**
  * Discovers the OIDC/MAS issuer and endpoints for a homeserver via the
  * Matrix client's stable `/auth_metadata` endpoint. Matrix 42 performs this