Refactor config, auth, and storage modules with runtime validation and encryption

- Centralized and refactored configuration management (`config`) with runtime validation for environment variables.
- Introduced utilities for secure token storage, including AES-GCM encryption and fallback handling.
- Enhanced `authStore` state management with token validation, secure persistence, and initialization from storage.
- Modularized authentication utilities and updated export structure for better maintainability.
- Improved error handling, input validation, and added detailed comments for enhanced clarity.

frontend/src/lib/auth/__tests__/crypto.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Tests for crypto utilities
+ */
+
+import { encryptData, decryptData, clearEncryptionKey } from '../crypto';
+
+describe('Crypto Utilities', () => {
+  beforeEach(() => {
+    // Clear encryption key before each test
+    clearEncryptionKey();
+    sessionStorage.clear();
+  });
+
+  describe('encryptData', () => {
+    it('should encrypt string data', async () => {
+      const plaintext = 'test data';
+      const encrypted = await encryptData(plaintext);
+
+      expect(encrypted).toBeDefined();
+      expect(typeof encrypted).toBe('string');
+      expect(encrypted).not.toBe(plaintext);
+    });
+
+    it('should produce different ciphertext for same plaintext', async () => {
+      const plaintext = 'test data';
+      const encrypted1 = await encryptData(plaintext);
+      const encrypted2 = await encryptData(plaintext);
+
+      // Due to random IV, ciphertexts should be different
+      expect(encrypted1).not.toBe(encrypted2);
+    });
+
+    it('should handle empty strings', async () => {
+      const encrypted = await encryptData('');
+      expect(encrypted).toBeDefined();
+    });
+
+    it('should handle special characters', async () => {
+      const special = '!@#$%^&*()_+-=[]{}|;:",.<>?/~`';
+      const encrypted = await encryptData(special);
+      const decrypted = await decryptData(encrypted);
+
+      expect(decrypted).toBe(special);
+    });
+  });
+
+  describe('decryptData', () => {
+    it('should decrypt data encrypted by encryptData', async () => {
+      const plaintext = 'test data';
+      const encrypted = await encryptData(plaintext);
+      const decrypted = await decryptData(encrypted);
+
+      expect(decrypted).toBe(plaintext);
+    });
+
+    it('should throw error for invalid encrypted data', async () => {
+      await expect(decryptData('invalid')).rejects.toThrow();
+    });
+
+    it('should throw error for tampered data', async () => {
+      const plaintext = 'test data';
+      const encrypted = await encryptData(plaintext);
+
+      // Tamper with encrypted data
+      const tampered = encrypted.slice(0, -4) + 'XXXX';
+
+      await expect(decryptData(tampered)).rejects.toThrow();
+    });
+  });
+
+  describe('clearEncryptionKey', () => {
+    it('should clear encryption key from session', async () => {
+      // Encrypt some data (creates key)
+      await encryptData('test');
+
+      // Clear key
+      clearEncryptionKey();
+
+      // Session storage should be empty
+      expect(sessionStorage.getItem('auth_encryption_key')).toBeNull();
+    });
+
+    it('should invalidate previously encrypted data after key cleared', async () => {
+      const plaintext = 'test data';
+      const encrypted = await encryptData(plaintext);
+
+      // Clear key
+      clearEncryptionKey();
+
+      // Try to decrypt - should fail because key is regenerated
+      await expect(decryptData(encrypted)).rejects.toThrow();
+    });
+  });
+
+  describe('Key persistence', () => {
+    it('should reuse same key within session', async () => {
+      const plaintext = 'test data';
+
+      const encrypted1 = await encryptData(plaintext);
+      const decrypted1 = await decryptData(encrypted1);
+
+      const encrypted2 = await encryptData(plaintext);
+      const decrypted2 = await decryptData(encrypted2);
+
+      expect(decrypted1).toBe(plaintext);
+      expect(decrypted2).toBe(plaintext);
+    });
+  });
+});

frontend/src/lib/auth/crypto.ts

