@entropy-softworks/ui 2026.7.31

package/src/hooks/useAuth.tsx

@@ -0,0 +1,567 @@
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { type Href } from "expo-router";
+import { useNavigation } from "../context/NavigationContext";
+import { useAppConfig } from "../context/AppConfigContext";
+import AuthService, { type AuthResponse, type User } from "../services/auth.service";
+
+/**
+ * Outcome of a passkey login attempt. Used by apps with a client-side
+ * unlock step (e.g. vault's symmetric-key derivation) so the login
+ * screen can route to either the home tab or a password-prompt dialog.
+ *
+ *   `unlocked: true`  — the authenticator honored PRF and the local
+ *                       unlock work is done. Route to `routes.home`.
+ *   `unlocked: false` — server accepted the assertion and the session
+ *                       is established, but the consumer still needs
+ *                       the master password. The login screen renders
+ *                       its unlock dialog and calls `unlockWithPassword`.
+ */
+export interface PasskeyLoginResult {
+  unlocked: boolean;
+  user: User;
+}
+
+interface AuthContextType {
+  user: User | null;
+  isLoading: boolean;
+  isAuthenticated: boolean;
+  login: (email: string, password: string) => Promise<void>;
+  /**
+   * Drive a passkey ceremony end-to-end. Available when the consumer
+   * provided `loginWithPasskey` to `AuthProvider`; throws otherwise.
+   * `signal` aborts an in-flight WebAuthn ceremony on web — wire it
+   * to a `useEffect` cleanup so unmounting the screen tears the OS
+   * prompt down instead of leaving an orphaned resolution.
+   */
+  loginWithPasskey: (email?: string, signal?: AbortSignal) => Promise<PasskeyLoginResult>;
+  /**
+   * Complete a non-PRF passkey unlock by deriving the local key from
+   * the master password. Available when the consumer provided
+   * `unlockWithPassword` to `AuthProvider`.
+   */
+  unlockWithPassword: (password: string) => Promise<void>;
+  register: (
+    email: string,
+    username: string | undefined,
+    password: string,
+    displayName?: string
+  ) => Promise<void>;
+  logout: () => Promise<void>;
+  refreshUser: () => Promise<void>;
+  deleteAccount: (password: string) => Promise<void>;
+  checkAuth: () => Promise<void>;
+  error: string | null;
+  clearError: () => void;
+}
+
+const AuthContext = createContext<AuthContextType | undefined>(undefined);
+
+export interface AuthProviderProps {
+  children: React.ReactNode;
+  /**
+   * Optional hook called after a successful login. Vault wires its
+   * `KeyManager.unlock(password)` here; bootstrap leaves it unset.
+   * Throwing rolls the login back via `AuthService.logout()` and bubbles
+   * the error to the caller.
+   */
+  onAfterLogin?: (password: string, response: AuthResponse) => Promise<void> | void;
+  /** Optional post-register hook (mirror of `onAfterLogin`). */
+  onAfterRegister?: (password: string, response: AuthResponse) => Promise<void> | void;
+  /**
+   * Optional pre-logout hook. Vault wires `KeyManager.lock()` and
+   * websocket teardown here; failures are swallowed to keep logout
+   * idempotent.
+   */
+  onBeforeLogout?: () => Promise<void> | void;
+  /**
+   * Optional pre-checkAuth hook. Vault uses this to fetch the server's
+   * HIBP policy alongside the initial session probe.
+   */
+  onBeforeCheckAuth?: () => Promise<void> | void;
+  /**
+   * Optional passkey-ceremony driver. When provided, `useAuth()` exposes
+   * `loginWithPasskey`; the consumer owns the WebAuthn round-trip and the
+   * post-assertion vault unlock. Returning `{ unlocked: true }` finishes
+   * the flow; returning `{ unlocked: false }` keeps the session but tells
+   * the screen to collect the master password and call `unlockWithPassword`.
+   */
+  loginWithPasskey?: (email?: string, signal?: AbortSignal) => Promise<PasskeyLoginResult>;
+  /**
+   * Optional master-password unlock. Used by the passkey flow when the
+   * authenticator did not honor PRF.
+   */
+  unlockWithPassword?: (password: string) => Promise<void>;
+  /**
+   * Optional telemetry hook. Invoked with every error AuthProvider
+   * would otherwise swallow into a `__DEV__`-gated `console.warn` —
+   * post-login hook throw, post-register hook throw, refreshUser
+   * failure, logout API failure, etc. Wire this to Sentry / Rollbar /
+   * your structured-log shipper to get production visibility into
+   * paths the UI hides from the user.
+   *
+   * The `context` string identifies the call site (`"login-hook"`,
+   * `"register-hook"`, `"refresh-user"`, `"logout"`, …) so the
+   * consumer can route or filter without parsing the error message.
+   */
+  onError?: (error: unknown, context: string) => void;
+}
+
+export function AuthProvider({
+  children,
+  onAfterLogin,
+  onAfterRegister,
+  onBeforeLogout,
+  onBeforeCheckAuth,
+  loginWithPasskey: providedLoginWithPasskey,
+  unlockWithPassword: providedUnlockWithPassword,
+  onError,
+}: AuthProviderProps) {
+  // Stable wrapper so `console.warn`-then-onError stays a single
+  // pattern across every silent catch in this provider.
+  const reportError = useCallback(
+    (error: unknown, context: string) => {
+      if (__DEV__) {
+        console.warn(`[auth:${context}]`, error);
+      }
+      try {
+        onError?.(error, context);
+      } catch {
+        // Telemetry must never crash the auth flow.
+      }
+    },
+    [onError]
+  );
+  const [user, setUser] = useState<User | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [isAuthenticated, setIsAuthenticated] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const router = useNavigation();
+  const { routes } = useAppConfig();
+  const authCheckRef = useRef(false);
+  const sessionGenRef = useRef(0);
+
+  const clearError = useCallback(() => {
+    setError(null);
+  }, []);
+
+  const routeAfterAuth = useCallback(
+    (response: AuthResponse, email: string) => {
+      const step = response.user.onboarding_step;
+      if (step === "email_verification") {
+        router.replace({ pathname: routes.verifyEmail, params: { email } } as Href);
+      } else if (step === "mfa_enrollment") {
+        router.replace(routes.mfaEnroll);
+      } else if (step === "import") {
+        router.replace(routes.importData);
+      } else if (step === "complete" || step == null) {
+        router.replace(routes.home);
+      } else {
+        // Unknown step (server added a new onboarding step the
+        // client doesn't recognize). Route home — the consumer's
+        // route guards will catch the still-incomplete state and
+        // either prompt an app update or re-route to welcome.
+        // Don't strand the user in the auth flow.
+        router.replace(routes.home);
+      }
+    },
+    [router, routes]
+  );
+
+  const checkAuth = useCallback(async () => {
+    if (authCheckRef.current) {
+      return;
+    }
+    authCheckRef.current = true;
+    const gen = ++sessionGenRef.current;
+
+    try {
+      setIsLoading(true);
+      const isAuth = await AuthService.isAuthenticated();
+      if (gen !== sessionGenRef.current) {
+        return;
+      }
+
+      if (isAuth) {
+        const userData = await AuthService.getCurrentUser();
+        if (gen !== sessionGenRef.current) {
+          return;
+        }
+        if (userData) {
+          // Unblock navigation immediately with cached data.
+          setUser(userData);
+          setIsAuthenticated(true);
+          setIsLoading(false);
+          authCheckRef.current = false;
+
+          // Refresh from the server in the background.
+          AuthService.refreshUserData()
+            .then((fresh) => {
+              if (fresh && gen === sessionGenRef.current) {
+                setUser(fresh);
+              }
+            })
+            .catch((e) => reportError(e, "background-refresh"));
+          return;
+        } else {
+          await AuthService.logout();
+          if (gen !== sessionGenRef.current) {
+            return;
+          }
+          setUser(null);
+          setIsAuthenticated(false);
+        }
+      } else {
+        setUser(null);
+        setIsAuthenticated(false);
+      }
+    } catch (e) {
+      // Distinguish a transport failure (server unreachable on cold
+      // start) from a real auth failure. Falling through to
+      // "logged out" on transient network errors paints the welcome
+      // screen unjustly to a user whose cookie is still valid, then
+      // flips back the moment a request lands. Keep any persisted
+      // user record while we wait for the next probe.
+      if (gen !== sessionGenRef.current) {
+        return;
+      }
+      const persisted = await AuthService.getCurrentUser().catch(() => null);
+      if (gen !== sessionGenRef.current) {
+        return;
+      }
+      if (persisted) {
+        setUser(persisted);
+        setIsAuthenticated(true);
+        reportError(e instanceof Error ? e : new Error(String(e)), "check-auth-transient");
+      } else {
+        setUser(null);
+        setIsAuthenticated(false);
+      }
+    } finally {
+      if (gen === sessionGenRef.current) {
+        setIsLoading(false);
+      }
+      authCheckRef.current = false;
+    }
+  }, [reportError]);
+
+  useEffect(() => {
+    AuthService.loadServerUrlOverride()
+      .then(() => (onBeforeCheckAuth ? onBeforeCheckAuth() : undefined))
+      .catch((e) => reportError(e, "pre-check-auth"))
+      .then(() => checkAuth());
+  }, [checkAuth, onBeforeCheckAuth, reportError]);
+
+  const login = useCallback(
+    async (email: string, password: string) => {
+      try {
+        setIsLoading(true);
+        setError(null);
+
+        const response = await AuthService.login(email, password);
+
+        if (onAfterLogin) {
+          try {
+            await onAfterLogin(password, response);
+          } catch (hookErr) {
+            await AuthService.logout();
+            const message = hookErr instanceof Error ? hookErr.message : "Post-login hook failed";
+            // Deliberately do NOT attach `cause: hookErr` — the inner
+            // error from the consumer's post-login hook may carry
+            // key-derivation context (raw masterPassword references,
+            // server payloads) that would be exposed if downstream
+            // logging surfaces `err.cause` (Sentry, devtools, …).
+
+            throw new Error(message);
+          }
+        }
+
+        setUser(response.user);
+        setIsAuthenticated(true);
+        routeAfterAuth(response, email);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Login failed";
+        setError(message);
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [onAfterLogin, routeAfterAuth]
+  );
+
+  const register = useCallback(
+    async (email: string, username: string | undefined, password: string, displayName?: string) => {
+      try {
+        setIsLoading(true);
+        setError(null);
+
+        const response = await AuthService.register(email, username, password, displayName);
+
+        if (onAfterRegister) {
+          try {
+            await onAfterRegister(password, response);
+          } catch (hookErr) {
+            await AuthService.logout();
+            const message =
+              hookErr instanceof Error ? hookErr.message : "Post-register hook failed";
+            // No `cause` chain — see login() above for rationale.
+
+            throw new Error(message);
+          }
+        }
+
+        setUser(response.user);
+        setIsAuthenticated(true);
+        routeAfterAuth(response, email);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Registration failed";
+        setError(message);
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [onAfterRegister, routeAfterAuth]
+  );
+
+  const logout = useCallback(async () => {
+    sessionGenRef.current++;
+    setIsLoading(true);
+    // Flip React auth state FIRST so any in-flight queries that
+    // re-render against `user` / `isAuthenticated` see "logged out"
+    // immediately. Previously this happened after `AuthService.logout()`
+    // resolved, opening a window where the pre-logout hook had already
+    // torn down KeyManager / queryClient / WS but components still
+    // rendered as authenticated — any React-Query refetch in that
+    // window would hit a half-disassembled client.
+    setUser(null);
+    setIsAuthenticated(false);
+    if (onBeforeLogout) {
+      try {
+        await onBeforeLogout();
+      } catch (e) {
+        // pre-logout hook errors are non-fatal — proceed to clear
+        // state. Telemetry sees it via the onError surface.
+        reportError(e, "pre-logout-hook");
+      }
+    }
+    router.replace(routes.login);
+    // Server-side revoke runs in the background. Failure is also
+    // surfaced through the onError hook so consumers can detect
+    // half-broken logouts (server session still alive after the
+    // user thinks they're gone).
+    try {
+      await AuthService.logout();
+    } catch (e) {
+      reportError(e, "logout-revoke");
+    }
+    setIsLoading(false);
+  }, [onBeforeLogout, router, routes, reportError]);
+
+  const refreshUser = useCallback(async () => {
+    try {
+      const userData = await AuthService.refreshUserData();
+      if (userData) {
+        setUser(userData);
+        setIsAuthenticated(true);
+      } else {
+        setUser(null);
+        setIsAuthenticated(false);
+        router.replace(routes.login);
+      }
+    } catch {
+      // Refresh failed — try again on next interval.
+    }
+  }, [router, routes]);
+
+  const deleteAccount = useCallback(
+    async (password: string) => {
+      sessionGenRef.current++;
+      try {
+        setIsLoading(true);
+        await AuthService.deleteAccount(password);
+        if (onBeforeLogout) {
+          try {
+            await onBeforeLogout();
+          } catch {
+            // ignore
+          }
+        }
+        setUser(null);
+        setIsAuthenticated(false);
+        router.replace(routes.welcome);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Failed to delete account";
+        setError(message);
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [onBeforeLogout, router, routes]
+  );
+
+  const loginWithPasskey = useCallback(
+    async (email?: string, signal?: AbortSignal): Promise<PasskeyLoginResult> => {
+      if (!providedLoginWithPasskey) {
+        throw new Error(
+          "entropy-ui: loginWithPasskey() called but AuthProvider wasn't given a loginWithPasskey handler."
+        );
+      }
+      try {
+        setIsLoading(true);
+        setError(null);
+        const result = await providedLoginWithPasskey(email, signal);
+        setUser(result.user);
+        setIsAuthenticated(true);
+        return result;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Passkey sign-in failed";
+        setError(message);
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [providedLoginWithPasskey]
+  );
+
+  const unlockWithPassword = useCallback(
+    async (password: string): Promise<void> => {
+      if (!providedUnlockWithPassword) {
+        throw new Error(
+          "entropy-ui: unlockWithPassword() called but AuthProvider wasn't given an unlockWithPassword handler."
+        );
+      }
+      await providedUnlockWithPassword(password);
+    },
+    [providedUnlockWithPassword]
+  );
+
+  const value = useMemo<AuthContextType>(
+    () => ({
+      user,
+      isLoading,
+      isAuthenticated,
+      login,
+      loginWithPasskey,
+      unlockWithPassword,
+      register,
+      logout,
+      refreshUser,
+      deleteAccount,
+      checkAuth,
+      error,
+      clearError,
+    }),
+    [
+      user,
+      isLoading,
+      isAuthenticated,
+      login,
+      loginWithPasskey,
+      unlockWithPassword,
+      register,
+      logout,
+      refreshUser,
+      deleteAccount,
+      checkAuth,
+      error,
+      clearError,
+    ]
+  );
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+
+export function useAuth(): AuthContextType {
+  const context = useContext(AuthContext);
+  if (context === undefined) {
+    throw new Error("useAuth must be used within an AuthProvider");
+  }
+  return context;
+}
+
+export type { AuthContextType };
+
+export function useRole(requiredRole: "Admin" | "User"): boolean {
+  const { user } = useAuth();
+  if (!user) {
+    return false;
+  }
+  if (requiredRole === "User") {
+    return true;
+  }
+  return user.role === "Admin";
+}
+
+export function useRequireAuth(redirectTo?: Href) {
+  const { isAuthenticated, isLoading } = useAuth();
+  const router = useNavigation();
+  const { routes } = useAppConfig();
+  const target = redirectTo ?? routes.login;
+
+  useEffect(() => {
+    if (!isLoading && !isAuthenticated) {
+      router.replace(target);
+    }
+  }, [isAuthenticated, isLoading, router, target]);
+
+  return { isAuthenticated, isLoading };
+}
+
+export function useSession() {
+  const { user, refreshUser, isAuthenticated } = useAuth();
+  const intervalRef = useRef<ReturnType<typeof setInterval> | undefined>(undefined);
+  const refreshingRef = useRef(false);
+
+  useEffect(() => {
+    if (isAuthenticated) {
+      intervalRef.current = setInterval(
+        () => {
+          if (refreshingRef.current) {
+            return;
+          }
+          refreshingRef.current = true;
+          refreshUser()
+            .catch((e) => {
+              // `useSession` lives outside the provider's
+              // reportError closure; auto-refresh failures only
+              // surface in dev. The `refreshUser()` impl itself
+              // reports via onError when wired.
+              if (__DEV__) {
+                console.warn("[auth:session-refresh-interval]", e);
+              }
+            })
+            .finally(() => {
+              refreshingRef.current = false;
+            });
+        },
+        10 * 60 * 1000
+      );
+    }
+
+    return () => {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+      }
+    };
+  }, [isAuthenticated, refreshUser]);
+
+  return { user };
+}
+
+// Validators live in `utils/validation` and are re-exported via the
+// utils barrel. Existing consumers that imported them from this module
+// pull them from the package root barrel instead.
+export { validateEmail, validatePassword, validateUsername } from "../utils/validation";
+
+export default useAuth;

package/src/hooks/useAutoLock.ts

@@ -0,0 +1,110 @@
+import { useEffect } from "react";
+import { AppState as RNAppState, Platform } from "react-native";
+
+const DEFAULT_IDLE_LOCK_MS = 10 * 60 * 1000;
+
+export interface UseAutoLockOptions {
+  /**
+   * Reports whether the session is currently "unlocked" (vault-style
+   * apps) or any other state where the auto-lock should still fire.
+   * Returning `false` short-circuits the lock call.
+   */
+  isUnlocked: () => boolean;
+  /** Called when the lock should fire. App owns side-effects. */
+  onLock: () => void;
+  /** Reports whether auto-lock is enabled for this user (settings flag). */
+  isEnabled?: () => boolean | Promise<boolean>;
+  /** Idle threshold in milliseconds. Defaults to 10 minutes. */
+  idleLockMs?: number;
+}
+
+/**
+ * Auto-lock a session after a period of inactivity. Generic over the
+ * lock predicate — vault wires `KeyManager.isUnlocked` / `KeyManager.lock`,
+ * other apps wire their own state. Web uses an idle-timer only; native
+ * additionally locks immediately when the app goes to the background.
+ */
+export function useAutoLock(options: UseAutoLockOptions): void {
+  const { isUnlocked, onLock, isEnabled, idleLockMs = DEFAULT_IDLE_LOCK_MS } = options;
+
+  useEffect(() => {
+    let idleTimer: ReturnType<typeof setTimeout> | null = null;
+    let lastActivityAt = Date.now();
+
+    const lockIfEnabled = () => {
+      if (idleTimer !== null) {
+        clearTimeout(idleTimer);
+        idleTimer = null;
+      }
+      if (!isUnlocked()) {
+        return;
+      }
+      Promise.resolve(isEnabled ? isEnabled() : true)
+        .then((enabled) => {
+          if (enabled && isUnlocked()) {
+            onLock();
+          }
+        })
+        .catch(() => {});
+    };
+
+    const armIdleTimer = () => {
+      if (idleTimer !== null) {
+        clearTimeout(idleTimer);
+      }
+      const remaining = idleLockMs - (Date.now() - lastActivityAt);
+      if (remaining <= 0) {
+        lockIfEnabled();
+        return;
+      }
+      idleTimer = setTimeout(lockIfEnabled, remaining);
+    };
+
+    const onActivity = () => {
+      lastActivityAt = Date.now();
+      armIdleTimer();
+    };
+
+    // On web, RN Web's AppState mirrors document visibility — tab-hidden
+    // becomes 'background', which would otherwise fire an immediate lock.
+    // Only treat 'background' as a lock signal on real native platforms.
+    const subscription = RNAppState.addEventListener("change", (nextState) => {
+      if (nextState === "background" && Platform.OS !== "web") {
+        lockIfEnabled();
+      } else if (nextState === "active") {
+        armIdleTimer();
+      }
+    });
+
+    const cleanups: (() => void)[] = [];
+
+    if (Platform.OS === "web" && typeof document !== "undefined") {
+      const onVisibility = () => {
+        if (document.visibilityState === "visible") {
+          armIdleTimer();
+        }
+      };
+      document.addEventListener("visibilitychange", onVisibility);
+      cleanups.push(() => document.removeEventListener("visibilitychange", onVisibility));
+
+      const activityEvents = ["mousemove", "mousedown", "keydown", "touchstart", "scroll"] as const;
+      for (const e of activityEvents) {
+        window.addEventListener(e, onActivity, { passive: true });
+        cleanups.push(() => window.removeEventListener(e, onActivity));
+      }
+    }
+
+    armIdleTimer();
+
+    return () => {
+      subscription.remove();
+      for (const fn of cleanups) {
+        fn();
+      }
+      if (idleTimer !== null) {
+        clearTimeout(idleTimer);
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+}

package/src/hooks/useDebouncedValue.ts

@@ -0,0 +1,32 @@
+import { useEffect, useState } from "react";
+
+import { debounce } from "../utils/debounce";
+
+/**
+ * Returns a debounced copy of `value` that only updates after `value` has
+ * stopped changing for `delayMs`. Use it to keep a controlled input
+ * responsive (bind the input to the raw value) while throttling the
+ * expensive work it drives — a network query, a react-query cache key, a
+ * filter over a large list.
+ *
+ * The pending update is cancelled on unmount and whenever `value` changes
+ * again, so a fast typer never fires an update per keystroke and there is no
+ * setState-after-unmount on the trailing edge.
+ *
+ * @example
+ * const [term, setTerm] = useState("");
+ * const debouncedTerm = useDebouncedValue(term, 300);
+ * // <Input value={term} onChangeText={setTerm} />  — instant feedback
+ * // useQuery({ queryKey: ["search", debouncedTerm], ... })  — one fetch per pause
+ */
+export function useDebouncedValue<T>(value: T, delayMs = 300): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const update = debounce((next: T) => setDebounced(next), delayMs);
+    update(value);
+    return update.cancel;
+  }, [value, delayMs]);
+
+  return debounced;
+}