@evolu/common 6.0.1-preview.19 → 6.0.1-preview.20

package/src/Evolu/Owner.ts

@@ -1,118 +1,159 @@
-/* eslint-disable jsdoc/no-undefined-types */
-/**
- * Evolu Owner - Data Ownership and Collaboration
- *
- * An {@link Owner} is an entity that represents ownership of data in Evolu. It
- * consists of cryptographic keys derived from a {@link Mnemonic} via SLIP-21:
- *
- * - **{@link OwnerId}**: Globally unique public identifier
- * - **{@link EncryptionKey}**: Symmetric encryption key for data protection
- * - **{@link WriteKey}**: Authentication token for write operations
- *
- * Every Evolu app has at least one owner, the {@link AppOwner}. There are
- * several owner variants for different use cases:
- *
- * **{@link ShardOwner}**: Derived from {@link AppOwner} for partitioning data and
- * selective synchronization using {@link createShardOwner}
- *
- * **{@link SharedOwner}**: Created for collaboration with write access, not
- * meant to be shared directly
- *
- * **{@link SharedReadonlyOwner}**: Read-only version for safe data sharing,
- * created from {@link SharedOwner} using {@link createSharedReadonlyOwner}
- *
- * Owners are designed for data synchronization and backup. Authentication
- * systems built on public/private key cryptography use these primitives. This
- * design ensures Evolu Relay knows as little as possible - it only sees
- * Timestamp, OwnerId, and EncryptedDbChange.
- *
- * @module
- */
-
+import * as bip39 from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english.js";
 import { NonEmptyReadonlyArray } from "../Array.js";
 import {
-  CreateMnemonicDep,
-  CreateRandomBytesDep,
   createSlip21,
-  createSlip21Id,
   EncryptionKey,
-  MnemonicSeed,
-  mnemonicToMnemonicSeed,
+  Entropy16,
+  Entropy32,
+  RandomBytesDep,
 } from "../Crypto.js";
 import {
-  Base64Url,
   brand,
   Id,
-  length,
+  IdBytes,
+  idBytesToId,
+  idToIdBytes,
   Mnemonic,
   NonNegativeInt,
-  Uint8Array,
 } from "../Type.js";
 
 /**
- * Represents ownership of data in Evolu. Created from a {@link Mnemonic} via
- * SLIP-21 key derivation using {@link createOwner}, providing cryptographic keys
- * for data access and authentication.
+ * 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;
+
+/**
+ * The Owner represents ownership of data in Evolu. Every database change is
+ * assigned to an owner, enabling sync functionality and access control.
+ *
+ * Owners enable **partial sync** - applications can choose which owners to
+ * sync, allowing selective data synchronization based on specific needs.
+ *
+ * Owners also provide **real data deletion** - while individual changes in
+ * local-first/distributed systems can only be marked as deleted, entire owners
+ * can be completely deleted from both relays and devices (except for
+ * {@link AppOwner}, which must be preserved for sync coordination).
+ *
+ * Evolu provides different owner types depending on their use case:
+ *
+ * - **Coordination**: {@link AppOwner} for sync coordination and long-term
+ *   persistence
+ * - **Data partitioning**: {@link ShardOwner} for partitioning application data
+ * - **Collaboration**: {@link SharedOwner} for collaborative write access
+ * - **Data sharing**: {@link SharedReadonlyOwner} for read-only access to shared
+ *   data
+ *
+ * Owners are cryptographically derived from an {@link OwnerSecret} using
+ * SLIP-21, ensuring secure and deterministic key generation:
  *
  * - {@link OwnerId}: Globally unique public identifier
  * - {@link EncryptionKey}: Symmetric encryption key for data protection
- * - {@link WriteKey}: Authentication token for write operations (rotatable)
+ * - {@link OwnerWriteKey}: Authentication token for write operations (rotatable)
+ *
+ * @see {@link createOwner}
  */
 export interface Owner {
   readonly id: OwnerId;
-  readonly encryptionKey: EncryptionKey;
-  readonly writeKey: WriteKey;
+  readonly encryptionKey: OwnerEncryptionKey;
+  readonly writeKey: OwnerWriteKey;
 }
 
 /**
- * The unique identifier of {@link Owner} derived from the {@link Mnemonic}.
- *
- * This branded {@link Id} type, generated by {@link createSlip21Id}, is a
- * 21-character {@link Base64Url} string (126 bits of entropy), providing a
- * compact, shareable, and secure identifier for UI use, tied to the owner's
- * mnemonic and derivation path.
+ * OwnerId is a branded {@link Id} that uniquely identifies an {@link Owner}.
+ * Branded from {@link Id} to leverage existing helpers like {@link idToIdBytes}.
  */
 export const OwnerId = brand("OwnerId", Id);
 export type OwnerId = typeof OwnerId.Type;
 
