@telecrypt-io/storage 0.3.0 → 0.5.7

package/dist/core/constants.d.ts

@@ -0,0 +1,16 @@
+/** Maximum plaintext media body accepted by the non-streaming SDK surface. */
+export declare const MAX_MEDIA_FILE_BYTES: number;
+/** Matrix's canonical identifier bounds used at authenticated-client boundaries. */
+export declare const MAX_MATRIX_USER_ID_BYTES = 255;
+export declare const MAX_MATRIX_DEVICE_ID_LENGTH = 128;
+export declare const MAX_MATRIX_IDENTIFIER_LENGTH = 512;
+/**
+ * Validates a new/current Matrix identity and binds its server name exactly to
+ * the caller's independently trusted Matrix topology. The Matrix server name
+ * is deliberately explicit: a deployment may expose its homeserver through a
+ * backend hostname that differs from the user-visible Matrix server name.
+ */
+export declare function validateCanonicalMatrixUserId(value: unknown, serverName: 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

@@ -0,0 +1,54 @@
+/** Maximum plaintext media body accepted by the non-streaming SDK surface. */
+export const MAX_MEDIA_FILE_BYTES = 128 * 1024 * 1024;
+/** Matrix's canonical identifier bounds used at authenticated-client boundaries. */
+export const MAX_MATRIX_USER_ID_BYTES = 255;
+export const MAX_MATRIX_DEVICE_ID_LENGTH = 128;
+export const MAX_MATRIX_IDENTIFIER_LENGTH = 512;
+const MATRIX_SERVER_NAME_PATTERN = "(?:\\[[0-9A-Fa-f:.]+\\]|[A-Za-z0-9.-]+)(?::\\d{1,5})?";
+const MATRIX_SERVER_NAME_REGEXP = new RegExp(`^${MATRIX_SERVER_NAME_PATTERN}$`);
+const MATRIX_USER_ID_PATTERN = new RegExp(`^@([A-Za-z0-9._=+\\-/]+):(${MATRIX_SERVER_NAME_PATTERN})$`);
+const MATRIX_DEVICE_ID_PATTERN = /^[A-Za-z0-9._~-]{1,128}$/;
+const MATRIX_ROOM_ID_PATTERN = new RegExp(`^![A-Za-z0-9._~+\\/-]+:${MATRIX_SERVER_NAME_PATTERN}$`);
+const MATRIX_EVENT_ID_PATTERN = /^\$[A-Za-z0-9._~:/+\-]{1,511}$/;
+/**
+ * Validates a new/current Matrix identity and binds its server name exactly to
+ * the caller's independently trusted Matrix topology. The Matrix server name
+ * is deliberately explicit: a deployment may expose its homeserver through a
+ * 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_USER_ID_BYTES) {
+        throw new Error("invalid Matrix user ID");
+    }
+    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);
+    if (!match || match[2].toLowerCase() !== serverName.toLowerCase()) {
+        throw new Error("invalid Matrix user ID for this homeserver");
+    }
+    return value;
+}
+export function validateMatrixDeviceId(value) {
+    if (typeof value !== "string" || value.length > MAX_MATRIX_DEVICE_ID_LENGTH || !MATRIX_DEVICE_ID_PATTERN.test(value)) {
+        throw new Error("invalid Matrix device ID");
+    }
+    return value;
+}
+export function validateMatrixRoomId(value, name = "room ID") {
+    if (typeof value !== "string" ||
+        value.length > MAX_MATRIX_IDENTIFIER_LENGTH ||
+        !MATRIX_ROOM_ID_PATTERN.test(value)) {
+        throw new Error(`invalid Matrix ${name}`);
+    }
+    return value;
+}
+export function validateMatrixEventId(value, name = "event ID") {
+    if (typeof value !== "string" ||
+        value.length > MAX_MATRIX_IDENTIFIER_LENGTH ||
+        !MATRIX_EVENT_ID_PATTERN.test(value)) {
+        throw new Error(`invalid Matrix ${name}`);
+    }
+    return value;
+}

package/dist/core/errors.d.ts

@@ -1,7 +1,73 @@
 /** A user-facing operation error: a clean, prefix-free message meant to be
  * shown directly to a user — never a raw stack trace. Thrown for expected failure
- * conditions (bad login, wrong recovery key, missing file/folder, not
+ * 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);
 }
+/** Setup would replace account recovery state, which this SDK never does. */
+export declare class RecoveryAlreadyConfiguredError extends StorageError {
+    readonly code: "RECOVERY_ALREADY_CONFIGURED";
+    constructor();
+}
+/** Restore failed without exposing provider or crypto-library error details. */
+export declare class RecoveryRestoreError extends StorageError {
+    readonly code: "RECOVERY_RESTORE_FAILED";
+    constructor();
+}
+/** Setup failed before the generated Recovery Key could be safely returned. */
+export declare class RecoverySetupError extends StorageError {
+    readonly code: "RECOVERY_SETUP_FAILED";
+    constructor();
+}
+/** 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();
+}
+/** Recovery restore was cancelled after the provider may have changed state. */
+export declare class RecoveryRestoreAmbiguousError extends StorageError {
+    readonly code: "RECOVERY_RESTORE_AMBIGUOUS";
+    constructor();
+}
+/** 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);
+}
+/** 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);
+}
+/** A vault or folder still contains files or child folders. */
+export declare class NonEmptyTreeError extends StorageError {
+    readonly code: "NON_EMPTY_TREE";
+    readonly treeId: string;
+    constructor(treeId: string);
+}
+/** Room creation timed out or returned an unusable identity. */
+export declare class RoomCreationAmbiguousError extends StorageError {
+    readonly code: "ROOM_CREATION_AMBIGUOUS";
+    readonly operation: string;
+    constructor(operation?: string);
+}
+/** 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);
+}
+/** The SDK's single product file-size limit was exceeded. */
+export declare class FileTooLargeError extends StorageError {
+    readonly code: "FILE_TOO_LARGE";
+    constructor();
+}
+/** The file event is present, but this device has no key to decrypt it. */
+export declare class UndecryptableFileError extends StorageError {
+    readonly code: "FILE_UNDECRYPTABLE";
+    constructor();
+}

package/dist/core/errors.js

@@ -1,6 +1,6 @@
 /** A user-facing operation error: a clean, prefix-free message meant to be
  * shown directly to a user — never a raw stack trace. Thrown for expected failure
- * conditions (bad login, wrong recovery key, missing file/folder, not
+ * 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) {
@@ -8,3 +8,111 @@ export class StorageError extends Error {
         this.name = "StorageError";
     }
 }
+/** Setup would replace account recovery state, which this SDK never does. */
+export class RecoveryAlreadyConfiguredError extends StorageError {
+    code = "RECOVERY_ALREADY_CONFIGURED";
+    constructor() {
+        super("recovery is already configured for this account; use the existing Recovery Key or restore it on this device");
+        this.name = "RecoveryAlreadyConfiguredError";
+    }
+}
+/** 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");
+        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");
+        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");
+        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");
+        this.name = "RecoveryRestoreAmbiguousError";
+    }
+}
+/** A Matrix mutation was cancelled after its request started. */
+export class MutationOutcomeUnknownError extends StorageError {
+    code = "MUTATION_OUTCOME_UNKNOWN";
+    operation;
+    constructor(operation = "operation") {
+        super(`${operation} outcome is unknown; reconcile current state before retrying`);
+        this.name = "MutationOutcomeUnknownError";
+        this.operation = operation;
+    }
+}
+/** A multi-room mutation committed some work before a later step failed. */
+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`);
+        this.name = "MutationPartialError";
+        this.operation = operation;
+        this.completedIds = [...completedIds];
+    }
+}
+/** A vault or folder still contains files or child folders. */
+export class NonEmptyTreeError extends StorageError {
+    code = "NON_EMPTY_TREE";
+    treeId;
+    constructor(treeId) {
+        super("cannot delete a nonempty vault or folder; delete its files and empty child folders first");
+        this.name = "NonEmptyTreeError";
+        this.treeId = treeId;
+    }
+}
+/** Room creation timed out or returned an unusable identity. */
+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`);
+        this.name = "RoomCreationAmbiguousError";
+        this.operation = operation;
+    }
+}
+/** A newly-created room could not be fully rolled back. */
+export class RoomCleanupIncompleteError extends StorageError {
+    code = "ROOM_CLEANUP_INCOMPLETE";
+    roomId;
+    constructor(roomId) {
+        super("created room cleanup is incomplete; retry cleanup for the created room");
+        this.name = "RoomCleanupIncompleteError";
+        this.roomId = roomId;
+    }
+}
+/** The SDK's single product file-size limit was exceeded. */
+export class FileTooLargeError extends StorageError {
+    code = "FILE_TOO_LARGE";
+    constructor() {
+        super("file exceeds the 128 MiB limit");
+        this.name = "FileTooLargeError";
+    }
+}
+/** The file event is present, but this device has no key to decrypt it. */
+export class UndecryptableFileError extends StorageError {
+    code = "FILE_UNDECRYPTABLE";
+    constructor() {
+        super("downloadFile: could not read file info from the event — it is likely undecryptable on this device (missing megolm session; try restoring from a Recovery Key)");
+        this.name = "UndecryptableFileError";
+    }
+}

