@evolu/common 6.0.1-preview.25 → 6.0.1-preview.27

package/src/Evolu/LocalAuth.ts

@@ -10,9 +10,9 @@ import {
   OwnerWriteKey,
 } from "./Owner.js";
 
-/** 
- * Local authentication and authorization system for Evolu.
- * This is API is subject to change and not recommended for production use.
+/**
+ * Local authentication and authorization system for Evolu. This is API is
+ * subject to change and not recommended for production use.
  *
  * @experimental
  */
@@ -84,7 +84,7 @@ export const createLocalAuth = (
     id: OwnerId,
     options?: LocalAuthOptions,
   ): Promise<void> => {
-    await deps.secureStorage.setItem(AUTH_METAKEY_LAST_OWNER, id, {
+    await deps.secureStorage.setItem(localAuthMetakeyLastOwner, id, {
       ...buildAuthOptions(options),
       accessControl: "none",
     });
@@ -93,7 +93,7 @@ export const createLocalAuth = (
   const getLastOwnerId = async (
     options?: LocalAuthOptions,
   ): Promise<OwnerId | undefined> => {
-    const item = await deps.secureStorage.getItem(AUTH_METAKEY_LAST_OWNER, {
+    const item = await deps.secureStorage.getItem(localAuthMetakeyLastOwner, {
       ...buildAuthOptions(options),
       accessControl: "none",
     });
@@ -103,7 +103,7 @@ export const createLocalAuth = (
   const getOwnerNames = async (
     options?: LocalAuthOptions,
   ): Promise<Record<OwnerId, string>> => {
-    const item = await deps.secureStorage.getItem(AUTH_METAKEY_OWNER_NAMES, {
+    const item = await deps.secureStorage.getItem(localAuthMetakeyOwnerNames, {
       ...buildAuthOptions(options),
       accessControl: "none",
     });
@@ -122,7 +122,7 @@ export const createLocalAuth = (
     const names = await getOwnerNames(options);
     names[id] = username;
     await deps.secureStorage.setItem(
-      AUTH_METAKEY_OWNER_NAMES,
+      localAuthMetakeyOwnerNames,
       JSON.stringify(names),
       {
         ...buildAuthOptions(options),
@@ -137,7 +137,7 @@ export const createLocalAuth = (
   ): Promise<void> => {
     const { [id]: _, ...names } = await getOwnerNames(options);
     await deps.secureStorage.setItem(
-      AUTH_METAKEY_OWNER_NAMES,
+      localAuthMetakeyOwnerNames,
       JSON.stringify(names),
       {
         ...buildAuthOptions(options),
@@ -157,8 +157,8 @@ export const createLocalAuth = (
       .filter(Boolean)
       .filter(
         (i) =>
-          i.key !== AUTH_METAKEY_LAST_OWNER &&
-          i.key !== AUTH_METAKEY_OWNER_NAMES,
+          i.key !== localAuthMetakeyLastOwner &&
+          i.key !== localAuthMetakeyOwnerNames,
       )
       .map((i) => i.key as OwnerId);
   };
@@ -171,17 +171,29 @@ export const createLocalAuth = (
     username?: string,
   ): LocalAuthOptions => {
     const newOptions: LocalAuthOptions = {
-      ...AUTH_DEFAULT_OPTIONS,
+      ...localAuthDefaultOptions,
       ...(username && { webAuthnUsername: username }),
       ...options,
     };
     return {
       ...newOptions,
       authenticationPrompt: {
-        title: replaceMessageTokens(newOptions.authenticationPrompt?.title ?? "", username),
-        cancel: replaceMessageTokens(newOptions.authenticationPrompt?.cancel ?? "", username),
-        subtitle: replaceMessageTokens(newOptions.authenticationPrompt?.subtitle ?? "", username),
-        description: replaceMessageTokens(newOptions.authenticationPrompt?.description ?? "", username),
+        title: replaceMessageTokens(
+          newOptions.authenticationPrompt?.title ?? "",
+          username,
+        ),
+        cancel: replaceMessageTokens(
+          newOptions.authenticationPrompt?.cancel ?? "",
+          username,
+        ),
+        subtitle: replaceMessageTokens(
+          newOptions.authenticationPrompt?.subtitle ?? "",
+          username,
+        ),
+        description: replaceMessageTokens(
+          newOptions.authenticationPrompt?.description ?? "",
+          username,
+        ),
       },
     };
   };
@@ -299,13 +311,11 @@ export const createLocalAuth = (
   };
 };
 
-// TOHO: With `const`, we don't need UPPER_CASE
-export const AUTH_NAMESPACE = "evolu";
-export const AUTH_METAKEY_LAST_OWNER = "_last_owner";
-export const AUTH_METAKEY_OWNER_NAMES = "_owner_names";
-export const AUTH_DEFAULT_OPTIONS: LocalAuthOptions = {
-  service: AUTH_NAMESPACE,
-  keychainGroup: AUTH_NAMESPACE,
+export const localAuth_Namespace = "evolu";
+
+export const localAuthDefaultOptions: LocalAuthOptions = {
+  service: localAuth_Namespace,
+  keychainGroup: localAuth_Namespace,
   androidBiometricsStrongOnly: true,
   iosSynchronizable: true,
   webAuthnUsername: "Evolu User",
@@ -314,6 +324,9 @@ export const AUTH_DEFAULT_OPTIONS: LocalAuthOptions = {
   },
 };
 
+const localAuthMetakeyLastOwner = "_last_owner";
+const localAuthMetakeyOwnerNames = "_owner_names";
+
 export interface AuthResult {
   /** The app owner created during registration. */
   readonly owner: AppOwner | undefined;

package/src/Evolu/Owner.ts

@@ -16,29 +16,12 @@ import {
   idToIdBytes,
   Mnemonic,
   NonNegativeInt,
+  PositiveInt,
 } from "../Type.js";
 import { getOrNull } from "../Result.js";
-
-/**
- * 32 bytes of cryptographic entropy used to derive {@link Owner} keys.
- *
- * Can be created using {@link createOwnerSecret} or converted from a
- * {@link Mnemonic} using {@link mnemonicToOwnerSecret}.
- */
-export const OwnerSecret = brand("OwnerSecret", Entropy32);
-export type OwnerSecret = typeof OwnerSecret.Type;
-
-/** Creates a {@link OwnerSecret}. */
-export const createOwnerSecret = (deps: RandomBytesDep): OwnerSecret =>
-  deps.randomBytes.create(32) as OwnerSecret;
-
-/** Converts an {@link OwnerSecret} to a {@link Mnemonic}. */
-export const ownerSecretToMnemonic = (secret: OwnerSecret): Mnemonic =>
-  bip39.entropyToMnemonic(secret, wordlist) as Mnemonic;
-
-/** Converts a {@link Mnemonic} to an {@link OwnerSecret}. */
-export const mnemonicToOwnerSecret = (mnemonic: Mnemonic): OwnerSecret =>
-  bip39.mnemonicToEntropy(mnemonic, wordlist) as OwnerSecret;
+import type { Timestamp } from "./Timestamp.js";
+import { TimestampBytes } from "./Timestamp.js";
+import type { Storage } from "./Storage.js";
 
 /**
  * The Owner represents ownership of data in Evolu. Every database change is
@@ -105,6 +88,27 @@ export type OwnerEncryptionKey = typeof OwnerEncryptionKey.Type;
 export const OwnerWriteKey = brand("OwnerWriteKey", Entropy16);
 export type OwnerWriteKey = typeof OwnerWriteKey.Type;
 
+/**
+ * 32 bytes of cryptographic entropy used to derive {@link Owner} keys.
+ *
+ * Can be created using {@link createOwnerSecret} or converted from a
+ * {@link Mnemonic} using {@link mnemonicToOwnerSecret}.
+ */
+export const OwnerSecret = brand("OwnerSecret", Entropy32);
+export type OwnerSecret = typeof OwnerSecret.Type;
+
+/** Creates a {@link OwnerSecret}. */
+export const createOwnerSecret = (deps: RandomBytesDep): OwnerSecret =>
+  deps.randomBytes.create(32) as OwnerSecret;
+
+/** Converts an {@link OwnerSecret} to a {@link Mnemonic}. */
+export const ownerSecretToMnemonic = (secret: OwnerSecret): Mnemonic =>
+  bip39.entropyToMnemonic(secret, wordlist) as Mnemonic;
+
+/** Converts a {@link Mnemonic} to an {@link OwnerSecret}. */
+export const mnemonicToOwnerSecret = (mnemonic: Mnemonic): OwnerSecret =>
+  bip39.mnemonicToEntropy(mnemonic, wordlist) as OwnerSecret;
+
 /** Creates a randomly generated {@link OwnerWriteKey}. */
 export const createOwnerWriteKey = (deps: RandomBytesDep): OwnerWriteKey =>
   deps.randomBytes.create(16) as OwnerWriteKey;
@@ -174,82 +178,6 @@ export const createAppOwner = (secret: OwnerSecret): AppOwner => ({
   ...createOwner(secret),
 });
 
-/**
- * Transport configuration for connecting to relays.
- *
- * Each {@link Owner} can specify one or more transports to connect to different
- * relays for data synchronization. Currently supports WebSocket transport, with
- * future support planned for Bluetooth, LocalNetwork, and other protocols.
- */
-export type TransportConfig = WebSocketTransportConfig;
-
-/**
- * WebSocket transport configuration for relay connections.
- *
- * Use {@link createWebSocketTransportConfig} to create a properly formatted URL
- * with {@link OwnerId}. The relay uses {@link parseOwnerIdFromUrl} to extract the
- * OwnerId from the query string.
- *
- * ### Authentication and Error Handling
- *
- * When a relay rejects a connection (invalid OwnerId, unauthorized owner, or
- * server error), the browser WebSocket API does not expose the specific HTTP
- * status code or reason - it only reports a generic connection failure. The
- * client automatically retries with exponential backoff and jitter, eventually
- * succeeding once the configuration or server issue is resolved.
- *
- * Legitimate clients will be properly configured with valid credentials, so
- * automatic retry is appropriate.
- *
- * @see {@link createWebSocketTransportConfig}
- * @see {@link parseOwnerIdFromUrl}
- */
-export interface WebSocketTransportConfig {
-  readonly type: "WebSocket";
-  readonly url: string;
-}
-
-/**
- * Creates a {@link WebSocketTransportConfig} for the given relay URL and
- * {@link OwnerId}.
- *
- * ### Example
- *
- * ```ts
- * const transport = createWebSocketTransportConfig({
- *   relayUrl: "wss://relay.evolu.dev",
- *   ownerId: owner.id,
- * });
- * // Result: { type: "WebSocket", url: "wss://relay.evolu.dev?ownerId=..." }
- * ```
- */
-export const createWebSocketTransportConfig = ({
-  relayUrl,
-  ownerId,
-}: {
-  readonly relayUrl: string;
-  readonly ownerId: OwnerId;
-}): WebSocketTransportConfig => ({
-  type: "WebSocket",
-  url: `${relayUrl}?ownerId=${ownerId}`,
-});
-
-/**
- * Extracts {@link OwnerId} from a URL query string.
- *
- * Parses the query string `?ownerId=...` and validates that the extracted value
- * is a valid {@link OwnerId}.
- *
- * ### Example
- *
- * ```ts
- * parseOwnerIdFromUrl("/sync?ownerId=_12345678abcdefgh");
- * // Returns: OwnerId or null
- * ```
- */
-export const parseOwnerIdFromUrl = (url: string | undefined): OwnerId | null =>
-  getOrNull(OwnerId.fromUnknown(url?.split("=")[1]));
-
 /**
  * An {@link Owner} for sharding data.
  *
@@ -263,13 +191,13 @@ export const parseOwnerIdFromUrl = (url: string | undefined): OwnerId | null =>
  */
 export interface ShardOwner extends Owner {
   readonly type: "ShardOwner";
-  readonly transports?: ReadonlyArray<TransportConfig>;
+  readonly transports?: ReadonlyArray<OwnerTransport>;
 }
 
 /** Creates a {@link ShardOwner} from an {@link OwnerSecret}. */
 export const createShardOwner = (
   secret: OwnerSecret,
-  transports?: ReadonlyArray<TransportConfig>,
+  transports?: ReadonlyArray<OwnerTransport>,
 ): ShardOwner => {
   return {
     type: "ShardOwner",
@@ -299,7 +227,7 @@ export const createShardOwner = (
 export const deriveShardOwner = (
   owner: AppOwner,
   path: NonEmptyReadonlyArray<string | number>,
-  transports?: ReadonlyArray<TransportConfig>,
+  transports?: ReadonlyArray<OwnerTransport>,
 ): ShardOwner => {
   const secret = createSlip21(owner.encryptionKey, path) as OwnerSecret;
 
@@ -313,7 +241,7 @@ export const deriveShardOwner = (
 /** An {@link Owner} for collaborative data with write access. */
 export interface SharedOwner extends Owner {
   readonly type: "SharedOwner";
-  readonly transports?: ReadonlyArray<TransportConfig>;
+  readonly transports?: ReadonlyArray<OwnerTransport>;
 }
 
 /**
@@ -325,7 +253,7 @@ export interface SharedOwner extends Owner {
  */
 export const createSharedOwner = (
   secret: OwnerSecret,
-  transports?: ReadonlyArray<TransportConfig>,
+  transports?: ReadonlyArray<OwnerTransport>,
 ): SharedOwner => {
   return {
     type: "SharedOwner",
@@ -343,7 +271,7 @@ export interface SharedReadonlyOwner {
   readonly type: "SharedReadonlyOwner";
   readonly id: OwnerId;
   readonly encryptionKey: EncryptionKey;
-  readonly transports?: ReadonlyArray<TransportConfig>;
+  readonly transports?: ReadonlyArray<OwnerTransport>;
 }
 
 /** Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}. */
@@ -355,3 +283,112 @@ export const createSharedReadonlyOwner = (
   encryptionKey: sharedOwner.encryptionKey,
   ...(sharedOwner.transports && { transports: sharedOwner.transports }),
 });
+
+/**
+ * Transport configuration for connecting to relays.
+ *
+ * Currently only WebSocket, in the future Bluetooth, LocalNetwork, etc.
+ */
+export type OwnerTransport = OwnerWebSocketTransport;
+
+/**
+ * WebSocket transport configuration.
+ *
+ * ### Authentication and Error Handling
+ *
+ * When a relay rejects a connection (invalid OwnerId, unauthorized owner, or
+ * server error), the browser WebSocket API does not expose the specific HTTP
+ * status code or reason - it only reports a generic connection failure. The
+ * client automatically retries with exponential backoff and jitter, eventually
+ * succeeding once the configuration or server issue is resolved.
+ *
+ * Legitimate clients will be properly configured with valid credentials, so
+ * automatic retry is OK.
+ *
+ * @see {@link createOwnerWebSocketTransport}
+ * @see {@link parseOwnerIdFromOwnerWebSocketTransportUrl}
+ */
+export interface OwnerWebSocketTransport {
+  readonly type: "WebSocket";
+  readonly url: string;
+}
+
+/**
+ * Creates an {@link OwnerWebSocketTransport} for the given relay URL and
+ * {@link OwnerId}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const transport = createOwnerWebSocketTransport({
+ *   url: "wss://relay.evolu.dev",
+ *   ownerId: owner.id,
+ * });
+ * // Result: { type: "WebSocket", url: "wss://relay.evolu.dev?ownerId=..." }
+ * ```
+ */
+export const createOwnerWebSocketTransport = (config: {
+  readonly url: string;
+  readonly ownerId: OwnerId;
+}): OwnerWebSocketTransport => ({
+  type: "WebSocket",
+  url: `${config.url}?ownerId=${config.ownerId}`,
+});
+
+/**
+ * Extracts {@link OwnerId} from an {@link OwnerWebSocketTransport} URL query
+ * string.
+ *
+ * Parses the query string `?ownerId=...` and validates that the extracted value
+ * is a valid {@link OwnerId}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * parseOwnerIdFromOwnerWebSocketTransportUrl(
+ *   "/sync?ownerId=_12345678abcdefgh",
+ * );
+ * // Returns: OwnerId or null
+ * ```
+ */
+export const parseOwnerIdFromOwnerWebSocketTransportUrl = (
+  url: string,
+): OwnerId | null => getOrNull(OwnerId.fromUnknown(url.split("=")[1]));
+
+/**
+ * Usage data for an {@link OwnerId}.
+ *
+ * Tracks data consumption to monitor usage patterns and enforce quotas if
+ * needed. Used by both relays and clients.
+ *
+ * Relays and clients must handle rate limiting, connection limits, and request
+ * throttling separately with in-memory state.
+ */
+export interface OwnerUsage {
+  /** The {@link Owner} this usage data belongs to. */
+  readonly ownerId: OwnerIdBytes;
+
+  /** Total bytes stored in the database. */
+  readonly storedBytes: PositiveInt;
+
+  /** Total bytes received. */
+  readonly receivedBytes: number;
+
+  /** Total bytes sent. */
+  readonly sentBytes: number;
+
+  /**
+   * The minimum {@link Timestamp}.
+   *
+   * Helps {@link Storage} choose faster algorithms.
+   */
+  readonly firstTimestamp: TimestampBytes | null;
+
+  /**
+   * The maximum {@link Timestamp}.
+   *
+   * Helps {@link Storage} choose faster algorithms. Free relays can use it to
+   * identify inactive accounts for cleanup or archival.
+   */
+  readonly lastTimestamp: TimestampBytes | null;
+}

package/src/Evolu/Relay.ts

@@ -3,13 +3,13 @@ import { ConsoleConfig, ConsoleDep } from "../Console.js";
 import { TimingSafeEqualDep } from "../Crypto.js";
 import { LazyValue } from "../Function.js";
 import { err, ok, Result } from "../Result.js";
-import { sql, SqliteError } from "../Sqlite.js";
+import { sql, SqliteDep, SqliteError } from "../Sqlite.js";
 import { SimpleName } from "../Type.js";
-import { OwnerId, OwnerWriteKey, TransportConfig } from "./Owner.js";
+import { OwnerId, OwnerTransport, OwnerWriteKey } from "./Owner.js";
 import { ProtocolInvalidDataError } from "./Protocol.js";
 import {
-  createSqliteStorageBase,
-  CreateSqliteStorageBaseOptions,
+  createBaseSqliteStorage,
+  CreateBaseSqliteStorageOptions,
   EncryptedDbChange,
   SqliteStorageDeps,
   Storage,
@@ -44,9 +44,9 @@ export interface RelayConfig extends ConsoleConfig {
    * this only controls relay access, not write permissions. Since all data is
    * encrypted on the relay, OwnerId exposure is safe.
    *
-   * Owners specify which relays to connect to via {@link TransportConfig}. In
+   * Owners specify which relays to connect to via {@link OwnerTransport}. In
    * WebSocket-based implementations, this check occurs before accepting the
-   * connection, with the OwnerId typically extracted from the URL path (e.g.,
+   * connection, with the OwnerId typically extracted from the URL Path (e.g.,
    * `ws://localhost:4000/<ownerId>`).
    *
    * ### Example
@@ -68,36 +68,11 @@ export interface RelayConfig extends ConsoleConfig {
 
 export const createRelaySqliteStorage =
   (deps: SqliteStorageDeps & TimingSafeEqualDep) =>
-  (options: CreateSqliteStorageBaseOptions): Result<Storage, SqliteError> => {
-    const sqliteStorageBase = createSqliteStorageBase(deps)(options);
-    if (!sqliteStorageBase.ok) return sqliteStorageBase;
-
-    for (const query of [
-      sql`
-        create table if not exists evolu_writeKey (
-          "ownerId" blob not null,
-          "writeKey" blob not null,
-          primary key ("ownerId")
-        )
-        strict;
-      `,
-
-      sql`
-        create table if not exists evolu_message (
-          "ownerId" blob not null,
-          "timestamp" blob not null,
-          "change" blob not null,
-          primary key ("ownerId", "timestamp")
-        )
-        strict;
-      `,
-    ]) {
-      const result = deps.sqlite.exec(query);
-      if (!result.ok) return result;
-    }
-
-    return ok({
-      ...sqliteStorageBase.value,
+  (options: CreateBaseSqliteStorageOptions): Storage => {
+    const sqliteStorageBase = createBaseSqliteStorage(deps)(options);
+
+    return {
+      ...sqliteStorageBase,
 
       /**
        * Lazily authorizes the initiator's {@link OwnerWriteKey} for the given
@@ -159,11 +134,10 @@ export const createRelaySqliteStorage =
       writeMessages: async (ownerId, messages) => {
         const result = deps.sqlite.transaction(() => {
           for (const message of messages) {
-            const insertTimestampResult =
-              sqliteStorageBase.value.insertTimestamp(
-                ownerId,
-                timestampToTimestampBytes(message.timestamp),
-              );
+            const insertTimestampResult = sqliteStorageBase.insertTimestamp(
+              ownerId,
+              timestampToTimestampBytes(message.timestamp),
+            );
             if (!insertTimestampResult.ok) return insertTimestampResult;
 
             const insertMessage = deps.sqlite.exec(sql`
@@ -207,18 +181,18 @@ export const createRelaySqliteStorage =
 
       deleteOwner: (ownerId) => {
         const result = deps.sqlite.transaction(() => {
-          const del1 = deps.sqlite.exec(sql`
+          const deleteWriteKey = deps.sqlite.exec(sql`
             delete from evolu_writeKey where ownerId = ${ownerId};
           `);
-          if (!del1.ok) return del1;
+          if (!deleteWriteKey.ok) return deleteWriteKey;
 
-          const del2 = deps.sqlite.exec(sql`
+          const deleteMessages = deps.sqlite.exec(sql`
             delete from evolu_message where ownerId = ${ownerId};
           `);
-          if (!del2.ok) return del2;
+          if (!deleteMessages.ok) return deleteMessages;
 
-          const del3 = sqliteStorageBase.value.deleteOwner(ownerId);
-          if (!del3) return err(null);
+          const deleteBaseOwner = sqliteStorageBase.deleteOwner(ownerId);
+          if (!deleteBaseOwner) return err(null);
 
           return ok();
         });
@@ -228,9 +202,39 @@ export const createRelaySqliteStorage =
         }
         return true;
       },
-    });
+    };
   };
 
+export const createRelayStorageTables = (
+  deps: SqliteDep,
+): Result<void, SqliteError> => {
+  for (const query of [
+    sql`
+      create table evolu_writeKey (
+        "ownerId" blob not null,
+        "writeKey" blob not null,
+        primary key ("ownerId")
+      )
+      strict;
+    `,
+
+    sql`
+      create table evolu_message (
+        "ownerId" blob not null,
+        "timestamp" blob not null,
+        "change" blob not null,
+        primary key ("ownerId", "timestamp")
+      )
+      strict;
+    `,
+  ]) {
+    const result = deps.sqlite.exec(query);
+    if (!result.ok) return result;
+  }
+
+  return ok();
+};
+
 export interface RelayLogger {
   readonly started: (enableLogging: boolean, port: number) => void;
   readonly storageError: (error: unknown) => void;