@djangocfg/api 2.1.545 → 2.1.547

package/src/_api/generated/types.gen.ts

@@ -587,6 +587,81 @@ export type OtpVerifyResponse = {
     persistent_session?: boolean;
 };
 
+/**
+ * Typed error response for password login.
+ *
+ * error_code values:
+ * - invalid_credentials — wrong email/password, inactive or deleted account
+ * - rate_limited        — IP rate limit hit
+ * - locked_out          — too many failed attempts for this email
+ */
+export type PasswordLoginError = {
+    /**
+     * Human-readable error message
+     */
+    error: string;
+    /**
+     * Machine-readable error code
+     */
+    error_code: string;
+    /**
+     * Seconds until the caller may retry (throttled responses only)
+     */
+    retry_after?: number | null;
+};
+
+/**
+ * Validate email+password against live accounts only.
+ *
+ * Subclasses SimpleJWT so the field/validation contract stays theirs, but
+ * replaces ``validate()`` — the token pair itself is minted by the view via
+ * ``mint_tokens_for_request`` so the DPoP binding and remembered-session
+ * lifetime match OTP, OAuth and TOTP exactly.
+ */
+export type PasswordLoginRequest = {
+    /**
+     * Keep this browser signed in for 30 days
+     */
+    remember_me?: boolean;
+};
+
+/**
+ * Password-login response.
+ *
+ * Mirrors the OTP verify response so a client can treat every login flow
+ * identically. ``requires_2fa=True`` carries a session id instead of tokens.
+ */
+export type PasswordLoginResponse = {
+    /**
+     * Whether 2FA verification is required
+     */
+    requires_2fa?: boolean;
+    /**
+     * 2FA session ID (if requires_2fa is True)
+     */
+    session_id?: string | null;
+    /**
+     * JWT refresh token (if requires_2fa is False)
+     */
+    refresh?: string | null;
+    /**
+     * JWT access token (if requires_2fa is False)
+     */
+    access?: string | null;
+    /**
+     * User information (if requires_2fa is False)
+     */
+    user?: User | null;
+    /**
+     * Whether user should be prompted to enable 2FA
+     */
+    should_prompt_2fa?: boolean;
+    /**
+     * Whether this login should persist across browser restarts
+     */
+    persistent_session?: boolean;
+};
+
 /**
  * Serializer for updating user profile.
  */
@@ -987,6 +1062,60 @@ export type OtpVerifyResponseWritable = {
     persistent_session?: boolean;
 };
 
+/**
+ * Validate email+password against live accounts only.
+ *
+ * Subclasses SimpleJWT so the field/validation contract stays theirs, but
+ * replaces ``validate()`` — the token pair itself is minted by the view via
+ * ``mint_tokens_for_request`` so the DPoP binding and remembered-session
+ * lifetime match OTP, OAuth and TOTP exactly.
+ */
+export type PasswordLoginRequestWritable = {
+    /**
+     * Keep this browser signed in for 30 days
+     */
+    remember_me?: boolean;
+    email: string;
+    password: string;
+};
+
+/**
+ * Password-login response.
+ *
+ * Mirrors the OTP verify response so a client can treat every login flow
+ * identically. ``requires_2fa=True`` carries a session id instead of tokens.
+ */
+export type PasswordLoginResponseWritable = {
+    /**
+     * Whether 2FA verification is required
+     */
+    requires_2fa?: boolean;
+    /**
+     * 2FA session ID (if requires_2fa is True)
+     */
+    session_id?: string | null;
+    /**
+     * JWT refresh token (if requires_2fa is False)
+     */
+    refresh?: string | null;
+    /**
+     * JWT access token (if requires_2fa is False)
+     */
+    access?: string | null;
+    /**
+     * User information (if requires_2fa is False)
+     */
+    user?: UserWritable | null;
+    /**
+     * Whether user should be prompted to enable 2FA
+     */
+    should_prompt_2fa?: boolean;
+    /**
+     * Whether this login should persist across browser restarts
+     */
+    persistent_session?: boolean;
+};
+
 export type TokenRefreshWritable = {
     refresh: string;
 };
