@evolu/common 6.0.1-preview.9 → 7.0.0

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

@@ -0,0 +1,150 @@
+import { RandomBytesDep } from "../Crypto.js";
+import { Mnemonic } from "../Type.js";
+import { AppOwner, OwnerId } from "./Owner.js";
+/**
+ * Local authentication and authorization system for Evolu. This is API is
+ * subject to change and not recommended for production use.
+ *
+ * @experimental
+ */
+export interface LocalAuth {
+    /** Logs in with the given owner ID, or loads the target owner if not provided. */
+    login: (ownerId: OwnerId, options?: LocalAuthOptions) => 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>;
+    /** Gets the current owner (last logged in or last registered owner) */
+    getOwner: (options?: LocalAuthOptions) => Promise<AuthResult | null>;
+    /** Lists all registered owner ids with associated usernames. */
+    getProfiles: (options?: LocalAuthOptionsValues) => Promise<Array<AuthList>>;
+    /** 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 localAuth_Namespace = "evolu";
+export declare const localAuthDefaultOptions: LocalAuthOptions;
+export interface AuthResult {
+    /** The app owner created during registration. */
+    readonly owner: AppOwner | undefined;
+    /** The name provided by the user during registration. */
+    readonly username: string;
+}
+export interface AuthList {
+    /** The app owner ID. */
+    readonly ownerId: OwnerId;
+    /** 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":"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"}

package/dist/src/Evolu/LocalAuth.js

@@ -0,0 +1,174 @@
+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(localAuthMetakeyLastOwner, id, {
+            ...buildAuthOptions(options),
+            accessControl: "none",
+        });
+    };
+    const getLastOwnerId = async (options) => {
+        const item = await deps.secureStorage.getItem(localAuthMetakeyLastOwner, {
+            ...buildAuthOptions(options),
+            accessControl: "none",
+        });
+        return item?.value;
+    };
+    const getOwnerNames = async (options) => {
+        const item = await deps.secureStorage.getItem(localAuthMetakeyOwnerNames, {
+            ...buildAuthOptions(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(localAuthMetakeyOwnerNames, JSON.stringify(names), {
+            ...buildAuthOptions(options),
+            accessControl: "none",
+        });
+    };
+    const deleteOwnerName = async (id, options) => {
+        const { [id]: _, ...names } = await getOwnerNames(options);
+        await deps.secureStorage.setItem(localAuthMetakeyOwnerNames, JSON.stringify(names), {
+            ...buildAuthOptions(options),
+            accessControl: "none",
+        });
+    };
+    const getOwnerIds = async (options) => {
+        const items = await deps.secureStorage.getAllItems({
+            ...buildAuthOptions(options),
+            includeValues: false,
+        });
+        return items
+            .filter(Boolean)
+            .filter((i) => i.key !== localAuthMetakeyLastOwner &&
+            i.key !== localAuthMetakeyOwnerNames)
+            .map((i) => i.key);
+    };
+    const clearAuthStore = (options) => deps.secureStorage.clearService(buildAuthOptions(options));
+    const buildAuthOptions = (options, username) => {
+        const newOptions = {
+            ...localAuthDefaultOptions,
+            ...(username && { webAuthnUsername: username }),
+            ...options,
+        };
+        return {
+            ...newOptions,
+            authenticationPrompt: {
+                title: replaceMessageTokens(newOptions.authenticationPrompt?.title ?? "", username),
+                cancel: replaceMessageTokens(newOptions.authenticationPrompt?.cancel ?? "", username),
+                subtitle: replaceMessageTokens(newOptions.authenticationPrompt?.subtitle ?? "", username),
+                description: replaceMessageTokens(newOptions.authenticationPrompt?.description ?? "", username),
+            },
+        };
+    };
+    const replaceMessageTokens = (text, username) => {
+        if (!username)
+            return text;
+        return text.replace("|USERNAME|", username);
+    };
+    return {
+        login: async (ownerId, options) => {
+            // Lookup the associated username
+            const names = await getOwnerNames(options);
+            const username = names[ownerId] ?? "";
+            // Currently a reload is needed. This avoids 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.
+            await setLastOwnerId(ownerId, options);
+            return { owner: undefined, 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 }), buildAuthOptions(options, username)),
+                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, buildAuthOptions(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);
+                }
+            }
+        },
+        getOwner: async (options) => {
+            const ownerId = await getLastOwnerId(options);
+            if (!ownerId)
+                return null;
+            const names = await getOwnerNames(options);
+            const username = names[ownerId] ?? "";
+            // Retrieve and decrypt the owner (this will trigger device authentication)
+            const account = await deps.secureStorage.getItem(ownerId, buildAuthOptions(options, username));
+            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(ownerId, options);
+            // Return the owner and associated username
+            return { owner, username };
+        },
+        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);
+        },
+    };
+};
+export const localAuth_Namespace = "evolu";
+export const localAuthDefaultOptions = {
+    service: localAuth_Namespace,
+    keychainGroup: localAuth_Namespace,
+    androidBiometricsStrongOnly: true,
+    iosSynchronizable: true,
+    webAuthnUsername: "Evolu User",
+    authenticationPrompt: {
+        title: "Authenticate as |USERNAME|",
+    },
+};
+const localAuthMetakeyLastOwner = "_last_owner";
+const localAuthMetakeyOwnerNames = "_owner_names";