@telecrypt-io/storage 0.2.13 → 0.3.0

package/README.md

@@ -8,14 +8,13 @@ Files are encrypted on the client before upload. The server stores only opaque c
 never holds the decryption keys. Shared folders let multiple people add and read files, and a
 Recovery Key restores your files on a new device — even if you lose the original.
 
-**Status:** library source only. `@telecrypt-io/storage@0.2.5` is the current public release,
-published from this repository's protected `v0.2.5` tag with NPM Trusted Publishing/OIDC
-provenance. The older `0.1.3` release is the immutable legacy combined library-and-CLI package.
+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.
 
 ## Install
 
 ```bash
-npm install @telecrypt-io/storage@0.2.5
+npm install @telecrypt-io/storage@0.3.0
 ```
 
 This gives you the `TeleCryptIOStorage` library and its browser-safe `core` API.
@@ -61,13 +60,13 @@ stock Synapse.
 ## Development
 
 ```bash
-npm install
-npm run synapse:up     # disposable local Synapse for tests
+npm ci
+npm run synapse:up     # disposable local Synapse/MAS fixture
 npm test
 npm run synapse:down
 ```
 
-Tests run against a real local Synapse in podman, never against a production server.
+Tests run against a real local Synapse/MAS fixture in Podman, never against a production server.
 
 See [RELEASING.md](./RELEASING.md) for the guarded npm release procedure.
 

package/dist/TeleCryptIOStorage.js

@@ -434,8 +434,7 @@ export class TeleCryptIOStorage {
             // of a useful error. Surface the real cause.
             throw new Error(`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)`);
         }
-        // Belt-and-braces: if a future matrix-js-sdk version returns a
-        // placeholder without throwing, still fail with the clear message.
+        // Also reject an incomplete placeholder if matrix-js-sdk returns one.
         if (!info || typeof info.url !== "string") {
             throw new Error("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)");
         }

package/dist/core/errors.d.ts

@@ -1,8 +1,7 @@
 /** A user-facing operation error: a clean, prefix-free message meant to be
- * shown directly to a user (CLI stderr today, a future UI's error toast
- * tomorrow) — never a raw stack trace. Thrown for expected failure
+ * shown directly to a user — never a raw stack trace. Thrown for expected failure
  * conditions (bad login, wrong recovery key, missing file/folder, not
  * logged in, ...). Platform-agnostic: no Node/CLI dependencies. */