@@ -0,0 +1,108 @@
+/**
+ * Cryptographic utilities for secure token storage
+ * Implements AES-GCM encryption for localStorage fallback
+ */
+
+const ENCRYPTION_KEY_NAME = 'auth_encryption_key';
+
+/**
+ * Generate or retrieve encryption key
+ * Key is stored in sessionStorage (cleared on browser close)
+ */
+async function getEncryptionKey(): Promise<CryptoKey> {
+  // Check if key exists in session
+  const storedKey = sessionStorage.getItem(ENCRYPTION_KEY_NAME);
+
+  if (storedKey) {
+    const keyData = JSON.parse(storedKey);
+    return await crypto.subtle.importKey(
+      'jwk',
+      keyData,
+      { name: 'AES-GCM', length: 256 },
+      true,
+      ['encrypt', 'decrypt']
+    );
+  }
+
+  // Generate new key
+  const key = await crypto.subtle.generateKey(
+    { name: 'AES-GCM', length: 256 },
+    true,
+    ['encrypt', 'decrypt']
+  );
+
+  // Store key in sessionStorage
+  const exportedKey = await crypto.subtle.exportKey('jwk', key);
+  sessionStorage.setItem(ENCRYPTION_KEY_NAME, JSON.stringify(exportedKey));
+
+  return key;
+}
+
+/**
+ * Encrypt data using AES-GCM
+ * @param data - Data to encrypt
+ * @returns Base64 encoded encrypted data with IV
+ */
+export async function encryptData(data: string): Promise<string> {
+  try {
+    const key = await getEncryptionKey();
+    const iv = crypto.getRandomValues(new Uint8Array(12)); // 96-bit IV for GCM
+    const encoder = new TextEncoder();
+    const encodedData = encoder.encode(data);
+
+    const encryptedData = await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv },
+      key,
+      encodedData
+    );
+
+    // Combine IV and encrypted data
+    const combined = new Uint8Array(iv.length + encryptedData.byteLength);
+    combined.set(iv);
+    combined.set(new Uint8Array(encryptedData), iv.length);
+
+    // Convert to base64
+    return btoa(String.fromCharCode(...combined));
+  } catch (error) {
+    console.error('Encryption failed:', error);
+    throw new Error('Failed to encrypt data');
+  }
+}
+
+/**
+ * Decrypt data encrypted with encryptData
+ * @param encryptedData - Base64 encoded encrypted data with IV
+ * @returns Decrypted string
+ */
+export async function decryptData(encryptedData: string): Promise<string> {
+  try {
+    const key = await getEncryptionKey();
+
+    // Decode from base64
+    const combined = Uint8Array.from(atob(encryptedData), c => c.charCodeAt(0));
+
+    // Extract IV and encrypted data
+    const iv = combined.slice(0, 12);
+    const data = combined.slice(12);
+
+    const decryptedData = await crypto.subtle.decrypt(
+      { name: 'AES-GCM', iv },
+      key,
+      data
+    );
+
+    const decoder = new TextDecoder();
+    return decoder.decode(decryptedData);
+  } catch (error) {
+    console.error('Decryption failed:', error);
+    throw new Error('Failed to decrypt data');
+  }
+}
+
+/**
+ * Clear encryption key from session
+ * Call this on logout to invalidate encrypted data
+ */
+export function clearEncryptionKey(): void {
+  sessionStorage.removeItem(ENCRYPTION_KEY_NAME);
+}

frontend/src/lib/auth/index.ts

@@ -1,4 +1,19 @@
 // Authentication utilities
 // Examples: Token management, auth helpers, session utilities, etc.
 
-export {};
+export {
+  encryptData,
+  decryptData,
+  clearEncryptionKey,
+} from './crypto';
+
+export {
+  saveTokens,
+  getTokens,
+  clearTokens,
+  getStorageMethod,
+  setStorageMethod,
+  isStorageAvailable,
+  type TokenStorage,
+  type StorageMethod,
+} from './storage';

