@startsimpli/auth 0.4.15 → 0.4.16

package/src/client/__tests__/token-auth-core.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  TokenAuthClient,
+  InMemoryTokenStorage,
+  type TokenStorage,
+} from '../token-auth-core';
+
+// Build a fake (unsigned) JWT with a real `exp` so getTokenExpiresAt works.
+function makeToken(secondsFromNow = 3600): string {
+  const exp = Math.floor(Date.now() / 1000) + secondsFromNow;
+  const header = btoa(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+  const body = btoa(JSON.stringify({ tokenType: 'access', exp, iat: exp - 3600, jti: 'x', userId: '1' }));
+  return `${header}.${body}.sig`;
+}
+
+const ACCESS = makeToken();
+const ACCESS2 = makeToken(7200);
+
+// Minimal fetch-mock helper returning a Response-like object.
+function jsonResponse(body: unknown, ok = true, status = 200) {
+  return { ok, status, json: async () => body } as Response;
+}
+
+function makeClient(storage: TokenStorage = new InMemoryTokenStorage()) {
+  const fetchMock = vi.fn<typeof fetch>();
+  const client = new TokenAuthClient({
+    apiBaseUrl: 'http://localhost:8001',
+    storage,
+    fetch: fetchMock,
+  });
+  return { client, fetchMock, storage };
+}
+
+// Pull [url, init] out of the Nth fetch call for assertions.
+function call(fetchMock: ReturnType<typeof vi.fn>, n = 0): [string, RequestInit] {
+  const [url, init] = fetchMock.mock.calls[n];
+  return [String(url), (init ?? {}) as RequestInit];
+}
+
+describe('TokenAuthClient.login', () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it('opts into token mode (X-Auth-Mode), stores the refresh token, returns a session', async () => {
+    const { client, fetchMock, storage } = makeClient();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ access: ACCESS, refresh: 'refresh-1', user: { id: 'u1', email: 'a@b.co' } })
+    );
+
+    const session = await client.login('a@b.co', 'pw');
+
+    const [url, init] = call(fetchMock);
+    expect(url).toBe('http://localhost:8001/api/v1/auth/token/');
+    expect(init.method).toBe('POST');
+    expect((init.headers as Record<string, string>)['X-Auth-Mode']).toBe('token');
+    expect(JSON.parse(init.body as string)).toEqual({ email: 'a@b.co', password: 'pw' });
+
+    expect(session.accessToken).toBe(ACCESS);
+    expect(session.expiresAt).toBeGreaterThan(Date.now());
+    expect(session.user.id).toBe('u1');
+    expect(client.getAccessToken()).toBe(ACCESS);
+    expect(await storage.getRefreshToken()).toBe('refresh-1');
+  });
+
+  it('fetches /me/ when the login response omits the user', async () => {
+    const { client, fetchMock } = makeClient();
+    fetchMock
+      .mockResolvedValueOnce(jsonResponse({ access: ACCESS, refresh: 'r' })) // login, no user
+      .mockResolvedValueOnce(
+        jsonResponse({ user: { id: 'u9', email: 'me@x.co', first_name: 'Me', last_name: 'X' } })
+      ); // /me/
+
+    const session = await client.login('me@x.co', 'pw');
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(call(fetchMock, 1)[0]).toBe('http://localhost:8001/api/v1/auth/me/');
+    expect(session.user.id).toBe('u9');
+    expect(session.user.firstName).toBe('Me');
+  });
+
+  it('throws the extracted API error on failure and stores nothing', async () => {
+    const { client, fetchMock, storage } = makeClient();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ error: 'No active account found' }, false, 401)
+    );
+
+    await expect(client.login('a@b.co', 'bad')).rejects.toThrow('No active account found');
+    expect(await storage.getRefreshToken()).toBeNull();
+    expect(client.getAccessToken()).toBeNull();
+  });
+});
+
+describe('TokenAuthClient.refreshToken', () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it('sends the stored refresh token in the body and rotates it', async () => {
+    const storage = new InMemoryTokenStorage();
+    await storage.setRefreshToken('refresh-old');
+    const { client, fetchMock } = makeClient(storage);
+    fetchMock.mockResolvedValueOnce(jsonResponse({ access: ACCESS2, refresh: 'refresh-new' }));
+
+    const access = await client.refreshToken();
+
+    const [url, init] = call(fetchMock);
+    expect(url).toBe('http://localhost:8001/api/v1/auth/token/refresh/');
+    expect(JSON.parse(init.body as string)).toEqual({ refresh: 'refresh-old' });
+    expect(access).toBe(ACCESS2);
+    expect(client.getAccessToken()).toBe(ACCESS2);
+    expect(await storage.getRefreshToken()).toBe('refresh-new'); // rotated
+  });
+
+  it('throws when there is no stored refresh token', async () => {
+    const { client, fetchMock } = makeClient();
+    await expect(client.refreshToken()).rejects.toThrow();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it('clears storage when the refresh is rejected', async () => {
+    const storage = new InMemoryTokenStorage();
+    await storage.setRefreshToken('refresh-old');
+    const { client, fetchMock } = makeClient(storage);
+    fetchMock.mockResolvedValueOnce(jsonResponse({ detail: 'expired' }, false, 401));
+
+    await expect(client.refreshToken()).rejects.toThrow();
+    expect(await storage.getRefreshToken()).toBeNull();
+  });
+});
+
+describe('TokenAuthClient.logout', () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it('sends Bearer access + refresh in the body and clears storage', async () => {
+    const storage = new InMemoryTokenStorage();
+    await storage.setRefreshToken('refresh-1');
+    const { client, fetchMock } = makeClient(storage);
+    // seed an access token via a login
+    fetchMock.mockResolvedValueOnce(jsonResponse({ access: ACCESS, refresh: 'refresh-1', user: { id: 'u', email: 'e@e.co' } }));
+    await client.login('e@e.co', 'pw');
+    fetchMock.mockResolvedValueOnce(jsonResponse({}, true, 205));
+
+    await client.logout();
+
+    const [url, init] = call(fetchMock, 1);
+    expect(url).toBe('http://localhost:8001/api/v1/auth/logout/');
+    expect((init.headers as Record<string, string>)['Authorization']).toBe(`Bearer ${ACCESS}`);
+    expect(JSON.parse(init.body as string)).toEqual({ refresh: 'refresh-1' });
+    expect(await storage.getRefreshToken()).toBeNull();
+    expect(client.getAccessToken()).toBeNull();
+  });
+
+  it('clears storage even if the network call fails', async () => {
+    const storage = new InMemoryTokenStorage();
+    await storage.setRefreshToken('refresh-1');
+    const { client, fetchMock } = makeClient(storage);
+    fetchMock.mockRejectedValueOnce(new Error('network down'));
+
+    await client.logout();
+    expect(await storage.getRefreshToken()).toBeNull();
+  });
+});
+
+describe('TokenAuthClient.getCurrentUser', () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it('sends Bearer and normalizes the snake_case {user} envelope', async () => {
+    const { client, fetchMock } = makeClient();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        user: {
+          id: 'abc',
+          email: 't@x.co',
+          first_name: 'Test',
+          last_name: 'User',
+          is_email_verified: true,
+          created_at: '2026-01-01T00:00:00Z',
+          updated_at: '2026-01-02T00:00:00Z',
+        },
+      })
+    );
+
+    const user = await client.getCurrentUser(ACCESS);
+
+    const [url, init] = call(fetchMock);
+    expect(url).toBe('http://localhost:8001/api/v1/auth/me/');
+    expect((init.headers as Record<string, string>)['Authorization']).toBe(`Bearer ${ACCESS}`);
+    expect(user.id).toBe('abc');
+    expect(user.firstName).toBe('Test');
+    expect(user.lastName).toBe('User');
+    expect(user.isEmailVerified).toBe(true);
+  });
+});

