feat: OAuth PKCE flow and external auth provider UI (#1547)

* feat: add OAuth PKCE flow and external auth provider UI

Implement OAuth authorization code flow with PKCE (RFC 7636) for
redirect-based authentication via Dex external connectors. Add login
page UI for external auth provider buttons with graceful fallback
when the provider discovery API is unavailable.

- PKCE utilities: code verifier, S256 challenge, state generation
- useOAuthFlow hook: initiates PKCE flow and redirects to Dex
- CallbackPage: handles authorization code exchange with CSRF validation
- useAuthProviders hook: fetches available providers with fallback
- Provider button and icon components (Google, GitHub, Microsoft)
- Auth divider component between password form and external providers
- /callback route added to App.tsx router
- MSW handler for /api/auth/providers (404 default for graceful degradation)
- 17 new tests covering PKCE, callback, and provider hooks

* fix: resolve eslint errors in auth components and callback page

- Split provider-icons.tsx to export only components (react-refresh rule)
- Move provider icon selection logic into ProviderIcon component
- Refactor CallbackPage to use useMemo for synchronous validation
  instead of setState inside useEffect

* fix: remove unused vi import from callback test

* fix: address CodeRabbit review feedback

- Return empty array on 404 from providers API (password-only fallback)
- Update test to assert empty data instead of isError on 404
- Surface error message to user when OAuth flow fails to start

* fix: move sessionStorage cleanup out of useMemo into useEffect

The validateCallbackParams function is called from useMemo which must
be pure. Move the sessionStorage.removeItem calls into the useEffect
that performs the code exchange.

* fix: use replace navigation to prevent stale callback URL in history

Use navigate with { replace: true } on both success and error paths
to prevent the callback URL (with spent authorization code) from
remaining in browser history.

* fix: add AbortController to cancel token exchange on unmount

Prevent state updates on unmounted component by aborting the fetch
request when the callback page unmounts during token exchange.

* fix: defer PKCE cleanup until terminal outcome

Keep PKCE verifier and state in sessionStorage until the token
exchange succeeds or fails terminally. Transient failures (network
errors) preserve the values so a page refresh can retry the flow.

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

frontend/src/App.tsx

@@ -7,11 +7,16 @@ import { PageErrorBoundary, RouteErrorBoundary } from '@/components/error-bounda
 import { AuthProvider, useAuth } from '@/contexts/auth-context'
 import { TenantProvider, useTenantContext } from '@/contexts/tenant-context'
 import { useTenants } from '@/hooks/use-tenants'
+import { useAuthProviders, type AuthProvider as AuthProviderType } from '@/hooks/use-auth-providers'
+import { useOAuthFlow } from '@/hooks/use-oauth-flow'
 import { ApiClientProvider } from '@/api/context'
 import { ProtectedRoute, PlatformOnlyRoute, AdminOnlyRoute, TenantSubdomainEnforcer } from '@/components/routing'
 import { FeatureGuard } from '@/components/feature-guard'
 import { AppShell } from '@/components/layout/app-shell'
 import { TooltipProvider } from '@/components/ui/tooltip'
+import { CallbackPage } from '@/pages/callback'
+import { ProviderButton } from '@/components/auth/provider-button'
+import { AuthDivider } from '@/components/auth/auth-divider'
 import { AccountsPage, AccountDetailPage } from '@/features/accounts'
 import { PaymentsPage, PaymentDetailPage } from '@/features/payments'
 import { LedgerPage, BookingLogDetailPage } from '@/features/ledger'
@@ -64,6 +69,10 @@ function LoginPage() {
   const [password, setPassword] = useState('')
   const [error, setError] = useState('')
   const [loading, setLoading] = useState(false)
+  const { data: providers } = useAuthProviders()
+  const { startFlow } = useOAuthFlow()
+
+  const externalProviders = providers?.filter((p: AuthProviderType) => p.type === 'oidc') ?? []
 
   const handleDexLogin = useCallback(
     async (e: FormEvent) => {
@@ -182,6 +191,22 @@ function LoginPage() {
           </form>
         )}
 
+        {/* External auth provider buttons */}
+        {externalProviders.length > 0 && (
+          <>
+            {(import.meta.env.VITE_DEMO_MODE === 'true' || !import.meta.env.DEV) && <AuthDivider />}
+            <div className="space-y-2">
+              {externalProviders.map((provider: AuthProviderType) => (
+                <ProviderButton
+                  key={provider.id}
+                  provider={provider}
+                  onClick={() => startFlow(provider.id)}
+                />
+              ))}
+            </div>
+          </>
+        )}
+
         {/* Dev-only fake JWT buttons */}
         {import.meta.env.DEV && (
           <div className="space-y-2">
@@ -397,6 +422,7 @@ function AuthenticatedApp() {
           <BrowserRouter>
             <Routes>
               <Route path="/login" element={<LoginPage />} />
+              <Route path="/callback" element={<CallbackPage />} />
               <Route
                 path="/*"
                 element={

frontend/src/components/auth/auth-divider.tsx

@@ -0,0 +1,12 @@
+export function AuthDivider() {
+  return (
+    <div className="relative">
+      <div className="absolute inset-0 flex items-center">
+        <span className="w-full border-t border-muted" />
+      </div>
+      <div className="relative flex justify-center text-xs uppercase">
+        <span className="bg-background px-2 text-muted-foreground">Or continue with</span>
+      </div>
+    </div>
+  )
+}

frontend/src/components/auth/provider-button.tsx

@@ -0,0 +1,48 @@
+import { useState } from 'react'
+import { Button } from '@/components/ui/button'
+import { GoogleIcon, GitHubIcon, MicrosoftIcon, DefaultProviderIcon } from './provider-icons'
+import type { AuthProvider } from '@/hooks/use-auth-providers'
+
+interface ProviderButtonProps {
+  provider: AuthProvider
+  onClick: () => Promise<void>
+}
+
+function ProviderIcon({ providerId }: { providerId: string }) {
+  const normalized = providerId.toLowerCase()
+  if (normalized.includes('google')) return <GoogleIcon className="size-4" />
+  if (normalized.includes('github')) return <GitHubIcon className="size-4" />
+  if (normalized.includes('microsoft')) return <MicrosoftIcon className="size-4" />
+  return <DefaultProviderIcon className="size-4" />
+}
+
+export function ProviderButton({ provider, onClick }: ProviderButtonProps) {
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  const handleClick = async () => {
+    setLoading(true)
+    setError(null)
+    try {
+      await onClick()
+    } catch {
+      setError('Failed to start sign-in. Please try again.')
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div>
+      <Button
+        variant="outline"
+        className="w-full"
+        disabled={loading}
+        onClick={() => void handleClick()}
+      >
+        <ProviderIcon providerId={provider.id} />
+        {loading ? 'Redirecting...' : `Sign in with ${provider.displayName}`}
+      </Button>
+      {error && <p className="mt-1 text-xs text-destructive">{error}</p>}
+    </div>
+  )
+}

frontend/src/components/auth/provider-icons.tsx

@@ -0,0 +1,36 @@
+export function GoogleIcon({ className }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" fill="currentColor">
+      <path d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92a5.06 5.06 0 0 1-2.2 3.32v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.1z" />
+      <path d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z" />
+      <path d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z" />
+      <path d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z" />
+    </svg>
+  )
+}
+
+export function GitHubIcon({ className }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" fill="currentColor">
+      <path d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0 1 12 6.844a9.59 9.59 0 0 1 2.504.337c1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.02 10.02 0 0 0 22 12.017C22 6.484 17.522 2 12 2z" />
+    </svg>
+  )
+}
+
+export function MicrosoftIcon({ className }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" fill="currentColor">
+      <path d="M3 3h8.5v8.5H3V3zm9.5 0H21v8.5h-8.5V3zM3 12.5h8.5V21H3v-8.5zm9.5 0H21V21h-8.5v-8.5z" />
+    </svg>
+  )
+}
+
+export function DefaultProviderIcon({ className }: { className?: string }) {
+  return (
+    <svg className={className} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M15 3h4a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2h-4" />
+      <polyline points="10 17 15 12 10 7" />
+      <line x1="15" y1="12" x2="3" y2="12" />
+    </svg>
+  )
+}

frontend/src/hooks/use-auth-providers.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest'
+import { renderHook, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { http, HttpResponse } from 'msw'
+import { server } from '@/test/msw-handlers'
+import { useAuthProviders } from './use-auth-providers'
+import type { ReactNode } from 'react'
+
+function createWrapper() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  })
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return QueryClientProvider({ client: queryClient, children })
+  }
+}
+
+describe('useAuthProviders', () => {
+  it('returns empty array when API returns 404 (password-only mode)', async () => {
+    // Default MSW handler returns 404
+    const { result } = renderHook(() => useAuthProviders(), { wrapper: createWrapper() })
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true)
+    })
+
+    expect(result.current.data).toEqual([])
+  })
+
+  it('returns providers when API succeeds', async () => {
+    server.use(
+      http.get('/api/auth/providers', () => {
+        return HttpResponse.json({
+          providers: [
+            { id: 'local', type: 'password', displayName: 'Email' },
+            { id: 'google', type: 'oidc', displayName: 'Google' },
+          ],
+        })
+      }),
+    )
+
+    const { result } = renderHook(() => useAuthProviders(), { wrapper: createWrapper() })
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true)
+    })
+
+    expect(result.current.data).toHaveLength(2)
+    expect(result.current.data?.[1]?.id).toBe('google')
+    expect(result.current.data?.[1]?.type).toBe('oidc')
+  })
+})

