@djangocfg/api 2.1.567 → 2.1.570

package/dist/auth.d.cts

@@ -1212,14 +1212,84 @@ declare const useDeleteAccount: () => UseDeleteAccountReturn;
 declare const validateEmail: (email: string) => boolean;
 
 /**
- * Format authentication error for display.
+ * Translation keys for the copy this module can choose.
+ *
+ * Every one already exists, translated, in all 17 locales of `@djangocfg/i18n`
+ * — `api.errors.*` for transport conditions and `ui.errors.*` for the ones a
+ * person can act on. Nothing is added here: a second key saying "Server is
+ * unavailable" in a namespace of its own would be a second owner of the same
+ * sentence, and the one that loses is whichever the caller did not use.
+ *
+ * A 404 maps to `serverUnavailable`, not to `ui.errors.notFound` ("Not found"):
+ * on a sign-in POST the missing thing is the ENDPOINT, which tells the visitor
+ * nothing about a page and everything about the service being down.
+ */
+declare const AUTH_ERROR_KEYS: {
+    readonly invalidCredentials: "ui.errors.unauthorized";
+    readonly rateLimited: "api.errors.rateLimited";
+    readonly serverUnavailable: "api.errors.serverUnavailable";
+    readonly networkError: "api.errors.networkError";
+    readonly generic: "ui.errors.generic";
+};
+type AuthErrorKey = (typeof AUTH_ERROR_KEYS)[keyof typeof AUTH_ERROR_KEYS];
+/** What the auth layer decided to show, and why. */
+interface AuthErrorCopy {
+    /** Ready-to-render text: server prose, or this module's English fallback. */
+    message: string;
+    /**
+     * Set only when `message` came from `FALLBACK_COPY`. A caller holding a
+     * translator renders `t(key)` instead; server prose carries no key because
+     * the backend already chose the words and the locale.
+     */
+    key?: AuthErrorKey;
+}
+/**
+ * Decide what a failed auth call should say.
+ *
+ * Order: text the SERVER wrote, then copy chosen from the status code, then a
+ * generic sentence. Server prose wins because the backend knows the specific
+ * reason ("This code has expired") that a status code cannot express.
  *
  * Each candidate is checked to be a string before it is returned. Under the
  * previous `any` the check was only that the property was truthy, so a DRF
  * field-error object (`{detail: {email: [...]}}`) reached the UI as
  * "[object Object]" — an error message that tells the user nothing.
+ *
+ * `HTTP <code>:` strings are rejected on the way through. They are the
+ * transport restating its own status line, not prose anyone wrote to be read,
+ * and treating them as a message is what put a bare `HTTP 404:` under a
+ * sign-in field. The code itself stays useful — `logAuthFailure` puts it in
+ * the console, where diagnosis belongs.
+ */
+declare const resolveAuthError: (error: unknown, fallback?: string) => AuthErrorCopy;
+/**
+ * `resolveAuthError` for callers that only want the string.
+ *
+ * Kept because most call sites store a plain `error` string in form state and
+ * have no translator to hand.
+ */
+declare const formatAuthError: (error: unknown, fallback?: string) => string;
+/**
+ * Log a failed auth call at the level its cause deserves.
+ *
+ * A 4xx on an auth endpoint is the USER getting it wrong — a mistyped OTP, an
+ * expired code, a bad password. It is the endpoint working. Logged through
+ * `console.error` it became a production alert: `@djangocfg/devtools` captures
+ * `console.error` as an `ERROR` event, so every typo raised "❌ Error" in
+ * Telegram, complete with consola's `%c` CSS in the message body. Real faults
+ * drown in that.
+ *
+ * 5xx, a network failure and a broken response contract stay at `error`:
+ * nobody can fix those by retyping, and they are what the alert is for.
+ *
+ * Both `statusCode` (what `APIError` declares) and `status` are read, because
+ * a Response-shaped rejection can reach here from code that does not go
+ * through the interceptor.
  */