package/src/client/auth-client.ts

@@ -13,6 +13,7 @@ import type {
 import { isTokenExpired, getTokenExpiresAt, shouldRefreshToken } from '../utils';
 import { extractApiError, setAccessToken as setModuleAccessToken } from './functions';
 import { deleteCookie } from '../utils/cookies';
+import type { AuthBackend, RegisterPayload } from './backend';
 
 /**
  * sessionStorage key set by logout to suppress any subsequent
@@ -41,7 +42,7 @@ function hasLoggedOutFlag(): boolean {
   }
 }
 
-export class AuthClient {
+export class AuthClient implements AuthBackend {
   private config: Required<AuthConfig>;
   private session: Session | null = null;
   private refreshTimer: NodeJS.Timeout | null = null;
@@ -118,14 +119,7 @@ export class AuthClient {
    * backend returns a user in the response, use it directly; otherwise fall
    * back to /me/ (same pattern as login).
    */
-  async register(payload: {
-    email: string;
-    password: string;
-    passwordConfirm: string;
-    name?: string;
-    firstName?: string;
-    lastName?: string;
-  }): Promise<Session> {
+  async register(payload: RegisterPayload): Promise<Session> {
     // Derive first/last from `name` if the caller used it.
     const rawName = payload.name?.trim() ?? '';
     const [firstFromName, ...rest] = rawName ? rawName.split(/\s+/) : [];
@@ -508,6 +502,15 @@ export class AuthClient {
     }
   }
 
+  /**
+   * AuthBackend contract: restore a persisted session on mount. For the
+   * Django client this is the refresh-token-cookie bootstrap; aliased so the
+   * provider can call a backend-neutral name.
+   */
+  restoreSession(): Promise<Session | null> {
+    return this.bootstrapFromCookies();
+  }
+
   /**
    * Get current session
    */

package/src/client/auth-context.tsx

@@ -15,6 +15,7 @@ import {
 } from 'react';
 import { AuthClient } from './auth-client';
 import { setOnSessionExpired } from './functions';
+import type { AuthBackend } from './backend';
 import type { AuthConfig, AuthState, Session, AuthUser } from '../types';
 
 interface AuthContextValue extends AuthState {
@@ -45,16 +46,33 @@ const AuthContext = createContext<AuthContextValue | undefined>(undefined);
 
 interface AuthProviderProps {
   children: ReactNode;
-  config: AuthConfig;
+  /**
+   * Django/JWT configuration. Used to construct the default {@link AuthClient}.
+   * Optional when an explicit `backend` is supplied instead.
+   */
+  config?: AuthConfig;
+  /**
+   * An explicit {@link AuthBackend} to drive auth state. When provided, the
+   * provider uses it directly and ignores `config` (no AuthClient is created).
+   * This is how backendless apps inject a mock/offline backend.
+   */
+  backend?: AuthBackend;
   initialSession?: Session | null;
 }
 
 export function AuthProvider({
   children,
   config,
+  backend,
   initialSession,
 }: AuthProviderProps) {
-  const [authClient] = useState(() => new AuthClient(config));
+  const [authClient] = useState<AuthBackend>(() => {
+    if (backend) return backend;
+    if (!config) {
+      throw new Error('AuthProvider requires either a `config` or a `backend` prop');
+    }
+    return new AuthClient(config);
+  });
   const [state, setState] = useState<AuthState>(() => ({
     session: initialSession || null,
     isLoading: !initialSession,
@@ -90,7 +108,7 @@ export function AuthProvider({
     }
 
     authClient
-      .bootstrapFromCookies()
+      .restoreSession()
       .then((session) => {
         if (cancelled) return;
         setState({
@@ -111,12 +129,12 @@ export function AuthProvider({
 
   // Keep refs current on every render so the stable handleExpired closure
   // below always reads the latest config values without being in deps.
-  const loginPathRef = useRef(config.loginPath);
-  const callbackParamRef = useRef(config.callbackParam ?? 'callbackUrl');
-  const onSessionExpiredRef = useRef(config.onSessionExpired);
-  loginPathRef.current = config.loginPath;
-  callbackParamRef.current = config.callbackParam ?? 'callbackUrl';
-  onSessionExpiredRef.current = config.onSessionExpired;
+  const loginPathRef = useRef(config?.loginPath);
+  const callbackParamRef = useRef(config?.callbackParam ?? 'callbackUrl');
+  const onSessionExpiredRef = useRef(config?.onSessionExpired);
+  loginPathRef.current = config?.loginPath;
+  callbackParamRef.current = config?.callbackParam ?? 'callbackUrl';
+  onSessionExpiredRef.current = config?.onSessionExpired;
 
   // Session expiration handler — covers both AuthClient timer and authFetch 401.
   // Depends only on authClient (a useState singleton that never changes after
@@ -143,11 +161,15 @@ export function AuthProvider({
     };
 
     // Wire AuthClient's internal expiry calls and the functional API (FetchWrapper).
-    config.onSessionExpired = handleExpired;
+    // The Django client reads expiry via config; non-config backends (e.g. mock)
+    // accept the handler through the optional setOnSessionExpired method.
+    if (config) config.onSessionExpired = handleExpired;
+    authClient.setOnSessionExpired?.(handleExpired);
     setOnSessionExpired(handleExpired);
 
     return () => {
       setOnSessionExpired(null);
+      authClient.setOnSessionExpired?.(null);
       authClient.destroy();
     };
   // eslint-disable-next-line react-hooks/exhaustive-deps

package/src/client/backend.ts

@@ -0,0 +1,58 @@
+/**
+ * Backend-agnostic authentication contract.
+ *
+ * AuthProvider drives all of its state from one object satisfying this
+ * interface. The Django/JWT implementation is {@link AuthClient}; backendless
+ * apps (demos, offline-first, Storybook) can inject any other implementation
+ * — e.g. `createMockAuthBackend` — without the provider knowing the difference.
+ *
+ * The method set is exactly what AuthProvider needs; nothing here is
+ * Django-specific.
+ */
+
+import type { Session, AuthUser } from '../types';
+
+export interface RegisterPayload {
+  email: string;
+  password: string;
+  passwordConfirm: string;
+  name?: string;
+  firstName?: string;
+  lastName?: string;
+}
+
+export interface AuthBackend {
+  /** Authenticate and open a session. Rejects on bad credentials. */
+  login(email: string, password: string): Promise<Session>;
+  /** End the session and clear any persisted state. */
+  logout(): Promise<void>;
+  /** Create an account and open a session. */
+  register(payload: RegisterPayload): Promise<Session>;
+  /** Re-fetch the current user (e.g. after a profile change). */
+  getCurrentUser(): Promise<AuthUser>;
+  /** Return a valid access token, refreshing if needed; null if unauthenticated. */
+  getAccessToken(): Promise<string | null>;
+  /** Synchronous current session, or null. May clear+return null if expired. */
+  getSession(): Session | null;
+  /** Adopt an externally-acquired session (SSR/hydration/OAuth callback). */
+  setSession(session: Session): void;
+  /**
+   * Restore a persisted session on mount. Web/Django reads the refresh-token
+   * cookie; native/mock backends read secure storage. Returns null when there
+   * is nothing to restore.
+   */
+  restoreSession(): Promise<Session | null>;
+  /** Begin an OAuth flow; returns the authorization URL to redirect to. */
+  signInWithGoogle(redirectTo?: string): Promise<string>;
+  /** Complete an OAuth flow by exchanging the code+state for a session. */
+  completeGoogleCallback(code: string, state: string): Promise<Session>;
+  /**
+   * Optional. Register the provider's session-expiry handler. The Django
+   * AuthClient wires this through AuthConfig.onSessionExpired instead, so it
+   * is optional — backends that don't take an AuthConfig (e.g. the mock) use
+   * this to notify the provider when a session goes away out-of-band.
+   */
+  setOnSessionExpired?(cb: (() => void) | null): void;
+  /** Release timers/listeners. Called on AuthProvider unmount. */
+  destroy(): void;
+}

package/src/client/functions.ts

@@ -12,6 +12,9 @@
  */
 
 import { deleteCookie } from '../utils/cookies';
+// Local binding for internal use; also re-exported below to preserve this
+// module's public surface.
+import { extractApiError } from '../utils/api-error';
 import { decodeToken } from '../utils/token';
 
 // --- Types ---
@@ -210,58 +213,10 @@ function _syncAuthCookie(token: string | null): void {
 
 const AUTH_TIMEOUT_MS = 15_000;
 
-/**
- * Extract a human-readable message from a Django REST Framework error response body.
- *
- * Handles the shapes we've seen in practice:
- *   { detail: "..." }                                 → the string
- *   { detail: ["...", "..."] }                        → first string
- *   { detail: { token: ["Invalid..."] } }             → first nested string
- *   { email: ["already exists"] }                     → first field-level string
- *   { non_field_errors: ["..."] }                     → first field-level string
- *   { error: "CODE", detail: { field: ["..."] } }     → first nested string
- *
- * @internal Shared with AuthClient; still considered implementation detail
- * of the auth package. Do not rely on from outside `@startsimpli/auth`.
- */
-export function extractApiError(d: Record<string, unknown>, fallback: string): string {
-  const pluck = (val: unknown): string | null => {
-    if (typeof val === 'string') return val
-    if (Array.isArray(val) && val.length > 0) {
-      for (const item of val) {
-        const s = pluck(item)
-        if (s) return s
-      }
-    }
-    if (val && typeof val === 'object') {
-      for (const v of Object.values(val as Record<string, unknown>)) {
-        const s = pluck(v)
-        if (s) return s
-      }
-    }
-    return null
-  }
-
-  // Standard DRF: { detail: "..." }
-  const fromDetail = pluck(d.detail)
-  if (fromDetail) return fromDetail
-  // Some backend shapes use `error` as the human-readable message (e.g.
-  // our Django auth errors: { "error": "No active account...", "code": "unauthorized" }).
-  // Prefer this over field-level probing so we don't accidentally return a
-  // code like "unauthorized" from a sibling field.
-  const fromError = pluck(d.error)
-  if (fromError) return fromError
-  // Field-level: { email: ["already exists"] } or { non_field_errors: ["..."] }
-  // Skip known meta/code fields so `{ code: "unauthorized" }` doesn't leak
-  // an internal identifier as a user-facing message.
-  const META_KEYS = new Set(['detail', 'error', 'code', 'statusCode', 'status', 'timestamp'])
-  for (const [key, val] of Object.entries(d)) {
-    if (META_KEYS.has(key)) continue
-    const s = pluck(val)
-    if (s) return s
-  }
-  return fallback
-}
+// extractApiError moved to ../utils/api-error (DOM-free, shared with the
+// platform-neutral token-auth core). Imported above for internal use and
+// re-exported here to preserve this module's public surface (e.g. AuthClient).
+export { extractApiError }
 
 function fetchWithTimeout(url: string, options: RequestInit): Promise<Response> {
   const controller = new AbortController();

package/src/client/index.ts

@@ -1,4 +1,19 @@
 export { AuthClient } from './auth-client';
+export type { AuthBackend, RegisterPayload } from './backend';
+export {
+  createMockAuthBackend,
+  type MockAuthBackend,
+  type MockAuthBackendOptions,
+  type MockAccount,
+} from './mock-backend';
+export {
+  createMemorySessionStorage,
+  createWebSessionStorage,
+  createRememberAwareSessionStorage,
+  SESSION_STORAGE_KEY,
+  type SessionStorage,
+} from './session-storage';
+export { createSecureSessionStorage } from './secure-session-storage';
 export { AuthProvider, useAuthContext } from './auth-context';
 export { useAuth, useRequireAuth, type UseAuthReturn, type UseRequireAuthReturn, type UseRequireAuthOptions } from './use-auth';
 export { usePermissions, type UsePermissionsReturn } from './use-permissions';