@djangocfg/api 2.1.546 → 2.1.548

package/src/auth/context/AuthContext.tsx

@@ -40,7 +40,12 @@ import { authLogger } from '../utils/logger';
 import { AccountsProvider, useAccountsContext } from './AccountsContext';
 
 import type { AuthContextType, AuthProviderProps, UserProfile } from './types';
-import type { OTPRequestConsent, OTPRequestResult } from '../types';
+import type {
+  OTPRequestConsent,
+  OTPRequestResult,
+  PasswordLoginOptions,
+  PasswordLoginResult,
+} from '../types';
 import type { OtpRequestRequest } from '../../_api/generated/_cfg_accounts/types.gen';
 
 // The ONLY place route conventions are declared. '/auth' is the sign-in page
@@ -368,6 +373,98 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
     [setStoredEmail, redirectManager, router],
   );
 
+  // ── Password login flow ────────────────────────────────────────────────────
+
+  // Same envelope, same branches and the same single session owner as
+  // verifyOTP — only the credential differs. Anything that diverges here
+  // (a second token store, a bespoke fetch) forks the session.
+  const login = useCallback(
+    async (
+      email: string,
+      password: string,
+      options?: PasswordLoginOptions,
+    ): Promise<PasswordLoginResult> => {
+      const { redirectUrl, skipRedirect, rememberMe = false } = options || {};
+
+      try {
+        // The caller opting out of redirect commits to handling ALL navigation
+        // for this login — including the 2FA continuation and success screen.
+        pendingManualNavRef.current = Boolean(skipRedirect);
+
+        const result = await accountsRef.current.loginWithPassword({
+          email,
+          password,
+          remember_me: rememberMe,
+        });
+
+        if (result.requires_2fa && result.session_id) {
+          authLogger.info('2FA required, session:', result.session_id);
+          return {
+            success: true,
+            message: 'Password verified, 2FA required',
+            requires_2fa: true,
+            session_id: result.session_id,
+            should_prompt_2fa: result.should_prompt_2fa,
+          };
+        }
+
+        if (!result.access || !result.refresh) {
+          authLogger.error('Password login returned invalid response:', result);
+          return { success: false, message: 'Invalid login response' };
+        }
+        setStoredEmail(email);
+
+        Analytics.event(AnalyticsEvent.AUTH_LOGIN_SUCCESS, {
+          category: AnalyticsCategory.AUTH,
+          label: 'password',
+        });
+        if (result.user?.id) {
+          Analytics.setUser(String(result.user.id));
+        }
+
+        if (!skipRedirect) {
+          // Priority: saved back-url (per-visit intent from the guard) >
+          // explicit redirectUrl (static app default) > config default.
+          // hardPush = full page load so every context reinitializes cleanly.
+          const saved = redirectManager.hasRedirect() ? redirectManager.getRedirect() : null;
+          if (saved) redirectManager.clearRedirect();
+          const finalRedirectUrl = saved || redirectUrl || routesRef.current.defaultCallback;
+          authLogger.info('Redirecting after auth to:', finalRedirectUrl);
+          router.hardPush(finalRedirectUrl);
+        }
+
+        return {
+          success: true,
+          message: 'Login successful',
+          user: result.user as UserProfile,
+          should_prompt_2fa: result.should_prompt_2fa,
+        };
+      } catch (error) {
+        authLogger.error('Password login error:', error);
+        Analytics.event(AnalyticsEvent.AUTH_PASSWORD_LOGIN_FAIL, {
+          category: AnalyticsCategory.AUTH,
+          label: 'password',
+        });
+        if (error instanceof APIError) {
+          // 429 carries `retry_after`; 401 carries only `error_code`. Both are
+          // surfaced so a form can show a countdown instead of a dead message.
+          const body = error.response as
+            | { error_code?: string; retry_after?: number }
+            | undefined;
+          return {
+            success: false,
+            statusCode: error.statusCode,
+            message: apiErrorMessage(error),
+            errorCode: body?.error_code,
+            retryAfter: typeof body?.retry_after === 'number' ? body.retry_after : undefined,
+          };
+        }
+        return { success: false, message: 'Failed to sign in' };
+      }
+    },
+    [setStoredEmail, redirectManager, router],
+  );
+
   // ── Session actions ────────────────────────────────────────────────────────
 
   const refreshToken = useCallback(async (): Promise<{ success: boolean; message: string }> => {
@@ -442,6 +539,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
       clearSavedEmail: clearStoredEmail,
       requestOTP,
       verifyOTP,
+      login,
       refreshToken,
       logout,
       saveRedirectUrl: redirectManager.setRedirect,
@@ -464,6 +562,7 @@ const AuthProviderInternal: React.FC<AuthProviderProps> = ({ children, config })
       clearStoredEmail,
       requestOTP,
       verifyOTP,
+      login,
       refreshToken,
       logout,
       redirectManager,
@@ -522,6 +621,10 @@ const defaultAuthState: AuthContextType = {
     authLogger.warn('useAuth: verifyOTP called outside AuthProvider');
     return { success: false, message: 'AuthProvider not available' };
   },
+  login: async () => {
+    authLogger.warn('useAuth: login called outside AuthProvider');
+    return { success: false, message: 'AuthProvider not available' };
+  },
   refreshToken: async () => {
     authLogger.warn('useAuth: refreshToken called outside AuthProvider');
     return { success: false, message: 'AuthProvider not available' };

package/src/auth/context/types.ts

@@ -1,7 +1,12 @@
 import React from 'react';
 
 import type { User } from '../../';
-import type { OTPRequestConsent, OTPRequestResult } from '../types';
+import type {
+  OTPRequestConsent,
+  OTPRequestResult,
+  PasswordLoginOptions,
+  PasswordLoginResult,
+} from '../types';
 
 // User profile type
 export type UserProfile = User;
@@ -58,6 +63,10 @@ export interface AuthContextType {
     session_id?: string | null;
     should_prompt_2fa?: boolean;
   }>;
+  // Password Method - same envelope and the same session owner as verifyOTP;
+  // `requires_2fa` hands off to the existing 2FA flow with a session id.
+  login: (email: string, password: string, options?: PasswordLoginOptions) => Promise<PasswordLoginResult>;
+
   refreshToken: () => Promise<{ success: boolean; message: string }>;
   logout: () => void;
 

package/src/auth/hooks/useAuthForm.ts

@@ -43,6 +43,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
   const {
     requestOTP,
     verifyOTP,
+    login,
     getSavedEmail,
     saveEmail,
   } = useAuth();
@@ -51,6 +52,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
   const {
     identifier,
     otp,
+    password,
     acceptedTerms,
     marketingConsent,
     rememberMe,
@@ -235,6 +237,87 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
     await submitOTP(identifier, otp);
   }, [identifier, otp, submitOTP]);
 
+  // ─────────────────────────────────────────────────────────────────────────
+  // Password Submit
+  // ─────────────────────────────────────────────────────────────────────────
+
+  // The password credential lands on the SAME step machine as the OTP code:
+  // both end at '2fa' or 'success', so the layout renders one set of screens.
+  const submitPassword = useCallback(async (
+    submitIdentifier: string,
+    submitPassword_: string,
+  ): Promise<boolean> => {
+    if (!submitIdentifier || !validateIdentifier(submitIdentifier)) {
+      const msg = 'Please enter a valid email address';
+      setError(msg);
+      onError?.(msg);
+      return false;
+    }
+
+    if (!submitPassword_) {
+      const msg = 'Please enter your password';
+      setError(msg);
+      onError?.(msg);
+      return false;
+    }
+
+    setIsLoading(true);
+    clearError();
+
+    try {
+      // Skip redirect - we'll show success screen first
+      const result = await login(submitIdentifier, submitPassword_, {
+        redirectUrl,
+        skipRedirect: true,
+        rememberMe,
+      });
+
+      if (result.requires_2fa && result.session_id) {
+        authLogger.info('2FA required after password login');
+        setTwoFactorSessionId(result.session_id);
+        setShouldPrompt2FA(result.should_prompt_2fa || false);
+        setStep('2fa');
+        saveIdentifierToStorage(submitIdentifier);
+        return true; // Password was accepted, now need 2FA
+      }
+
+      if (result.success) {
+        saveIdentifierToStorage(submitIdentifier);
+        authLogger.info('Password login successful, showing success screen');
+        setStep('success');
+        onOTPSuccess?.();
+        return true;
+      }
+
+      // A lockout (429) carries a retry-after; show the countdown instead of a
+      // message the user can only re-trigger.
+      if (result.retryAfter) {
+        startRateLimitCountdown(result.retryAfter);
+        clearError();
+      } else {
+        setError(result.message);
+        onError?.(result.message);
+      }
+      return false;
+    } catch {
+      const msg = 'An unexpected error occurred';
+      setError(msg);
+      onError?.(msg);
+      return false;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [
+    login, validateIdentifier, saveIdentifierToStorage, setError, setIsLoading,
+    clearError, startRateLimitCountdown, onOTPSuccess, onError, redirectUrl,
+    rememberMe, setTwoFactorSessionId, setShouldPrompt2FA, setStep,
+  ]);
+
+  const handlePasswordSubmit = useCallback(async (e: React.FormEvent) => {
+    e.preventDefault();
+    await submitPassword(identifier, password);
+  }, [identifier, password, submitPassword]);
+
   const handleResendOTP = useCallback(async () => {
     setIsLoading(true);
     clearError();
@@ -370,6 +453,7 @@ export const useAuthForm = (options: UseAuthFormOptions): AuthFormReturn => {
     // Submit handlers
     handleIdentifierSubmit,
     handleOTPSubmit,
+    handlePasswordSubmit,
     handleResendOTP,
     handleBackToIdentifier,
     forceOTPStep,

package/src/auth/hooks/useAuthFormState.ts

@@ -21,6 +21,7 @@ export const useAuthFormState = (
 ): UseAuthFormStateReturn => {
   const [identifier, setIdentifier] = useState(initialIdentifier);
   const [otp, setOtp] = useState('');
+  const [password, setPassword] = useState('');
   const [isLoading, setIsLoading] = useState(false);
   const [acceptedTerms, setAcceptedTerms] = useState(true);
   // null until the marketing-consent feature (if enabled) resolves its
@@ -66,6 +67,7 @@ export const useAuthFormState = (
     // State
     identifier,
     otp,
+    password,
     isLoading,
     acceptedTerms,
     marketingConsent,
@@ -83,6 +85,7 @@ export const useAuthFormState = (
     // Handlers
     setIdentifier,
     setOtp,
+    setPassword,
     setAcceptedTerms,
     setMarketingConsent,
     setRememberMe,

package/src/auth/types/form.ts

@@ -7,7 +7,7 @@
 
 import type { MutableRefObject } from 'react';
 
-import type { WebmailLink } from '../../_api/generated/types.gen';
+import type { User, WebmailLink } from '../../_api/generated/types.gen';
 
 export type { WebmailLink };
 
@@ -41,6 +41,41 @@ export interface OTPRequestConsent {
   disclosureVersion: string;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Password Login Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface PasswordLoginOptions {
+  /** URL to redirect to after a successful login (ignored when skipRedirect). */
+  redirectUrl?: string;
+  /** Caller owns ALL navigation for this login, including the 2FA continuation. */
+  skipRedirect?: boolean;
+  /** Ask the server for a 30-day session instead of the default lifetime. */
+  rememberMe?: boolean;
+}
+
+/**
+ * Result of a password login.
+ *
+ * Deliberately the same shape as the verifyOTP result plus the failure codes
+ * the password endpoint adds: a sign-in form branches on `requires_2fa` the
+ * same way whichever credential it collected.
+ */
+export interface PasswordLoginResult {
+  success: boolean;
+  message: string;
+  user?: User;
+  requires_2fa?: boolean;
+  session_id?: string | null;
+  should_prompt_2fa?: boolean;
+  /** HTTP status of a failure — 401 for bad credentials, 429 when throttled. */
+  statusCode?: number;
+  /** Machine-readable failure code, e.g. `invalid_credentials`, `locked_out`. */
+  errorCode?: string;
+  /** Seconds until a throttled caller may retry (429 only). */
+  retryAfter?: number;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Form State
 // ─────────────────────────────────────────────────────────────────────────────
@@ -50,6 +85,8 @@ export interface AuthFormState {
   identifier: string;
   /** OTP code input */
   otp: string;
+  /** Password input (password sign-in; empty for the OTP-only flow) */
+  password: string;
   /** Loading state */
   isLoading: boolean;
   /** Terms acceptance state */
@@ -91,6 +128,7 @@ export interface AuthFormState {
 export interface AuthFormStateHandlers {
   setIdentifier: (identifier: string) => void;
   setOtp: (otp: string) => void;
+  setPassword: (password: string) => void;
   setAcceptedTerms: (accepted: boolean) => void;
   setMarketingConsent: (consent: boolean | null) => void;
   setRememberMe: (rememberMe: boolean) => void;
@@ -111,6 +149,8 @@ export interface AuthFormStateHandlers {
 export interface AuthFormSubmitHandlers {
   handleIdentifierSubmit: (e: React.FormEvent) => Promise<void>;
   handleOTPSubmit: (e: React.FormEvent) => Promise<void>;
+  /** Submit email + password against the password grant */
+  handlePasswordSubmit: (e: React.FormEvent) => Promise<void>;
   handleResendOTP: () => Promise<void>;
   handleBackToIdentifier: () => void;
   forceOTPStep: () => void;

package/src/auth/types/index.ts

@@ -14,6 +14,8 @@ export type {
   UseAuthFormOptions,
   OTPRequestResult,
   OTPRequestConsent,
+  PasswordLoginOptions,
+  PasswordLoginResult,
   WebmailLink,
 } from './form';
 

package/src/auth/utils/analytics.ts

@@ -19,6 +19,7 @@ export enum AnalyticsEvent {
   AUTH_OTP_REQUEST = 'auth_otp_request',
   AUTH_LOGIN_SUCCESS = 'auth_login_success',
   AUTH_OTP_VERIFY_FAIL = 'auth_otp_verify_fail',
+  AUTH_PASSWORD_LOGIN_FAIL = 'auth_password_login_fail',
   AUTH_SESSION_EXPIRED = 'auth_session_expired',
   AUTH_TOKEN_REFRESH = 'auth_token_refresh',
   AUTH_TOKEN_REFRESH_FAIL = 'auth_token_refresh_fail',

package/src/auth/utils/guard.ts

@@ -9,7 +9,9 @@
  *
  * Invariant that fixes the bug: once auth is resolved (`authLoading === false`)
  * and the user is unauthenticated, `isLoading` must become false so the guard
- * redirects to the form instead of spinning forever.
+ * redirects to the form instead of spinning forever. The same invariant covers
+ * the forbidden case: a signed-in user without the required privilege must stop
+ * loading too, or the preloader spins on a state no redirect will ever clear.
  */
 
 export interface GuardInput {
@@ -23,6 +25,29 @@ export interface GuardInput {
   isRedirecting: boolean;
   /** User currently has a (valid-looking) session. */
   isAuthenticated: boolean;
+  /** Route requires staff/admin privileges, not just a session. */
+  requireStaff?: boolean;
+  /** `is_staff || is_superuser`, from `useAuth().isAdminUser`. */
+  isAdminUser?: boolean;
+}
+
+/**
+ * True when the session is valid but lacks the required privilege.
+ *
+ * Distinct from unauthenticated: the fix is a different account, not signing
+ * in, so this must never redirect to the auth form. Redirecting would also
+ * loop — the guard saves the current URL first, so a successful re-login on
+ * the same account returns straight to the wall.
+ */
+export function isForbidden(s: GuardInput): boolean {
+  return Boolean(
+    s.mounted &&
+    s.requireAuth &&
+    s.requireStaff &&
+    !s.authLoading &&
+    s.isAuthenticated &&
+    !s.isAdminUser
+  );
 }
 
 /**
@@ -32,6 +57,7 @@ export interface GuardInput {
 export function resolveGuardIsLoading(s: GuardInput): boolean {
   if (!s.mounted) return true; // pre-hydration: always preloader
   if (!s.requireAuth) return false; // public route: never blocks
+  if (isForbidden(s)) return false; // resolved: render the wall, don't spin
   return s.authLoading || s.isRedirecting || !s.isAuthenticated;
 }
 

package/src/auth/utils/index.ts

@@ -4,6 +4,7 @@ export {
   resolveGuardIsLoading,
   shouldRedirectToAuth,
   resolveGuardIsAuthenticated,
+  isForbidden,
   type GuardInput,
 } from './guard';
 export { normalizePath, isAllowedAuthPath } from './path';