@@ -1428,6 +1557,26 @@ export type CfgAccountsProfileUpdateUpdateResponses = {
 
 export type CfgAccountsProfileUpdateUpdateResponse = CfgAccountsProfileUpdateUpdateResponses[keyof CfgAccountsProfileUpdateUpdateResponses];
 
+export type CfgAccountsTokenCreateData = {
+    body: PasswordLoginRequestWritable;
+    path?: never;
+    query?: never;
+    url: '/cfg/accounts/token/';
+};
+
+export type CfgAccountsTokenCreateErrors = {
+    401: PasswordLoginError;
+    429: PasswordLoginError;
+};
+
+export type CfgAccountsTokenCreateError = CfgAccountsTokenCreateErrors[keyof CfgAccountsTokenCreateErrors];
+
+export type CfgAccountsTokenCreateResponses = {
+    200: PasswordLoginResponse;
+};
+
+export type CfgAccountsTokenCreateResponse = CfgAccountsTokenCreateResponses[keyof CfgAccountsTokenCreateResponses];
+
 export type CfgAccountsTokenBlacklistCreateData = {
     body: TokenBlacklistRequest;
     path?: never;

package/src/auth/__tests__/passwordLogin.test.tsx

@@ -0,0 +1,239 @@
+/**
+ * Password login contract test.
+ *
+ * The password grant returns the SAME envelope as OTP verify, and the point of
+ * that is a single session owner: tokens are written by exactly one path, and
+ * the 2FA branch carries a session id and NO tokens. These three cases are the
+ * regression guard for a second token store creeping in — a bespoke fetch that
+ * "also" saves an access token would pass a shape test and fail these.
+ *
+ * `AccountsContext` is mocked at the module boundary so the test drives the
+ * real `AuthContext.login` (branching, redirect suppression, error mapping)
+ * against a scripted server envelope.
+ */
+
+// @vitest-environment jsdom
+import { act, renderHook } from '@testing-library/react';
+import React from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { APIError } from '../../_api/generated/helpers';
+
+const hardPush = vi.fn();
+const hardReplace = vi.fn();
+
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ push: vi.fn(), replace: vi.fn(), prefetch: vi.fn(), back: vi.fn() }),
+  usePathname: () => '/auth',
+  useSearchParams: () => new URLSearchParams(),
+}));
+
+vi.mock('../hooks/useCfgRouter', () => ({
+  useCfgRouter: () => ({ push: vi.fn(), replace: vi.fn(), hardPush, hardReplace }),
+}));
+
+// The token store stands in for the ONE write path. Asserting on this fake is
+// how "a 401 stored nothing" and "the 2FA branch stored nothing" are proven.
+const tokens: { access: string | null; refresh: string | null } = { access: null, refresh: null };
+vi.mock('../../_api/generated/helpers/auth', () => ({
+  // The generated client self-installs this at import time; the mock must
+  // carry it or every module that touches the SDK fails to load.
+  installAuthOnClient: () => {},
+  auth: {
+    getToken: () => tokens.access,
+    getRefreshToken: () => tokens.refresh,
+    isAuthenticated: () => Boolean(tokens.access),
+    setSession: ({ access, refresh }: { access: string; refresh?: string | null }) => {
+      tokens.access = access;
+      tokens.refresh = refresh ?? null;
+    },
+    clearSession: () => {
+      tokens.access = null;
+      tokens.refresh = null;
+    },
+    onSessionExpired: () => () => {},
+    subscribe: () => () => {},
+  },
+}));
+
+vi.mock('../utils/logger', () => ({
+  authLogger: { debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+vi.mock('../hooks/useSession', () => ({
+  useSession: () => ({ status: tokens.access ? 'authenticated' : 'anonymous' }),
+}));
+
+// Mirrors AccountsContext.loginWithPassword: settles the envelope through the
+// same store the OTP path uses, then hands the raw response back.
+const loginWithPassword = vi.fn();
+const accountsValue = {
+  profile: undefined,
+  isLoadingProfile: false,
+  profileError: null,
+  updateProfile: vi.fn(),
+  partialUpdateProfile: vi.fn(),
+  uploadAvatar: vi.fn(),
+  refreshProfile: vi.fn().mockResolvedValue(undefined),
+  requestOTP: vi.fn(),
+  verifyOTP: vi.fn(),
+  loginWithPassword,
+  logout: vi.fn(),
+};
+
+vi.mock('../context/AccountsContext', () => ({
+  AccountsProvider: ({ children }: { children: React.ReactNode }) => children,
+  useAccountsContext: () => accountsValue,
+}));
+
+const USER = { id: 7, email: 'jane@example.com' };
+
+/** Script `loginWithPassword` with a server envelope, settled like the real one. */
+function respondWith(envelope: Record<string, unknown>) {
+  loginWithPassword.mockImplementation(async () => {
+    const { auth } = await import('../../_api/generated/helpers/auth');
+    if (envelope.requires_2fa && envelope.session_id) return envelope;
+    if (envelope.access && envelope.refresh) {
+      auth.setSession({
+        access: envelope.access as string,
+        refresh: envelope.refresh as string,
+      });
+    }
+    return envelope;
+  });
+}
+
+async function renderAuth() {
+  const { AuthProvider, useAuth } = await import('../context/AuthContext');
+  return renderHook(() => useAuth(), {
+    wrapper: ({ children }: { children: React.ReactNode }) => (
+      <AuthProvider>{children}</AuthProvider>
+    ),
+  });
+}
+
+describe('AuthContext.login (password grant)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    tokens.access = null;
+    tokens.refresh = null;
+  });
+
+  it('stores the token pair and returns the user on success', async () => {
+    respondWith({ requires_2fa: false, access: 'access-1', refresh: 'refresh-1', user: USER });
+    const { result } = await renderAuth();
+
+    let outcome!: Awaited<ReturnType<typeof result.current.login>>;
+    await act(async () => {
+      outcome = await result.current.login('jane@example.com', 'correct horse', {
+        skipRedirect: true,
+      });
+    });
+
+    expect(outcome.success).toBe(true);
+    expect(outcome.user).toEqual(USER);
+    expect(outcome.requires_2fa).toBeUndefined();
+    expect(tokens).toEqual({ access: 'access-1', refresh: 'refresh-1' });
+  });
+
+  it('sends email, password and remember_me to the password endpoint', async () => {
+    respondWith({ requires_2fa: false, access: 'access-1', refresh: 'refresh-1', user: USER });
+    const { result } = await renderAuth();
+
+    await act(async () => {
+      await result.current.login('jane@example.com', 'correct horse', {
+        skipRedirect: true,
+        rememberMe: true,
+      });
+    });
+
+    expect(loginWithPassword).toHaveBeenCalledWith({
+      email: 'jane@example.com',
+      password: 'correct horse',
+      remember_me: true,
+    });
+  });
+
+  it('surfaces a 401 as a typed failure and stores nothing', async () => {
+    loginWithPassword.mockRejectedValue(
+      new APIError(
+        401,
+        'Unauthorized',
+        { error: 'Authentication failed', error_code: 'invalid_credentials' },
+        '/cfg/accounts/token/',
+      ),
+    );
+    const { result } = await renderAuth();
+
+    let outcome!: Awaited<ReturnType<typeof result.current.login>>;
+    await act(async () => {
+      outcome = await result.current.login('jane@example.com', 'wrong', { skipRedirect: true });
+    });
+
+    expect(outcome.success).toBe(false);
+    expect(outcome.statusCode).toBe(401);
+    expect(outcome.errorCode).toBe('invalid_credentials');
+    expect(outcome.message).toBe('Authentication failed');
+    expect(tokens).toEqual({ access: null, refresh: null });
+    expect(hardPush).not.toHaveBeenCalled();
+  });
+
+  it('carries retry_after from a 429 lockout', async () => {
+    loginWithPassword.mockRejectedValue(
+      new APIError(
+        429,
+        'Too Many Requests',
+        {
+          error: 'Too many failed attempts. Please try again later.',
+          error_code: 'locked_out',
+          retry_after: 900,
+        },
+        '/cfg/accounts/token/',
+      ),
+    );
+    const { result } = await renderAuth();
+
+    let outcome!: Awaited<ReturnType<typeof result.current.login>>;
+    await act(async () => {
+      outcome = await result.current.login('jane@example.com', 'wrong', { skipRedirect: true });
+    });
+
+    expect(outcome.success).toBe(false);
+    expect(outcome.statusCode).toBe(429);
+    expect(outcome.errorCode).toBe('locked_out');
+    expect(outcome.retryAfter).toBe(900);
+    expect(tokens).toEqual({ access: null, refresh: null });
+  });
+
+  it('returns the session id and stores NO tokens when 2FA is required', async () => {
+    respondWith({ requires_2fa: true, session_id: 'sess-abc', should_prompt_2fa: false });
+    const { result } = await renderAuth();
+
+    let outcome!: Awaited<ReturnType<typeof result.current.login>>;
+    await act(async () => {
+      outcome = await result.current.login('jane@example.com', 'correct horse', {
+        skipRedirect: true,
+      });
+    });
+
+    expect(outcome.success).toBe(true);
+    expect(outcome.requires_2fa).toBe(true);
+    expect(outcome.session_id).toBe('sess-abc');
+    expect(outcome.user).toBeUndefined();
+    expect(tokens).toEqual({ access: null, refresh: null });
+    expect(hardPush).not.toHaveBeenCalled();
+  });
+
+  it('redirects on success when the caller does not opt out', async () => {
+    respondWith({ requires_2fa: false, access: 'access-1', refresh: 'refresh-1', user: USER });
+    const { result } = await renderAuth();
+
+    await act(async () => {
+      await result.current.login('jane@example.com', 'correct horse', {
+        redirectUrl: '/dashboard',
+      });
+    });
+
+    expect(hardPush).toHaveBeenCalledWith('/dashboard');
+  });
+});

package/src/auth/context/AccountsContext.tsx

@@ -25,6 +25,7 @@ import {
     useCfgAccountsProfileAvatarCreate,
     useCfgAccountsProfilePartialUpdate,
     useCfgAccountsProfileUpdateUpdate,
+    useCfgAccountsTokenCreate,
 } from '../../_api/generated/_cfg_accounts/hooks';
 import { PatchedCfgUserUpdateRequestSchema } from '../../_api/generated/_cfg_accounts/schemas';
 import { clearProfileCache, getCachedProfile, setCachedProfile } from '../hooks/useProfileCache';
@@ -57,6 +58,8 @@ import type {
     OtpVerifyRequest,
     OtpRequestResponse,
     OtpVerifyResponse,
+    PasswordLoginRequestWritable,
+    PasswordLoginResponse,
 } from '../../_api/generated/_cfg_accounts/types.gen';
 
 export { PatchedCfgUserUpdateRequestSchema };
@@ -78,6 +81,7 @@ export interface AccountsContextValue {
 
   requestOTP: (data: OtpRequestRequest) => Promise<OtpRequestResponse>;
   verifyOTP: (data: OtpVerifyRequest) => Promise<OtpVerifyResponse>;
+  loginWithPassword: (data: PasswordLoginRequestWritable) => Promise<PasswordLoginResponse>;
   logout: () => void;
 }
 
@@ -111,6 +115,7 @@ export function AccountsProvider({ children }: AccountsProviderProps) {
   const { trigger: triggerAvatar } = useCfgAccountsProfileAvatarCreate();
   const { trigger: triggerOtpRequest } = useCfgAccountsOtpRequestCreate();
   const { trigger: triggerOtpVerify } = useCfgAccountsOtpVerifyCreate();
+  const { trigger: triggerPasswordLogin } = useCfgAccountsTokenCreate();
 
   const refreshProfile = useCallback(async (options?: { callerId?: string; force?: boolean }): Promise<User | undefined> => {
     const { callerId, force } = options || {};
@@ -177,12 +182,16 @@ export function AccountsProvider({ children }: AccountsProviderProps) {
     return result as OtpRequestResponse;
   }, [triggerOtpRequest]);
 
-  const verifyOTP = useCallback(async (data: OtpVerifyRequest): Promise<OtpVerifyResponse> => {
-    const result = (await triggerOtpVerify({ body: data })) as OtpVerifyResponse;
-
+  // OTP verify and password login return the SAME envelope by design, so both
+  // settle it here — one 2FA branch, one token write, one profile refresh. A
+  // second copy of this is a second session owner.
+  const settleLoginEnvelope = useCallback(async (
+    result: OtpVerifyResponse | PasswordLoginResponse,
+    callerId: string,
+  ): Promise<void> => {
     if (result.requires_2fa && result.session_id) {
       authLogger.info('2FA required, session:', result.session_id);
-      return result;
+      return;
     }
 
     if (result.access && result.refresh) {
@@ -194,14 +203,28 @@ export function AccountsProvider({ children }: AccountsProviderProps) {
       // next page load and would never look at sessionStorage again.
       auth.setSession({ access: result.access, refresh: result.refresh });
       try {
-        await refreshProfile({ callerId: 'verifyOTP', force: true });
+        await refreshProfile({ callerId, force: true });
       } catch (profileError) {
-        authLogger.warn('Profile refresh failed after OTP verify (tokens are saved):', profileError);
+        authLogger.warn(`Profile refresh failed after ${callerId} (tokens are saved):`, profileError);
       }
     }
+  }, [refreshProfile]);
 
+  const verifyOTP = useCallback(async (data: OtpVerifyRequest): Promise<OtpVerifyResponse> => {
+    const result = (await triggerOtpVerify({ body: data })) as OtpVerifyResponse;
+    await settleLoginEnvelope(result, 'verifyOTP');
+    return result;
+  }, [triggerOtpVerify, settleLoginEnvelope]);
+
+  const loginWithPassword = useCallback(async (
+    data: PasswordLoginRequestWritable,
+  ): Promise<PasswordLoginResponse> => {
+    // Errors propagate: the SWR trigger throws APIError for 401/429 and the
+    // caller maps them. Nothing is written to the session on a failure.
+    const result = (await triggerPasswordLogin({ body: data })) as PasswordLoginResponse;
+    await settleLoginEnvelope(result, 'loginWithPassword');
     return result;
-  }, [triggerOtpVerify, refreshProfile]);
+  }, [triggerPasswordLogin, settleLoginEnvelope]);
 
   const logout = useCallback(() => {
     // Best-effort server-side revocation: without blacklisting, a stolen
@@ -229,6 +252,7 @@ export function AccountsProvider({ children }: AccountsProviderProps) {
     refreshProfile,
     requestOTP,
     verifyOTP,
+    loginWithPassword,
     logout,
   }), [
     profile,
@@ -240,6 +264,7 @@ export function AccountsProvider({ children }: AccountsProviderProps) {
     refreshProfile,
     requestOTP,
     verifyOTP,
+    loginWithPassword,
     logout,
   ]);
 

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;