Critical: Missing API key validation causes extension to fail silently

[aaron-seq]

Problem Description

The extension loads successfully but fails silently when API keys are missing or invalid. Users see no error messages, making it impossible to diagnose configuration issues[web:33].

Root Cause

No validation exists in the initialization flow to check if required API keys are configured before attempting AI operations.

Current Behavior

1. Extension installs without errors
2. Users click on features (summarize, Q&A, translate)
3. Operations fail silently with no feedback
4. Console shows generic network errors
5. Users don't know API key is missing/invalid

Code Locations

• background.js - Service worker initialization
• core/config-manager.js - Configuration management
• providers/ - AI provider integrations
• .env.example - Environment configuration template

Impact

• Severity: Critical
• Poor first-time user experience
• Increased support burden
• Users abandon extension thinking it's broken
• No clear setup instructions

Proposed Solution

Add Validation Layer

// core/validators/api-key-validator.ts
export interface ApiKeyStatus {
  provider: string;
  configured: boolean;
  valid: boolean;
  error?: string;
}

export async function validateApiKeys(): Promise<ApiKeyStatus[]> {
  const results: ApiKeyStatus[] = [];
  
  // Check OpenAI
  const openaiKey = await getApiKey('openai');
  if (openaiKey) {
    try {
      await testOpenAIConnection(openaiKey);
      results.push({ provider: 'OpenAI', configured: true, valid: true });
    } catch (error) {
      results.push({ 
        provider: 'OpenAI', 
        configured: true, 
        valid: false, 
        error: error.message 
      });
    }
  } else {
    results.push({ provider: 'OpenAI', configured: false, valid: false });
  }
  
  // Repeat for Claude, Gemini
  return results;
}

Show Setup Wizard on First Install

// background.js
chrome.runtime.onInstalled.addListener(async (details) => {
  if (details.reason === 'install') {
    // Check if any API keys configured
    const status = await validateApiKeys();
    const hasConfigured = status.some(s => s.configured && s.valid);
    
    if (!hasConfigured) {
      // Open setup page
      chrome.tabs.create({
        url: chrome.runtime.getURL('options.html?firstRun=true')
      });
    }
  }
});

Add Status Indicator in Popup

// popup.js
async function displayApiStatus() {
  const status = await validateApiKeys();
  const container = document.getElementById('api-status');
  
  if (status.every(s => !s.configured)) {
    container.innerHTML = `
      <div class="alert alert-warning">
        <p>No API keys configured. Features will not work.</p>
        <button onclick="openOptions()">Configure Now</button>
      </div>
    `;
  } else if (status.some(s => s.configured && !s.valid)) {
    container.innerHTML = `
      <div class="alert alert-error">
        <p>Some API keys are invalid. Check your settings.</p>
        <button onclick="openOptions()">Fix Configuration</button>
      </div>
    `;
  }
}

Required Changes

1. Create core/validators/ directory with API validation logic
2. Add first-run detection in background.js
3. Implement setup wizard in options.html
4. Add status indicator to popup.html
5. Show clear error messages for failed operations
6. Add connection test buttons in options page
7. Update documentation with setup instructions

User Experience Flow

1. Install extension
2. Setup wizard opens automatically
3. User enters API key(s)
4. Extension tests connection
5. Shows success/error immediately
6. Allows retrying with different key
7. Only enables features when valid key exists

Testing Requirements

• Test with no API keys
• Test with invalid API keys
• Test with valid API keys
• Test with mixed (some valid, some invalid)
• Test first-run flow
• Test validation caching
• Test error message clarity

Related Issues

• Empty .env.example file needs documentation
• Options page needs better UX for API key entry
• Error messages in console need user-friendly alternatives