frontend/src/hooks/use-auth-providers.ts

@@ -0,0 +1,38 @@
+import { useQuery } from '@tanstack/react-query'
+
+export interface AuthProvider {
+  id: string
+  type: 'password' | 'oidc'
+  displayName: string
+  iconUrl?: string
+}
+
+interface ProvidersResponse {
+  providers: AuthProvider[]
+}
+
+async function fetchProviders(): Promise<AuthProvider[]> {
+  const response = await fetch('/api/auth/providers')
+  if (response.status === 404) {
+    // Provider discovery API not available - password-only mode
+    return []
+  }
+  if (!response.ok) {
+    throw new Error(`Failed to fetch providers: ${response.status}`)
+  }
+  const data = (await response.json()) as ProvidersResponse
+  return data.providers
+}
+
+/**
+ * Fetches available authentication providers from the backend.
+ * Gracefully falls back to empty array on error (password-only mode).
+ */
+export function useAuthProviders() {
+  return useQuery<AuthProvider[]>({
+    queryKey: ['auth', 'providers'],
+    queryFn: fetchProviders,
+    staleTime: 5 * 60 * 1000,
+    retry: false,
+  })
+}

frontend/src/hooks/use-oauth-flow.ts

@@ -0,0 +1,37 @@
+import { useCallback } from 'react'
+import { generateCodeVerifier, generateCodeChallenge, generateState } from '@/lib/pkce'
+
+const PKCE_VERIFIER_KEY = 'meridian_pkce_verifier'
+const PKCE_STATE_KEY = 'meridian_pkce_state'
+
+/**
+ * Hook that initiates an OAuth authorization code flow with PKCE.
+ * Generates PKCE parameters, stores them in sessionStorage, and redirects to Dex.
+ */
+export function useOAuthFlow() {
+  const startFlow = useCallback(async (connectorId: string) => {
+    const verifier = generateCodeVerifier()
+    const challenge = await generateCodeChallenge(verifier)
+    const state = generateState()
+
+    sessionStorage.setItem(PKCE_VERIFIER_KEY, verifier)
+    sessionStorage.setItem(PKCE_STATE_KEY, state)
+
+    const params = new URLSearchParams({
+      client_id: 'meridian-service',
+      response_type: 'code',
+      scope: 'openid email profile',
+      redirect_uri: `${window.location.origin}/callback`,
+      code_challenge: challenge,
+      code_challenge_method: 'S256',
+      state,
+      connector_id: connectorId,
+    })
+
+    window.location.href = `/dex/auth?${params.toString()}`
+  }, [])
+
+  return { startFlow }
+}
+
+export { PKCE_VERIFIER_KEY, PKCE_STATE_KEY }

