@startsimpli/auth 0.4.6 → 0.4.8

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@startsimpli/auth",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Shared authentication package for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./client": "./src/client/index.ts",
+    "./components": "./src/components/index.ts",
     "./server": "./src/server/index.ts",
     "./types": "./src/types/index.ts",
     "./email": "./src/email/index.ts"

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

@@ -4,7 +4,7 @@ import { AuthClient } from '../client/auth-client';
 // Helpers
 function makeToken(exp: number): string {
   const header = btoa(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
-  const body = btoa(JSON.stringify({ token_type: 'access', exp, iat: exp - 3600, jti: 'test', user_id: '123' }));
+  const body = btoa(JSON.stringify({ tokenType: 'access', exp, iat: exp - 3600, jti: 'test', userId: '123' }));
   return `${header}.${body}.signature`;
 }
 

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

@@ -36,23 +36,8 @@ function makeJwt(payload: object): string {
   return `${encode({ alg: 'HS256' })}.${encode(payload)}.sig`;
 }
 
-const VALID_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 3600, user_id: '1' });
-const REFRESHED_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 7200, user_id: '1' });
-
-// Stub the CSRF token helper so refreshAccessToken() doesn't fail
-vi.mock('../utils/cookies', () => ({
-  getCsrfToken: () => 'test-csrf',
-  setCsrfToken: vi.fn(),
-}));
-
-// Stub fetchCsrfToken (called inside refreshAccessToken)
-vi.mock('../client/functions', async (importOriginal) => {
-  const original = await importOriginal<typeof import('../client/functions')>();
-  return {
-    ...original,
-    fetchCsrfToken: vi.fn().mockResolvedValue(undefined),
-  };
-});
+const VALID_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 3600, userId: '1' });
+const REFRESHED_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 7200, userId: '1' });
 
 describe('authFetch — concurrent 401 refresh atomicity (uhxu)', () => {
   beforeEach(() => {

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

@@ -72,6 +72,7 @@ const {
   setAccessToken,
   getAccessToken,
   setOnSessionExpired,
+  notifySessionExpired,
   setRememberMe,
 } = await import('../client/functions');
 
@@ -83,7 +84,7 @@ function makeJwt(payload: object): string {
   return `${encode({ alg: 'HS256' })}.${encode(payload)}.sig`;
 }
 
-const VALID_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 3600, user_id: '1' });
+const VALID_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 3600, userId: '1' });
 
 describe('CSRF not required for signin/register (endpoints are @csrf_exempt)', () => {
   beforeEach(() => {
@@ -212,6 +213,46 @@ describe('authFetch session expiration on unrecoverable 401', () => {
   });
 });
 
+describe('notifySessionExpired cooldown', () => {
+  beforeEach(() => {
+    setOnSessionExpired(null);
+  });
+
+  afterEach(() => {
+    setOnSessionExpired(null);
+  });
+
+  it('fires the registered callback at most once per cooldown window', () => {
+    const onExpired = vi.fn();
+    setOnSessionExpired(onExpired);
+
+    notifySessionExpired();
+    notifySessionExpired();
+    notifySessionExpired();
+    notifySessionExpired();
+    notifySessionExpired();
+
+    expect(onExpired).toHaveBeenCalledTimes(1);
+  });
+
+  it('no-ops when no callback is registered', () => {
+    expect(() => notifySessionExpired()).not.toThrow();
+  });
+
+  it('resets the cooldown when a new callback is registered', () => {
+    const first = vi.fn();
+    setOnSessionExpired(first);
+    notifySessionExpired();
+    expect(first).toHaveBeenCalledTimes(1);
+
+    // re-register: cooldown resets, so next notify should fire the new callback
+    const second = vi.fn();
+    setOnSessionExpired(second);
+    notifySessionExpired();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe('signOut cookie cleanup', () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -258,20 +299,41 @@ describe('refreshAccessToken clears session on failure', () => {
   });
 
   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({
+    mockFetch.mockImplementation(() =>
+      Promise.resolve({
         ok: false,
         status: 401,
         json: async () => ({ detail: 'Token expired' }),
-      });
-    });
+      })
+    );
 
     const result = await refreshAccessToken();
 
     expect(result).toBeNull();
     expect(getAccessToken()).toBeNull();
   });
+
+  it('does not fetch the CSRF endpoint or send X-CSRFToken', async () => {
+    mockFetch.mockImplementation(() =>
+      Promise.resolve({
+        ok: true,
+        status: 200,
+        json: async () => ({ access: VALID_TOKEN }),
+      })
+    );
+
+    await refreshAccessToken();
+
+    const csrfCall = mockFetch.mock.calls.find(
+      (c: unknown[]) => typeof c[0] === 'string' && (c[0] as string).includes('/csrf/')
+    );
+    expect(csrfCall).toBeUndefined();
+
+    const refreshCall = mockFetch.mock.calls.find(
+      (c: unknown[]) => typeof c[0] === 'string' && (c[0] as string).includes('/auth/token/refresh/')
+    );
+    expect(refreshCall).toBeDefined();
+    const headers = refreshCall![1]?.headers;
+    expect(headers['X-CSRFToken']).toBeUndefined();
+  });
 });

package/src/__tests__/token.test.ts

@@ -10,16 +10,16 @@ describe('Token utilities', () => {
   describe('decodeToken', () => {
     it('should decode valid JWT token', () => {
       const token =
-        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzM5MjI3MjAwLCJpYXQiOjE3MzkxNDA4MDAsImp0aSI6InRlc3QtanRpIiwidXNlcl9pZCI6IjEyMzQ1In0.test-signature';
+        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlblR5cGUiOiJhY2Nlc3MiLCJleHAiOjE3MzkyMjcyMDAsImlhdCI6MTczOTE0MDgwMCwianRpIjoidGVzdC1qdGkiLCJ1c2VySWQiOiIxMjM0NSJ9.test-signature';
 
       const payload = decodeToken(token);
 
       expect(payload).toEqual({
-        token_type: 'access',
+        tokenType: 'access',
         exp: 1739227200,
         iat: 1739140800,
         jti: 'test-jti',
-        user_id: '12345',
+        userId: '12345',
       });
     });
 

package/src/client/functions.ts

@@ -2,11 +2,16 @@
  * Functional auth API for Django backend
  *
  * Stateless functions for authentication flows: sign in, register, OAuth, token refresh, etc.
- * Uses fetch (browser/Node) and getCsrfToken from shared utils.
- * No Next.js dependency.
+ * Uses fetch (browser/Node). No Next.js dependency.
+ *
+ * CSRF note: the Django auth endpoints (signin, register, token/refresh, logout,
+ * OAuth) are all @csrf_exempt or JWT-authenticated. The frontend does not send
+ * X-CSRFToken headers and does not fetch /auth/csrf/ — any CSRF plumbing here
+ * would be dead weight (and previously caused refresh to fail whenever the CSRF
+ * endpoint was flaky).
  */
 
-import { getCsrfToken, deleteCookie } from '../utils/cookies';
+import { deleteCookie } from '../utils/cookies';
 import { decodeToken } from '../utils/token';
 
 // --- Types ---
@@ -28,10 +33,27 @@ export interface AuthUser {
 export type OnSessionExpiredCallback = () => void;
 
 let _onSessionExpired: OnSessionExpiredCallback | null = null;
+let _sessionExpiredFiredAt = 0;
+const SESSION_EXPIRED_COOLDOWN_MS = 5000;
 
 /** Register a callback for unrecoverable 401s (typically set by AuthProvider). */
 export function setOnSessionExpired(cb: OnSessionExpiredCallback | null): void {
   _onSessionExpired = cb;
+  if (cb !== null) _sessionExpiredFiredAt = 0;
+}
+
+/**
+ * Fire the registered session-expired callback at most once per cooldown window.
+ * Exposed so non-authFetch callers (e.g. the @startsimpli/api FetchWrapper) can
+ * route 401-after-refresh through the same sink that authFetch uses, instead of
+ * each caller wiring up its own redirect.
+ */
+export function notifySessionExpired(): void {
+  if (!_onSessionExpired) return;
+  const now = Date.now();
+  if (now - _sessionExpiredFiredAt < SESSION_EXPIRED_COOLDOWN_MS) return;
+  _sessionExpiredFiredAt = now;
+  _onSessionExpired();
 }
 
 // --- Endpoint paths (Django backend defaults) ---
@@ -431,43 +453,12 @@ export async function completeGoogleOAuth(code: string, state: string) {
   return parsed;
 }
 
-async function fetchCsrfToken(): Promise<void> {
-  if (getCsrfToken()) return;
-  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) {
-    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',
     headers: {
       'Content-Type': 'application/json',
-      'X-CSRFToken': csrfToken,
     },
     credentials: 'include',
   });
@@ -512,7 +503,6 @@ export async function getMe(): Promise<AuthUser | null> {
 }
 
 export async function signOut(): Promise<void> {
-  const csrfToken = getCsrfToken();
   const token = getAccessToken();
 
   try {
@@ -520,7 +510,6 @@ export async function signOut(): Promise<void> {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
-        ...(csrfToken ? { 'X-CSRFToken': csrfToken } : {}),
         ...(token ? { Authorization: `Bearer ${token}` } : {}),
       },
       credentials: 'include',
@@ -583,7 +572,7 @@ export async function authFetch(
     if (!refreshed || retryResponse.status === 401) {
       // Refresh failed or retried request still unauthorized — session is dead.
       setAccessToken(null);
-      _onSessionExpired?.();
+      notifySessionExpired();
     }
 
     return retryResponse;

package/src/components/google-sign-in-button.tsx

@@ -0,0 +1,78 @@
+'use client'
+
+import { useState } from 'react'
+import { initiateGoogleOAuth } from '../client/functions'
+
+export interface GoogleSignInButtonProps {
+  /** Path for the OAuth callback page (default: "/auth/callback") */
+  callbackPath?: string
+  /** URL to redirect to after successful auth */
+  redirectTo?: string
+  /** Error handler */
+  onError?: (message: string) => void
+  /** Button text (default: "Continue with Google") */
+  children?: React.ReactNode
+  /** Additional class names */
+  className?: string
+  /** Disabled state */
+  disabled?: boolean
+}
+
+/**
+ * Google Sign-In button that handles the full OAuth initiate flow:
+ * 1. Calls backend to get authorization URL with PKCE
+ * 2. Stores state nonce in sessionStorage for CSRF protection
+ * 3. Redirects to Google consent screen
+ */
+export function GoogleSignInButton({
+  callbackPath = '/auth/callback',
+  redirectTo,
+  onError,
+  children,
+  className,
+  disabled,
+}: GoogleSignInButtonProps) {
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleClick = async () => {
+    setIsLoading(true)
+    try {
+      // Use a clean callback URL with no query params — Google requires exact redirect_uri match
+      const redirectUri = new URL(callbackPath, window.location.origin).toString()
+
+      const data = await initiateGoogleOAuth(redirectUri)
+      if (!data?.authorization_url) {
+        throw new Error('Missing authorization URL from server')
+      }
+
+      // Store state nonce for CSRF validation on the callback page
+      const authUrlParams = new URL(data.authorization_url).searchParams
+      const stateNonce = authUrlParams.get('state')
+      if (stateNonce) {
+        sessionStorage.setItem('oauth_state_nonce', stateNonce)
+      }
+
+      // Store post-auth redirect separately (not in the redirect_uri)
+      if (redirectTo) {
+        sessionStorage.setItem('oauth_redirect_to', redirectTo)
+      }
+
+      window.location.href = data.authorization_url
+    } catch (err) {
+      setIsLoading(false)
+      const message = err instanceof Error ? err.message : 'Failed to initiate Google sign-in'
+      onError?.(message)
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      disabled={disabled || isLoading}
+      className={className}
+    >
+      {children ?? 'Continue with Google'}
+    </button>
+  )
+}

package/src/components/index.ts

@@ -0,0 +1,4 @@
+export { GoogleSignInButton, type GoogleSignInButtonProps } from './google-sign-in-button'
+export { OAuthCallback, type OAuthCallbackProps } from './oauth-callback'
+export { useOAuthCallback, type UseOAuthCallbackOptions, type UseOAuthCallbackReturn, type OAuthCallbackResult } from './use-oauth-callback'
+export { OAuthConnectionCard, type OAuthConnectionCardProps } from './oauth-connection-card'

package/src/components/oauth-callback.tsx

@@ -0,0 +1,95 @@
+'use client'
+
+import type { AuthUser } from '../types'
+import { useOAuthCallback, type OAuthCallbackResult } from './use-oauth-callback'
+
+export interface OAuthCallbackProps {
+  /** Code from OAuth redirect URL params */
+  code: string | null
+  /** State from OAuth redirect URL params */
+  state: string | null
+  /** Called on successful authentication. redirectTo is the path stored by GoogleSignInButton. */
+  onSuccess: (result: OAuthCallbackResult & { redirectTo: string }) => void
+  /** Called on error */
+  onError?: (message: string) => void
+  /** Path to redirect to on "Back to Sign In" (default: "/auth/signin") */
+  signInPath?: string
+  /** Custom loading content */
+  loadingContent?: React.ReactNode
+  /** Custom error content renderer */
+  renderError?: (error: string, signInPath: string) => React.ReactNode
+}
+
+/**
+ * OAuth callback handler component with built-in loading/error UI.
+ *
+ * Handles the full callback flow: state validation, token exchange, user fetch.
+ * Drop into your /auth/callback page:
+ *
+ * ```tsx
+ * const searchParams = useSearchParams()
+ * <OAuthCallback
+ *   code={searchParams.get('code')}
+ *   state={searchParams.get('state')}
+ *   onSuccess={({ access, user }) => {
+ *     setAccessToken(access); setUser(user); router.replace('/dashboard')
+ *   }}
+ * />
+ * ```
+ */
+export function OAuthCallback({
+  code,
+  state,
+  onSuccess,
+  onError,
+  signInPath = '/auth/signin',
+  loadingContent,
+  renderError,
+}: OAuthCallbackProps) {
+  const { error, isProcessing, redirectTo } = useOAuthCallback(
+    { code, state },
+    {
+      onSuccess: (result) => onSuccess({ ...result, redirectTo }),
+      onError,
+    },
+  )
+
+  if (error) {
+    if (renderError) {
+      return <>{renderError(error, signInPath)}</>
+    }
+
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-gradient-to-br from-slate-50 to-slate-100 p-4">
+        <div className="w-full max-w-md rounded-2xl bg-white p-8 shadow-xl shadow-slate-200/50 ring-1 ring-slate-200 text-center">
+          <h1 className="text-2xl font-bold text-slate-900 mb-2">Authentication failed</h1>
+          <p className="text-slate-600 mb-6">{error}</p>
+          <a
+            href={signInPath}
+            className="inline-block w-full rounded-lg bg-indigo-600 px-4 py-2.5 text-sm font-semibold text-white shadow-sm hover:bg-indigo-500"
+          >
+            Back to Sign In
+          </a>
+        </div>
+      </div>
+    )
+  }
+
+  if (isProcessing) {
+    if (loadingContent) {
+      return <>{loadingContent}</>
+    }
+
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-gradient-to-br from-slate-50 to-slate-100 p-4">
+        <div className="w-full max-w-md rounded-2xl bg-white p-8 shadow-xl shadow-slate-200/50 ring-1 ring-slate-200 text-center">
+          <div className="mx-auto mb-4 h-12 w-12 animate-spin rounded-full border-4 border-indigo-200 border-t-indigo-600" />
+          <h1 className="text-xl font-semibold text-slate-900">Finishing sign in...</h1>
+          <p className="text-slate-600 mt-2">This will only take a moment.</p>
+        </div>
+      </div>
+    )
+  }
+
+  return null
+}

package/src/components/oauth-connection-card.tsx

@@ -0,0 +1,117 @@
+'use client'
+
+import { useState, useCallback } from 'react'
+
+export interface OAuthConnectionCardProps {
+  providerName: string
+  providerIcon?: React.ReactNode
+  description?: string
+  connected: boolean
+  accountLabel?: string
+  lastSync?: string
+  connectUrl?: string
+  onConnect?: () => void | Promise<void>
+  onDisconnect?: () => void | Promise<void>
+}
+
+/**
+ * Card showing OAuth service connection status with connect/disconnect actions.
+ * Used for email (Gmail/Outlook), calendar, CRM integrations.
+ */
+export function OAuthConnectionCard({
+  providerName,
+  providerIcon,
+  description,
+  connected,
+  accountLabel,
+  lastSync,
+  connectUrl,
+  onConnect,
+  onDisconnect,
+}: OAuthConnectionCardProps) {
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleConnect = useCallback(async () => {
+    if (connectUrl) {
+      window.location.href = connectUrl
+      return
+    }
+    if (onConnect) {
+      setIsLoading(true)
+      try {
+        await onConnect()
+      } finally {
+        setIsLoading(false)
+      }
+    }
+  }, [connectUrl, onConnect])
+
+  const handleDisconnect = useCallback(async () => {
+    if (onDisconnect) {
+      setIsLoading(true)
+      try {
+        await onDisconnect()
+      } finally {
+        setIsLoading(false)
+      }
+    }
+  }, [onDisconnect])
+
+  return (
+    <div className="rounded-lg border border-gray-200 bg-white p-5">
+      <div className="flex items-start gap-4">
+        {providerIcon && (
+          <div className="flex-shrink-0 w-10 h-10 rounded-lg bg-gray-100 flex items-center justify-center">
+            {providerIcon}
+          </div>
+        )}
+        <div className="flex-1 min-w-0">
+          <div className="flex items-center justify-between mb-1">
+            <h3 className="font-medium text-gray-900">{providerName}</h3>
+            <span
+              className={`text-xs px-2 py-0.5 rounded-full font-medium ${
+                connected
+                  ? 'bg-green-100 text-green-700'
+                  : 'bg-gray-100 text-gray-500'
+              }`}
+            >
+              {connected ? 'Connected' : 'Not connected'}
+            </span>
+          </div>
+
+          {description && (
+            <p className="text-sm text-gray-600 mb-2">{description}</p>
+          )}
+
+          {connected && accountLabel && (
+            <p className="text-sm text-gray-700 mb-1">{accountLabel}</p>
+          )}
+
+          {connected && lastSync && (
+            <p className="text-xs text-gray-400 mb-2">Last sync: {lastSync}</p>
+          )}
+
+          <div className="mt-3">
+            {connected ? (
+              <button
+                onClick={handleDisconnect}
+                disabled={isLoading}
+                className="px-3 py-1.5 text-sm font-medium text-red-700 bg-red-50 hover:bg-red-100 rounded-md disabled:opacity-50 transition-colors"
+              >
+                {isLoading ? 'Disconnecting...' : 'Disconnect'}
+              </button>
+            ) : (
+              <button
+                onClick={handleConnect}
+                disabled={isLoading}
+                className="px-3 py-1.5 text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 rounded-md disabled:opacity-50 transition-colors"
+              >
+                {isLoading ? 'Connecting...' : `Connect ${providerName}`}
+              </button>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/use-oauth-callback.ts

@@ -0,0 +1,123 @@
+'use client'
+
+import { useEffect, useRef, useState } from 'react'
+import { completeGoogleOAuth, getMe } from '../client/functions'
+import type { AuthUser } from '../types'
+
+export interface OAuthCallbackResult {
+  /** Access token from successful auth */
+  access: string
+  /** Authenticated user */
+  user: AuthUser
+}
+
+export interface UseOAuthCallbackOptions {
+  /** Called on successful authentication */
+  onSuccess: (result: OAuthCallbackResult) => void
+  /** Called on error */
+  onError?: (message: string) => void
+}
+
+export interface UseOAuthCallbackReturn {
+  /** Error message if callback failed */
+  error: string
+  /** Whether the callback is still processing */
+  isProcessing: boolean
+  /** Post-auth redirect path stored by GoogleSignInButton (default: '/dashboard') */
+  redirectTo: string
+}
+
+/**
+ * Hook that handles the OAuth callback flow:
+ * 1. Reads code + state from URL search params
+ * 2. Validates state nonce against sessionStorage (CSRF protection)
+ * 3. Exchanges code for tokens via backend
+ * 4. Fetches user if not returned with tokens
+ * 5. Calls onSuccess with access token + user
+ *
+ * Usage in a Next.js callback page:
+ * ```tsx
+ * const searchParams = useSearchParams()
+ * const { error, isProcessing } = useOAuthCallback({
+ *   code: searchParams.get('code'),
+ *   state: searchParams.get('state'),
+ *   onSuccess: ({ access, user }) => {
+ *     setAccessToken(access)
+ *     setUser(user)
+ *     router.replace('/dashboard')
+ *   },
+ * })
+ * ```
+ */
+export function useOAuthCallback(
+  params: {
+    code: string | null
+    state: string | null
+  },
+  options: UseOAuthCallbackOptions,
+): UseOAuthCallbackReturn {
+  const [error, setError] = useState('')
+  const [isProcessing, setIsProcessing] = useState(true)
+  const [redirectTo] = useState(() => {
+    if (typeof window === 'undefined') return '/dashboard'
+    const stored = sessionStorage.getItem('oauth_redirect_to')
+    sessionStorage.removeItem('oauth_redirect_to')
+    return stored || '/dashboard'
+  })
+  const ranRef = useRef(false)
+
+  useEffect(() => {
+    // Prevent double-execution in React strict mode
+    if (ranRef.current) return
+    ranRef.current = true
+
+    const handleCallback = async () => {
+      const { code, state } = params
+      if (!code || !state) {
+        setError('Invalid OAuth callback — missing code or state')
+        setIsProcessing(false)
+        return
+      }
+
+      // CSRF check: validate state nonce against pre-auth sessionStorage value
+      const storedNonce = sessionStorage.getItem('oauth_state_nonce')
+      sessionStorage.removeItem('oauth_state_nonce')
+      if (!storedNonce || storedNonce !== state) {
+        setError('Invalid OAuth state — possible CSRF attempt')
+        setIsProcessing(false)
+        return
+      }
+
+      try {
+        const result = await completeGoogleOAuth(code, state)
+        const access = result?.access
+
+        if (!access) {
+          throw new Error('No access token returned')
+        }
+
+        let user = result?.user as AuthUser | undefined
+        if (!user) {
+          user = await getMe() as AuthUser | undefined
+        }
+
+        if (!user) {
+          throw new Error('Failed to retrieve user after authentication')
+        }
+
+        setIsProcessing(false)
+        options.onSuccess({ access, user })
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Authentication failed'
+        setError(message)
+        setIsProcessing(false)
+        options.onError?.(message)
+      }
+    }
+
+    handleCallback()
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  return { error, isProcessing, redirectTo }
+}

package/src/types/index.ts

@@ -58,11 +58,11 @@ export interface AuthUser {
  * JWT token payload structure
  */
 export interface TokenPayload {
-  token_type: 'access';
+  tokenType: 'access';
   exp: number;
   iat: number;
   jti: string;
-  user_id: string;
+  userId: string;
 }
 
 /**