-declare const formatAuthError: (error: unknown) => string;
+declare const logAuthFailure: (log: {
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}, message: string, error: unknown) => void;
 
 /**
  * Pure auth-guard state resolution.
@@ -1370,4 +1440,4 @@ declare const Analytics: {
     setUser(userId: string | null): void;
 };
 
-export { AUTH_CONSTANTS, type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AnalyticsSink, type AuthConfig, AuthContext, type AuthContextType, type AuthFormAutoSubmit, type AuthFormReturn, type AuthFormState, type AuthFormStateHandlers, type AuthFormSubmitHandlers, type AuthFormValidation, AuthProvider, type AuthProviderProps, type AuthStep, type DeleteAccountResult, type GuardInput, type OTPRequestConsent, type OTPRequestResult, type PasswordLoginOptions, type PasswordLoginResult, type PatchedCfgUserUpdateRequest, PatchedCfgUserUpdateRequestSchema, type ProfileCacheOptions, type SessionSnapshot, type SessionStatus, type TwoFactorDevice, type TwoFactorSetupData, type UseAuthFormOptions, type UseAuthFormStateReturn, type UseAutoAuthOptions, type UseDeleteAccountReturn, type UseGithubAuthOptions, type UseGithubAuthReturn, type UseTwoFactorOptions, type UseTwoFactorReturn, type UseTwoFactorSetupOptions, type UseTwoFactorSetupReturn, type UseTwoFactorStatusReturn, type UseTwoFactorVerifyOptions, type UseTwoFactorVerifyReturn, type UserProfile, type WebmailLink, authLogger, clearProfileCache, consumeSavedRedirect, decodeBase64, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, isAllowedAuthPath, isForbidden, logger, normalizePath, peekSavedRedirect, resolveGuardIsAuthenticated, resolveGuardIsLoading, setAnalyticsSink, setCachedProfile, shouldRedirectToAuth, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useQueryParams, useSession, useSessionStorage, useTwoFactor, useTwoFactorSetup, useTwoFactorStatus, useTwoFactorVerify, validateEmail, validateIdentifier };
+export { AUTH_CONSTANTS, AUTH_ERROR_KEYS, type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AnalyticsSink, type AuthConfig, AuthContext, type AuthContextType, type AuthErrorCopy, type AuthErrorKey, type AuthFormAutoSubmit, type AuthFormReturn, type AuthFormState, type AuthFormStateHandlers, type AuthFormSubmitHandlers, type AuthFormValidation, AuthProvider, type AuthProviderProps, type AuthStep, type DeleteAccountResult, type GuardInput, type OTPRequestConsent, type OTPRequestResult, type PasswordLoginOptions, type PasswordLoginResult, type PatchedCfgUserUpdateRequest, PatchedCfgUserUpdateRequestSchema, type ProfileCacheOptions, type SessionSnapshot, type SessionStatus, type TwoFactorDevice, type TwoFactorSetupData, type UseAuthFormOptions, type UseAuthFormStateReturn, type UseAutoAuthOptions, type UseDeleteAccountReturn, type UseGithubAuthOptions, type UseGithubAuthReturn, type UseTwoFactorOptions, type UseTwoFactorReturn, type UseTwoFactorSetupOptions, type UseTwoFactorSetupReturn, type UseTwoFactorStatusReturn, type UseTwoFactorVerifyOptions, type UseTwoFactorVerifyReturn, type UserProfile, type WebmailLink, authLogger, clearProfileCache, consumeSavedRedirect, decodeBase64, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, isAllowedAuthPath, isForbidden, logAuthFailure, logger, normalizePath, peekSavedRedirect, resolveAuthError, resolveGuardIsAuthenticated, resolveGuardIsLoading, setAnalyticsSink, setCachedProfile, shouldRedirectToAuth, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useQueryParams, useSession, useSessionStorage, useTwoFactor, useTwoFactorSetup, useTwoFactorStatus, useTwoFactorVerify, validateEmail, validateIdentifier };

package/dist/auth.d.ts

@@ -1212,14 +1212,84 @@ declare const useDeleteAccount: () => UseDeleteAccountReturn;
 declare const validateEmail: (email: string) => boolean;
 
 /**
- * Format authentication error for display.
+ * Translation keys for the copy this module can choose.
+ *
+ * Every one already exists, translated, in all 17 locales of `@djangocfg/i18n`
+ * — `api.errors.*` for transport conditions and `ui.errors.*` for the ones a
+ * person can act on. Nothing is added here: a second key saying "Server is
+ * unavailable" in a namespace of its own would be a second owner of the same
+ * sentence, and the one that loses is whichever the caller did not use.
+ *
+ * A 404 maps to `serverUnavailable`, not to `ui.errors.notFound` ("Not found"):
+ * on a sign-in POST the missing thing is the ENDPOINT, which tells the visitor
+ * nothing about a page and everything about the service being down.
+ */
+declare const AUTH_ERROR_KEYS: {
+    readonly invalidCredentials: "ui.errors.unauthorized";
+    readonly rateLimited: "api.errors.rateLimited";
+    readonly serverUnavailable: "api.errors.serverUnavailable";
+    readonly networkError: "api.errors.networkError";
+    readonly generic: "ui.errors.generic";
+};
+type AuthErrorKey = (typeof AUTH_ERROR_KEYS)[keyof typeof AUTH_ERROR_KEYS];
+/** What the auth layer decided to show, and why. */
+interface AuthErrorCopy {
+    /** Ready-to-render text: server prose, or this module's English fallback. */
+    message: string;
+    /**
+     * Set only when `message` came from `FALLBACK_COPY`. A caller holding a
+     * translator renders `t(key)` instead; server prose carries no key because
+     * the backend already chose the words and the locale.
+     */
+    key?: AuthErrorKey;
+}
+/**
+ * Decide what a failed auth call should say.
+ *
+ * Order: text the SERVER wrote, then copy chosen from the status code, then a
+ * generic sentence. Server prose wins because the backend knows the specific
+ * reason ("This code has expired") that a status code cannot express.
  *
  * Each candidate is checked to be a string before it is returned. Under the
  * previous `any` the check was only that the property was truthy, so a DRF
  * field-error object (`{detail: {email: [...]}}`) reached the UI as
  * "[object Object]" — an error message that tells the user nothing.
+ *
+ * `HTTP <code>:` strings are rejected on the way through. They are the
+ * transport restating its own status line, not prose anyone wrote to be read,
+ * and treating them as a message is what put a bare `HTTP 404:` under a
+ * sign-in field. The code itself stays useful — `logAuthFailure` puts it in
+ * the console, where diagnosis belongs.
+ */
+declare const resolveAuthError: (error: unknown, fallback?: string) => AuthErrorCopy;
+/**
+ * `resolveAuthError` for callers that only want the string.
+ *
+ * Kept because most call sites store a plain `error` string in form state and
+ * have no translator to hand.
+ */
+declare const formatAuthError: (error: unknown, fallback?: string) => string;
+/**
+ * Log a failed auth call at the level its cause deserves.
+ *
+ * A 4xx on an auth endpoint is the USER getting it wrong — a mistyped OTP, an
+ * expired code, a bad password. It is the endpoint working. Logged through
+ * `console.error` it became a production alert: `@djangocfg/devtools` captures
+ * `console.error` as an `ERROR` event, so every typo raised "❌ Error" in
+ * Telegram, complete with consola's `%c` CSS in the message body. Real faults
+ * drown in that.
+ *
+ * 5xx, a network failure and a broken response contract stay at `error`:
+ * nobody can fix those by retyping, and they are what the alert is for.
+ *
+ * Both `statusCode` (what `APIError` declares) and `status` are read, because
+ * a Response-shaped rejection can reach here from code that does not go
+ * through the interceptor.
  */
