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

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

@@ -0,0 +1,144 @@
+import { RandomBytesDep } from "../Crypto.js";
+import { Mnemonic } from "../Type.js";
+import { AppOwner, OwnerId } from "./Owner.js";
+/** @experimental */
+export interface LocalAuth {
+    /** Logs in with the given owner ID, or loads the target owner if not provided. */
+    login: (ownerId?: OwnerId, options?: LocalAuthOptions & {
+        reloadNeeded?: boolean;
+    }) => Promise<AuthResult | null>;
+    /** Registers a new owner with the given username. */
+    register: (username: string, options?: LocalAuthOptions & {
+        mnemonic?: Mnemonic | null;
+    }) => Promise<AuthResult | null>;
+    /** Unregisters an owner with the given owner ID. */
+    unregister: (ownerId: OwnerId, options?: LocalAuthOptions) => Promise<void>;
+    /** Lists all registered owner ids with associated usernames. */
+    getProfiles: (options?: LocalAuthOptionsValues) => Promise<Array<{
+        ownerId: OwnerId;
+        username: string;
+    }>>;
+    /** Clears all owners and metadata from the local auth. */
+    clearAll: (options?: LocalAuthOptions) => Promise<void>;
+}
+export interface LocalAuthDep {
+    readonly localAuth: LocalAuth;
+}
+/**
+ * - **⚠️
+ *
+ * Secure storage interface that must be implemented by each platform.
+ */
+export interface SecureStorage {
+    setItem: (key: string, value: string, options?: LocalAuthOptions) => Promise<MutationResult>;
+    getItem: (key: string, options?: LocalAuthOptionsValues) => Promise<SensitiveInfoItem | null>;
+    deleteItem: (key: string, options?: LocalAuthOptions) => Promise<boolean>;
+    getAllItems: (options?: LocalAuthOptionsValues) => Promise<Array<SensitiveInfoItem>>;
+    clearService: (options?: LocalAuthOptions) => Promise<void>;
+}
+export interface SecureStorageDep {
+    readonly secureStorage: SecureStorage;
+}
+/**
+ * Creates a local auth using the given secure storage implementation. This
+ * factory function allows each platform to provide its own storage layer while
+ * sharing the common auth logic.
+ */
+export declare const createLocalAuth: (deps: SecureStorageDep & RandomBytesDep) => LocalAuth;
+export declare const AUTH_NAMESPACE = "evolu";
+export declare const AUTH_METAKEY_LAST_OWNER = "_last_owner";
+export declare const AUTH_METAKEY_OWNER_NAMES = "_owner_names";
+export declare const AUTH_DEFAULT_OPTIONS: LocalAuthOptions;
+export interface AuthResult {
+    /** The owner created during registration. */
+    readonly owner: AppOwner | undefined;
+    /** The name provided by the user during registration. */
+    readonly username: string;
+}
+export interface LocalAuthOptions {
+    /**
+     * Native: Namespaces the stored entry. Defaults to the bundle identifier
+     * (when available) or `default`.
+     */
+    readonly service?: string;
+    /** IOS: Enable keychain item synchronization via iCloud. */
+    readonly iosSynchronizable?: boolean;
+    /** IOS: Custom keychain access group. */
+    readonly keychainGroup?: string;
+    /**
+     * Native: Desired access-control policy. The native implementation will
+     * automatically fall back to the strongest supported policy for the current
+     * device (Secure Enclave ➝ Biometry ➝ Device Credential ➝ None).
+     */
+    readonly accessControl?: AccessControl;
+    /**
+     * Android: Fine tune whether the hardware-authenticated key should require
+     * biometrics only.
+     */
+    readonly androidBiometricsStrongOnly?: boolean;
+    /**
+     * Native: Optional prompt configuration that will be shown when protected
+     * keys require user presence.
+     */
+    readonly authenticationPrompt?: AuthenticationPrompt;
+    /** Web: The relying party ID for WebAuthn. Defaults to the current hostname. */
+    readonly relyingPartyID?: string;
+    /** Web: The relying party name for WebAuthn. Defaults to 'Evolu'. */
+    readonly relyingPartyName?: string;
+    /** Web: The username for WebAuthn. Defaults to 'Evolu User'. */
+    readonly webAuthnUsername?: string;
+    /**
+     * Web: The user verification requirement for WebAuthn. Defaults to
+     * 'required'.
+     */
+    readonly webAuthnUserVerification?: UserVerificationRequirement;
+    /** Web: The authenticator attachment for WebAuthn. Defaults to 'platform'. */
+    readonly webAuthnAuthenticatorAttachment?: AuthenticatorAttachment;
+}
+export interface LocalAuthOptionsValues extends LocalAuthOptions {
+    /** When true, the stored value is returned for each item. Defaults to false. */
+    readonly includeValues?: boolean;
+}
+/**
+ * Configuration for the biometric/device credential prompt shown when a
+ * protected item is accessed.
+ */
+export interface AuthenticationPrompt {
+    readonly title: string;
+    readonly subtitle?: string;
+    readonly description?: string;
+    readonly cancel?: string;
+}
+export interface SensitiveInfoGetRequest extends LocalAuthOptions {
+    readonly key: string;
+    /** Include the encrypted value when available. Defaults to true. */
+    readonly includeValue?: boolean;
+}
+export interface StorageMetadata {
+    readonly securityLevel: SecurityLevel;
+    readonly backend: StorageBackend;
+    readonly accessControl: AccessControl;
+    readonly timestamp: number;
+}
+export interface SensitiveInfoItem {
+    readonly key: string;
+    readonly service: string;
+    readonly value?: string;
+    readonly metadata: StorageMetadata;
+}
+export interface MutationResult {
+    readonly metadata: StorageMetadata;
+}
+/**
+ * Enumerates the highest security tier that was effectively applied while
+ * storing a value.
+ */
+export type SecurityLevel = "secureEnclave" | "strongBox" | "biometry" | "deviceCredential" | "software";
+/** Enumerates the native storage backend used to persist sensitive data. */
+export type StorageBackend = "keychain" | "androidKeystore" | "encryptedSharedPreferences";
+/**
+ * Enumerates the access-control policy enforced by the underlying secure
+ * storage.
+ */
+export type AccessControl = "secureEnclaveBiometry" | "biometryCurrentSet" | "biometryAny" | "devicePasscode" | "none";
+//# sourceMappingURL=LocalAuth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LocalAuth.d.ts","sourceRoot":"","sources":["../../../src/Evolu/LocalAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EACL,QAAQ,EAKR,OAAO,EAER,MAAM,YAAY,CAAC;AAEpB,oBAAoB;AACpB,MAAM,WAAW,SAAS;IACxB,kFAAkF;IAClF,KAAK,EAAE,CACL,OAAO,CAAC,EAAE,OAAO,EACjB,OAAO,CAAC,EAAE,gBAAgB,GAAG;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,KACpD,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAEhC,qDAAqD;IACrD,QAAQ,EAAE,CACR,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,gBAAgB,GAAG;QAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;KAAE,KACxD,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAEhC,oDAAoD;IACpD,UAAU,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5E,gEAAgE;IAChE,WAAW,EAAE,CACX,OAAO,CAAC,EAAE,sBAAsB,KAC7B,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAE5D,0DAA0D;IAC1D,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CACP,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,gBAAgB,KACvB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,OAAO,EAAE,CACP,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,sBAAsB,KAC7B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACvC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1E,WAAW,EAAE,CACX,OAAO,CAAC,EAAE,sBAAsB,KAC7B,OAAO,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACvC,YAAY,EAAE,CAAC,OAAO,CAAC,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;CACvC;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAC1B,MAAM,gBAAgB,GAAG,cAAc,KACtC,SA2MF,CAAC;AAGF,eAAO,MAAM,cAAc,UAAU,CAAC;AACtC,eAAO,MAAM,uBAAuB,gBAAgB,CAAC;AACrD,eAAO,MAAM,wBAAwB,iBAAiB,CAAC;AACvD,eAAO,MAAM,oBAAoB,EAAE,gBASlC,CAAC;AAEF,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;IACrC,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAID,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B,4DAA4D;IAC5D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAErC,yCAAyC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,2BAA2B,CAAC,EAAE,OAAO,CAAC;IAE/C;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAErD,gFAAgF;IAChF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC,qEAAqE;IACrE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAEnC,gEAAgE;IAChE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAEnC;;;OAGG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,2BAA2B,CAAC;IAEhE,8EAA8E;IAC9E,QAAQ,CAAC,+BAA+B,CAAC,EAAE,uBAAuB,CAAC;CACpE;AAED,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,gFAAgF;IAChF,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,UAAU,CAAC;AAEf,4EAA4E;AAC5E,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,iBAAiB,GACjB,4BAA4B,CAAC;AAEjC;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB,uBAAuB,GACvB,oBAAoB,GACpB,aAAa,GACb,gBAAgB,GAChB,MAAM,CAAC"}

