Job-Info/OAUTH2_REFERENCE_GUIDE.md

/**
 * REFERENCE TOOL: OAuth2 + Microsoft Graph Implementation Guide
 * 
 * This document provides exact patterns and code structures to follow when
 * building OAuth2 and Microsoft Graph integration.
 */

// ============================================================================
// PART 1: BACKEND OAUTH ROUTES (Hono + TypeScript)
// ============================================================================

/**
 * Route: POST /api/auth/authorize
 * Purpose: Exchange authorization code for tokens using service worker credentials
 * 
 * CRITICAL: This route uses CLIENT_SECRET on backend only. Never expose to frontend.
 * 
 * Request body:
 * {
 *   code: string;           // Authorization code from Microsoft
 *   state: string;          // State value for CSRF protection
 *   codeVerifier: string;   // PKCE code verifier (for SPA security)
 * }
 * 
 * Response:
 * {
 *   accessToken: string;        // Short-lived token for Graph API (1 hour)
 *   refreshToken: string;       // Long-lived refresh token (24 hours for SPA)
 *   expiresIn: number;          // Token expiration in seconds
 *   user: {                      // User info from Microsoft
 *     id: string;
 *     displayName: string;
 *     mail: string;
 *   }
 * }
 * 
 * Error responses:
 * {
 *   error: "invalid_code" | "expired_code" | "invalid_request";
 *   message: string;
 * }
 */

// Pseudo-code (actual implementation will be TypeScript):
async function authorizeRoute(c: Context) {
  // 1. EXTRACT & VALIDATE request
  const { code, state, codeVerifier } = c.req.json();
  
  // VALIDATION CHECKLIST:
  if (!code || !state || !codeVerifier) {
    return c.json({ error: 'Missing required parameters' }, 400);
  }
  
  // Verify state matches session state (CSRF protection)
  // This requires storing state in session/Redis during login initiation
  
  // 2. EXCHANGE CODE for tokens using CLIENT_SECRET
  const tokenResponse = await fetch('https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      client_id: process.env.MICROSOFT_CLIENT_ID,
      client_secret: process.env.MICROSOFT_CLIENT_SECRET,  // BACKEND ONLY
      code: code,
      redirect_uri: process.env.MICROSOFT_REDIRECT_URI,
      grant_type: 'authorization_code',
      code_verifier: codeVerifier,  // Required for PKCE
    }).toString(),
  });
  
  if (!tokenResponse.ok) {
    const error = await tokenResponse.json();
    console.error('Microsoft token error:', error);
    return c.json({ error: error.error, message: error.error_description }, 400);
  }
  
  const tokens = await tokenResponse.json();
  // tokens contains: { access_token, refresh_token, expires_in, token_type, ... }
  
  // 3. GET USER INFO from Microsoft Graph
  const userResponse = await fetch('https://graph.microsoft.com/v1.0/me', {
    headers: { Authorization: `Bearer ${tokens.access_token}` },
  });
  
  if (!userResponse.ok) {
    return c.json({ error: 'Failed to fetch user info' }, 500);
  }
  
  const userInfo = await userResponse.json();
  // userInfo contains: { id, displayName, mail, ... }
  
  // 4. STORE REFRESH TOKEN in PocketBase (secured backend)
  // Pattern:
  // - Create/update user record in PocketBase with refresh_token field
  // - Key field: Microsoft ID or email
  // - Store encrypted refresh token
  // - NEVER return refresh token to frontend
  
  await pb.collection('users').upsert({
    microsoftId: userInfo.id,
    email: userInfo.mail,
    displayName: userInfo.displayName,
    refreshToken: tokens.refresh_token,  // Store securely
    refreshTokenExpiry: Date.now() + (24 * 60 * 60 * 1000),  // 24 hours
  });
  
  // 5. RETURN ONLY ACCESS TOKEN to frontend
  return c.json({
    accessToken: tokens.access_token,
    expiresIn: tokens.expires_in,  // Usually 3600 seconds (1 hour)
    user: {
      id: userInfo.id,
      displayName: userInfo.displayName,
      mail: userInfo.mail,
    },
  });
}

// ============================================================================
// PART 2: TOKEN REFRESH ROUTE
// ============================================================================

/**
 * Route: POST /api/auth/refresh
 * Purpose: Get new access token using refresh token from PocketBase
 * 
 * Headers required:
 * - Authorization: Bearer {userId}  (user ID from frontend, used to lookup refresh token)
 * 
 * Response:
 * {
 *   accessToken: string;
 *   expiresIn: number;
 * }
 */