-declare const formatAuthError: (error: unknown) => string;
+declare const logAuthFailure: (log: {
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}, message: string, error: unknown) => void;
 
 /**
  * Pure auth-guard state resolution.
@@ -1370,4 +1440,4 @@ declare const Analytics: {
     setUser(userId: string | null): void;
 };
 
-export { AUTH_CONSTANTS, type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AnalyticsSink, type AuthConfig, AuthContext, type AuthContextType, type AuthFormAutoSubmit, type AuthFormReturn, type AuthFormState, type AuthFormStateHandlers, type AuthFormSubmitHandlers, type AuthFormValidation, AuthProvider, type AuthProviderProps, type AuthStep, type DeleteAccountResult, type GuardInput, type OTPRequestConsent, type OTPRequestResult, type PasswordLoginOptions, type PasswordLoginResult, type PatchedCfgUserUpdateRequest, PatchedCfgUserUpdateRequestSchema, type ProfileCacheOptions, type SessionSnapshot, type SessionStatus, type TwoFactorDevice, type TwoFactorSetupData, type UseAuthFormOptions, type UseAuthFormStateReturn, type UseAutoAuthOptions, type UseDeleteAccountReturn, type UseGithubAuthOptions, type UseGithubAuthReturn, type UseTwoFactorOptions, type UseTwoFactorReturn, type UseTwoFactorSetupOptions, type UseTwoFactorSetupReturn, type UseTwoFactorStatusReturn, type UseTwoFactorVerifyOptions, type UseTwoFactorVerifyReturn, type UserProfile, type WebmailLink, authLogger, clearProfileCache, consumeSavedRedirect, decodeBase64, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, isAllowedAuthPath, isForbidden, logger, normalizePath, peekSavedRedirect, resolveGuardIsAuthenticated, resolveGuardIsLoading, setAnalyticsSink, setCachedProfile, shouldRedirectToAuth, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useQueryParams, useSession, useSessionStorage, useTwoFactor, useTwoFactorSetup, useTwoFactorStatus, useTwoFactorVerify, validateEmail, validateIdentifier };
+export { AUTH_CONSTANTS, AUTH_ERROR_KEYS, type AccountsContextValue, AccountsProvider, Analytics, AnalyticsCategory, type AnalyticsCategoryType, AnalyticsEvent, type AnalyticsEventType, type AnalyticsSink, type AuthConfig, AuthContext, type AuthContextType, type AuthErrorCopy, type AuthErrorKey, type AuthFormAutoSubmit, type AuthFormReturn, type AuthFormState, type AuthFormStateHandlers, type AuthFormSubmitHandlers, type AuthFormValidation, AuthProvider, type AuthProviderProps, type AuthStep, type DeleteAccountResult, type GuardInput, type OTPRequestConsent, type OTPRequestResult, type PasswordLoginOptions, type PasswordLoginResult, type PatchedCfgUserUpdateRequest, PatchedCfgUserUpdateRequestSchema, type ProfileCacheOptions, type SessionSnapshot, type SessionStatus, type TwoFactorDevice, type TwoFactorSetupData, type UseAuthFormOptions, type UseAuthFormStateReturn, type UseAutoAuthOptions, type UseDeleteAccountReturn, type UseGithubAuthOptions, type UseGithubAuthReturn, type UseTwoFactorOptions, type UseTwoFactorReturn, type UseTwoFactorSetupOptions, type UseTwoFactorSetupReturn, type UseTwoFactorStatusReturn, type UseTwoFactorVerifyOptions, type UseTwoFactorVerifyReturn, type UserProfile, type WebmailLink, authLogger, clearProfileCache, consumeSavedRedirect, decodeBase64, encodeBase64, formatAuthError, getCacheMetadata, getCachedProfile, hasValidCache, isAllowedAuthPath, isForbidden, logAuthFailure, logger, normalizePath, peekSavedRedirect, resolveAuthError, resolveGuardIsAuthenticated, resolveGuardIsLoading, setAnalyticsSink, setCachedProfile, shouldRedirectToAuth, useAccountsContext, useAuth, useAuthForm, useAuthFormState, useAuthRedirectManager, useAuthValidation, useAutoAuth, useBase64, useCfgRouter, useDeleteAccount, useGithubAuth, useLocalStorage, useQueryParams, useSession, useSessionStorage, useTwoFactor, useTwoFactorSetup, useTwoFactorStatus, useTwoFactorVerify, validateEmail, validateIdentifier };

package/dist/auth.mjs

@@ -2496,6 +2496,67 @@ var Analytics = {
   }
 };
 
+// src/auth/utils/errors.ts
+var prop = /* @__PURE__ */ __name((value, key) => typeof value === "object" && value !== null ? value[key] : void 0, "prop");
+var TRANSPORT_FALLBACK = /^HTTP \d{3}:\s*/;
+var AUTH_ERROR_KEYS = {
+  invalidCredentials: "ui.errors.unauthorized",
+  rateLimited: "api.errors.rateLimited",
+  serverUnavailable: "api.errors.serverUnavailable",
+  networkError: "api.errors.networkError",
+  generic: "ui.errors.generic"
+};
+var FALLBACK_COPY = {
+  [AUTH_ERROR_KEYS.invalidCredentials]: "Please sign in to continue",
+  [AUTH_ERROR_KEYS.rateLimited]: "Too many requests. Please wait.",
+  [AUTH_ERROR_KEYS.serverUnavailable]: "Server is unavailable",
+  [AUTH_ERROR_KEYS.networkError]: "Network error",
+  [AUTH_ERROR_KEYS.generic]: "Something went wrong"
+};
+var keyForStatus = /* @__PURE__ */ __name((status) => {
+  if (status === void 0) return AUTH_ERROR_KEYS.generic;
+  if (status === 401 || status === 403) return AUTH_ERROR_KEYS.invalidCredentials;
+  if (status === 404) return AUTH_ERROR_KEYS.serverUnavailable;
+  if (status === 429) return AUTH_ERROR_KEYS.rateLimited;
+  if (status >= 500) return AUTH_ERROR_KEYS.serverUnavailable;
+  return AUTH_ERROR_KEYS.generic;
+}, "keyForStatus");
+var resolveAuthError = /* @__PURE__ */ __name((error, fallback) => {
+  if (typeof error === "string" && error && !TRANSPORT_FALLBACK.test(error)) {
+    return { message: error };
+  }
+  const candidates = [
+    prop(error, "message"),
+    prop(error, "detail"),
+    prop(prop(error, "response"), "error"),
+    prop(prop(error, "response"), "detail"),
+    prop(prop(error, "response"), "message"),
+    prop(prop(prop(error, "response"), "data"), "detail")
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate && !TRANSPORT_FALLBACK.test(candidate)) {
+      return { message: candidate };
+    }
+  }
+  const rawStatus = prop(error, "statusCode") ?? prop(error, "status");
+  const status = typeof rawStatus === "number" ? rawStatus : void 0;
+  if (status === void 0 && fallback) {
+    return { message: fallback };
+  }
+  const key = keyForStatus(status);
+  return { message: FALLBACK_COPY[key], key };
+}, "resolveAuthError");
+var formatAuthError = /* @__PURE__ */ __name((error, fallback) => resolveAuthError(error, fallback).message, "formatAuthError");
+var logAuthFailure = /* @__PURE__ */ __name((log, message, error) => {
+  const code = prop(error, "statusCode") ?? prop(error, "status");
+  const isClientError = typeof code === "number" && code >= 400 && code < 500;
+  if (isClientError) {
+    log.warn(message, error);
+    return;
+  }
+  log.error(message, error);
+}, "logAuthFailure");
+
 // src/auth/hooks/useSessionStorage.ts
 import { useState as useState3 } from "react";
 
