@startsimpli/auth 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/auth",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Shared authentication package for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/__tests__/auth-functions.test.ts

@@ -0,0 +1,271 @@
+/**
+ * Tests for auth function fixes:
+ * - CSRF token included in signin/register
+ * - authFetch triggers session expiration on unrecoverable 401
+ * - signOut clears all cookies
+ * - refreshAccessToken clears session on failure
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+// Mock sessionStorage
+const mockSessionStorage = (() => {
+  let store: Record<string, string> = {};
+  return {
+    getItem: (k: string) => store[k] ?? null,
+    setItem: (k: string, v: string) => { store[k] = v; },
+    removeItem: (k: string) => { delete store[k]; },
+    clear: () => { store = {}; },
+  };
+})();
+vi.stubGlobal('sessionStorage', mockSessionStorage);
+
+// Mock localStorage
+const mockLocalStorage = (() => {
+  let store: Record<string, string> = {};
+  return {
+    getItem: (k: string) => store[k] ?? null,
+    setItem: (k: string, v: string) => { store[k] = v; },
+    removeItem: (k: string) => { delete store[k]; },
+    clear: () => { store = {}; },
+  };
+})();
+vi.stubGlobal('localStorage', mockLocalStorage);
+
+// Mock document.cookie for cookie tests
+let cookieJar = '';
+Object.defineProperty(document, 'cookie', {
+  get: () => cookieJar,
+  set: (v: string) => {
+    // Simple cookie jar: parse and store
+    const [pair] = v.split(';');
+    const [name, val] = pair.split('=');
+    if (!val || v.includes('max-age=0') || v.includes('Expires=Thu, 01 Jan 1970')) {
+      // Delete cookie
+      cookieJar = cookieJar
+        .split('; ')
+        .filter((c) => !c.startsWith(`${name}=`))
+        .join('; ');
+    } else {
+      // Set cookie
+      const existing = cookieJar.split('; ').filter((c) => !c.startsWith(`${name}=`));
+      existing.push(`${name}=${val}`);
+      cookieJar = existing.filter(Boolean).join('; ');
+    }
+  },
+  configurable: true,
+});
+
+vi.mock('../utils/cookies', () => ({
+  getCsrfToken: vi.fn(() => 'test-csrf'),
+  deleteCookie: vi.fn(),
+}));
+
+const {
+  signInWithCredentials,
+  registerAccount,
+  signOut,
+  authFetch,
+  refreshAccessToken,
+  setAccessToken,
+  getAccessToken,
+  setOnSessionExpired,
+  setRememberMe,
+} = await import('../client/functions');
+
+const { deleteCookie } = await import('../utils/cookies');
+
+function makeJwt(payload: object): string {
+  const encode = (obj: object) =>
+    btoa(JSON.stringify(obj)).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+  return `${encode({ alg: 'HS256' })}.${encode(payload)}.sig`;
+}
+
+const VALID_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 3600, user_id: '1' });
+
+describe('CSRF token on signin/register', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSessionStorage.clear();
+    mockLocalStorage.clear();
+  });
+
+  it('signInWithCredentials sends X-CSRFToken header', async () => {
+    mockFetch.mockImplementation((url: string) => {
+      if (url.includes('/csrf/')) {
+        return Promise.resolve({ ok: true });
+      }
+      return Promise.resolve({
+        ok: true,
+        status: 200,
+        json: async () => ({ access: VALID_TOKEN, user: { id: '1', email: 'a@b.com' } }),
+      });
+    });
+
+    await signInWithCredentials('test@test.com', 'password');
+
+    // Find the token endpoint call (not the csrf call)
+    const tokenCall = mockFetch.mock.calls.find(
+      (c: unknown[]) => typeof c[0] === 'string' && (c[0] as string).includes('/auth/token/') && !(c[0] as string).includes('csrf') && !(c[0] as string).includes('refresh')
+    );
+    expect(tokenCall).toBeDefined();
+    const headers = tokenCall![1]?.headers;
+    expect(headers['X-CSRFToken']).toBe('test-csrf');
+  });
+
+  it('registerAccount sends X-CSRFToken header', async () => {
+    mockFetch.mockImplementation((url: string) => {
+      if (url.includes('/csrf/')) {
+        return Promise.resolve({ ok: true });
+      }
+      return Promise.resolve({
+        ok: true,
+        status: 200,
+        json: async () => ({ access: VALID_TOKEN, user: { id: '1', email: 'a@b.com' } }),
+      });
+    });
+
+    await registerAccount({
+      email: 'new@test.com',
+      password: 'securepassword',
+      passwordConfirm: 'securepassword',
+    });
+
+    const registerCall = mockFetch.mock.calls.find(
+      (c: unknown[]) => typeof c[0] === 'string' && (c[0] as string).includes('/auth/register/')
+    );
+    expect(registerCall).toBeDefined();
+    const headers = registerCall![1]?.headers;
+    expect(headers['X-CSRFToken']).toBe('test-csrf');
+  });
+});
+
+describe('authFetch session expiration on unrecoverable 401', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSessionStorage.clear();
+    mockLocalStorage.clear();
+    setAccessToken(VALID_TOKEN);
+  });
+
+  afterEach(() => {
+    setOnSessionExpired(null);
+  });
+
+  it('calls onSessionExpired callback when refresh fails', async () => {
+    const onExpired = vi.fn();
+    setOnSessionExpired(onExpired);
+
+    mockFetch.mockImplementation((url: string) => {
+      if (typeof url === 'string' && url.includes('token/refresh')) {
+        return Promise.resolve({
+          ok: false,
+          status: 401,
+          json: async () => ({}),
+        });
+      }
+      if (typeof url === 'string' && url.includes('/csrf/')) {
+        return Promise.resolve({ ok: true });
+      }
+      return Promise.resolve({
+        ok: false,
+        status: 401,
+        json: async () => ({}),
+      });
+    });
+
+    await authFetch('/api/v1/data/');
+
+    expect(onExpired).toHaveBeenCalledTimes(1);
+  });
+
+  it('clears access token when refresh fails on 401', async () => {
+    mockFetch.mockImplementation((url: string) => {
+      if (typeof url === 'string' && url.includes('token/refresh')) {
+        return Promise.resolve({
+          ok: false,
+          status: 401,
+          json: async () => ({}),
+        });
+      }
+      if (typeof url === 'string' && url.includes('/csrf/')) {
+        return Promise.resolve({ ok: true });
+      }
+      return Promise.resolve({
+        ok: false,
+        status: 401,
+        json: async () => ({}),
+      });
+    });
+
+    await authFetch('/api/v1/data/');
+
+    expect(getAccessToken()).toBeNull();
+  });
+});
+
+describe('signOut cookie cleanup', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSessionStorage.clear();
+    mockLocalStorage.clear();
+    setAccessToken(VALID_TOKEN);
+  });
+
+  it('clears all auth cookies on signOut', async () => {
+    mockFetch.mockResolvedValue({ ok: true });
+
+    await signOut();
+
+    expect(deleteCookie).toHaveBeenCalledWith('auth_session');
+    expect(deleteCookie).toHaveBeenCalledWith('access_token');
+    expect(deleteCookie).toHaveBeenCalledWith('csrftoken');
+  });
+
+  it('clears access token from storage', async () => {
+    mockFetch.mockResolvedValue({ ok: true });
+
+    await signOut();
+
+    expect(getAccessToken()).toBeNull();
+  });
+
+  it('resets rememberMe flag', async () => {
+    setRememberMe(true);
+    expect(mockLocalStorage.getItem('auth_remember_me')).toBe('1');
+
+    mockFetch.mockResolvedValue({ ok: true });
+    await signOut();
+
+    expect(mockLocalStorage.getItem('auth_remember_me')).toBeNull();
+  });
+});
+
+describe('refreshAccessToken clears session on failure', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockSessionStorage.clear();
+    mockLocalStorage.clear();
+    setAccessToken(VALID_TOKEN);
+  });
+
+  it('clears token when refresh endpoint returns non-ok', async () => {
+    mockFetch.mockImplementation((url: string) => {
+      if (typeof url === 'string' && url.includes('/csrf/')) {
+        return Promise.resolve({ ok: true });
+      }
+      return Promise.resolve({
+        ok: false,
+        status: 401,
+        json: async () => ({ detail: 'Token expired' }),
+      });
+    });
+
+    const result = await refreshAccessToken();
+
+    expect(result).toBeNull();
+    expect(getAccessToken()).toBeNull();
+  });
+});

package/src/__tests__/token-storage.test.ts

@@ -1,25 +1,22 @@
 /**
- * Tests for getAccessToken / setAccessToken using sessionStorage.
+ * Tests for getAccessToken / setAccessToken using sessionStorage and localStorage.
  * Regression for fund-your-startup-fe28 (access token was in module-level global).
  */
 import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { getAccessToken, setAccessToken } from '../client/functions';