async function refreshRoute(c: Context) {
  // 1. EXTRACT user ID from auth header
  const auth = c.req.header('Authorization');
  if (!auth || !auth.startsWith('Bearer ')) {
    return c.json({ error: 'Unauthorized' }, 401);
  }
  const userId = auth.replace('Bearer ', '');
  
  // 2. RETRIEVE refresh token from PocketBase
  const user = await pb.collection('users').getOne(userId);
  if (!user || !user.refreshToken) {
    return c.json({ error: 'No refresh token found' }, 401);
  }
  
  // 3. EXCHANGE refresh token for new access token
  const tokenResponse = await fetch('https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      client_id: process.env.MICROSOFT_CLIENT_ID,
      client_secret: process.env.MICROSOFT_CLIENT_SECRET,
      refresh_token: user.refreshToken,
      grant_type: 'refresh_token',
      scope: 'https://graph.microsoft.com/.default',
    }).toString(),
  });
  
  if (!tokenResponse.ok) {
    const error = await tokenResponse.json();
    // If refresh token invalid, user must re-authenticate
    return c.json({ error: 'Token refresh failed', needsReauth: true }, 401);
  }
  
  const tokens = await tokenResponse.json();
  
  // 4. UPDATE refresh token in PocketBase (tokens may have new refresh token)
  if (tokens.refresh_token) {
    await pb.collection('users').update(userId, {
      refreshToken: tokens.refresh_token,
    });
  }
  
  // 5. RETURN new access token (never refresh token)
  return c.json({
    accessToken: tokens.access_token,
    expiresIn: tokens.expires_in,
  });
}

// ============================================================================
// PART 3: FRONTEND OAUTH FLOW (Svelte + PKCE)
// ============================================================================

/**
 * PKCE Pattern (Proof Key for Code Exchange)
 * 
 * Why: SPAs can't securely store client secrets, so PKCE adds extra layer.
 * Flow:
 * 1. Generate random code_verifier (43-128 chars)
 * 2. Create code_challenge = BASE64_URL(SHA256(code_verifier))
 * 3. Send code_challenge to Microsoft
 * 4. Microsoft verifies code_verifier when exchanging code
 * 
 * This prevents authorization code interception attacks.
 */

// Generate PKCE code verifier and challenge
function generatePKCE() {
  // Step 1: Generate random string 43-128 chars, base64url encoded
  const codeVerifier = Array.from(crypto.getRandomValues(new Uint8Array(32)))
    .map(b => String.fromCharCode(b))
    .join('');
  // Actually encode as base64url:
  const encoded = btoa(codeVerifier)
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
  
  // Step 2: Create code challenge = SHA256(verifier) -> base64url
  const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(encoded));
  const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(hash)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
  
  return { codeVerifier: encoded, codeChallenge };
}

// Initiate login
function initiateLogin() {
  const { codeVerifier, codeChallenge } = generatePKCE();
  
  // STORE code_verifier in sessionStorage (lost on page refresh, safe)
  sessionStorage.setItem('oauth_code_verifier', codeVerifier);
  
  // Generate state for CSRF protection
  const state = crypto.getRandomValues(new Uint8Array(16)).toString();
  sessionStorage.setItem('oauth_state', state);
  
  // Redirect to Microsoft login
  const params = new URLSearchParams({
    client_id: process.env.PUBLIC_MICROSOFT_CLIENT_ID,
    response_type: 'code',
    scope: 'https://graph.microsoft.com/User.Read https://graph.microsoft.com/Files.Read.All',
    redirect_uri: 'http://localhost:5173/auth/callback',
    code_challenge: codeChallenge,
    code_challenge_method: 'S256',
    state: state,
    prompt: 'select_account',  // Let user choose account
  });
  
  window.location.href = `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?${params.toString()}`;
}

// Handle callback (in /auth/callback route)
async function handleOAuthCallback() {
  // Step 1: Extract code and state from URL
  const params = new URLSearchParams(window.location.search);
  const code = params.get('code');
  const returnedState = params.get('state');
  
  if (!code || !returnedState) {
    throw new Error('Missing code or state in callback');
  }
  
  // Step 2: Verify state (CSRF protection)
  const storedState = sessionStorage.getItem('oauth_state');
  if (returnedState !== storedState) {
    throw new Error('State mismatch - possible CSRF attack');
  }
  
  // Step 3: Retrieve code verifier
  const codeVerifier = sessionStorage.getItem('oauth_code_verifier');
  if (!codeVerifier) {
    throw new Error('Code verifier not found');
  }
  
  // Step 4: Send to backend to exchange code for tokens
  const response = await fetch('/api/auth/authorize', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ code, state: returnedState, codeVerifier }),
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }
  
  const { accessToken, expiresIn, user } = await response.json();
  
  // Step 5: Store in Svelte stores and sessionStorage
  authStore.set({ user, accessToken, expiresIn });
  sessionStorage.setItem('ms_access_token', accessToken);
  sessionStorage.setItem('ms_token_expiry', (Date.now() + expiresIn * 1000).toString());
  
  // Clear OAuth temporary values
  sessionStorage.removeItem('oauth_code_verifier');
  sessionStorage.removeItem('oauth_state');
  
  // Redirect to home
  goto('/');
}

