@entropy-softworks/ui 2026.7.31

package/src/services/auth.service.ts

@@ -0,0 +1,498 @@
+import { Platform } from "react-native";
+import { apiFetch } from "../utils/api-fetch";
+import { extractApiError, extractErrorMessage } from "../utils/http-error";
+import {
+  validateEmail as validateEmailUtil,
+  validatePassword as validatePasswordUtil,
+  validateUsername as validateUsernameUtil,
+} from "../utils/validation";
+import * as ApiConfig from "./api-config";
+import { clearCachedPolicy as clearHibpPolicyCache } from "./hibp-cache";
+
+// Native persists the user record in SecureStore so the next app launch
+// has it before /auth/me lands. Web keeps it in process memory only —
+// sessionStorage is XSS-readable and the cookie-bound session lets us
+// re-fetch the record from the server on the next mount without a
+// noticeable UX regression. See SECURITY.md.
+const USER_DATA_KEY_SUFFIX = "user_data";
+let inMemoryUser: User | null = null;
+
+function userDataKey(): string {
+  return `${ApiConfig.getStoragePrefix()}_${USER_DATA_KEY_SUFFIX}`;
+}
+
+async function persistUser(user: User): Promise<void> {
+  if (Platform.OS === "web") {
+    inMemoryUser = user;
+    return;
+  }
+  await ApiConfig.kvPut(userDataKey(), JSON.stringify(user));
+}
+
+async function clearPersistedUser(): Promise<void> {
+  if (Platform.OS === "web") {
+    inMemoryUser = null;
+    return;
+  }
+  await ApiConfig.kvPut(userDataKey(), null);
+}
+
+/**
+ * Normalize a login/register response body into an {@link AuthResponse}.
+ * Single-tenant servers wrap the user as `{ user, session_token }`;
+ * the multi-tenant IdP (access) returns the user record directly and
+ * establishes the session via an HttpOnly cookie (no bearer token).
+ */
+async function parseAuthResponse(response: Response): Promise<AuthResponse> {
+  const json: unknown = await response.json();
+  if (json && typeof json === "object" && "user" in json) {
+    return json as AuthResponse;
+  }
+  return { user: json as User, session_token: "" };
+}
+
+async function loadPersistedUser(): Promise<User | null> {
+  if (Platform.OS === "web") {
+    return inMemoryUser;
+  }
+  try {
+    const userJson = await ApiConfig.kvGet(userDataKey());
+    if (!userJson) {
+      return null;
+    }
+    return JSON.parse(userJson) as User;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Shape of the user record returned by Entropy Softworks servers. Apps
+ * may carry additional fields — extend the interface in the consumer if
+ * needed and pass the extended type through `useAuth<TUser>()`.
+ */
+/**
+ * Conventional onboarding-step values produced by Entropy Softworks
+ * servers. Apps may carry additional vendor-specific steps — keep the
+ * field typed as `string` to stay compatible with the openapi-generated
+ * `UserPublic` shape that vault and bootstrap import from their shared
+ * packages.
+ */
+export type OnboardingStep = "email_verification" | "mfa_enrollment" | "import" | "complete";
+
+export interface User {
+  id: string;
+  email: string;
+  /** Optional: email-only servers (e.g. Simple Finance) don't issue usernames. */
+  username?: string;
+  display_name?: string;
+  role: "Admin" | "User";
+  /**
+   * Pending step in the post-signup onboarding flow. Typed as `string`
+   * (rather than the `OnboardingStep` union) to stay assignment-compatible
+   * with server-generated openapi types; the auth screens compare against
+   * the known constants and treat unknown values as "complete".
+   */
+  onboarding_step?: string | null;
+  email_verified?: boolean;
+  mfa_enabled?: boolean;
+  mfa_verified?: boolean;
+  created_at?: string;
+}
+
+export interface AuthResponse {
+  user: User;
+  /**
+   * Bearer token for native clients. Web clients receive an HttpOnly
+   * cookie and ignore this field.
+   */
+  session_token: string;
+}
+
+/** Public server feature flags from `GET /config`. */
+export interface ServerConfig {
+  /** New accounts must enroll a passkey/TOTP during onboarding. */
+  require_mfa_enrollment: boolean;
+  registration_enabled: boolean;
+}
+
+export interface LoginRequest {
+  email: string;
+  password: string;
+}
+
+export interface RegisterRequest {
+  email: string;
+  /** Optional: omitted for email-only servers (e.g. Simple Finance). */
+  username?: string;
+  password: string;
+  display_name?: string;
+}
+
+export interface ErrorResponse {
+  error: {
+    message: string;
+    details?: string[];
+    code?: string;
+  };
+}
+
+export interface MfaSetupResponse {
+  uri: string;
+  secret: string;
+  recovery_codes: string[];
+}
+
+/**
+ * Auth client for Entropy Softworks servers. Apps call `configureApi`
+ * (from `@entropy-softworks/ui/services`) at startup so storage keys and
+ * the base URL are wired up before any of these methods run.
+ */
+class AuthService {
+  static loadServerUrlOverride = ApiConfig.loadServerUrlOverride;
+  static getBaseUrl = ApiConfig.getBaseUrl;
+  static setBaseUrl = ApiConfig.setBaseUrl;
+  static resetBaseUrl = ApiConfig.resetBaseUrl;
+  static getSessionToken = ApiConfig.getSessionToken;
+
+  /**
+   * Persist the session credential + user record produced by an
+   * alternative auth path (passkey-finish, magic-link, etc.) so the
+   * rest of `useAuth` / `getCurrentUser` sees the same state the
+   * password `login` flow leaves behind.
+   *
+   * Web: session credential is a server-set HttpOnly cookie; only
+   * the user record persists here, and it lives in process memory
+   * (NOT sessionStorage) so an XSS exploit cannot read it.
+   * Native: token goes through SecureStore, user record goes
+   * through SecureStore alongside it.
+   */
+  static async persistAuthSession(data: AuthResponse): Promise<void> {
+    // Both writes target independent storage keys; parallelising them
+    // saves one round-trip on the login / register hot path.
+    await Promise.all([ApiConfig.storeSessionToken(data.session_token), persistUser(data.user)]);
+  }
+
+  static async login(email: string, password: string): Promise<AuthResponse> {
+    // NFC-normalize every password that crosses the wire so the
+    // server-side auth hash agrees with whatever key the client
+    // derived from the same string. Without this a master password
+    // typed on a keyboard / IME that emits combining-character
+    // sequences on one device and precomposed forms on another
+    // produces two different hashes — login looks like wrong
+    // password while everything visually matches. See
+    // `shared/crypto/webcrypto.ts deriveMasterKey` for the
+    // client-side twin.
+    const pw = password.normalize("NFC");
+    // Multi-tenant IdP (access): { tenant, identifier, password } where the
+    // identifier is an email OR username and the tenant is contextual (set
+    // via ApiConfig.setTenant from the OIDC flow). Single-tenant servers use
+    // the { email, password } contract. `email` is the identifier either way.
+    const body =
+      ApiConfig.getAuthMode() === "multi-tenant"
+        ? { tenant: ApiConfig.getTenant(), identifier: email, password: pw }
+        : ({ email, password: pw } satisfies LoginRequest);
+    const response = await apiFetch("/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      throw await extractApiError(response, "Login failed");
+    }
+
+    const data = await parseAuthResponse(response);
+    await AuthService.persistAuthSession(data);
+    return data;
+  }
+
+  static async register(
+    email: string,
+    username: string | undefined,
+    password: string,
+    displayName?: string
+  ): Promise<AuthResponse> {
+    const body: RegisterRequest = { email, password: password.normalize("NFC") };
+    if (username) {
+      body.username = username;
+    }
+    if (displayName !== undefined) {
+      body.display_name = displayName;
+    }
+    const response = await apiFetch("/auth/register", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      throw await extractApiError(response, "Registration failed");
+    }
+
+    const data = await parseAuthResponse(response);
+    await AuthService.persistAuthSession(data);
+    return data;
+  }
+
+  static async logout(): Promise<void> {
+    try {
+      await apiFetch("/auth/logout", { method: "POST" });
+    } catch (e) {
+      // Logout network call failed — still clear local state below.
+      // Surface the underlying reason in dev so a half-broken logout
+      // (server session still alive after the user thinks they're
+      // gone) doesn't slip past unnoticed. In production we always
+      // clear local state so the UX is "logged out" even if the
+      // server didn't get the request.
+      if (__DEV__) {
+        console.warn("[auth] /auth/logout failed; clearing local state anyway:", e);
+      }
+    } finally {
+      await ApiConfig.clearSessionToken();
+      await clearPersistedUser();
+      clearHibpPolicyCache();
+    }
+  }
+
+  static async getCurrentUser(): Promise<User | null> {
+    return loadPersistedUser();
+  }
+
+  static async refreshUserData(): Promise<User | null> {
+    try {
+      if (!(await this.isAuthenticated())) {
+        return null;
+      }
+      const response = await apiFetch("/auth/me", { method: "GET" });
+      if (!response.ok) {
+        if (response.status === 401) {
+          await this.logout();
+        }
+        return null;
+      }
+      const user: User = await response.json();
+      await persistUser(user);
+      return user;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Web: HttpOnly cookies aren't readable from JS. We use the
+   * presence of the (non-HttpOnly) `csrf_token` cookie — set by the
+   * server alongside the session cookie at login — as the
+   * "authenticated" probe. Falls back to the in-memory user record if
+   * cookies are unreadable (SSR / non-browser test envs).
+   * Native: a token in SecureStore.
+   */
+  static async isAuthenticated(): Promise<boolean> {
+    if (Platform.OS === "web") {
+      if (typeof document !== "undefined" && document.cookie) {
+        if (/(?:^|;\s*)csrf_token=/.test(document.cookie)) {
+          return true;
+        }
+      }
+      return (await this.getCurrentUser()) !== null;
+    }
+    const token = await ApiConfig.getSessionToken();
+    return token !== null;
+  }
+
+  static async hasRole(role: "Admin" | "User"): Promise<boolean> {
+    const user = await this.getCurrentUser();
+    return user?.role === role;
+  }
+
+  static async deleteAccount(password: string): Promise<void> {
+    const response = await apiFetch("/auth/delete", {
+      method: "DELETE",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ password: password.normalize("NFC") }),
+    });
+    if (!response.ok) {
+      throw new Error(await extractErrorMessage(response, "Failed to delete account"));
+    }
+    await ApiConfig.clearSessionToken();
+    await clearPersistedUser();
+  }
+
+  static async changePassword(
+    currentPassword: string,
+    newPassword: string,
+    reWrappedKey?: { symmetric_key_enc: string; pbkdf2_salt: string }
+  ): Promise<void> {
+    const body: Record<string, unknown> = {
+      current_password: currentPassword.normalize("NFC"),
+      new_password: newPassword.normalize("NFC"),
+    };
+    if (reWrappedKey) {
+      body.symmetric_key_enc = reWrappedKey.symmetric_key_enc;
+      body.pbkdf2_salt = reWrappedKey.pbkdf2_salt;
+    }
+    const response = await apiFetch("/auth/password", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+      throw new Error(await extractErrorMessage(response, "Failed to change password"));
+    }
+  }
+
+  static async changeEmail(newEmail: string, password: string): Promise<void> {
+    const response = await apiFetch("/auth/email", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ new_email: newEmail, password: password.normalize("NFC") }),
+    });
+    if (!response.ok) {
+      throw new Error(await extractErrorMessage(response, "Failed to change email"));
+    }
+  }
+
+  static async updateDisplayName(displayName: string): Promise<void> {
+    const response = await apiFetch("/auth/display-name", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ display_name: displayName }),
+    });
+    if (!response.ok) {
+      throw new Error(await extractErrorMessage(response, "Failed to update display name"));
+    }
+  }
+
+  static async setupMfa(): Promise<MfaSetupResponse> {
+    const response = await apiFetch("/auth/mfa/setup", { method: "POST" });
+    if (!response.ok) {
+      throw new Error(await extractErrorMessage(response, "Failed to set up MFA"));
+    }
+    return await response.json();
+  }
+
+  static async verifyMfaSetup(code: string): Promise<void> {
+    const response = await apiFetch("/auth/mfa/verify-setup", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ code }),
+    });
+    if (!response.ok) {
+      throw new Error(await extractErrorMessage(response, "Invalid verification code"));
+    }
+  }
+
+  static async verifyMfa(code: string): Promise<void> {
+    const response = await apiFetch("/auth/mfa/verify", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ code }),
+    });
+    if (!response.ok) {
+      throw new Error(await extractErrorMessage(response, "Invalid MFA code"));
+    }
+  }
+
+  static async disableMfa(password: string): Promise<void> {
+    const response = await apiFetch("/auth/mfa", {
+      method: "DELETE",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ password: password.normalize("NFC") }),
+    });
+    if (!response.ok) {
+      throw new Error(await extractErrorMessage(response, "Failed to disable MFA"));
+    }
+  }
+
+  static async forgotPassword(email: string): Promise<void> {
+    // Multi-tenant IdP scopes the reset request to a tenant.
+    const body =
+      ApiConfig.getAuthMode() === "multi-tenant"
+        ? { tenant: ApiConfig.getTenant(), email }
+        : { email };
+    const response = await apiFetch("/auth/forgot-password", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+      throw new Error(await extractErrorMessage(response, "Failed to send reset email"));
+    }
+  }
+
+  static async validateResetCode(code: string): Promise<void> {
+    const response = await apiFetch("/auth/validate-reset-code", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ code }),
+    });
+    if (!response.ok) {
+      throw await extractApiError(response, "Invalid or expired code");
+    }
+  }
+
+  static async resetPassword(code: string, newPassword: string): Promise<void> {
+    const response = await apiFetch("/auth/reset-password", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ code, new_password: newPassword.normalize("NFC") }),
+    });
+    if (!response.ok) {
+      throw await extractApiError(response, "Failed to reset password");
+    }
+  }
+
+  static async verifyEmail(code: string): Promise<void> {
+    const response = await apiFetch("/auth/verify-email", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ code }),
+    });
+    if (!response.ok) {
+      throw new Error(await extractErrorMessage(response, "Email verification failed"));
+    }
+  }
+
+  static async resendVerification(): Promise<void> {
+    const response = await apiFetch("/auth/resend-verification", { method: "POST" });
+    if (!response.ok) {
+      throw new Error(await extractErrorMessage(response, "Failed to resend verification email"));
+    }
+  }
+
+  static async completeOnboarding(): Promise<void> {
+    const response = await apiFetch("/auth/complete-onboarding", { method: "POST" });
+    if (!response.ok) {
+      throw new Error(await extractErrorMessage(response, "Failed to complete onboarding"));
+    }
+  }
+
+  /**
+   * Public server configuration (feature flags) — read pre-auth to adapt the
+   * UI, e.g. whether MFA enrollment is mandatory during onboarding. Returns
+   * permissive defaults if the endpoint is unavailable so onboarding never
+   * hard-blocks on a missing/older server.
+   */
+  static async getServerConfig(): Promise<ServerConfig> {
+    try {
+      const response = await apiFetch("/config", { method: "GET" });
+      if (!response.ok) {
+        return { require_mfa_enrollment: false, registration_enabled: true };
+      }
+      return (await response.json()) as ServerConfig;
+    } catch {
+      return { require_mfa_enrollment: false, registration_enabled: true };
+    }
+  }
+
+  // Validator hints kept on the class as re-exports of the canonical
+  // free functions in `utils/validation`. The server enforces the same
+  // rules authoritatively (see entropy-auth's `password::policy`); the
+  // versions here are UI-only previews so the user sees feedback before
+  // the round-trip.
+  static validatePassword = validatePasswordUtil;
+  static validateEmail = validateEmailUtil;
+  static validateUsername = validateUsernameUtil;
+}
+
+export default AuthService;