@@ -2716,18 +2777,6 @@ var useAuthRedirectManager = /* @__PURE__ */ __name((options = {}) => {
 
 // src/auth/hooks/twoFactor.shared.ts
 var TOTP_CODE_LENGTH = 6;
-function extractTwoFactorError(err, fallback) {
-  if (err instanceof APIError) {
-    const body = err.response ?? null;
-    if (typeof body?.error === "string") return body.error;
-    if (typeof body?.detail === "string") return body.detail;
-    if (typeof body?.message === "string") return body.message;
-    return err.errorMessage ?? err.message;
-  }
-  if (err instanceof Error) return err.message;
-  return fallback;
-}
-__name(extractTwoFactorError, "extractTwoFactorError");
 function extractAttemptsRemaining(err) {
   if (err instanceof APIError) {
     const body = err.response ?? null;
@@ -2803,8 +2852,8 @@ var useTwoFactorVerify = /* @__PURE__ */ __name((options = {}) => {
       handleSuccess(response);
       return true;
     } catch (err) {
-      authLogger.error("2FA TOTP verification error:", err);
-      const errorMessage = extractTwoFactorError(err, "Invalid verification code");
+      logAuthFailure(authLogger, "2FA TOTP verification failed:", err);
+      const errorMessage = formatAuthError(err, "Invalid verification code");
       const attempts = extractAttemptsRemaining(err);
       if (attempts !== null) setAttemptsRemaining(attempts);
       setError(errorMessage);
@@ -2849,8 +2898,8 @@ var useTwoFactorVerify = /* @__PURE__ */ __name((options = {}) => {
       handleSuccess(response);
       return true;
     } catch (err) {
-      authLogger.error("2FA backup code verification error:", err);
-      const errorMessage = extractTwoFactorError(err, "Invalid backup code");
+      logAuthFailure(authLogger, "2FA backup code verification failed:", err);
+      const errorMessage = formatAuthError(err, "Invalid backup code");
       const attempts = extractAttemptsRemaining(err);
       if (attempts !== null) setAttemptsRemaining(attempts);
       setError(errorMessage);
@@ -3273,7 +3322,7 @@ var useGithubAuth = /* @__PURE__ */ __name((options = {}) => {
       }
       window.location.href = response.authorization_url;
     } catch (err) {
-      const errorMessage = err instanceof Error ? err.message : "Failed to start GitHub authentication";
+      const errorMessage = formatAuthError(err, "Failed to start GitHub authentication");
       authLogger.error("GitHub OAuth start error:", err);
       setError(errorMessage);
       onError?.(errorMessage);
@@ -3336,7 +3385,7 @@ var useGithubAuth = /* @__PURE__ */ __name((options = {}) => {
       }
       return;
     } catch (err) {
-      const errorMessage = err instanceof Error ? err.message : "GitHub authentication failed";
+      const errorMessage = formatAuthError(err, "GitHub authentication failed");
       authLogger.error("GitHub OAuth callback error:", err);
       setError(errorMessage);
       onError?.(errorMessage);
@@ -3398,8 +3447,8 @@ var useTwoFactorSetup = /* @__PURE__ */ __name((options = {}) => {
       authLogger.info("2FA setup initiated, expires in:", data.expiresIn, "seconds");
       return data;
     } catch (err) {
-      const errorMessage = extractTwoFactorError(err, "Failed to start 2FA setup");
-      authLogger.error("2FA setup error:", err);
+      const errorMessage = formatAuthError(err, "Failed to start 2FA setup");
+      logAuthFailure(authLogger, "2FA setup failed:", err);
       setError(errorMessage);
       setSetupStep("idle");
       onError?.(errorMessage);
@@ -3439,8 +3488,8 @@ var useTwoFactorSetup = /* @__PURE__ */ __name((options = {}) => {
       onComplete?.(codes);
       return codes;
     } catch (err) {
-      const errorMessage = extractTwoFactorError(err, "Invalid code. Please try again.");
-      authLogger.error("2FA setup confirmation error:", err);
+      const errorMessage = formatAuthError(err, "Invalid code. Please try again.");
+      logAuthFailure(authLogger, "2FA setup confirmation failed:", err);
       setError(errorMessage);
       setSetupStep("scanning");
       onError?.(errorMessage);
@@ -3491,8 +3540,8 @@ var useTwoFactorStatus = /* @__PURE__ */ __name(() => {
       setHas2FAEnabled(response.has_2fa_enabled);
       authLogger.info("2FA status:", response.has_2fa_enabled ? "enabled" : "disabled");
     } catch (err) {
-      const errorMessage = extractTwoFactorError(err, "Failed to fetch 2FA status");
-      authLogger.error("Failed to fetch 2FA status:", err);
+      const errorMessage = formatAuthError(err, "Failed to fetch 2FA status");
+      logAuthFailure(authLogger, "Failed to fetch 2FA status:", err);
       setError(errorMessage);
     } finally {
       setIsLoading(false);
@@ -3513,8 +3562,8 @@ var useTwoFactorStatus = /* @__PURE__ */ __name(() => {
       authLogger.info("2FA disabled successfully");
       return true;
     } catch (err) {
-      const errorMessage = extractTwoFactorError(err, "Invalid verification code");
-      authLogger.error("Failed to disable 2FA:", err);
+      const errorMessage = formatAuthError(err, "Invalid verification code");
+      logAuthFailure(authLogger, "Failed to disable 2FA:", err);
       setError(errorMessage);
       return false;
     } finally {
@@ -4700,10 +4749,6 @@ var resolveAuthRoutes = /* @__PURE__ */ __name((routes) => ({
 }), "resolveAuthRoutes");
 var EMAIL_STORAGE_KEY = "auth_email";
 var AuthContext = createContext2(void 0);
-var apiErrorMessage = /* @__PURE__ */ __name((error) => {
-  const body = error.response;
-  return body?.error || body?.detail || body?.message || error.errorMessage;
-}, "apiErrorMessage");
 var AuthProviderInternal = /* @__PURE__ */ __name(({ children, config }) => {
   const accounts = useAccountsContext();
   const session = useSession();
@@ -4831,18 +4876,18 @@ var AuthProviderInternal = /* @__PURE__ */ __name(({ children, config }) => {
           webmail: result.webmail ?? null
         };
       } catch (error) {
-        authLogger.error("Request OTP error:", error);
+        logAuthFailure(authLogger, "Request OTP failed:", error);
         if (error instanceof APIError) {
           const body = error.response;
           const retryAfter = body?.retry_after ?? body?.retryAfter;
           return {
             success: false,
             statusCode: error.statusCode,
-            message: apiErrorMessage(error),
+            message: formatAuthError(error),
             retryAfter: typeof retryAfter === "number" ? retryAfter : void 0
           };
         }
-        return { success: false, message: "Failed to send OTP" };
+        return { success: false, message: formatAuthError(error, "Failed to send OTP") };
       }
     },
     []
@@ -4895,15 +4940,15 @@ var AuthProviderInternal = /* @__PURE__ */ __name(({ children, config }) => {
           should_prompt_2fa: result.should_prompt_2fa
         };
       } catch (error) {
-        authLogger.error("Verify OTP error:", error);
+        logAuthFailure(authLogger, "Verify OTP failed:", error);
         Analytics.event("auth_otp_verify_fail" /* AUTH_OTP_VERIFY_FAIL */, {
           category: "auth" /* AUTH */,
           label: "email"
         });
         if (error instanceof APIError) {
-          return { success: false, message: apiErrorMessage(error) };
+          return { success: false, message: formatAuthError(error) };
         }
-        return { success: false, message: "Failed to verify OTP" };
+        return { success: false, message: formatAuthError(error, "Failed to verify OTP") };
       }
     },
     [setStoredEmail, redirectManager, router]
@@ -4954,7 +4999,7 @@ var AuthProviderInternal = /* @__PURE__ */ __name(({ children, config }) => {
           should_prompt_2fa: result.should_prompt_2fa
         };
       } catch (error) {
-        authLogger.error("Password login error:", error);
+        logAuthFailure(authLogger, "Password login failed:", error);
         Analytics.event("auth_password_login_fail" /* AUTH_PASSWORD_LOGIN_FAIL */, {
           category: "auth" /* AUTH */,
           label: "password"
@@ -4964,12 +5009,12 @@ var AuthProviderInternal = /* @__PURE__ */ __name(({ children, config }) => {
           return {
             success: false,
             statusCode: error.statusCode,
-            message: apiErrorMessage(error),
+            message: formatAuthError(error),
             errorCode: body?.error_code,
             retryAfter: typeof body?.retry_after === "number" ? body.retry_after : void 0
           };
         }
-        return { success: false, message: "Failed to sign in" };
+        return { success: false, message: formatAuthError(error, "Failed to sign in") };
       }
     },
     [setStoredEmail, redirectManager, router]
@@ -5139,25 +5184,6 @@ var validateEmail = /* @__PURE__ */ __name((email) => {
   return emailRegex.test(email);
 }, "validateEmail");
 
-// src/auth/utils/errors.ts
-var prop = /* @__PURE__ */ __name((value, key) => typeof value === "object" && value !== null ? value[key] : void 0, "prop");
-var formatAuthError = /* @__PURE__ */ __name((error) => {
-  if (typeof error === "string") {
-    return error;
-  }
-  const candidates = [
-    prop(error, "message"),
-    prop(error, "detail"),
-    prop(prop(prop(error, "response"), "data"), "detail")
-  ];
-  for (const candidate of candidates) {
-    if (typeof candidate === "string" && candidate) {
-      return candidate;
-    }
-  }
-  return "An unexpected error occurred";
-}, "formatAuthError");
-
 // src/auth/utils/guard.ts
 function isForbidden(s) {
   return Boolean(
@@ -5182,6 +5208,7 @@ function resolveGuardIsAuthenticated(s) {
 __name(resolveGuardIsAuthenticated, "resolveGuardIsAuthenticated");
 export {
   AUTH_CONSTANTS,
+  AUTH_ERROR_KEYS,
   AccountsProvider,
   Analytics,
   AnalyticsCategory,
@@ -5200,9 +5227,11 @@ export {
   hasValidCache,
   isAllowedAuthPath,
   isForbidden,
+  logAuthFailure,
   logger,
   normalizePath,
   peekSavedRedirect,
+  resolveAuthError,
   resolveGuardIsAuthenticated,
   resolveGuardIsLoading,
   setAnalyticsSink,