package/dist/src/Evolu/LocalAuth.js

@@ -0,0 +1,171 @@
+import { createAppOwner, createOwnerSecret, mnemonicToOwnerSecret, OwnerEncryptionKey, OwnerWriteKey, } from "./Owner.js";
+/**
+ * Creates a local auth using the given secure storage implementation. This
+ * factory function allows each platform to provide its own storage layer while
+ * sharing the common auth logic.
+ */
+export const createLocalAuth = (deps) => {
+    const setLastOwnerId = async (id, options) => {
+        await deps.secureStorage.setItem(AUTH_METAKEY_LAST_OWNER, id, {
+            ...AUTH_DEFAULT_OPTIONS,
+            ...options,
+            accessControl: "none",
+        });
+    };
+    const getLastOwnerId = async (options) => {
+        const item = await deps.secureStorage.getItem(AUTH_METAKEY_LAST_OWNER, {
+            ...AUTH_DEFAULT_OPTIONS,
+            ...options,
+            accessControl: "none",
+        });
+        return item?.value;
+    };
+    const getOwnerNames = async (options) => {
+        const item = await deps.secureStorage.getItem(AUTH_METAKEY_OWNER_NAMES, {
+            ...AUTH_DEFAULT_OPTIONS,
+            ...options,
+            accessControl: "none",
+        });
+        let names = {};
+        if (item?.value) {
+            names = JSON.parse(item.value);
+        }
+        return names;
+    };
+    const setOwnerName = async (id, username, options) => {
+        const names = await getOwnerNames(options);
+        names[id] = username;
+        await deps.secureStorage.setItem(AUTH_METAKEY_OWNER_NAMES, JSON.stringify(names), {
+            ...AUTH_DEFAULT_OPTIONS,
+            ...options,
+            accessControl: "none",
+        });
+    };
+    const deleteOwnerName = async (id, options) => {
+        const { [id]: _, ...names } = await getOwnerNames(options);
+        await deps.secureStorage.setItem(AUTH_METAKEY_OWNER_NAMES, JSON.stringify(names), {
+            ...AUTH_DEFAULT_OPTIONS,
+            ...options,
+            accessControl: "none",
+        });
+    };
+    const getOwnerIds = async (options) => {
+        const items = await deps.secureStorage.getAllItems({
+            ...AUTH_DEFAULT_OPTIONS,
+            ...options,
+            includeValues: false,
+        });
+        return items
+            .filter(Boolean)
+            .filter((i) => i.key !== AUTH_METAKEY_LAST_OWNER &&
+            i.key !== AUTH_METAKEY_OWNER_NAMES)
+            .map((i) => i.key);
+    };
+    const clearAuthStore = (options) => deps.secureStorage.clearService({
+        ...AUTH_DEFAULT_OPTIONS,
+        ...options,
+    });
+    return {
+        login: async (ownerId, options) => {
+            // Use either specified owner or the last owner used during registration/login.
+            const targetOwnerId = ownerId ?? (await getLastOwnerId(options));
+            if (!targetOwnerId)
+                return null;
+            // Lookup the associated username
+            const names = await getOwnerNames(options);
+            const username = names[targetOwnerId] ?? "";
+            // If a reload is needed, avoid authentication, it needs to be handled on next page load.
+            // We set the last owner so we know what the target is.
+            // It is the applications's responsibility to reload and trigger login.
+            if (options?.reloadNeeded) {
+                await setLastOwnerId(targetOwnerId, options);
+                return { owner: undefined, username };
+            }
+            // Retrieve and decrypt the owner (this will trigger device authentication)
+            const account = await deps.secureStorage.getItem(targetOwnerId, {
+                ...AUTH_DEFAULT_OPTIONS,
+                ...options,
+            });
+            if (!account?.value)
+                return null;
+            // Unserialize the values (TODO: save these as base64 instead of json serializing)
+            const result = JSON.parse(account.value);
+            const writeKey = OwnerWriteKey.orThrow(new Uint8Array(Object.values(result.owner.writeKey)));
+            const encryptionKey = OwnerEncryptionKey.orThrow(new Uint8Array(Object.values(result.owner.encryptionKey)));
+            const owner = { ...result.owner, writeKey, encryptionKey };
+            // Update the last owner for future login attempts
+            await setLastOwnerId(targetOwnerId, options);
+            // Return the owner and associated username
+            return { owner, username };
+        },
+        register: async (username, options) => {
+            // Create an owner with a new secret or use specified mnemonic
+            const owner = createAppOwner(options?.mnemonic
+                ? mnemonicToOwnerSecret(options.mnemonic)
+                : createOwnerSecret(deps));
+            // Store owner, associated username, and update last owner
+            await Promise.all([
+                // setOwnerItem
+                deps.secureStorage.setItem(owner.id, JSON.stringify({ owner }), {
+                    ...AUTH_DEFAULT_OPTIONS,
+                    webAuthnUsername: username,
+                    ...options,
+                }),
+                setOwnerName(owner.id, username, options),
+                setLastOwnerId(owner.id, options),
+            ]);
+            // Return the owner and associated username
+            return { owner, username };
+        },
+        unregister: async (ownerId, options) => {
+            // Delete the owner and associated username
+            await Promise.all([
+                // deleteOwnerItem
+                deps.secureStorage.deleteItem(ownerId, {
+                    ...AUTH_DEFAULT_OPTIONS,
+                    ...options,
+                }),
+                deleteOwnerName(ownerId, options),
+            ]);
+            // If the owner was the last owner then set to
+            // the next owner based on metadata timestamp
+            const lastOwnerId = await getLastOwnerId(options);
+            if (lastOwnerId === ownerId) {
+                const ids = await getOwnerIds(options);
+                if (ids.length > 0) {
+                    await setLastOwnerId(ids[0], options);
+                }
+            }
+        },
+        getProfiles: async (options) => {
+            // Get all owner ids and associated usernames
+            const [ids, names] = await Promise.all([
+                getOwnerIds(options),
+                getOwnerNames(options),
+            ]);
+            // Return the list of profiles (usually used for login UX)
+            return ids.map((ownerId) => ({
+                ownerId,
+                username: names[ownerId] ?? "",
+            }));
+        },
+        clearAll: async (options) => {
+            // Delete all owners and associated metadata (scoped to the service)
+            await clearAuthStore(options);
+        },
+    };
+};
+// 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 = {
+    service: AUTH_NAMESPACE,
+    keychainGroup: AUTH_NAMESPACE,
+    androidBiometricsStrongOnly: true,
+    iosSynchronizable: true,
+    webAuthnUsername: "Evolu User",
+    authenticationPrompt: {
+        title: "Authenticate to unlock your session",
+    },
+};

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

