@evolu/common 6.0.1-preview.8 → 7.0.0

package/dist/src/Evolu/Owner.js

@@ -1,131 +1,157 @@
+import * as bip39 from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english.js";
+import { createSlip21, EncryptionKey, Entropy16, Entropy32, } from "../Crypto.js";
+import { getOrNull } from "../Result.js";
+import { brand, Id, IdBytes, idBytesToId, idToIdBytes, NonNegativeInt, } from "../Type.js";
 /**
- * TODO:
- *
- * @module
- */
-import { assert } from "../Assert.js";
-import { createEncryptionKey, createSlip21, createSlip21Id, mnemonicToMnemonicSeed, } from "../Crypto.js";
-import { brand, DateIso, Id, length, Uint8Array, } from "../Type.js";
-import { createInitialTimestamp, timestampToTimestampString, } from "./Timestamp.js";
-/**
- * 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 const writeKeyLength = 16;
+/** Bytes representation of {@link OwnerId}. */
+export const OwnerIdBytes = brand("OwnerIdBytes", IdBytes);
+export const ownerIdToOwnerIdBytes = (ownerId) => idToIdBytes(ownerId);
+export const ownerIdBytesToOwnerId = (ownerIdBytes) => idBytesToId(ownerIdBytes);
+export const ownerWriteKeyLength = NonNegativeInt.orThrow(16);
+export const OwnerEncryptionKey = brand("OwnerEncryptionKey", EncryptionKey);
 /**
- * A secure token proving the initiator can write changes. Derived from a
- * mnemonic or randomly generated. It's 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 const OwnerWriteKey = brand("OwnerWriteKey", Entropy16);
 /**
- * Creates an {@link AppOwner}, optionally from an existing mnemonic to restore
- * it on another device; otherwise, generates a new mnemonic.
+ * 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 createAppOwner = (deps) => (mnemonic = deps.createMnemonic()) => {
-    const owner = createOwner(deps)(mnemonic);
-    return { type: "AppOwner", ...owner };
-};
+export const OwnerSecret = brand("OwnerSecret", Entropy32);
+/** Creates a {@link OwnerSecret}. */
+export const createOwnerSecret = (deps) => deps.randomBytes.create(32);
+/** Converts an {@link OwnerSecret} to a {@link Mnemonic}. */
+export const ownerSecretToMnemonic = (secret) => bip39.entropyToMnemonic(secret, wordlist);
+/** Converts a {@link Mnemonic} to an {@link OwnerSecret}. */
+export const mnemonicToOwnerSecret = (mnemonic) => bip39.mnemonicToEntropy(mnemonic, wordlist);
+/** Creates a randomly generated {@link OwnerWriteKey}. */
+export const createOwnerWriteKey = (deps) => deps.randomBytes.create(16);
 /**
- * Creates a {@link ShardOwner} for sharding app data with a freshly generated
- * mnemonic. Unlike {@link createAppOwner}, it doesn’t accept an existing
- * mnemonic because ShardOwner mnemonics are always generated and restored
- * automatically via database sync.
+ * 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 createShardOwner = (deps) => {
-    const owner = createOwner(deps)();
+export const createOwner = (secret) => ({
+    id: ownerIdBytesToOwnerId(OwnerIdBytes.orThrow(createSlip21(secret, ["Evolu", "OwnerIdBytes"]).slice(0, 16))),
+    encryptionKey: OwnerEncryptionKey.orThrow(createSlip21(secret, ["Evolu", "OwnerEncryptionKey"])),
+    writeKey: OwnerWriteKey.orThrow(createSlip21(secret, ["Evolu", "OwnerWriteKey"]).slice(0, 16)),
+});
+/** Creates an {@link AppOwner} from an {@link OwnerSecret}. */
+export const createAppOwner = (secret) => ({
+    type: "AppOwner",
+    mnemonic: ownerSecretToMnemonic(secret),
+    ...createOwner(secret),
+});
+/** Creates a {@link ShardOwner} from an {@link OwnerSecret}. */
+export const createShardOwner = (secret, transports) => {
     return {
         type: "ShardOwner",
-        mnemonic: owner.mnemonic,
-        writeKey: owner.writeKey,
+        ...createOwner(secret),
+        ...(transports && { transports }),
     };
 };
 /**
- * Creates a fresh {@link SharedOwner} for sharing data with write access. Takes
- * no arguments as both `mnemonic` and rotatable `writeKey` are newly generated;
- * when shared, recipients use the provided `mnemonic` and `writeKey` directly
- * as a {@link SharedOwner} without needing to recreate it.
+ * 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 createSharedOwner = (deps) => {
-    const mnemonic = deps.createMnemonic();
-    const writeKey = createWriteKey(deps)(); // Random, no seed
+export const deriveShardOwner = (owner, path, transports) => {
+    const secret = createSlip21(owner.encryptionKey, path);
     return {
-        type: "SharedOwner",
-        mnemonic,
-        writeKey,
+        type: "ShardOwner",
+        ...createOwner(secret),
+        ...(transports && { transports }),
     };
 };
 /**
- * Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner} for read-only
- * data sharing. Extracts the `mnemonic` from the provided {@link SharedOwner},
- * omitting its `writeKey` to ensure read-only access.
+ * 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 createSharedReadonlyOwner = (sharedOwner) => {
+export const createSharedOwner = (secret, transports) => {
     return {
-        type: "SharedReadonlyOwner",
-        mnemonic: sharedOwner.mnemonic,
-    };
-};
-/** Creates an {@link Owner} with optional `mnemonic` and `writeKey`. */
-export const createOwner = (deps) => (mnemonic = deps.createMnemonic(), writeKey) => {
-    const seed = mnemonicToMnemonicSeed(mnemonic);
-    const id = createSlip21Id(seed, ["Evolu", "Owner Id"]);
-    const encryptionKey = createEncryptionKey(seed);
-    const createdAt = DateIso.fromParent(new Date(deps.time.now()));
-    assert(createdAt.ok, "Invalid DateIso: bad system clock");
-    return {
-        mnemonic,
-        createdAt: createdAt.value,
-        id,
-        encryptionKey,
-        writeKey: writeKey ?? createWriteKey(deps)(seed),
+        type: "SharedOwner",
+        ...createOwner(secret),
+        ...(transports && { transports }),
     };
 };