package/src/services/favicon.ts

@@ -0,0 +1,102 @@
+/**
+ * Favicon-resolution helpers shared between mobile + extension.
+ *
+ * Items in the vault (and analogues in other Entropy apps) store an
+ * `icon_url` reference that may be:
+ *
+ *   * a `custom:<uploadId>` marker for a server-side upload — resolved
+ *     at render time through the auth-aware transport;
+ *   * an arbitrary public URL (logo CDN, etc.) — used verbatim;
+ *   * `null` / empty — the renderer derives a favicon URL from the
+ *     item's site URL via the server's favicon-proxy endpoint.
+ */
+
+import { getBaseUrl } from "./api-config";
+
+const CUSTOM_ICON_PREFIX = "custom:";
+
+/**
+ * Build the favicon-proxy URL for a site, or return `null` when no
+ * proxy URL can be built. The caller falls back to its default
+ * placeholder when null is returned.
+ */
+export function buildFaviconUrl(
+  siteUrl: string | null | undefined,
+  faviconPath = "/favicon"
+): string | null {
+  if (!siteUrl) {
+    return null;
+  }
+  const trimmed = siteUrl.trim();
+  if (!trimmed) {
+    return null;
+  }
+  let normalized = trimmed;
+  // Reject non-http(s) schemes up front. If we skipped this and just
+  // prepended `https://`, an `ftp:` input would parse as
+  // `https://ftp://…` — `URL` accepts it, the protocol comes out as
+  // `https:`, and a non-web origin leaks into the favicon proxy query.
+  const explicitScheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(normalized)?.[1];
+  if (explicitScheme && !/^https?$/i.test(explicitScheme)) {
+    return null;
+  }
+  if (!/^https?:\/\//i.test(normalized)) {
+    normalized = `https://${normalized}`;
+  }
+  try {
+    const parsed = new URL(normalized);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      return null;
+    }
+    return `${getBaseUrl()}${faviconPath}?url=${encodeURIComponent(parsed.toString())}`;
+  } catch {
+    return null;
+  }
+}
+
+/** Wrap a raw upload id as a `custom:<id>` reference for storage. */
+export function customIconRef(uploadId: string): string {
+  return `${CUSTOM_ICON_PREFIX}${uploadId}`;
+}
+
+/** True if the stored icon reference points at a custom upload. */
+export function isCustomIconRef(iconRef: string | null | undefined): boolean {
+  return !!iconRef && iconRef.startsWith(CUSTOM_ICON_PREFIX);
+}
+
+/** Extract the upload id from a `custom:<id>` reference. */
+export function customIconId(iconRef: string | null | undefined): string | null {
+  if (!iconRef || !iconRef.startsWith(CUSTOM_ICON_PREFIX)) {
+    return null;
+  }
+  const id = iconRef.slice(CUSTOM_ICON_PREFIX.length);
+  return id || null;
+}
+
+/** Tagged result describing how the renderer should source an item's icon. */
+export type ResolvedIcon =
+  | { kind: "upload"; uploadId: string }
+  | { kind: "url"; uri: string }
+  | { kind: "none" };
+
+/**
+ * Pick the right source for an item's icon. Returning a tagged variant
+ * (rather than always coercing to a URL string) lets the renderer
+ * handle the auth-required upload case differently from public-favicon
+ * URLs without sniffing path patterns at the call site.
+ */
+export function resolveIcon(opts: {
+  iconUrl?: string | null;
+  siteUrl?: string | null;
+  faviconPath?: string;
+}): ResolvedIcon {
+  if (opts.iconUrl) {
+    const uploadId = customIconId(opts.iconUrl);
+    if (uploadId) {
+      return { kind: "upload", uploadId };
+    }
+    return { kind: "url", uri: opts.iconUrl };
+  }
+  const fav = buildFaviconUrl(opts.siteUrl, opts.faviconPath);
+  return fav ? { kind: "url", uri: fav } : { kind: "none" };
+}