@@ -1,160 +1,185 @@
+import { NonEmptyReadonlyArray } from "../Array.js";
+import { EncryptionKey, RandomBytesDep } from "../Crypto.js";
+import { Mnemonic, NonNegativeInt } from "../Type.js";
 /**
- * TODO:
+ * 32 bytes of cryptographic entropy used to derive {@link Owner} keys.
  *
- * @module
+ * Can be created using {@link createOwnerSecret} or converted from a
+ * {@link Mnemonic} using {@link mnemonicToOwnerSecret}.
  */
-import { CreateMnemonicDep, CreateRandomBytesDep, EncryptionKey, MnemonicSeed } from "../Crypto.js";
-import { NanoIdLibDep } from "../NanoId.js";
-import { TimeDep } from "../Time.js";
-import { DateIsoString, Mnemonic, NonNegativeInt } from "../Type.js";
-import { TimestampString } from "./Timestamp.js";
+export declare const OwnerSecret: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", Uint8Array<ArrayBufferLike> & import("../Brand.js").Brand<"Entropy">, Uint8Array<ArrayBufferLike>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>, Uint8Array<ArrayBufferLike>, never>, "Length32", import("../Type.js").LengthError<32>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>>, "OwnerSecret", import("../Type.js").BrandWithoutRefineError<"OwnerSecret", import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError> | import("../Type.js").LengthError<32>>, never>;
+export type OwnerSecret = typeof OwnerSecret.Type;
+/** Creates a {@link OwnerSecret}. */
+export declare const createOwnerSecret: (deps: RandomBytesDep) => OwnerSecret;
+/** Converts an {@link OwnerSecret} to a {@link Mnemonic}. */
+export declare const ownerSecretToMnemonic: (secret: OwnerSecret) => Mnemonic;
+/** Converts a {@link Mnemonic} to an {@link OwnerSecret}. */
+export declare const mnemonicToOwnerSecret: (mnemonic: Mnemonic) => OwnerSecret;
 /**
- * `Owner` is an entity in Evolu that owns data, meaning it is locally stored on
- * a device under the user’s control. Data can be personal private, peer-to-peer
- * shared, or aggregated from multiple owners.
- *
- * An owner has a {@link Mnemonic} from which {@link OwnerId} and
- * {@link EncryptionKey} are deterministically derived using SLIP-21, and an
- * optional {@link WriteKey} that, when present, enables writing to the Evolu
- * Relay or peers. The {@link WriteKey} can be rotated.
- *
- * Variants include {@link AppOwner}, {@link ShardOwner}, {@link SharedOwner}, and
- * {@link SharedReadonlyOwner}, each with specific roles and properties detailed
- * in their respective definitions.
- *
- * Public-key cryptography isn’t included here as it belongs to app and varies
- * by use case. An Evolu app without collaboration doesn’t need it, while a
- * Nostr-like app can leverage Nostr NIPs, or a super-safe app can use
- * post-quantum cryptography.
+ * 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 OwnerWriteKey}: Authentication token for write operations (rotatable)
+ *
+ * @see {@link createOwner}
  */
 export interface Owner {
-    readonly mnemonic: Mnemonic;
-    readonly createdAt: DateIsoString;
     readonly id: OwnerId;
-    readonly encryptionKey: EncryptionKey;
-    readonly writeKey: WriteKey;
-}
-export interface OwnerWithWriteAccess {
-    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 declare const OwnerId: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "Id", import("../Type.js").RegexError<"Id">, import("../Type.js").StringError>, "OwnerId", import("../Type.js").BrandWithoutRefineError<"OwnerId", import("../Type.js").StringError | import("../Type.js").RegexError<"Id">>, never>;
+export declare const OwnerId: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "Id", import("../Type.js").IdError, import("../Type.js").StringError>, "OwnerId", import("../Type.js").BrandWithoutRefineError<"OwnerId", import("../Type.js").StringError | import("../Type.js").IdError>, never>;
 export type OwnerId = typeof OwnerId.Type;
-export declare const writeKeyLength: NonNegativeInt;
+/** Bytes representation of {@link OwnerId}. */
+export declare const OwnerIdBytes: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError>, "Length16", import("../Type.js").LengthError<16>, import("../Type.js").Uint8ArrayError>, "IdBytes", import("../Type.js").BrandWithoutRefineError<"IdBytes", import("../Type.js").LengthError<16> | import("../Type.js").Uint8ArrayError>, never>, "OwnerIdBytes", import("../Type.js").BrandWithoutRefineError<"OwnerIdBytes", import("../Type.js").BrandWithoutRefineError<"IdBytes", import("../Type.js").LengthError<16> | import("../Type.js").Uint8ArrayError>>, never>;
+export type OwnerIdBytes = typeof OwnerIdBytes.Type;
+export declare const ownerIdToOwnerIdBytes: (ownerId: OwnerId) => OwnerIdBytes;
+export declare const ownerIdBytesToOwnerId: (ownerIdBytes: OwnerIdBytes) => OwnerId;
+export declare const ownerWriteKeyLength: NonNegativeInt;
+export declare const OwnerEncryptionKey: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", Uint8Array<ArrayBufferLike> & import("../Brand.js").Brand<"Entropy">, Uint8Array<ArrayBufferLike>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>, Uint8Array<ArrayBufferLike>, never>, "Length32", import("../Type.js").LengthError<32>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>>, "EncryptionKey", import("../Type.js").BrandWithoutRefineError<"EncryptionKey", import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError> | import("../Type.js").LengthError<32>>, never>, "OwnerEncryptionKey", import("../Type.js").BrandWithoutRefineError<"OwnerEncryptionKey", import("../Type.js").BrandWithoutRefineError<"EncryptionKey", import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError> | import("../Type.js").LengthError<32>>>, never>;
+export type OwnerEncryptionKey = typeof OwnerEncryptionKey.Type;
 /**
- * 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 declare const WriteKey: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError, Uint8Array<ArrayBufferLike>, import("../Type.js").Uint8ArrayError>, `Length${number & import("../Types.js").Brand<"Int"> & import("../Types.js").Brand<"NonNegative">}`, import("../Type.js").LengthError<number & import("../Types.js").Brand<"Int"> & import("../Types.js").Brand<"NonNegative">>, import("../Type.js").Uint8ArrayError>, "WriteKey", import("../Type.js").BrandWithoutRefineError<"WriteKey", import("../Type.js").Uint8ArrayError | import("../Type.js").LengthError<number & import("../Types.js").Brand<"Int"> & import("../Types.js").Brand<"NonNegative">>>, never>;
-export type WriteKey = typeof WriteKey.Type;
+export declare const OwnerWriteKey: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", Uint8Array<ArrayBufferLike> & import("../Brand.js").Brand<"Entropy">, Uint8Array<ArrayBufferLike>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>, Uint8Array<ArrayBufferLike>, never>, "Length16", import("../Type.js").LengthError<16>, import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>>, "OwnerWriteKey", import("../Type.js").BrandWithoutRefineError<"OwnerWriteKey", import("../Type.js").LengthError<16> | import("../Type.js").BrandWithoutRefineError<"Entropy", import("../Type.js").Uint8ArrayError>>, never>;
+export type OwnerWriteKey = typeof OwnerWriteKey.Type;
+/** Creates a randomly generated {@link OwnerWriteKey}. */
+export declare const createOwnerWriteKey: (deps: RandomBytesDep) => OwnerWriteKey;
 /**
- * The root owner of an Evolu app, created from a mnemonic safely generated on a
- * device when the app is initialized or restored on another device using an
- * existing mnemonic. It manages the app's core data, including the storage of
- * other owners' mnemonics in an encrypted app table. Its `writeKey` is
- * deterministic and rotatable. Never share the AppOwner mnemonic with anyone.
+ * 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 declare const createOwner: (secret: OwnerSecret) => Owner;
+/**
+ * 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";
+    /**
+     * The mnemonic that was used to derive the AppOwner keys. Optional when the
+     * AppOwner is created from external keys to avoid sharing the mnemonic with
+     * the Evolu app.
+     */
+    readonly mnemonic?: Mnemonic | null;
+}
+/** Creates an {@link AppOwner} from an {@link OwnerSecret}. */
+export declare const createAppOwner: (secret: OwnerSecret) => AppOwner;
+export type TransportConfig = WebSocketTransportConfig;
+export interface WebSocketTransportConfig {
+    readonly type: "WebSocket";
+    readonly url: string;
 }
 /**
- * Used to shard data within an app for partial or deferred sync. Created in the
- * Evolu `initialData` function or dynamically as needed. Its mnemonic is stored
- * in an app table (encrypted by `AppOwner`) and synced between devices. Its
- * `writeKey` is deterministic and rotatable, enabling selective syncing of data
- * subsets. Not intended for sharing outside the app.
- *
- * This type omits `id`, `encryptionKey`, and `createdAt` as they are derived by
- * Evolu from the `mnemonic`, reducing storage overhead.
+ * 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 {
+export interface ShardOwner extends Owner {
     readonly type: "ShardOwner";
-    readonly mnemonic: Mnemonic;
-    readonly writeKey: WriteKey;
+    readonly transports?: ReadonlyArray<TransportConfig>;
 }
+/** Creates a {@link ShardOwner} from an {@link OwnerSecret}. */
+export declare const createShardOwner: (secret: OwnerSecret, transports?: ReadonlyArray<TransportConfig>) => ShardOwner;
 /**
- * Used to share data among one or more users, enabling collaboration or
- * controlled access. Its `writeKey` is random (not derived from the mnemonic,
- * stored alongside it in the app table) and rotatable, ensuring it cannot be
- * regenerated by others if shared. Share the `mnemonic` alone for read-only
- * access (as `SharedReadonlyOwner`) or share SharedOwner itself for write
- * access.
- *
- * This type omits `id`, `encryptionKey`, and `createdAt` as they are derived by
- * Evolu from the `mnemonic`, reducing storage overhead.
+ * 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 interface SharedOwner {
+export declare const deriveShardOwner: (owner: AppOwner, path: NonEmptyReadonlyArray<string | number>, transports?: ReadonlyArray<TransportConfig>) => ShardOwner;
+/** An {@link Owner} for collaborative data with write access. */
+export interface SharedOwner extends Owner {
     readonly type: "SharedOwner";
-    readonly mnemonic: Mnemonic;
-    readonly writeKey: WriteKey;
+    readonly transports?: ReadonlyArray<TransportConfig>;
 }
 /**
- * Used for sharing data that can only be read, such as with followers or peers
- * in a read-only sync scenario. It lacks a `writeKey`, containing only the
- * `mnemonic` from which `id` and `encryptionKey` are derived by Evolu.
- * Typically derived from a `SharedOwner` by sharing its `mnemonic` without the
- * `writeKey`.
+ * Creates a {@link SharedOwner} from an {@link OwnerSecret} for collaborative
+ * write access.
+ *
+ * Use {@link createSharedReadonlyOwner} to create a read-only version for
+ * sharing.
+ */
+export declare const createSharedOwner: (secret: OwnerSecret, transports?: ReadonlyArray<TransportConfig>) => SharedOwner;
+/**
+ * Read-only version of a {@link SharedOwner} for data sharing. Contains only the
+ * {@link OwnerId} and {@link EncryptionKey} needed for others to read the shared
+ * data without write access.
  */
 export interface SharedReadonlyOwner {
     readonly type: "SharedReadonlyOwner";
-    readonly mnemonic: Mnemonic;
+    readonly id: OwnerId;
+    readonly encryptionKey: EncryptionKey;
+    readonly transports?: ReadonlyArray<TransportConfig>;
 }