package/dist/core/http.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+export interface BoundedResponseBody {
+    bytes: Uint8Array<ArrayBuffer>;
+    truncated: boolean;
+}
+export interface BoundedResponseOptions {
+    /** 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.
+ */
+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>;

package/dist/core/http.js

@@ -0,0 +1,199 @@
+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.
+ */
+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());
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => signal.removeEventListener("abort", abort);
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            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.
+                    }
+                    reject(error());
+                });
+            });
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        Promise.resolve(operation).then((value) => finish(() => resolve(value)), (reason) => finish(() => reject(reason)));
+        if (signal.aborted)
+            abort();
+    });
+}
+function cancelWithoutWaiting(cancel) {
+    try {
+        return Promise.resolve(cancel()).catch(() => undefined);
+    }
+    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();
+    }
+}
+function releaseReaderWithoutThrowing(reader) {
+    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.
+    }
+}
+export async function readBoundedResponseBody(response, maxBytes, signal, options = {}) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+        throw new Error("invalid response body limit");
+    }
+    const cancelBody = () => {
+        if (response.body)
+            cancelWithoutWaiting(() => response.body.cancel());
+    };
+    const cancelAbortedResponse = () => {
+        if (!response.body) {
+            cancelBody();
+            return;
+        }
+        let reader;
+        try {
+            reader = response.body.getReader();
+        }
+        catch {
+            cancelBody();
+            return;
+        }
+        const cancellation = cancelWithoutWaiting(() => reader.cancel());
+        if (options.deferReaderRelease)
+            void cancellation.then(() => releaseReaderWithoutThrowing(reader));
+        else
+            releaseReaderWithoutThrowing(reader);
+    };
+    if (signal?.aborted) {
+        cancelAbortedResponse();
+        throw options.abortError?.() ?? abortError();
+    }
+    const contentLength = response.headers.get("content-length");
+    if (contentLength !== null && (!/^\d+$/.test(contentLength) || Number(contentLength) > maxBytes)) {
+        cancelBody();
+        return { bytes: new Uint8Array(), truncated: true };
+    }
+    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));
+        }
+        else {
+            releaseReaderWithoutThrowing(reader);
+        }
+    };
+    const chunks = [];
+    let bytesRead = 0;
+    const readChunk = () => {
+        if (!signal)
+            return reader.read();
+        if (signal.aborted) {
+            cancelReader();
+            return Promise.reject(options.abortError?.() ?? abortError());
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const cleanup = () => signal.removeEventListener("abort", onAbort);
+            const onAbort = () => {
+                if (settled)
+                    return;
+                settled = true;
+                cancelReader();
+                cleanup();
+                reject(options.abortError?.() ?? abortError());
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+            reader.read().then((result) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve(result);
+            }, (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(error);
+            });
+        });
+    };
+    try {
+        for (;;) {
+            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 };
+            }
+            const chunk = new Uint8Array(value.byteLength);
+            chunk.set(value);
+            chunks.push(chunk);
+            bytesRead += value.byteLength;
+        }
+    }
+    finally {
+        releaseReader();
+    }
+    return { bytes: joinBytes(chunks, bytesRead), truncated: false };
+}
+function joinBytes(chunks, total) {
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}

package/dist/core/index.d.ts

@@ -3,3 +3,4 @@ export * from "./types.js";
 export * from "./operations.js";
 export * from "./errors.js";
 export * from "./oidc.js";
+export * from "./constants.js";

package/dist/core/index.js

@@ -3,3 +3,4 @@ export * from "./types.js";
 export * from "./operations.js";
 export * from "./errors.js";
 export * from "./oidc.js";
+export * from "./constants.js";