-export const writeKeyLength = 16 as NonNegativeInt;
+/** Bytes representation of {@link OwnerId}. */
+export const OwnerIdBytes = brand("OwnerIdBytes", IdBytes);
+export type OwnerIdBytes = typeof OwnerIdBytes.Type;
+
+export const ownerIdToOwnerIdBytes = (ownerId: OwnerId): OwnerIdBytes =>
+  idToIdBytes(ownerId) as OwnerIdBytes;
+
+export const ownerIdBytesToOwnerId = (ownerIdBytes: OwnerIdBytes): OwnerId =>
+  idBytesToId(ownerIdBytes as IdBytes) as OwnerId;
+
+export const ownerWriteKeyLength = 16 as NonNegativeInt;
+
+export const OwnerEncryptionKey = brand("OwnerEncryptionKey", EncryptionKey);
+export type OwnerEncryptionKey = typeof OwnerEncryptionKey.Type;
 
 /**
- * A secure token proving that the initiator can write changes. Derived from a
- * mnemonic or randomly generated via {@link createWriteKey}. It is rotatable.
+ * A secure token for write operations. It's derived from {@link OwnerSecret} by
+ * default and can be rotated via {@link createOwnerWriteKey}.
  */
-export const WriteKey = brand("WriteKey", length(writeKeyLength)(Uint8Array));
-export type WriteKey = typeof WriteKey.Type;
-
-/** Creates a randomly generated {@link WriteKey}. */
-export const createWriteKey = (deps: CreateRandomBytesDep): WriteKey =>
-  deps.createRandomBytes(16) as unknown as WriteKey;
+export const OwnerWriteKey = brand("OwnerWriteKey", Entropy16);
+export type OwnerWriteKey = typeof OwnerWriteKey.Type;
 
-/** Creates an {@link Owner} from a {@link Mnemonic} using SLIP-21 key derivation. */
-export const createOwner = (mnemonic: Mnemonic): Owner => {
-  const seed = mnemonicToMnemonicSeed(mnemonic);
-  return createOwnerFromMnemonicSeed(seed);
-};
+/** Creates a randomly generated {@link OwnerWriteKey}. */
+export const createOwnerWriteKey = (deps: RandomBytesDep): OwnerWriteKey =>
+  deps.randomBytes.create(16) as OwnerWriteKey;
 
 /**
- * Creates an {@link Owner} from a {@link MnemonicSeed} using SLIP-21 key
+ * Creates an {@link Owner} from a {@link OwnerSecret} using SLIP-21 key
  * derivation.
+ *
+ * This is an internal helper function, use:
+ *
+ * - {@link createAppOwner}
+ * - {@link createShardOwner}
+ * - {@link createSharedOwner}
+ * - {@link createSharedReadonlyOwner}
  */