-/**
- * Creates an {@link AppOwner}, optionally from an existing mnemonic to restore
- * it on another device; otherwise, generates a new mnemonic.
- */
-export declare const createAppOwner: (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) => (mnemonic?: string & import("../Types.js").Brand<"Trimmed"> & import("../Types.js").Brand<"MinLength1"> & import("../Types.js").Brand<"Mnemonic">) => AppOwner;
-/**
- * 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.
- */
-export declare const createShardOwner: (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) => ShardOwner;
-/**
- * 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.
- */
-export declare const createSharedOwner: (deps: CreateRandomBytesDep & CreateMnemonicDep) => SharedOwner;
-/**
- * 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 SharedReadonlyOwner} from a {@link SharedOwner}. */
 export declare const createSharedReadonlyOwner: (sharedOwner: SharedOwner) => SharedReadonlyOwner;
-/** Creates an {@link Owner} with optional `mnemonic` and `writeKey`. */
-export declare const createOwner: (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) => (mnemonic?: string & import("../Types.js").Brand<"Trimmed"> & import("../Types.js").Brand<"MinLength1"> & import("../Types.js").Brand<"Mnemonic">, writeKey?: WriteKey) => Owner;
-export declare const createWriteKey: (deps: CreateRandomBytesDep) => (seed?: MnemonicSeed) => WriteKey;
-/**
- * An `OwnerRow` represents a row in the `evolu_owner` table, based on an
- * {@link Owner} with an added `timestamp` ({@link TimestampString}) for CRDT
- * sync. It supports all {@link Owner} variants with an optional `writeKey`; use
- * {@link createOwnerRow} to align it with a specific {@link Owner}.
- */
-export type OwnerRow = Omit<Owner, "writeKey"> & {
-    readonly writeKey: WriteKey | null;
-    readonly timestamp: TimestampString;
-};
-/**
- * Creates an {@link OwnerRow} from any {@link Owner} variant for the
- * `evolu_owner` table, adding a `timestamp` ({@link TimestampString}) for CRDT
- * sync.
- */
-export declare const createOwnerRow: (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep & NanoIdLibDep) => (owner: AppOwner | ShardOwner | SharedOwner | SharedReadonlyOwner) => OwnerRow;
-/**
- * Rotates the {@link WriteKey} for an {@link AppOwner}, {@link ShardOwner}, or
- * {@link SharedOwner}, returning a new instance with the updated key.
- */
-export declare const rotateWriteKey: <T extends AppOwner | ShardOwner | SharedOwner>(owner: T, newWriteKey: WriteKey) => T;
 //# sourceMappingURL=Owner.d.ts.map