feat: implement token management architecture with TokenManager

Co-authored-by: aider (anthropic/claude-sonnet-4-20250514) <[e-mail]>

docs/examples/next-js-ssr-component.md

···
-- use the `getAccessTokenInServerComponent()` to access the token
-- pass the token in to the `ApiClient` as normal
+- use the `createServerApiClient()` helper function
 
 ```tsx
-const accessToken = await getAccessTokenInServerComponent();
-const apiClient = new ApiClient(
-  process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:3000',
-  () => accessToken,
-);
+import { createServerApiClient } from '@/api-client';
+
+export default async function SSRProfilePage() {
+  const apiClient = await createServerApiClient();
+  
+  let profile;
+  let error;
+
+  try {
+    profile = await apiClient.getMyProfile();
+  } catch (err: any) {
+    error = err.message || 'Failed to load profile';
+  }
+
+  // ... rest of component
+}
 ```
 
 - Full example
 
 ```tsx
-import { ApiClient } from '@/api-client/ApiClient';
-import { getAccessTokenInServerComponent } from '@/services/auth';
+import { createServerApiClient } from '@/api-client';
 import {
   Card,
   Container,
···
   Group,
 } from '@mantine/core';
 import { redirect } from 'next/navigation';
+import { getAccessTokenInServerComponent } from '@/services/auth';
 
 export default async function SSRProfilePage() {
+  // Check if user is authenticated
   const accessToken = await getAccessTokenInServerComponent();
   if (!accessToken) {
     redirect('/auth/signin');
   }
 
   // Create API client for server-side usage
-  const apiClient = new ApiClient(
-    process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:3000',
-    () => accessToken,
-  );
+  const apiClient = await createServerApiClient();
 
   let profile;
   let error;

src/webapp/api-client/ApiClient.ts

···
   UserClient,
   FeedClient,
 } from './clients';
+import { TokenManager } from '../services/TokenManager';
+import { createClientTokenManager } from '../services/auth';
 import type {
   // Request types
   AddUrlToLibraryRequest,
···
 
   constructor(
     private baseUrl: string,
-    private getAuthToken: () => string | null,
+    private tokenManager: TokenManager,
   ) {
-    this.queryClient = new QueryClient(baseUrl, getAuthToken);
-    this.cardClient = new CardClient(baseUrl, getAuthToken);
-    this.collectionClient = new CollectionClient(baseUrl, getAuthToken);
-    this.userClient = new UserClient(baseUrl, getAuthToken);
-    this.feedClient = new FeedClient(baseUrl, getAuthToken);
+    this.queryClient = new QueryClient(baseUrl, tokenManager);
+    this.cardClient = new CardClient(baseUrl, tokenManager);
+    this.collectionClient = new CollectionClient(baseUrl, tokenManager);
+    this.userClient = new UserClient(baseUrl, tokenManager);
+    this.feedClient = new FeedClient(baseUrl, tokenManager);
   }
 
   // Query operations - delegate to QueryClient

src/webapp/api-client/clients/BaseClient.ts

···
 import { ApiError, ApiErrorResponse } from '../types/errors';
+import { TokenManager } from '../../services/TokenManager';
 
 export abstract class BaseClient {
   constructor(
     protected baseUrl: string,
-    protected getAuthToken: () => string | null,
+    protected tokenManager: TokenManager,
   ) {}
 
   protected async request<T>(
···
     endpoint: string,
     data?: any,
   ): Promise<T> {
-    const url = `${this.baseUrl}${endpoint}`;
-    const token = this.getAuthToken();
+    const makeRequest = async (): Promise<T> => {
+      const url = `${this.baseUrl}${endpoint}`;
+      const token = await this.tokenManager.getAccessToken();
 
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/json',
-    };
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+      };
 
-    if (token) {
-      headers['Authorization'] = `Bearer ${token}`;
-    }
+      if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+      }
 
-    const config: RequestInit = {
-      method,
-      headers,
+      const config: RequestInit = {
+        method,
+        headers,
+      };
+
+      if (data && (method === 'POST' || method === 'PUT' || method === 'PATCH')) {
+        config.body = JSON.stringify(data);
+      }
+
+      const response = await fetch(url, config);
+      return this.handleResponse<T>(response);
     };
 
-    if (data && (method === 'POST' || method === 'PUT' || method === 'PATCH')) {
-      config.body = JSON.stringify(data);
+    try {
+      return await makeRequest();
+    } catch (error) {
+      // Handle 401/403 errors with automatic token refresh
+      if (
+        error instanceof ApiError &&
+        (error.status === 401 || error.status === 403)
+      ) {
+        return this.tokenManager.handleAuthError(makeRequest);
+      }
+      throw error;
     }
-
-    const response = await fetch(url, config);
-    return this.handleResponse<T>(response);
   }
 
   private async handleResponse<T>(response: Response): Promise<T> {

src/webapp/hooks/useAuth.tsx

···
     }
   }, [refreshTokens]);
 
-  // Set up automatic token refresh
+  // Helper function to check if a JWT token is expired or will expire soon
+  const isTokenExpiredWithBuffer = (token: string, bufferMinutes: number = 5): boolean => {
+    if (!token) return true;
+
+    try {
+      const payload = JSON.parse(atob(token.split('.')[1]));
+      const expiry = payload.exp * 1000; // Convert to milliseconds
+      const bufferTime = bufferMinutes * 60 * 1000; // Buffer in milliseconds
+      return Date.now() >= (expiry - bufferTime);
+    } catch (e) {
+      return true;
+    }
+  };
+
+  // PROACTIVE TOKEN REFRESH - This is the primary strategy
   useEffect(() => {
     if (!accessToken || !refreshToken) return;
 
-    const checkTokenExpiration = async () => {
-      if (isTokenExpired(accessToken)) {
+    const checkAndRefreshToken = async () => {
+      // Check if token will expire in the next 5 minutes
+      if (isTokenExpiredWithBuffer(accessToken, 5)) {
+        console.log('Proactively refreshing token before expiration');
         await refreshTokens();
       }
     };
 
-    // Check token expiration every minute
-    const interval = setInterval(checkTokenExpiration, 60000);
+    // Check immediately on mount
+    checkAndRefreshToken();
+    
+    // Then check every 5 minutes
+    const interval = setInterval(checkAndRefreshToken, 5 * 60 * 1000);
 
     return () => clearInterval(interval);
   }, [accessToken, refreshToken, refreshTokens]);

src/webapp/services/TokenManager.ts

···
+export interface AuthTokens {
+  accessToken: string | null;
+  refreshToken: string | null;
+}
+
+export interface TokenStorage {
+  getTokens(): AuthTokens;
+  setTokens(accessToken: string, refreshToken: string): Promise<void>;
+  clearTokens(): void;
+}
+
+export interface TokenRefresher {
+  refreshTokens(refreshToken: string): Promise<{ accessToken: string; refreshToken: string }>;
+}
+
+export class TokenManager {
+  private isRefreshing = false;
+  private refreshPromise: Promise<boolean> | null = null;
+  private failedRequestsQueue: Array<{
+    resolve: (value: any) => void;
+    reject: (error: any) => void;
+    request: () => Promise<any>;
+  }> = [];
+
+  constructor(
+    private storage: TokenStorage,
+    private refresher: TokenRefresher,
+  ) {}
+
+  async getAccessToken(): Promise<string | null> {
+    const { accessToken } = this.storage.getTokens();
+    return accessToken;
+  }
+
+  async handleAuthError<T>(originalRequest: () => Promise<T>): Promise<T> {
+    // If already refreshing, queue this request
+    if (this.isRefreshing) {
+      return new Promise((resolve, reject) => {
+        this.failedRequestsQueue.push({
+          resolve,
+          reject,
+          request: originalRequest,
+        });
+      });
+    }
+
+    // Start refresh process
+    this.isRefreshing = true;
+    
+    try {
+      // Use existing refresh promise or create new one
+      if (!this.refreshPromise) {
+        this.refreshPromise = this.performRefresh();
+      }
+
+      const refreshSuccess = await this.refreshPromise;
+
+      if (refreshSuccess) {
+        // Process queued requests
+        const queuedRequests = [...this.failedRequestsQueue];
+        this.failedRequestsQueue = [];
+
+        // Retry all queued requests
+        queuedRequests.forEach(async ({ resolve, reject, request }) => {
+          try {
+            const result = await request();
+            resolve(result);
+          } catch (error) {
+            reject(error);
+          }
+        });
+
+        // Retry original request
+        return await originalRequest();
+      } else {
+        // Refresh failed, reject all queued requests
+        const queuedRequests = [...this.failedRequestsQueue];
+        this.failedRequestsQueue = [];
+        
+        const refreshError = new Error('Token refresh failed');
+        queuedRequests.forEach(({ reject }) => reject(refreshError));
+        
+        throw refreshError;
+      }
+    } finally {
+      this.isRefreshing = false;
+      this.refreshPromise = null;
+    }
+  }
+
+  private async performRefresh(): Promise<boolean> {
+    const { refreshToken } = this.storage.getTokens();
+    if (!refreshToken) return false;
+
+    try {
+      const newTokens = await this.refresher.refreshTokens(refreshToken);
+      await this.storage.setTokens(newTokens.accessToken, newTokens.refreshToken);
+      return true;
+    } catch (error) {
+      console.error('Token refresh failed:', error);
+      this.storage.clearTokens();
+      return false;
+    }
+  }
+}

src/webapp/services/TokenRefresher.ts

···
+import { TokenRefresher } from './TokenManager';
+
+export class ApiTokenRefresher implements TokenRefresher {
+  constructor(private baseUrl: string) {}
+
+  async refreshTokens(refreshToken: string): Promise<{ accessToken: string; refreshToken: string }> {
+    const response = await fetch(`${this.baseUrl}/api/auth/refresh`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refreshToken }),
+    });
+
+    if (!response.ok) {
+      throw new Error('Token refresh failed');
+    }
+
+    return response.json();
+  }
+}

src/webapp/services/auth.ts

···
  * Authentication utilities for the client-side application
  */
 
+import { TokenManager } from './TokenManager';
+import { ClientTokenStorage } from './storage/ClientTokenStorage';
+import { ServerTokenStorage } from './storage/ServerTokenStorage';
+import { ApiTokenRefresher } from './TokenRefresher';
+
 // Check if the user is authenticated
 export const isAuthenticated = (): boolean => {
   if (typeof window === 'undefined') {
···
   localStorage.removeItem('accessToken');
   localStorage.removeItem('refreshToken');
 };
+
+// Client-side token manager
+export const createClientTokenManager = () => {
+  const storage = new ClientTokenStorage();
+  const refresher = new ApiTokenRefresher(
+    process.env.NEXT_PUBLIC_API_BASE_URL || 'http://localhost:3000'
+  );
+  return new TokenManager(storage, refresher);
+};
+
+// Server-side token manager (read-only, no refresh capability)
+export const createServerTokenManager = async () => {
+  const { cookies } = await import('next/headers');
+  const cookiesStore = await cookies();
+  const storage = new ServerTokenStorage(cookiesStore);
+  const refresher = new ApiTokenRefresher(''); // Won't be used
+  return new TokenManager(storage, refresher);
+};

src/webapp/services/storage/ClientTokenStorage.ts

···
+import { AuthTokens, TokenStorage } from '../TokenManager';
+
+export class ClientTokenStorage implements TokenStorage {
+  getTokens(): AuthTokens {
+    if (typeof window === 'undefined') {
+      return { accessToken: null, refreshToken: null };
+    }
+    
+    return {
+      accessToken: localStorage.getItem('accessToken'),
+      refreshToken: localStorage.getItem('refreshToken'),
+    };
+  }
+
+  async setTokens(accessToken: string, refreshToken: string): Promise<void> {
+    if (typeof window === 'undefined') return;
+    
+    localStorage.setItem('accessToken', accessToken);
+    localStorage.setItem('refreshToken', refreshToken);
+    
+    // Sync with server cookies
+    try {
+      await fetch('/api/auth/sync', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ accessToken, refreshToken }),
+        credentials: 'include',
+      });
+    } catch (error) {
+      console.warn('Failed to sync tokens with server:', error);
+    }
+  }
+
+  clearTokens(): void {
+    if (typeof window === 'undefined') return;
+    localStorage.removeItem('accessToken');
+    localStorage.removeItem('refreshToken');
+  }
+}

src/webapp/services/storage/ServerTokenStorage.ts

···
+import { AuthTokens, TokenStorage } from '../TokenManager';
+
+export class ServerTokenStorage implements TokenStorage {
+  constructor(private cookiesStore: any) {}
+
+  getTokens(): AuthTokens {
+    return {
+      accessToken: this.cookiesStore.get('accessToken')?.value || null,
+      refreshToken: this.cookiesStore.get('refreshToken')?.value || null,
+    };
+  }
+
+  async setTokens(): Promise<void> {
+    // Server-side can't set tokens - handled by client-side sync
+    throw new Error('Server-side token refresh not supported');
+  }
+
+  clearTokens(): void {
+    // Server-side can't clear tokens directly
+    throw new Error('Server-side token clearing not supported');
+  }
+}