Skip to content

HEADLESS_AUTH_IMPLEMENTATION.md

Latest commit

 

History

History
221 lines (168 loc) · 6.44 KB

HEADLESS_AUTH_IMPLEMENTATION.md

File metadata and controls

221 lines (168 loc) · 6.44 KB

Headless Authentication Implementation for Tauri

Overview

This document describes the complete headless/API-only authentication implementation for the Axis Tauri app. The system now supports both web-based authentication (using Stack/Neon Auth) and headless authentication for Tauri production builds.

Architecture

Authentication Flow Selection

The app automatically detects the environment and chooses the appropriate authentication provider:

  1. Web/Development: Uses Stack Auth React components directly
  2. Tauri Production: Uses custom headless authentication with browser-based OAuth

Detection logic in src/contexts/AuthContext.tsx:

export function shouldUseHeadlessAuth(): boolean {
  return isTauriEnvironment() && isProductionBuild()
}

Components

Backend (ai-backend-service)

  1. Auth Routes (src/routes/auth.ts)

    • POST /auth/initiate - Creates auth session and returns OAuth URL
    • GET /auth/status/:sessionId - Polling endpoint for auth status
    • GET /auth/callback - OAuth callback (Stack/Neon)
    • POST /auth/exchange - Manual token exchange
    • POST /auth/refresh-token - Token refresh endpoint

  2. Auth Session Manager (src/services/authSession.ts)

    • Manages temporary auth sessions with 5-minute TTL
    • Tracks session status and user data
    • Automatic cleanup of expired sessions

Frontend (ai-notes-app)

  1. Auth Context (src/contexts/AuthContext.tsx)

    • Defines standard auth interface matching Stack Auth API
    • Type guards for environment detection

  2. Tauri Auth Provider (src/providers/TauriAuthProvider.tsx)

    • Custom auth provider for Tauri builds
    • Token persistence using SecureStorage
    • Automatic token refresh every 5 minutes
    • Session validation on mount

  3. Unified Auth Hooks (src/hooks/useAppAuth.ts)

    • useAppAuth() - Unified auth hook
    • useAppUser() - Unified user hook
    • Automatically selects correct provider based on environment

  4. Auth Polling (src/hooks/useAuthPolling.ts)

    • Polls backend for auth completion
    • Visual progress indicators
    • Configurable timeout and retry logic

  5. Browser Auth (src/lib/browserAuth.ts)

    • Initiates OAuth sessions
    • Opens system browser for authentication
    • Token exchange functionality

  6. Secure Storage (src/lib/secureStorage.ts)

    • Uses Tauri keyring for desktop
    • Falls back to localStorage for web
    • Handles both access and refresh tokens

Authentication Flow

sequenceDiagram
    participant App as Tauri App
    participant Backend as Backend Server
    participant Browser as System Browser
    participant Clerk as Clerk Auth
    
    App->>Backend: POST /auth/initiate
    Backend->>App: Return sessionId & authUrl
    App->>Browser: Open authUrl
    Browser->>Clerk: User authenticates
    Clerk->>Backend: Redirect to /auth/callback
    Backend->>Backend: Validate & store token
    Backend->>Browser: Show success page
    
    loop Polling
        App->>Backend: GET /auth/status/:sessionId
        Backend->>App: Return auth status
    end
    
    App->>App: Store tokens securely
    App->>App: Navigate to dashboard
Loading

Token Management

Storage

  • Desktop: Uses OS keychain via Tauri commands
  • Web: Uses localStorage as fallback

Refresh Strategy

  • Tokens refresh automatically on 401 responses
  • Background refresh every 5 minutes
  • Seamless retry with exponential backoff

API Integration

The aiHttpApi.ts client handles token refresh:

if (response.status === 401 && retryCount === 0) {
  // Try to refresh token
  const refreshResponse = await fetch(`${backendUrl}/auth/refresh-token`, {
    method: 'POST',
    body: JSON.stringify({ refreshToken })
  })
  // Retry original request with new token
}

User Experience

Sign In/Sign Up Pages

  • Browser-based authentication for Tauri
  • Visual polling indicators with progress bar
  • Cancel and retry functionality
  • Manual token entry as fallback
  • Smooth transitions and animations

Session Persistence

  • Automatic session restoration on app restart
  • Token validation on mount
  • Graceful degradation for expired sessions

Migration Guide

For Components Using Clerk Directly

Replace Clerk imports with unified hooks:

// Before
import { useAuth, useUser } from '@clerk/clerk-react'

// After
import { useAppAuth, useAppUser } from '@/hooks/useAppAuth'

The API remains the same:

const { isSignedIn, getToken, signOut } = useAppAuth()
const { user } = useAppUser()

Environment Variables

Backend requires:

CLERK_SECRET_KEY=sk_test_...
CLERK_DOMAIN=your-instance.accounts.dev
BACKEND_URL=https://api.yourapp.com
ALLOWED_ORIGINS=tauri://localhost,https://yourapp.com

Security Considerations

  1. Token Storage: Uses OS keychain for maximum security
  2. Session Management: Short-lived sessions (5 minutes)
  3. CORS Configuration: Strict origin validation
  4. Token Validation: Server-side verification of all tokens
  5. Automatic Cleanup: Expired sessions removed regularly

Testing

Development Mode

  • Uses Clerk components directly
  • Standard web authentication flow
  • Hot reload works normally

Production Mode

# Build for production
npm run tauri:build

# Test authentication flow
1. Click "Sign In with Browser"
2. Complete authentication in browser
3. App detects completion automatically
4. Tokens stored securely
5. Session persists across restarts

Troubleshooting

Common Issues

  1. Authentication not detected

    • Check backend is accessible
    • Verify CLERK_DOMAIN is correct
    • Check browser console for errors

  2. Token refresh failures

    • Verify refresh endpoint is working
    • Check token expiration times
    • Review backend logs

  3. Session persistence issues

    • Verify Tauri keyring permissions
    • Check SecureStorage implementation
    • Review console logs for errors

Future Enhancements

  1. OAuth PKCE - Add code challenge/verifier
  2. SSO Support - Enterprise authentication
  3. Biometric Auth - TouchID/FaceID support
  4. Multi-factor Auth - Enhanced security

Conclusion

The headless authentication system provides a robust, secure, and user-friendly authentication experience for Tauri desktop applications while maintaining compatibility with web deployments. The implementation follows best practices for native app authentication and provides excellent user experience with visual feedback and error recovery.