// ============================================================================
// PART 4: SERVICE WORKER TOKEN REFRESH LOGIC
// ============================================================================

/**
 * Service Worker: Background token refresh
 * 
 * Pattern: Service Worker periodically checks token expiry and refreshes
 * before expiration, updating the frontend via postMessage.
 * 
 * Why: Ensures frontend always has valid token without user interaction
 */

// In service-worker.ts
let tokenExpiry = 0;
let userId = '';

// Main loop: Check and refresh every minute
setInterval(async () => {
  if (!userId || Date.now() < tokenExpiry - 5 * 60 * 1000) {
    // Token still valid (5 minute buffer), skip
    return;
  }
  
  try {
    const response = await fetch('/api/auth/refresh', {
      method: 'POST',
      headers: { Authorization: `Bearer ${userId}` },
    });
    
    if (!response.ok) {
      // Refresh failed, notify frontend
      const clients = await self.clients.matchAll();
      clients.forEach(client => {
        client.postMessage({
          type: 'TOKEN_REFRESH_FAILED',
          needsReauth: true,
        });
      });
      return;
    }
    
    const { accessToken, expiresIn } = await response.json();
    
    // Update token expiry
    tokenExpiry = Date.now() + expiresIn * 1000;
    
    // Notify all clients of new token
    const clients = await self.clients.matchAll();
    clients.forEach(client => {
      client.postMessage({
        type: 'TOKEN_REFRESHED',
        accessToken,
        expiresIn,
      });
    });
  } catch (error) {
    console.error('Token refresh error:', error);
  }
}, 60 * 1000);  // Every 60 seconds

// ============================================================================
// PART 5: CONSTANTS & CONFIGURATION
// ============================================================================

// Environment variables required (in .env and secrets/.env)
const OAUTH_CONFIG = {
  MICROSOFT_CLIENT_ID: 'your-client-id',
  MICROSOFT_CLIENT_SECRET: 'your-secret',      // Backend only
  MICROSOFT_TENANT_ID: 'common',               // Or specific tenant
  MICROSOFT_REDIRECT_URI: 'http://localhost:5173/auth/callback',
};

// Graph API scopes needed
const GRAPH_SCOPES = [
  'https://graph.microsoft.com/User.Read',         // Read user profile
  'https://graph.microsoft.com/Files.Read.All',    // Read files in OneDrive
  'offline_access',                                // Required for refresh token
];

// ============================================================================
// PART 6: ERROR HANDLING CHECKLIST
// ============================================================================

/**
 * Common OAuth errors and how to handle them:
 * 
 * invalid_code / expired_code
 *   → User took too long to complete auth, or code was reused
 *   → Solution: Restart login flow
 * 
 * invalid_request
 *   → Missing required parameters (client_id, redirect_uri, code, etc)
 *   → Solution: Check all required params are sent correctly
 * 
 * unauthorized_client
 *   → Client not registered in Azure or not configured
 *   → Solution: Verify app registration in Azure portal
 * 
 * access_denied
 *   → User declined consent or permissions
 *   → Solution: Retry with proper scopes, or user chose to not authorize
 * 
 * invalid_scope
 *   → Requested scope not allowed for this app
 *   → Solution: Check scopes in app registration, match exactly
 * 
 * invalid_client
 *   → Client secret is wrong
 *   → Solution: Verify MICROSOFT_CLIENT_SECRET is correct
 * 
 * token_expired
 *   → Refresh token expired (24 hours for SPA)
 *   → Solution: User must re-authenticate
 * 
 * AADSTS_error_codes
 *   → Azure-specific errors (look up AADSTS number)
 *   → Solution: Check error_description, consult Azure docs
 */

// ============================================================================
// SUMMARY
// ============================================================================

/**
 * GOLDEN RULES for OAuth2 + Microsoft:
 * 
 * 1. NEVER expose CLIENT_SECRET to frontend
 * 2. ALWAYS use PKCE for SPA (code challenge/verifier)
 * 3. ALWAYS validate state parameter (CSRF protection)
 * 4. ALWAYS store refresh token on backend only
 * 5. STORE access token in memory or sessionStorage, NEVER localStorage
 * 6. ACCESS token expires in 1 hour, refresh BEFORE expiry
 * 7. REFRESH token expires in 24 hours, user must re-auth after
 * 8. Use SERVICE WORKER to refresh tokens in background
 * 9. SCOPE must include offline_access for refresh token
 * 10. Test with actual Microsoft account, not demo account
 */