frontend/src/lib/auth/storage.ts

@@ -0,0 +1,128 @@
+/**
+ * Secure token storage abstraction
+ * Primary: httpOnly cookies (server-side)
+ * Fallback: Encrypted localStorage (client-side)
+ */
+
+import { encryptData, decryptData, clearEncryptionKey } from './crypto';
+
+export interface TokenStorage {
+  accessToken: string | null;
+  refreshToken: string | null;
+}
+
+const STORAGE_KEY = 'auth_tokens';
+const STORAGE_METHOD_KEY = 'auth_storage_method';
+
+export type StorageMethod = 'cookie' | 'localStorage';
+
+/**
+ * Get current storage method
+ */
+export function getStorageMethod(): StorageMethod {
+  // Check if we previously set a storage method
+  const stored = localStorage.getItem(STORAGE_METHOD_KEY);
+  if (stored === 'cookie' || stored === 'localStorage') {
+    return stored;
+  }
+
+  // Default to localStorage for client-side auth
+  // In Phase 2, we'll add cookie detection from server
+  return 'localStorage';
+}
+
+/**
+ * Set storage method preference
+ */
+export function setStorageMethod(method: StorageMethod): void {
+  localStorage.setItem(STORAGE_METHOD_KEY, method);
+}
+
+/**
+ * Save tokens securely
+ * @param tokens - Access and refresh tokens
+ */
+export async function saveTokens(tokens: TokenStorage): Promise<void> {
+  const method = getStorageMethod();
+
+  if (method === 'cookie') {
+    // Cookies are handled server-side via Set-Cookie headers
+    // This is a no-op for client-side, actual implementation in Phase 2
+    // when we add server-side API route handlers
+    console.debug('Token storage via cookies (server-side)');
+    return;
+  }
+
+  // Fallback: Encrypted localStorage
+  try {
+    const encrypted = await encryptData(JSON.stringify(tokens));
+    localStorage.setItem(STORAGE_KEY, encrypted);
+  } catch (error) {
+    console.error('Failed to save tokens:', error);
+    throw new Error('Token storage failed');
+  }
+}
+
+/**
+ * Retrieve tokens from storage
+ * @returns Stored tokens or null
+ */
+export async function getTokens(): Promise<TokenStorage | null> {
+  const method = getStorageMethod();
+
+  if (method === 'cookie') {
+    // Cookies are sent automatically with requests
+    // For client-side access, we'll implement this in Phase 2
+    // with a /api/auth/session endpoint
+    console.debug('Token retrieval via cookies (server-side)');
+    return null;
+  }
+
+  // Fallback: Encrypted localStorage
+  try {
+    const encrypted = localStorage.getItem(STORAGE_KEY);
+    if (!encrypted) {
+      return null;
+    }
+
+    const decrypted = await decryptData(encrypted);
+    return JSON.parse(decrypted) as TokenStorage;
+  } catch (error) {
+    console.error('Failed to retrieve tokens:', error);
+    // If decryption fails, clear invalid data
+    localStorage.removeItem(STORAGE_KEY);
+    return null;
+  }
+}
+
+/**
+ * Clear all tokens from storage
+ */
+export async function clearTokens(): Promise<void> {
+  const method = getStorageMethod();
+
+  if (method === 'cookie') {
+    // Cookie clearing via server-side Set-Cookie with Max-Age=0
+    // Implementation in Phase 2
+    console.debug('Token clearing via cookies (server-side)');
+  }
+
+  // Always clear localStorage (belt and suspenders)
+  localStorage.removeItem(STORAGE_KEY);
+  clearEncryptionKey();
+}
+
+/**
+ * Check if storage is available
+ * @returns true if localStorage is accessible
+ */
+export function isStorageAvailable(): boolean {
+  try {
+    const test = '__storage_test__';
+    localStorage.setItem(test, test);
+    localStorage.removeItem(test);
+    return true;
+  } catch {
+    return false;
+  }
+}