package/src/services/hibp-cache.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared HIBP policy cache — separated to avoid circular imports between
+ * `auth.service` (which clears it) and the consumer's policy fetcher.
+ */
+import { apiFetch } from "../utils/api-fetch";
+
+export interface HibpPolicy {
+  enabled: boolean;
+  enforce: boolean;
+  block_threshold: number;
+}
+
+interface ServerConfig {
+  hibp: HibpPolicy;
+}
+
+/** Conservative default — block re-use of widely-leaked passwords. */
+const DEFAULT_POLICY: HibpPolicy = {
+  enabled: true,
+  enforce: true,
+  block_threshold: 1000,
+};
+
+let cachedPolicy: HibpPolicy | null = null;
+
+export function getCachedPolicy(): HibpPolicy | null {
+  return cachedPolicy;
+}
+
+export function setCachedPolicy(policy: HibpPolicy): void {
+  cachedPolicy = policy;
+}
+
+export function clearCachedPolicy(): void {
+  cachedPolicy = null;
+}
+
+/**
+ * Fetch the HIBP policy from the server (`GET /config`). Result is
+ * memoized in the in-process cache for the lifetime of the app — call
+ * once at startup (typically from `<AuthProvider onBeforeCheckAuth>`).
+ * Server-unreachable falls back to `DEFAULT_POLICY` so the caller is
+ * never blocked.
+ */
+export async function fetchHibpPolicy(): Promise<HibpPolicy> {
+  const cached = cachedPolicy;
+  if (cached) {
+    return cached;
+  }
+  try {
+    const response = await apiFetch("/config");
+    if (response.ok) {
+      const config: ServerConfig = await response.json();
+      cachedPolicy = config.hibp;
+      return config.hibp;
+    }
+  } catch {
+    // Server unreachable — fall through to default.
+  }
+  cachedPolicy = DEFAULT_POLICY;
+  return DEFAULT_POLICY;
+}
+
+/**
+ * Synchronous view of the cached policy. Returns the default when
+ * `fetchHibpPolicy` hasn't completed yet; suitable for render-time
+ * gating where blocking is unacceptable.
+ */
+export function getHibpPolicy(): HibpPolicy {
+  return cachedPolicy ?? DEFAULT_POLICY;
+}