-export declare class CliError extends Error {
+export declare class StorageError extends Error {
     constructor(message: string);
 }

package/dist/core/errors.js

@@ -1,11 +1,10 @@
 /** A user-facing operation error: a clean, prefix-free message meant to be
- * shown directly to a user (CLI stderr today, a future UI's error toast
- * tomorrow) — never a raw stack trace. Thrown for expected failure
+ * shown directly to a user — never a raw stack trace. Thrown for expected failure
  * conditions (bad login, wrong recovery key, missing file/folder, not
  * logged in, ...). Platform-agnostic: no Node/CLI dependencies. */
-export class CliError extends Error {
+export class StorageError extends Error {
     constructor(message) {
         super(message);
-        this.name = "CliError";
+        this.name = "StorageError";
     }
 }

package/dist/core/index.d.ts

@@ -1,5 +1,4 @@
-/** Barrel: the full platform-agnostic surface a UI (or any non-CLI caller)
- * needs — the typed result contract plus every operation. */
+/** The full platform-agnostic surface for user-facing clients. */
 export * from "./types.js";
 export * from "./operations.js";
 export * from "./errors.js";

package/dist/core/index.js

@@ -1,5 +1,4 @@
-/** Barrel: the full platform-agnostic surface a UI (or any non-CLI caller)
- * needs — the typed result contract plus every operation. */
+/** The full platform-agnostic surface for user-facing clients. */
 export * from "./types.js";
 export * from "./operations.js";
 export * from "./errors.js";

package/dist/core/oidc.d.ts

@@ -21,10 +21,8 @@ export interface OidcTokenSet {
     expiresAt?: number;
 }
 /**
- * Discovers the OIDC/MAS issuer + endpoints for a homeserver, via
- * `MatrixClient.getAuthMetadata()` (MSC2965 `/auth_metadata`, falling back to
- * the legacy `/auth_issuer` + issuer well-known) — the non-deprecated path
- * recommended over `discoverAndValidateOIDCIssuerWellKnown`.
+ * Discovers the OIDC/MAS issuer and endpoints for a homeserver via the
+ * Matrix client's authentication metadata endpoint.
  *
  * NODE CALLERS: this internally constructs oidc-client-ts state that
  * requires `window.sessionStorage`/`window.localStorage` to exist (a real

package/dist/core/oidc.js

@@ -11,12 +11,10 @@
 import { createClient } from "matrix-js-sdk";
 import { registerOidcClient, generateScope, generateOidcAuthorizationUrl, completeAuthorizationCodeGrant, startDeviceAuthorization, waitForDeviceAuthorization, } from "matrix-js-sdk/lib/oidc/index.js";
 import { OidcClient, WebStorageStateStore } from "oidc-client-ts";
-import { CliError } from "./errors.js";
+import { StorageError } from "./errors.js";
 /**
- * Discovers the OIDC/MAS issuer + endpoints for a homeserver, via
- * `MatrixClient.getAuthMetadata()` (MSC2965 `/auth_metadata`, falling back to
- * the legacy `/auth_issuer` + issuer well-known) — the non-deprecated path
- * recommended over `discoverAndValidateOIDCIssuerWellKnown`.
+ * Discovers the OIDC/MAS issuer and endpoints for a homeserver via the
+ * Matrix client's authentication metadata endpoint.
  *
  * NODE CALLERS: this internally constructs oidc-client-ts state that
  * requires `window.sessionStorage`/`window.localStorage` to exist (a real
@@ -31,7 +29,7 @@ export async function discoverOidcIssuer(homeserverBaseUrl) {
         return await client.getAuthMetadata();
     }
     catch (err) {
-        throw new CliError(`OIDC discovery failed: ${err.message}`);
+        throw new StorageError(`OIDC discovery failed: ${err.message}`);
     }
 }
 /**
@@ -44,7 +42,7 @@ export async function registerClient(authMetadata, metadata) {
         return await registerOidcClient(authMetadata, metadata);
     }
     catch (err) {
-        throw new CliError(`OIDC dynamic client registration failed: ${err.message}`);
+        throw new StorageError(`OIDC dynamic client registration failed: ${err.message}`);
     }
 }
 // ---------------------------------------------------------------------------
@@ -177,26 +175,26 @@ export async function refreshOidcToken(tokenEndpoint, clientId, refreshToken) {
     });
     if (!res.ok) {
         const body = await res.text();
-        throw new CliError(`OIDC token refresh failed (${res.status}): ${body}`);
+        throw new StorageError(`OIDC token refresh failed (${res.status}): ${body}`);
     }
     const data = await res.json();
     if (!data || typeof data !== "object") {
-        throw new CliError("OIDC token refresh returned an invalid response");
+        throw new StorageError("OIDC token refresh returned an invalid response");
     }
     const record = data;
     const accessToken = record.access_token;
     const nextRefreshToken = record.refresh_token;
     const expiresIn = record.expires_in;
     if (typeof accessToken !== "string" || accessToken.trim() === "") {
-        throw new CliError("OIDC token refresh returned no access token");
+        throw new StorageError("OIDC token refresh returned no access token");
     }
     if (nextRefreshToken !== undefined &&
         (typeof nextRefreshToken !== "string" || nextRefreshToken.trim() === "")) {
-        throw new CliError("OIDC token refresh returned an invalid refresh token");
+        throw new StorageError("OIDC token refresh returned an invalid refresh token");
     }
     if (expiresIn !== undefined &&
         (typeof expiresIn !== "number" || !Number.isFinite(expiresIn) || expiresIn < 0)) {
-        throw new CliError("OIDC token refresh returned an invalid expiry");
+        throw new StorageError("OIDC token refresh returned an invalid expiry");
     }
     return {
         accessToken,

package/dist/core/operations.d.ts

@@ -3,13 +3,12 @@
  * taking an already-created `TeleCryptIOStorage` plus plain inputs and returning
  * one of the typed results in `./types.ts`. No I/O beyond the Matrix client
  * itself, no stdout, no `process`, no file paths — bytes in/out are always
- * `Uint8Array`. This is what the CLI's command actions call today and what
- * a future React UI calls directly, so both run the exact same tested logic
- * and share the exact same result shapes.
+ * `Uint8Array`. All callers run the same tested logic and share the same result
+ * shapes.
  *
  * `core/` never creates the `TeleCryptIOStorage`/`MatrixClient` itself — store
  * config (persistent crypto store, session credentials, etc.) is
- * platform-specific and stays with the caller (see `src/cli/storage.ts`).
+ * platform-specific and stays with the caller.
  */
 import { TeleCryptIOStorage } from "../TeleCryptIOStorage.js";
 import type { DownloadedFile, FileDetails, FileInfo, FolderDetails, FolderInfo, DeleteResult, JoinResult, Member, RecoveryRestore, RecoverySetup, RenameResult, ShareResult, UnshareResult } from "./types.js";

package/dist/core/operations.js

@@ -1,4 +1,4 @@
-import { CliError } from "./errors.js";
+import { StorageError } from "./errors.js";
 import { waitForCondition } from "./poll.js";
 /**
  * Production Synapse enforces the built-in rc_messages budget (per-account
@@ -17,7 +17,7 @@ function isRateLimited(error) {
     const isRateLimitError = error.isRateLimitError;
     return typeof isRateLimitError === "function" && isRateLimitError.call(error) === true;
 }
-async function withRateLimitRetry(label, operation) {
+async function withRateLimitRetry(operation) {
     for (let attempt = 0;; attempt++) {
         try {
             return await operation();
@@ -56,7 +56,7 @@ async function resolveTree(storage, folderId) {
         });
     }
     catch {
-        throw new CliError(`folder not found: ${folderId}`);
+        throw new StorageError(`folder not found: ${folderId}`);
     }
 }
 /** As `resolveTree`, but for a specific file within an already-resolved
@@ -67,14 +67,14 @@ async function resolveFile(tree, fileId) {
         return await waitForCondition(() => tree.getFile(fileId), { timeoutMs: 15000 });
     }
     catch {
-        throw new CliError(`file not found: ${fileId}`);
+        throw new StorageError(`file not found: ${fileId}`);
     }
 }
 function toArrayBuffer(bytes) {
     return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
 }
 export async function createFolder(storage, name) {
-    const tree = await withRateLimitRetry("createFolder", () => storage.createTree(name));
+    const tree = await withRateLimitRetry(() => storage.createTree(name));
     return { id: tree.id, name };
 }
 /** Top-level folders only — excludes subdirectories of an existing tree. */
@@ -92,10 +92,10 @@ export function getMyFolderRole(storage, folderId) {
 }
 export async function joinFolder(storage, folderId) {
     try {
-        await withRateLimitRetry("joinFolder", () => storage.getClient().joinRoom(folderId));
+        await withRateLimitRetry(() => storage.getClient().joinRoom(folderId));
     }
     catch (err) {
-        throw new CliError(`join failed: ${err.message}`);
+        throw new StorageError(`join failed: ${err.message}`);
     }
     return { folderId, joined: true };
 }
@@ -144,7 +144,7 @@ export async function listPendingInvites(storage) {
 export async function declineInvite(storage, folderId) {
     const client = storage.getClient();
     try {
-        await withRateLimitRetry("declineInvite", async () => {
+        await withRateLimitRetry(async () => {
             await client.leave(folderId);
             // The server only allows forgetting a room once this account's
             // membership is `leave`; forgetting removes the room from the local
@@ -155,7 +155,7 @@ export async function declineInvite(storage, folderId) {
         });
     }
     catch (err) {
-        throw new CliError(`decline failed: ${err.message}`);
+        throw new StorageError(`decline failed: ${err.message}`);
     }
     return { folderId, declined: true };
 }
@@ -169,33 +169,33 @@ export async function declineInvite(storage, folderId) {
  */
 export async function shareFolder(storage, folderId, userId, role) {
     if (role !== "viewer" && role !== "editor") {
-        throw new CliError(`invalid --role "${role}" (must be viewer or editor)`);
+        throw new StorageError(`invalid --role "${role}" (must be viewer or editor)`);
     }
     const tree = await resolveTree(storage, folderId);
     try {
-        await withRateLimitRetry("shareFolder.invite", () => tree.invite(userId));
+        await withRateLimitRetry(() => tree.invite(userId));
     }
     catch (err) {
         if (!/already in the room/i.test(err.message)) {
             throw err;
         }
     }
-    await withRateLimitRetry("shareFolder.setPermissions", () => tree.setPermissions(userId, role));
+    await withRateLimitRetry(() => tree.setPermissions(userId, role));
     return { folderId, userId, role };
 }
 export async function unshareFolder(storage, folderId, userId) {
     await resolveTree(storage, folderId);
     try {
-        await withRateLimitRetry("unshareFolder", () => storage.getClient().kick(folderId, userId, "unshared"));
+        await withRateLimitRetry(() => storage.getClient().kick(folderId, userId, "unshared"));
     }
     catch (err) {
-        throw new CliError(`unshare failed: ${err.message}`);
+        throw new StorageError(`unshare failed: ${err.message}`);
     }
     return { folderId, userId, removed: true };
 }
 export async function listMembers(storage, folderId) {
     const tree = await resolveTree(storage, folderId);
-    return withRateLimitRetry("listMembers", () => storage.listMembers(tree));
+    return withRateLimitRetry(() => storage.listMembers(tree));
 }
 export async function listFiles(storage, folderId) {
     const tree = await resolveTree(storage, folderId);
@@ -208,12 +208,12 @@ export async function listSubfolders(storage, folderId) {
 }
 export async function createSubfolder(storage, folderId, name) {
     const tree = await resolveTree(storage, folderId);
-    const sub = await withRateLimitRetry("createSubfolder", () => storage.createSubtree(tree, name));
+    const sub = await withRateLimitRetry(() => storage.createSubtree(tree, name));
     return { id: sub.id, name };
 }
 export async function renameFolder(storage, folderId, name) {
     const tree = await resolveTree(storage, folderId);
-    await withRateLimitRetry("renameFolder", () => tree.setName(name));
+    await withRateLimitRetry(() => tree.setName(name));
     return { id: folderId, name };
 }
 export async function deleteFolder(storage, folderId) {
@@ -227,7 +227,7 @@ export async function deleteFolder(storage, folderId) {
     // `leave`, which `tree.delete()` has just completed for the whole tree.
     const subdirectoryIds = tree.getDirectories().map((d) => d.id);
     const client = storage.getClient();
-    await withRateLimitRetry("deleteFolder", async () => {
+    await withRateLimitRetry(async () => {
         await tree.delete();
         await client.forget(folderId);
         for (const subId of subdirectoryIds) {
@@ -239,7 +239,7 @@ export async function deleteFolder(storage, folderId) {
 export async function renameFile(storage, folderId, fileId, name) {
     const tree = await resolveTree(storage, folderId);
     const branch = await resolveFile(tree, fileId);
-    await withRateLimitRetry("renameFile", () => branch.setName(name));
+    await withRateLimitRetry(() => branch.setName(name));
     // `setName` resolves when the homeserver accepts the state event, but a
     // fresh CLI/UI process can still read the previous local room state for a
     // short time. Do not report success until this client has observed the new
@@ -253,12 +253,12 @@ export async function renameFile(storage, folderId, fileId, name) {
 export async function deleteFile(storage, folderId, fileId) {
     const tree = await resolveTree(storage, folderId);
     const branch = await resolveFile(tree, fileId);
-    await withRateLimitRetry("deleteFile", () => branch.delete());
+    await withRateLimitRetry(() => branch.delete());
     return { id: fileId, deleted: true };
 }
 export async function uploadFile(storage, folderId, name, bytes, mimetype) {
     const tree = await resolveTree(storage, folderId);
-    const fileId = await withRateLimitRetry("uploadFile", () => storage.uploadFile(tree, name, toArrayBuffer(bytes), mimetype));
+    const fileId = await withRateLimitRetry(() => storage.uploadFile(tree, name, toArrayBuffer(bytes), mimetype));
     return { id: fileId, name, mimetype };
 }
 export async function downloadFile(storage, folderId, fileId) {
@@ -269,7 +269,7 @@ export async function downloadFile(storage, folderId, fileId) {
         result = await storage.downloadFile(branch);
     }
     catch (err) {
-        throw new CliError(`download failed: ${err.message}`);
+        throw new StorageError(`download failed: ${err.message}`);
     }
     return {
         bytes: new Uint8Array(result.data),

package/dist/core/types.d.ts

@@ -1,12 +1,4 @@
-/**
- * The shared typed result contract for every `core/operations.ts` function.
- * This is deliberately the ONE definition of these shapes: the CLI's
- * `--json` schema is these types (or a trivial projection of them, e.g.
- * `FolderInfo.id` -> the CLI's `folderId` key for backwards-compatible
- * command output), and the future React UI's data model is these types
- * directly. Keeping it here means the CLI and the UI can never drift apart
- * on what an operation returns.
- */
+/** The typed result contract for every `core/operations.ts` function. */
 export interface FolderInfo {
     id: string;
     name: string;

package/dist/core/types.js

@@ -1,10 +1,2 @@
-/**
- * The shared typed result contract for every `core/operations.ts` function.
- * This is deliberately the ONE definition of these shapes: the CLI's
- * `--json` schema is these types (or a trivial projection of them, e.g.
- * `FolderInfo.id` -> the CLI's `folderId` key for backwards-compatible
- * command output), and the future React UI's data model is these types
- * directly. Keeping it here means the CLI and the UI can never drift apart
- * on what an operation returns.
- */
+/** The typed result contract for every `core/operations.ts` function. */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telecrypt-io/storage",
-  "version": "0.2.13",
+  "version": "0.3.0",
   "license": "BUSL-1.1",
   "type": "module",
   "main": "dist/index.js",