The PKCE Guardian

// PKCE Flow Implementation for Single-Page Applications
// This flow is perfect for apps that cannot securely store a client_secret

// Step 1: Generate code verifier and challenge
function generateCodeVerifier() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return base64URLEncode(array);
}

function base64URLEncode(buffer) {
  return btoa(String.fromCharCode.apply(null, new Uint8Array(buffer)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}

async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const hash = await crypto.subtle.digest('SHA-256', data);
  return base64URLEncode(hash);
}

// Step 2: Initiate OAuth flow with PKCE
async function initiateOAuthFlowWithPKCE() {
  // Generate and store verifier
  const codeVerifier = generateCodeVerifier();
  sessionStorage.setItem('code_verifier', codeVerifier);

  // Generate challenge
  const codeChallenge = await generateCodeChallenge(codeVerifier);

  // Build authorization URL
  const authUrl = 'https://auth-server.com/oauth/authorize';
  const params = new URLSearchParams({
    response_type: 'code',
    client_id: 'your-public-client-id', // No secret needed!
    redirect_uri: 'https://yourapp.com/callback',
    scope: 'read write',
    state: generateRandomState(),
    code_challenge: codeChallenge,
    code_challenge_method: 'S256' // SHA-256
  });

  // Redirect user
  window.location.href = `${authUrl}?${params}`;
}

// Step 3: Handle callback and exchange code for tokens
async function handleOAuthCallback(authCode, state) {
  // Verify state
  if (state !== sessionStorage.getItem('oauth_state')) {
    throw new Error('State mismatch - possible CSRF attack!');
  }

  // Retrieve stored verifier
  const codeVerifier = sessionStorage.getItem('code_verifier');
  if (!codeVerifier) {
    throw new Error('Code verifier not found');
  }

  // Exchange code for tokens
  const tokenUrl = 'https://auth-server.com/oauth/token';
  const response = await fetch(tokenUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: authCode,
      redirect_uri: 'https://yourapp.com/callback',
      client_id: 'your-public-client-id',
      code_verifier: codeVerifier // The secret revealed!
    })
  });

  if (!response.ok) {
    throw new Error(`Token exchange failed: ${response.status}`);
  }

  const tokens = await response.json();
  // tokens = { access_token, refresh_token, expires_in, token_type }

  // Clean up
  sessionStorage.removeItem('code_verifier');
  sessionStorage.removeItem('oauth_state');

  return tokens;
}

// Step 4: Secure token storage (use httpOnly cookies on your backend proxy)
// For pure SPA, use memory storage with refresh token rotation
class TokenStore {
  constructor() {
    this.accessToken = null;
    this.refreshToken = null;
  }

  setTokens(accessToken, refreshToken) {
    this.accessToken = accessToken;
    this.refreshToken = refreshToken;
    // DO NOT store in localStorage (XSS vulnerable)
  }

  async getAccessToken() {
    // Check if token is expired, refresh if needed
    if (this.isTokenExpired()) {
      await this.refreshAccessToken();
    }
    return this.accessToken;
  }

  async refreshAccessToken() {
    const response = await fetch('https://auth-server.com/oauth/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        refresh_token: this.refreshToken,
        client_id: 'your-public-client-id'
      })
    });

    const tokens = await response.json();
    this.setTokens(tokens.access_token, tokens.refresh_token);
  }
}

// Helper functions
function generateRandomState() {
  const array = new Uint8Array(16);
  crypto.getRandomValues(array);
  const state = base64URLEncode(array);
  sessionStorage.setItem('oauth_state', state);
  return state;
}