-export const createOwnerFromMnemonicSeed = (seed: MnemonicSeed): Owner => ({
-  id: createSlip21Id(seed, ["Evolu", "Owner Id"]) as OwnerId,
+export const createOwner = (secret: OwnerSecret): Owner => ({
+  id: ownerIdBytesToOwnerId(
+    OwnerIdBytes.orThrow(
+      createSlip21(secret, ["Evolu", "OwnerIdBytes"]).slice(0, 16),
+    ),
+  ),
 
-  encryptionKey: createSlip21(seed, [
-    "Evolu",
-    "Encryption Key",
-  ]) as EncryptionKey,
+  encryptionKey: OwnerEncryptionKey.orThrow(
+    createSlip21(secret, ["Evolu", "OwnerEncryptionKey"]),
+  ),
 
-  writeKey: createSlip21(seed, ["Evolu", "Write Key"]).slice(0, 16) as WriteKey,
+  writeKey: OwnerWriteKey.orThrow(
+    createSlip21(secret, ["Evolu", "OwnerWriteKey"]).slice(0, 16),
+  ),
 });
 
 /**
- * The owner representing app data. Can be created from a {@link Mnemonic} or
- * from external keys when the mnemonic should not be shared with the Evolu
- * app.
+ * The AppOwner represents the application owner. It's created using a
+ * cryptographically secure random generator or derived from an external source,
+ * e.g., mnemonic stored securely in a hardware device.
+ *
+ * While it's possible to store all application data in AppOwner, the better
+ * approach is to use it only for sync coordination. Storing all app data in
+ * AppOwner means that data will be stored/synced forever. And that's a problem
+ * if we want to provide real data deletion or in-app data migration without
+ * data duplication. In local-first apps/distributed systems, we can't delete
+ * individual changes, we only mark them as deleted, otherwise sync could not
+ * work.
+ *
+ * If we really want to delete data or at least avoid syncing it, we must store
+ * it using a different owner than AppOwner, e.g. {@link ShardOwner} or
+ * {@link SharedOwner}, and delete that owner. The AppOwner itself must be
+ * preserved because it coordinates deletion information across devices. Other
+ * devices need to sync the information that an owner was deleted so they can
+ * delete their local data as well.
  */
 export interface AppOwner extends Owner {
   readonly type: "AppOwner";
@@ -125,71 +166,102 @@ export interface AppOwner extends Owner {
   readonly mnemonic?: Mnemonic | null;
 }
 
-export const createAppOwner = (mnemonic: Mnemonic): AppOwner => ({
+/** Creates an {@link AppOwner} from an {@link OwnerSecret}. */
+export const createAppOwner = (secret: OwnerSecret): AppOwner => ({
   type: "AppOwner",
-  mnemonic,
-  ...createOwner(mnemonic),
+  mnemonic: ownerSecretToMnemonic(secret),
+  ...createOwner(secret),
 });
 
+// DEV: Future transports: Bluetooth, LocalNetwork, etc.
+export type TransportConfig = WebSocketTransportConfig;
+
+export interface WebSocketTransportConfig {
+  readonly type: "WebSocket";
+  readonly url: string;
+}
+
 /**
- * Owner for sharding app data. Allows partitioning of database changes for
- * selective synchronization.
+ * An {@link Owner} for sharding data.
+ *
+ * ShardOwners are the recommended storage location for most application data
+ * because they can be completely deleted (both on relays and devices) and
+ * conditionally synced.
+ *
+ * Can be created from {@link OwnerSecret} via {@link createShardOwner} or
+ * deterministically derived from {@link AppOwner} using
+ * {@link deriveShardOwner}.
  */
 export interface ShardOwner extends Owner {
   readonly type: "ShardOwner";
+  readonly transports?: ReadonlyArray<TransportConfig>;
 }
 
-/**
- * Creates a {@link ShardOwner} derived from an {@link AppOwner} using the
- * specified path.
- *
- * ### Example
- *
- * ```ts
- * const contactsShard = createShardOwner(appOwner, ["contacts"]);
- * const projectShard = createShardOwner(appOwner, [
- *   "projects",
- *   "project-1",
- * ]);
- * ```
- */
+/** Creates a {@link ShardOwner} from an {@link OwnerSecret}. */
 export const createShardOwner = (
-  appOwner: AppOwner,
-  path: NonEmptyReadonlyArray<string>,
+  secret: OwnerSecret,
+  transports?: ReadonlyArray<TransportConfig>,
 ): ShardOwner => {
-  /**
-   * The shardSeed is never shared or persisted, only used for SLIP-21
-   * derivation to create shard-specific keys.
-   */
-  const shardSeed = createSlip21(
-    appOwner.encryptionKey as unknown as MnemonicSeed,
-    path,
-  ) as MnemonicSeed;
-
   return {
     type: "ShardOwner",
-    ...createOwnerFromMnemonicSeed(shardSeed),
+    ...createOwner(secret),
+    ...(transports && { transports }),
   };
 };
 
 /**
- * Owner for collaborative data with write access. Created by a user for their
- * own use, not meant to be shared directly. To share data, use
- * {@link createSharedReadonlyOwner} to create a {@link SharedReadonlyOwner} for
- * read-only access.
+ * Derives a {@link ShardOwner} from an {@link AppOwner} using the specified path.
+ *
+ * **Advantages of derived owners:**
+ *
+ * - **Deterministic**: Same path always produces the same ShardOwner across all
+ *   devices
+ * - **Immediate availability**: Can be hardcoded and used before sync occurs
+ * - **Consistent setup**: All devices start with identical data structure
+ * - **Lifecycle management**: Can implement epoch patterns for clean data
+ *   deletion and recreation
+ *
+ * **Common patterns:**
+ *
+ * - Use paths like `["shard", 1]` for versioned data lifecycle
+ * - Use paths like `["project", "MyApp", 1]` for named partitions with versions
+ * - Each device can derive the same owners and set up initial structure
  */
+export const deriveShardOwner = (
+  owner: AppOwner,
+  path: NonEmptyReadonlyArray<string | number>,
+  transports?: ReadonlyArray<TransportConfig>,
+): ShardOwner => {
+  const secret = createSlip21(owner.encryptionKey, path) as OwnerSecret;
+
+  return {
+    type: "ShardOwner",
+    ...createOwner(secret),
+    ...(transports && { transports }),
+  };
+};
+
+/** An {@link Owner} for collaborative data with write access. */
 export interface SharedOwner extends Owner {
   readonly type: "SharedOwner";
-  readonly mnemonic: Mnemonic;
+  readonly transports?: ReadonlyArray<TransportConfig>;
 }
 
-/** Creates a {@link SharedOwner} with a freshly generated {@link Mnemonic}. */
-export const createSharedOwner = (deps: CreateMnemonicDep): SharedOwner => {
-  const mnemonic = deps.createMnemonic();
+/**
+ * Creates a {@link SharedOwner} from an {@link OwnerSecret} for collaborative
+ * write access.
+ *
+ * Use {@link createSharedReadonlyOwner} to create a read-only version for
+ * sharing.
+ */
+export const createSharedOwner = (
+  secret: OwnerSecret,
+  transports?: ReadonlyArray<TransportConfig>,
+): SharedOwner => {
   return {
     type: "SharedOwner",
-    mnemonic,
-    ...createOwner(mnemonic),
+    ...createOwner(secret),
+    ...(transports && { transports }),
   };
 };
 
@@ -202,6 +274,7 @@ export interface SharedReadonlyOwner {
   readonly type: "SharedReadonlyOwner";
   readonly id: OwnerId;
   readonly encryptionKey: EncryptionKey;
+  readonly transports?: ReadonlyArray<TransportConfig>;
 }
 
 /** Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}. */
@@ -211,18 +284,5 @@ export const createSharedReadonlyOwner = (
   type: "SharedReadonlyOwner",
   id: sharedOwner.id,
   encryptionKey: sharedOwner.encryptionKey,
+  ...(sharedOwner.transports && { transports: sharedOwner.transports }),
 });
-
-/**
- * Rotates the {@link WriteKey} for an {@link AppOwner}, {@link ShardOwner}, or
- * {@link SharedOwner}, returning a new instance with the updated key.
- */
-export const rotateWriteKey = <T extends AppOwner | ShardOwner | SharedOwner>(
-  owner: T,
-  newWriteKey: WriteKey,
-): T => {
-  return {
-    ...owner,
-    writeKey: newWriteKey,
-  } as T;
-};

package/src/Evolu/Platform.ts

@@ -1,5 +1,3 @@
-import { Config } from "./Config.js";
-
 /**
  * FlushSync is for libraries like React to flush updates synchronously inside
  * the provided callback to ensure the DOM is updated immediately.
@@ -16,12 +14,14 @@ export interface FlushSyncDep {
   readonly flushSync: FlushSync;
 }
 
-export interface AppState {
-  readonly reset: () => void;
-}
-
-export type CreateAppState = (config: Config) => AppState;
+/**
+ * Reload the app in a platform-specific way.
+ *
+ * - **Web**: Redirects to the specified URL
+ * - **React Native**: Restarts the app (URL parameter ignored)
+ */
+export type ReloadApp = (url: string) => void;
 
-export interface CreateAppStateDep {
-  readonly createAppState: CreateAppState;
+export interface ReloadAppDep {
+  readonly reloadApp: ReloadApp;
 }