-export const createWriteKey = (deps) => (seed) => {
-    const key = seed
-        ? createSlip21(seed, ["Evolu", "Write Key"]).slice(0, 16)
-        : deps.createRandomBytes(16);
-    const writeKey = WriteKey.from(key);
-    assert(writeKey.ok, "Ensure valid WriteKey");
-    return writeKey.value;
-};
+/** Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}. */
+export const createSharedReadonlyOwner = (sharedOwner) => ({
+    type: "SharedReadonlyOwner",
+    id: sharedOwner.id,
+    encryptionKey: sharedOwner.encryptionKey,
+    ...(sharedOwner.transports && { transports: sharedOwner.transports }),
+});
 /**
- * Creates an {@link OwnerRow} from any {@link Owner} variant for the
- * `evolu_owner` table, adding a `timestamp` ({@link TimestampString}) for CRDT
- * sync.
+ * Creates an {@link OwnerWebSocketTransport} for the given relay URL and
+ * {@link OwnerId}.
+ *
+ * The URL must be a WebSocket base URL without query parameters or fragments
+ * (e.g., `wss://relay.evolu.dev`, not `wss://relay.evolu.dev?foo=bar`). The
+ * function appends the `ownerId` as a query parameter.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Create transport "wss://relay.evolu.dev?ownerId=..."
+ * const transport = createOwnerWebSocketTransport({
+ *   url: "wss://relay.evolu.dev",
+ *   ownerId: owner.id,
+ * });
+ *
+ * // Use with createEvolu
+ * const evolu = createEvolu(deps)(Schema, {
+ *   transports: [transport],
+ * });
+ * ```
  */
-export const createOwnerRow = (deps) => (owner) => {
-    const timestamp = timestampToTimestampString(createInitialTimestamp(deps));
-    switch (owner.type) {
-        case "AppOwner": {
-            const { type, ...rest } = owner;
-            return { ...rest, timestamp };
-        }
-        case "ShardOwner":
-        case "SharedOwner":
-            return {
-                ...createOwner(deps)(owner.mnemonic, owner.writeKey),
-                timestamp,
-            };
-        case "SharedReadonlyOwner":
-            return {
-                ...createOwner(deps)(owner.mnemonic),
-                writeKey: null,
-                timestamp,
-            };
-    }
-};
+export const createOwnerWebSocketTransport = (config) => ({
+    type: "WebSocket",
+    url: `${config.url}?ownerId=${config.ownerId}`,
+});
 /**
- * Rotates the {@link WriteKey} for an {@link AppOwner}, {@link ShardOwner}, or
- * {@link SharedOwner}, returning a new instance with the updated key.
+ * 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 rotateWriteKey = (owner, newWriteKey) => {
-    return {
-        ...owner,
-        writeKey: newWriteKey,
-    };
-};
+export const parseOwnerIdFromOwnerWebSocketTransportUrl = (url) => getOrNull(OwnerId.fromUnknown(url.split("=")[1]));

package/dist/src/Evolu/Platform.d.ts

@@ -1,4 +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.
@@ -13,11 +12,14 @@ export type FlushSync = (callback: () => void) => void;
 export interface FlushSyncDep {
     readonly flushSync: FlushSync;
 }
-export interface AppState {
-    readonly reset: () => void;
-}
-export type CreateAppState = (config: Config) => AppState;
-export interface CreateAppStateDep {
-    readonly createAppState: CreateAppState;
+/**
+ * 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 ReloadAppDep {
+    readonly reloadApp: ReloadApp;
 }
 //# sourceMappingURL=Platform.d.ts.map

package/dist/src/Evolu/Platform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Platform.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Platform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,QAAQ,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC"}
+{"version":3,"file":"Platform.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B"}