Owners refactor and external AppOwner support

Author: steida

.changeset/hot-peas-own.md

@@ -0,0 +1,38 @@
+---
+"@evolu/common": patch
+---
+
+# Owners refactor and external AppOwner support
+
+## 🚀 Features
+
+- **External AppOwner Support**: `AppOwner` can now be created from external keys without sharing the mnemonic with the Evolu app. The `mnemonic` property is now optional, allowing for better security when integrating with external authentication systems.
+
+- **New Config Option**: Added `initialAppOwner` configuration option to specify a pre-existing AppOwner when creating an Evolu instance, replacing the previous `mnemonic` option for better encapsulation.
+
+## 🔄 Breaking Changes
+
+- **Owner API Redesign**: Complete refactor of the Owner system with cleaner, more focused interfaces:
+  - Simplified `Owner` interface with only essential properties (`id`, `encryptionKey`, `writeKey`)
+  - Removed temporal properties (`createdAt`, `timestamp`) from core Owner interface
+  - Eliminated complex `OwnerRow` and `OwnerWithWriteAccess` types
+
+- **Database Schema Changes**:
+  - Replaced `evolu_owner` table with streamlined `evolu_config` table
+  - New `evolu_version` table for protocol versioning
+  - Simplified storage of AppOwner data in single config row
+
+- **Configuration Changes**:
+  - `Config.mnemonic` replaced with `Config.initialAppOwner`
+  - More explicit control over owner initialization
+
+## ✨ Improvements
+
+- **Enhanced Documentation**: Comprehensive JSDoc with clear explanations of owner types, use cases, and examples
+- **Clock Management**: New internal clock system for better timestamp handling
+- **Test Coverage**: Extensive test suite covering all owner types and edge cases
+
+## 🔧 Internal Changes
+
+- **Database Initialization**: Refactored database setup to use new schema with better separation of concerns
+- **Protocol Updates**: Updated to protocol version 0 with new storage format

apps/web/src/components/NextJsExample.tsx

@@ -103,7 +103,7 @@ const formatTypeError = createFormatTypeError<
 
 const evolu = createEvolu(evoluReactWebDeps)(Schema, {
   reloadUrl: "/docs/examples/react/nextjs",
-  name: getOrThrow(SimpleName.from("evolu-nextjs-example-v010725")),
+  name: getOrThrow(SimpleName.from("evolu-nextjs-example-v090725")),
 
   ...(process.env.NODE_ENV === "development" && {
     syncUrl: "http://localhost:4000",
@@ -560,7 +560,7 @@ const OwnerActions: FC = () => {
           onClick={handleDownloadDatabaseClick}
         />
       </div>
-      {showMnemonic && owner != null && (
+      {showMnemonic && owner?.mnemonic && (
         <div>
           <textarea
             value={owner.mnemonic}

examples/react-electron/src/EvoluDemo.tsx

@@ -433,7 +433,7 @@ const OwnerActions: FC = () => {
           onClick={handleDownloadDatabaseClick}
         />
       </div>
-      {showMnemonic && owner != null && (
+      {showMnemonic && owner?.mnemonic && (
         <div>
           <textarea
             style={{

examples/react-nextjs/components/NextJsExample.tsx

@@ -552,7 +552,7 @@ const OwnerActions: FC = () => {
           onClick={handleDownloadDatabaseClick}
         />
       </div>
-      {showMnemonic && owner != null && (
+      {showMnemonic && owner?.mnemonic && (
         <div>
           <textarea
             value={owner.mnemonic}

examples/react-vite-pwa/src/components/EvoluDemo.tsx

@@ -508,7 +508,7 @@ const OwnerActions: FC = () => {
           onClick={handleDownloadDatabaseClick}
         />
       </div>
-      {showMnemonic && owner != null && (
+      {showMnemonic && owner?.mnemonic && (
         <div>
           <textarea
             value={owner.mnemonic}

packages/common/src/Crypto.ts

@@ -21,6 +21,7 @@ import {
   Uint8Array,
 } from "./Type.js";
 import { Brand } from "./Types.js";
+import { assert } from "./Assert.js";
 
 /** `Uint8Array` created by {@link createRandomBytes}. */
 export type RandomBytes = Uint8Array & Brand<"RandomBytes">;
@@ -58,6 +59,11 @@ export const createSlip21 = (
   seed: MnemonicSeed,
   path: ReadonlyArray<string>,
 ): Uint8Array => {
+  assert(
+    seed.length >= 16 && seed.length <= 64,
+    `Unusual SLIP-0021 seed length: ${seed.length} bytes`,
+  );
+
   let m = hmac(sha512, "Symmetric key seed", seed);
   for (const component of path) {
     const p = new TextEncoder().encode(component);
@@ -100,9 +106,6 @@ export const createSlip21Id = (
 export const EncryptionKey = brand("EncryptionKey", length(32)(Uint8Array));
 export type EncryptionKey = typeof EncryptionKey.Type;
 
-export const createEncryptionKey = (seed: MnemonicSeed): EncryptionKey =>
-  createSlip21(seed, ["Evolu", "Encryption Key"]) as EncryptionKey;
-
 /** Symmetric cryptography. */
 export interface SymmetricCrypto {
   readonly nonceLength: NonNegativeInt;
@@ -185,7 +188,6 @@ export const padmePaddedLength = (length: NonNegativeInt): NonNegativeInt => {
  * Returns the PADMÉ padding length for a given input length. Uses
  * {@link padmePaddedLength}.
  */
-
 export const padmePaddingLength = (length: NonNegativeInt): NonNegativeInt => {
   return (padmePaddedLength(length) - length) as NonNegativeInt;
 };

packages/common/src/Evolu/Config.ts

@@ -1,7 +1,8 @@
 import { ConsoleConfig } from "../Console.js";
 import { getOrThrow } from "../Result.js";
-import { Mnemonic, SimpleName } from "../Type.js";
+import { SimpleName } from "../Type.js";
 import type { DbIndexesBuilder } from "./Kysely.js";
+import type { AppOwner } from "./Owner.js";
 
 export interface Config extends ConsoleConfig {
   /**
@@ -66,11 +67,10 @@ export interface Config extends ConsoleConfig {
   readonly indexes?: DbIndexesBuilder;
 
   /**
-   * Use this option to create Evolu with the specified mnemonic. If omitted,
-   * the mnemonic will be autogenerated. That should be the default behavior
-   * until special UX requirements are needed (e.g., multitenancy).
+   * Initial AppOwner to use when creating Evolu instance. If omitted, a new
+   * AppOwner will be generated automatically.
    */
-  readonly mnemonic?: Mnemonic;
+  readonly initialAppOwner?: AppOwner;
 
   /**
    * Use in-memory SQLite database instead of persistent storage. Useful for