+import { getAccessToken, setAccessToken, setRememberMe } from '../client/functions';
 
-describe('Token storage (sessionStorage)', () => {
+describe('Token storage (sessionStorage — default)', () => {
   beforeEach(() => {
-    // Clear sessionStorage before each test
     sessionStorage.clear();
-    // Reset to null so tests are independent
+    localStorage.clear();
+    setRememberMe(false);
     setAccessToken(null);
   });
 
   it('stores the token in sessionStorage, not a module-level global', () => {
     setAccessToken('tok-abc123');
 
-    // Value is readable via the getter
     expect(getAccessToken()).toBe('tok-abc123');
-
-    // Value is also in sessionStorage (not just a module variable)
     expect(sessionStorage.getItem('auth_access_token')).toBe('tok-abc123');
   });
 
@@ -44,10 +41,7 @@ describe('Token storage (sessionStorage)', () => {
   });
 
   it('reads fresh value from sessionStorage (survives module reload simulation)', () => {
-    // Simulate token set by a previous page load that wrote to sessionStorage
     sessionStorage.setItem('auth_access_token', 'pre-existing-token');
-
-    // getAccessToken reads from sessionStorage, not just a cached module variable
     expect(getAccessToken()).toBe('pre-existing-token');
   });
 
@@ -59,3 +53,50 @@ describe('Token storage (sessionStorage)', () => {
     expect(sessionStorage.getItem('unrelated_key')).toBe('should-not-matter');
   });
 });
+
+describe('Token storage (localStorage — remember me)', () => {
+  beforeEach(() => {
+    sessionStorage.clear();
+    localStorage.clear();
+    setRememberMe(false);
+    setAccessToken(null);
+  });
+
+  it('stores token in localStorage when rememberMe is enabled', () => {
+    setRememberMe(true);
+    setAccessToken('persistent-tok');
+
+    expect(getAccessToken()).toBe('persistent-tok');
+    expect(localStorage.getItem('auth_access_token')).toBe('persistent-tok');
+    // Should NOT be in sessionStorage
+    expect(sessionStorage.getItem('auth_access_token')).toBeNull();
+  });
+
+  it('reads from localStorage when rememberMe is enabled', () => {
+    setRememberMe(true);
+    localStorage.setItem('auth_access_token', 'pre-existing');
+
+    expect(getAccessToken()).toBe('pre-existing');
+  });
+
+  it('clearing token removes from both storages', () => {
+    setRememberMe(true);
+    setAccessToken('tok');
+    setAccessToken(null);
+
+    expect(localStorage.getItem('auth_access_token')).toBeNull();
+    expect(sessionStorage.getItem('auth_access_token')).toBeNull();
+  });
+
+  it('switching rememberMe off moves reads back to sessionStorage', () => {
+    setRememberMe(true);
+    setAccessToken('persistent');
+    setRememberMe(false);
+
+    // Token is still in localStorage but getter reads from sessionStorage now
+    expect(getAccessToken()).toBeNull();
+    // Put one in sessionStorage
+    sessionStorage.setItem('auth_access_token', 'session-tok');
+    expect(getAccessToken()).toBe('session-tok');
+  });
+});

package/src/__tests__/validation.test.ts

@@ -1,50 +1,72 @@
 import { describe, it, expect } from 'vitest';
-import { validatePassword, validateEmail } from '../validation';
+import { validatePassword, validatePasswordConfirm, validateEmail } from '../validation';
 
-describe('validatePassword', () => {
+describe('validatePassword — aligned with Django AUTH_PASSWORD_VALIDATORS', () => {
   it('rejects passwords shorter than 8 chars', () => {
-    const result = validatePassword('Ab1');
+    const result = validatePassword('abc');
     expect(result.isValid).toBe(false);
-    expect(result.error).toMatch(/8 characters/);
+    expect(result.errors).toContainEqual(expect.stringMatching(/8 characters/));
   });
 
-  it('rejects passwords with no uppercase letter', () => {
-    const result = validatePassword('abcdefg1');
+  it('rejects entirely numeric passwords', () => {
+    const result = validatePassword('12345678');
     expect(result.isValid).toBe(false);
-    expect(result.error).toMatch(/uppercase/i);
+    expect(result.errors).toContainEqual(expect.stringMatching(/entirely numeric/));
   });
 
-  it('rejects passwords with no lowercase letter', () => {
-    const result = validatePassword('ABCDEFG1');
+  it('rejects common passwords', () => {
+    const result = validatePassword('password1');
     expect(result.isValid).toBe(false);
-    expect(result.error).toMatch(/lowercase/i);
+    expect(result.errors).toContainEqual(expect.stringMatching(/too common/));
   });
 
-  it('rejects passwords with no number', () => {
-    const result = validatePassword('Abcdefgh');
+  it('returns multiple errors for passwords that fail multiple rules', () => {
+    const result = validatePassword('1234');
     expect(result.isValid).toBe(false);
-    expect(result.error).toMatch(/number/i);
+    expect(result.errors.length).toBeGreaterThanOrEqual(2);
   });
 
-  it('accepts a password with uppercase, lowercase, and number — no special char required', () => {
+  it('accepts a valid password with mixed chars', () => {
     const result = validatePassword('Testpassword1');
     expect(result.isValid).toBe(true);
-    expect(result.error).toBeUndefined();
+    expect(result.errors).toHaveLength(0);
   });
 
-  it('accepts a password that also has a special character', () => {
-    const result = validatePassword('Testpassword1!');
+  it('accepts lowercase-only password (Django does not require uppercase)', () => {
+    const result = validatePassword('myvalidpassword');
+    expect(result.isValid).toBe(true);
+  });
+
+  it('accepts password without numbers (Django does not require digits)', () => {
+    const result = validatePassword('myvalidpassword');
     expect(result.isValid).toBe(true);
   });
 
   it('accepts the canonical test credential', () => {
-    // Ensures test account Testpassword1! passes both frontend and backend rules
     expect(validatePassword('Testpassword1!').isValid).toBe(true);
-    // Without special char — must also pass (no drift from backend)
     expect(validatePassword('Testpassword1').isValid).toBe(true);
   });
 });
 
+describe('validatePasswordConfirm', () => {
+  it('rejects mismatched passwords', () => {
+    const result = validatePasswordConfirm('validpassword', 'different');
+    expect(result.isValid).toBe(false);
+    expect(result.errors).toContainEqual(expect.stringMatching(/do not match/));
+  });
+
+  it('validates the password after confirming match', () => {
+    const result = validatePasswordConfirm('short', 'short');
+    expect(result.isValid).toBe(false);
+    expect(result.errors).toContainEqual(expect.stringMatching(/8 characters/));
+  });
+
+  it('accepts matching valid passwords', () => {
+    const result = validatePasswordConfirm('validpassword', 'validpassword');
+    expect(result.isValid).toBe(true);
+  });
+});
+
 describe('validateEmail', () => {
   it('accepts valid email', () => {
     expect(validateEmail('user@example.com')).toBe(true);

package/src/client/auth-context.tsx

@@ -13,6 +13,7 @@ import {
   type ReactNode,
 } from 'react';
 import { AuthClient } from './auth-client';
+import { setOnSessionExpired } from './functions';
 import type { AuthConfig, AuthState, Session, AuthUser } from '../types';
 
 interface AuthContextValue extends AuthState {
@@ -62,19 +63,23 @@ export function AuthProvider({
     }
   }, [authClient, initialSession]);
 
-  // Session expiration handler
+  // Session expiration handler — covers both AuthClient timer and authFetch 401
   useEffect(() => {
-    const originalOnExpired = config.onSessionExpired;
-    config.onSessionExpired = () => {
+    const handleExpired = () => {
       setState({
         session: null,
         isLoading: false,
         isAuthenticated: false,
       });
-      originalOnExpired?.();
+      config.onSessionExpired?.();
     };
 
+    config.onSessionExpired = handleExpired;
+    // Wire up the functional API's session expiration callback
+    setOnSessionExpired(handleExpired);
+
     return () => {
+      setOnSessionExpired(null);
       authClient.destroy();
     };
   }, [authClient, config]);

package/src/client/functions.ts

@@ -6,7 +6,8 @@
  * No Next.js dependency.
  */
 
-import { getCsrfToken } from '../utils/cookies';
+import { getCsrfToken, deleteCookie } from '../utils/cookies';
+import { decodeToken } from '../utils/token';
 
 // --- Types ---
 
@@ -22,6 +23,16 @@ export interface AuthUser {
   isEmailVerified?: boolean;
 }
 
+/** Callback invoked when an unrecoverable 401 is detected (refresh failed). */
+export type OnSessionExpiredCallback = () => void;
+
+let _onSessionExpired: OnSessionExpiredCallback | null = null;
+
+/** Register a callback for unrecoverable 401s (typically set by AuthProvider). */
+export function setOnSessionExpired(cb: OnSessionExpiredCallback | null): void {
+  _onSessionExpired = cb;
+}
+
 // --- Endpoint paths (Django backend defaults) ---
 
 const API_BASE = '/api/v1';
@@ -70,39 +81,64 @@ export function resolveAuthUrl(path: string): string {
 }
 
 // --- Token storage ---
-// Uses sessionStorage when available (browser) so the token is scoped to the
-// current tab and cleared automatically when the tab closes.  Falls back to a
-// module-level variable for SSR environments where sessionStorage is absent.
+// By default uses sessionStorage (scoped to tab, cleared on close).
+// When `setRememberMe(true)` is called, switches to localStorage for persistence.
+// Falls back to a module-level variable for SSR environments.
 
 const TOKEN_STORAGE_KEY = 'auth_access_token';
+const REMEMBER_ME_KEY = 'auth_remember_me';
 
 let _memToken: string | null = null;
 
-function _sessionStorageAvailable(): boolean {
+function _storageAvailable(type: 'sessionStorage' | 'localStorage'): boolean {
   try {
-    return typeof window !== 'undefined' && !!window.sessionStorage;
+    return typeof window !== 'undefined' && !!window[type];
   } catch {
     return false;
   }
 }
 
-export function getAccessToken(): string | null {
-  if (_sessionStorageAvailable()) {
-    return sessionStorage.getItem(TOKEN_STORAGE_KEY);
+function _isRememberMe(): boolean {
+  if (_storageAvailable('localStorage')) {
+    return localStorage.getItem(REMEMBER_ME_KEY) === '1';
+  }
+  return false;
+}
+
+/** Enable/disable persistent token storage across browser sessions. */
+export function setRememberMe(enabled: boolean): void {
+  if (_storageAvailable('localStorage')) {
+    if (enabled) {
+      localStorage.setItem(REMEMBER_ME_KEY, '1');
+    } else {
+      localStorage.removeItem(REMEMBER_ME_KEY);
+    }
   }
+}
+
+function _getStorage(): Storage | null {
+  if (_isRememberMe() && _storageAvailable('localStorage')) return localStorage;
+  if (_storageAvailable('sessionStorage')) return sessionStorage;
+  return null;
+}
+
+export function getAccessToken(): string | null {
+  const storage = _getStorage();
+  if (storage) return storage.getItem(TOKEN_STORAGE_KEY);
   return _memToken;
 }
 
 export function setAccessToken(token: string | null): void {
-  if (_sessionStorageAvailable()) {
+  const storage = _getStorage();
+  if (storage) {
     if (token === null) {
-      sessionStorage.removeItem(TOKEN_STORAGE_KEY);
+      storage.removeItem(TOKEN_STORAGE_KEY);
+      // Also clear from the other storage in case rememberMe was toggled
+      if (_storageAvailable('sessionStorage')) sessionStorage.removeItem(TOKEN_STORAGE_KEY);
+      if (_storageAvailable('localStorage')) localStorage.removeItem(TOKEN_STORAGE_KEY);
     } else {
-      sessionStorage.setItem(TOKEN_STORAGE_KEY, token);
+      storage.setItem(TOKEN_STORAGE_KEY, token);
     }
-    // Sync to a cookie so Next.js middleware can check auth state.
-    // Vercel rewrites don't reliably pass through HttpOnly Set-Cookie
-    // headers from the Django backend, so we set our own.
     _syncAuthCookie(token);
     return;
   }
@@ -111,11 +147,22 @@ export function setAccessToken(token: string | null): void {
 
 const AUTH_COOKIE_NAME = 'auth_session';
 
+/** Derive cookie max-age from JWT exp claim instead of hardcoding. */
+function _getTokenMaxAge(token: string): number {
+  const payload = decodeToken(token);
+  if (payload?.exp) {
+    const secondsLeft = payload.exp - Math.floor(Date.now() / 1000);
+    if (secondsLeft > 0) return secondsLeft;
+  }
+  return 3600; // fallback 1hr — gives the 25min refresh interval plenty of headroom
+}
+
 function _syncAuthCookie(token: string | null): void {
   if (typeof document === 'undefined') return;
   if (token) {
+    const maxAge = _getTokenMaxAge(token);
     const secure = window.location.protocol === 'https:' ? '; Secure' : '';
-    document.cookie = `${AUTH_COOKIE_NAME}=${token}; path=/; max-age=1800; SameSite=Lax${secure}`;
+    document.cookie = `${AUTH_COOKIE_NAME}=${token}; path=/; max-age=${maxAge}; SameSite=Lax${secure}`;
   } else {
     document.cookie = `${AUTH_COOKIE_NAME}=; path=/; max-age=0`;
   }
@@ -183,9 +230,14 @@ function parseAuthResponse(data: unknown): { access?: string; user?: AuthUser }
 // --- Auth functions ---
 
 export async function signInWithCredentials(email: string, password: string) {
+  await fetchCsrfToken();
+  const csrfToken = getCsrfToken();
   const response = await fetchWithTimeout(resolveAuthUrl(AUTH_PATHS.TOKEN), {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: {
+      'Content-Type': 'application/json',
+      ...(csrfToken ? { 'X-CSRFToken': csrfToken } : {}),
+    },
     credentials: 'include',
     body: JSON.stringify({ email, password }),
   });
@@ -221,9 +273,14 @@ export async function registerAccount(payload: {
   const [firstFromName, ...rest] = rawName ? rawName.split(/\s+/) : [];
   const lastFromName = rest.length ? rest.join(' ') : undefined;
 
+  await fetchCsrfToken();
+  const csrfToken = getCsrfToken();
   const response = await fetchWithTimeout(resolveAuthUrl(AUTH_PATHS.REGISTER), {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: {
+      'Content-Type': 'application/json',
+      ...(csrfToken ? { 'X-CSRFToken': csrfToken } : {}),
+    },
     credentials: 'include',
     body: JSON.stringify({
       email: payload.email,
@@ -367,20 +424,35 @@ export async function completeGoogleOAuth(code: string, state: string) {
 
 async function fetchCsrfToken(): Promise<void> {
   if (getCsrfToken()) return;
-  try {
-    await fetch(resolveAuthUrl(`${API_BASE}/auth/csrf/`), {
-      credentials: 'include',
-      cache: 'no-store',
-    });
-  } catch (err) {
-    console.warn('[auth] CSRF token fetch failed — token refresh will fail:', err)
+  const maxAttempts = 3;
+  let lastError: unknown;
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      await fetch(resolveAuthUrl(`${API_BASE}/auth/csrf/`), {
+        credentials: 'include',
+        cache: 'no-store',
+      });
+      if (getCsrfToken()) return;
+    } catch (err) {
+      lastError = err;
+    }
+    if (attempt < maxAttempts - 1) {
+      await new Promise(r => setTimeout(r, 500));
+    }
   }
+  throw new Error(
+    `[auth] CSRF token fetch failed after ${maxAttempts} attempts: ${lastError instanceof Error ? lastError.message : String(lastError ?? 'no token set')}`
+  );
 }
 
 export async function refreshAccessToken(): Promise<string | null> {
   await fetchCsrfToken();
   const csrfToken = getCsrfToken();
-  if (!csrfToken) return null;
+  if (!csrfToken) {
+    console.warn('[auth] No CSRF token available — cannot refresh. Clearing session.');
+    setAccessToken(null);
+    return null;
+  }
 
   const response = await fetchWithTimeout(resolveAuthUrl(AUTH_PATHS.TOKEN_REFRESH), {
     method: 'POST',
@@ -394,6 +466,7 @@ export async function refreshAccessToken(): Promise<string | null> {
   const data = await response.json().catch(() => ({}));
 
   if (!response.ok) {
+    setAccessToken(null);
     return null;
   }
 
@@ -445,6 +518,11 @@ export async function signOut(): Promise<void> {
     });
   } finally {
     setAccessToken(null);
+    setRememberMe(false);
+    // Clear all auth-related cookies
+    deleteCookie(AUTH_COOKIE_NAME);
+    deleteCookie('access_token');
+    deleteCookie('csrftoken');
   }
 }
 
@@ -481,16 +559,25 @@ export async function authFetch(
 
   if (response.status === 401) {
     const refreshed = await _refreshOnce();
+    const retryHeaders = new Headers(init.headers || {});
+
     if (refreshed) {
-      const retryHeaders = new Headers(init.headers || {});
       retryHeaders.set('Authorization', `Bearer ${refreshed}`);
+    }
 
-      return fetch(resolvedInput, {
-        ...init,
-        headers: retryHeaders,
-        credentials: init.credentials ?? 'include',
-      });
+    const retryResponse = await fetch(resolvedInput, {
+      ...init,
+      headers: retryHeaders,
+      credentials: init.credentials ?? 'include',
+    });
+
+    if (!refreshed || retryResponse.status === 401) {
+      // Refresh failed or retried request still unauthorized — session is dead.
+      setAccessToken(null);
+      _onSessionExpired?.();
     }
+
+    return retryResponse;
   }
 
   return response;

package/src/client/index.ts

@@ -1,5 +1,5 @@
 export { AuthClient } from './auth-client';
 export { AuthProvider, useAuthContext } from './auth-context';
-export { useAuth, type UseAuthReturn } from './use-auth';
+export { useAuth, useRequireAuth, type UseAuthReturn, type UseRequireAuthReturn, type UseRequireAuthOptions } from './use-auth';
 export { usePermissions, type UsePermissionsReturn } from './use-permissions';
 export * from './functions';

package/src/client/use-auth.ts

@@ -1,9 +1,10 @@
 /**
- * React hook for authentication
+ * React hooks for authentication
  */
 
 'use client';
 
+import { useEffect } from 'react';
 import { useAuthContext } from './auth-context';
 import type { AuthUser, Session } from '../types';
 
@@ -43,3 +44,47 @@ export function useAuth(): UseAuthReturn {
     getAccessToken,
   };
 }
+
+export interface UseRequireAuthOptions {
+  redirectTo?: string;
+}
+
+export interface UseRequireAuthReturn {
+  user: AuthUser;
+  session: Session;
+  isLoading: boolean;
+  logout: () => Promise<void>;
+  refreshUser: () => Promise<void>;
+  getAccessToken: () => Promise<string | null>;
+}
+
+/**
+ * Hook that redirects unauthenticated users to login.
+ * Returns typed non-null user/session once authenticated.
+ * While loading or redirecting, returns isLoading: true with placeholder values.
+ */
+export function useRequireAuth(
+  options: UseRequireAuthOptions = {}
+): UseRequireAuthReturn {
+  const { redirectTo = '/auth/signin' } = options;
+  const auth = useAuth();
+
+  useEffect(() => {
+    if (!auth.isLoading && !auth.isAuthenticated) {
+      const callbackUrl = typeof window !== 'undefined' ? window.location.pathname : '/';
+      const url = `${redirectTo}?callbackUrl=${encodeURIComponent(callbackUrl)}`;
+      if (typeof window !== 'undefined') {
+        window.location.href = url;
+      }
+    }
+  }, [auth.isLoading, auth.isAuthenticated, redirectTo]);
+
+  return {
+    user: auth.user as AuthUser,
+    session: auth.session as Session,
+    isLoading: auth.isLoading || !auth.isAuthenticated,
+    logout: auth.logout,
+    refreshUser: auth.refreshUser,
+    getAccessToken: auth.getAccessToken,
+  };
+}

package/src/index.ts

@@ -17,10 +17,13 @@ export {
   AuthProvider,
   useAuthContext,
   useAuth,
+  useRequireAuth,
   usePermissions,
   resolveAuthUrl,
   getAccessToken,
   setAccessToken,
+  setRememberMe,
+  setOnSessionExpired,
   signInWithCredentials,
   registerAccount,
   requestPasswordReset,
@@ -36,6 +39,6 @@ export {
   hasPermission,
   hasGroup,
 } from './client';
-export type { UseAuthReturn, UsePermissionsReturn } from './client';
+export type { UseAuthReturn, UseRequireAuthReturn, UseRequireAuthOptions, UsePermissionsReturn } from './client';
 
 // DO NOT export './server' here - it uses next/headers and must be imported explicitly via '@startsimpli/auth/server'

package/src/validation/index.ts

@@ -6,29 +6,47 @@ export function validateEmail(email: string): boolean {
 
 export interface PasswordValidationResult {
   isValid: boolean;
+  errors: string[];
+  /** First error message, for backward compatibility with `.error` consumers. */
   error?: string;
 }
 
-// Canonical password rules for all StartSimpli apps
+// Common passwords subset — Django uses a 20k list; we check the most obvious ones
+// client-side and let the backend catch the rest.
+const COMMON_PASSWORDS = new Set([
+  'password', 'password1', '12345678', '123456789', '1234567890',
+  'qwerty123', 'abcdefgh', 'letmein12', 'welcome1', 'admin123',
+  'iloveyou1', 'sunshine1', 'princess1', 'football1', 'monkey123',
+]);
+
+/**
+ * Canonical password rules aligned with Django AUTH_PASSWORD_VALIDATORS:
+ * - MinimumLengthValidator: min_length=8
+ * - NumericPasswordValidator: not entirely numeric
+ * - CommonPasswordValidator: not in common list (partial client-side check)
+ *
+ * Django also runs UserAttributeSimilarityValidator server-side (needs user data).
+ * We don't enforce uppercase/special chars — Django doesn't either.
+ */
 export function validatePassword(password: string): PasswordValidationResult {
+  const errors: string[] = [];
+
   if (password.length < 8) {
-    return { isValid: false, error: 'Password must be at least 8 characters' };
+    errors.push('Password must be at least 8 characters');
   }
-  if (!/[A-Z]/.test(password)) {
-    return { isValid: false, error: 'Password must contain at least one uppercase letter' };
+  if (/^\d+$/.test(password)) {
+    errors.push('Password cannot be entirely numeric');
   }
-  if (!/[a-z]/.test(password)) {
-    return { isValid: false, error: 'Password must contain at least one lowercase letter' };
+  if (COMMON_PASSWORDS.has(password.toLowerCase())) {
+    errors.push('This password is too common');
   }
-  if (!/[0-9]/.test(password)) {
-    return { isValid: false, error: 'Password must contain at least one number' };
-  }
-  return { isValid: true };
+
+  return { isValid: errors.length === 0, errors, error: errors[0] };
 }
 
 export function validatePasswordConfirm(password: string, confirm: string): PasswordValidationResult {
   if (password !== confirm) {
-    return { isValid: false, error: 'Passwords do not match' };
+    return { isValid: false, errors: ['Passwords do not match'], error: 'Passwords do not match' };
   }
   return validatePassword(password);
 }