frontend/src/lib/__tests__/pkce.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest'
+import { generateCodeVerifier, generateCodeChallenge, generateState } from '../pkce'
+
+describe('PKCE utilities', () => {
+  describe('generateCodeVerifier', () => {
+    it('generates a 64-character string', () => {
+      const verifier = generateCodeVerifier()
+      expect(verifier).toHaveLength(64)
+    })
+
+    it('uses only unreserved characters (RFC 7636 4.1)', () => {
+      const verifier = generateCodeVerifier()
+      expect(verifier).toMatch(/^[A-Za-z0-9\-._~]+$/)
+    })
+
+    it('generates unique verifiers', () => {
+      const v1 = generateCodeVerifier()
+      const v2 = generateCodeVerifier()
+      expect(v1).not.toEqual(v2)
+    })
+  })
+
+  describe('generateCodeChallenge', () => {
+    it('produces a base64url string without padding', async () => {
+      const verifier = generateCodeVerifier()
+      const challenge = await generateCodeChallenge(verifier)
+      expect(challenge).toMatch(/^[A-Za-z0-9\-_]+$/)
+      expect(challenge).not.toContain('=')
+    })
+
+    it('produces a consistent challenge for the same verifier', async () => {
+      const verifier = 'test-verifier-for-consistency'
+      const c1 = await generateCodeChallenge(verifier)
+      const c2 = await generateCodeChallenge(verifier)
+      expect(c1).toEqual(c2)
+    })
+
+    it('produces different challenges for different verifiers', async () => {
+      const c1 = await generateCodeChallenge('verifier-one')
+      const c2 = await generateCodeChallenge('verifier-two')
+      expect(c1).not.toEqual(c2)
+    })
+  })
+
+  describe('generateState', () => {
+    it('generates a base64url string', () => {
+      const state = generateState()
+      expect(state).toMatch(/^[A-Za-z0-9\-_]+$/)
+    })
+
+    it('generates unique states', () => {
+      const s1 = generateState()
+      const s2 = generateState()
+      expect(s1).not.toEqual(s2)
+    })
+  })
+})

