@djangocfg/api 2.1.546 → 2.1.548

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__/guard.test.ts

@@ -15,6 +15,7 @@ import {
   resolveGuardIsLoading,
   resolveGuardIsAuthenticated,
   shouldRedirectToAuth,
+  isForbidden,
   type GuardInput,
 } from '../utils/guard';
 
@@ -101,6 +102,70 @@ describe('safety-net timeout (effectiveAuthLoading = authLoading && !timedOut)',
   });
 });
 
+/**
+ * Staff gate. A signed-in non-staff user reaching a staff-only shell is NOT an
+ * auth failure: signing in again cannot fix it. The guard must resolve to a
+ * distinct "forbidden" state — never a redirect (which loops, since the guard
+ * saves the current URL first) and never a spinner (the original hang bug).
+ */
+describe('isForbidden (staff gate)', () => {
+  const staff = (o: Partial<GuardInput>): GuardInput =>
+    s({ requireStaff: true, isAdminUser: false, ...o });
+
+  it('signed-in non-staff user on a staff route is forbidden', () => {
+    expect(isForbidden(staff({}))).toBe(true);
+  });
+
+  it('staff user passes the gate', () => {
+    expect(isForbidden(staff({ isAdminUser: true }))).toBe(false);
+  });
+
+  it('a superuser who is not is_staff passes (isAdminUser folds both flags)', () => {
+    // useAuth() computes isAdminUser as is_staff || is_superuser, so the guard
+    // only ever sees the fold. Checking is_staff alone here would hide the
+    // surface from the people most likely to need it.
+    expect(isForbidden(staff({ isAdminUser: true }))).toBe(false);
+  });
+
+  it('is not forbidden while auth is still resolving (role unknown yet)', () => {
+    expect(isForbidden(staff({ authLoading: true }))).toBe(false);
+  });
+
+  it('is not forbidden before mount (SSR never knows the role)', () => {
+    expect(isForbidden(staff({ mounted: false }))).toBe(false);
+  });
+
+  it('unauthenticated is a redirect, not a forbidden wall', () => {
+    expect(isForbidden(staff({ isAuthenticated: false }))).toBe(false);
+    expect(shouldRedirectToAuth(staff({ isAuthenticated: false }))).toBe(true);
+  });
+
+  it('routes that do not require staff are never forbidden', () => {
+    expect(isForbidden(s({ requireStaff: false, isAdminUser: false }))).toBe(false);
+    expect(isForbidden(base)).toBe(false); // requireStaff undefined
+  });
+
+  it('a public route is never forbidden', () => {
+    expect(isForbidden(staff({ requireAuth: false }))).toBe(false);
+  });
+
+  it('REGRESSION: a forbidden user stops loading (renders the wall, never spins)', () => {
+    expect(resolveGuardIsLoading(staff({}))).toBe(false);
+  });
+
+  it('REGRESSION: a forbidden user never triggers a redirect (no login loop)', () => {
+    expect(shouldRedirectToAuth(staff({}))).toBe(false);
+  });
+
+  it('a staff user on a staff route renders content', () => {
+    expect(resolveGuardIsLoading(staff({ isAdminUser: true }))).toBe(false);
+  });
+
+  it('still blocks while a staff route is resolving auth', () => {
+    expect(resolveGuardIsLoading(staff({ authLoading: true }))).toBe(true);
+  });
+});
+
 describe('resolveGuardIsAuthenticated', () => {
   it('is true on a public route regardless of session', () => {
     expect(resolveGuardIsAuthenticated({ requireAuth: false, isAuthenticated: false })).toBe(true);

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,
   ]);