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

package/dist/src/Evolu/Owner.js

@@ -1,106 +1,106 @@
-/* eslint-disable jsdoc/no-undefined-types */
+import * as bip39 from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english.js";
+import { createSlip21, EncryptionKey, Entropy16, Entropy32, } from "../Crypto.js";
+import { brand, Id, IdBytes, idBytesToId, idToIdBytes, } from "../Type.js";
 /**
- * Evolu Owner - Data Ownership and Collaboration
+ * 32 bytes of cryptographic entropy used to derive {@link Owner} keys.
  *
- * 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
+ * Can be created using {@link createOwnerSecret} or converted from a
+ * {@link Mnemonic} using {@link mnemonicToOwnerSecret}.
  */
-import { createSlip21, createSlip21Id, mnemonicToMnemonicSeed, } from "../Crypto.js";
-import { brand, Id, length, Uint8Array, } from "../Type.js";
+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);
 /**
- * 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 = 16;
+export const OwnerEncryptionKey = brand("OwnerEncryptionKey", EncryptionKey);
 /**
- * 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));
-/** Creates a randomly generated {@link WriteKey}. */
-export const createWriteKey = (deps) => deps.createRandomBytes(16);
-/** Creates an {@link Owner} from a {@link Mnemonic} using SLIP-21 key derivation. */
-export const createOwner = (mnemonic) => {
-    const seed = mnemonicToMnemonicSeed(mnemonic);
-    return createOwnerFromMnemonicSeed(seed);
-};
+export const OwnerWriteKey = brand("OwnerWriteKey", Entropy16);
+/** Creates a randomly generated {@link OwnerWriteKey}. */
+export const createOwnerWriteKey = (deps) => deps.randomBytes.create(16);
 /**
- * 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) => ({
-    id: createSlip21Id(seed, ["Evolu", "Owner Id"]),
-    encryptionKey: createSlip21(seed, [
-        "Evolu",
-        "Encryption Key",
-    ]),
-    writeKey: createSlip21(seed, ["Evolu", "Write Key"]).slice(0, 16),
+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)),
 });
-export const createAppOwner = (mnemonic) => ({
+/** Creates an {@link AppOwner} from an {@link OwnerSecret}. */
+export const createAppOwner = (secret) => ({
     type: "AppOwner",
-    mnemonic,
-    ...createOwner(mnemonic),
+    mnemonic: ownerSecretToMnemonic(secret),
+    ...createOwner(secret),
 });
+/** Creates a {@link ShardOwner} from an {@link OwnerSecret}. */
+export const createShardOwner = (secret, transports) => {
+    return {
+        type: "ShardOwner",
+        ...createOwner(secret),
+        ...(transports && { transports }),
+    };
+};
 /**
- * Creates a {@link ShardOwner} derived from an {@link AppOwner} using the
- * specified path.
+ * Derives a {@link ShardOwner} from an {@link AppOwner} using the specified path.
+ *
+ * **Advantages of derived owners:**
  *
- * ### Example
+ * - **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
  *
- * ```ts
- * const contactsShard = createShardOwner(appOwner, ["contacts"]);
- * const projectShard = createShardOwner(appOwner, [
- *   "projects",
- *   "project-1",
- * ]);
- * ```
+ * **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 createShardOwner = (appOwner, path) => {
-    /**
-     * The shardSeed is never shared or persisted, only used for SLIP-21
-     * derivation to create shard-specific keys.
-     */
-    const shardSeed = createSlip21(appOwner.encryptionKey, path);
+export const deriveShardOwner = (owner, path, transports) => {
+    const secret = createSlip21(owner.encryptionKey, path);
     return {
         type: "ShardOwner",
-        ...createOwnerFromMnemonicSeed(shardSeed),
+        ...createOwner(secret),
+        ...(transports && { transports }),
     };
 };
-/** Creates a {@link SharedOwner} with a freshly generated {@link Mnemonic}. */
-export const createSharedOwner = (deps) => {
-    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, transports) => {
     return {
         type: "SharedOwner",
-        mnemonic,
-        ...createOwner(mnemonic),
+        ...createOwner(secret),
+        ...(transports && { transports }),
     };
 };
 /** Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}. */
@@ -108,14 +108,5 @@ export const createSharedReadonlyOwner = (sharedOwner) => ({
     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 = (owner, newWriteKey) => {
-    return {
-        ...owner,
-        writeKey: newWriteKey,
-    };
-};

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"}