frontend/src/lib/pkce.ts

@@ -0,0 +1,49 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities for OAuth 2.0 authorization code flow.
+ * Implements RFC 7636 sections 4.1 and 4.2.
+ */
+
+const VERIFIER_CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~'
+const VERIFIER_LENGTH = 64
+
+/**
+ * Generate a cryptographically random code verifier (RFC 7636 4.1).
+ * Returns a 64-character string from the unreserved character set.
+ */
+export function generateCodeVerifier(): string {
+  const array = new Uint8Array(VERIFIER_LENGTH)
+  crypto.getRandomValues(array)
+  return Array.from(array, (byte) => VERIFIER_CHARSET[byte % VERIFIER_CHARSET.length]).join('')
+}
+
+/**
+ * Generate a S256 code challenge from a code verifier (RFC 7636 4.2).
+ * challenge = BASE64URL(SHA256(verifier))
+ */
+export async function generateCodeChallenge(verifier: string): Promise<string> {
+  const encoder = new TextEncoder()
+  const data = encoder.encode(verifier)
+  const digest = await crypto.subtle.digest('SHA-256', data)
+  return base64UrlEncode(digest)
+}
+
+/**
+ * Base64 URL encoding without padding (RFC 4648 section 5).
+ */
+function base64UrlEncode(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer)
+  let binary = ''
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte)
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+/**
+ * Generate a random state parameter for CSRF protection.
+ */
+export function generateState(): string {
+  const array = new Uint8Array(32)
+  crypto.getRandomValues(array)
+  return base64UrlEncode(array.buffer)
+}