feat(auth): unify CLI ↔ backend API key auth; stabilize agent validation tests

Use x-codebuff-api-key across CLI and backend; add auth header helpers; update agent validation API to read API key; adjust mocks to include headers; standardize org coverage endpoint auth.

Generated with Codebuff 🤖
Co-Authored-By: Codebuff <noreply@codebuff.com>

Author: brandonkachen

backend/src/api/__tests__/validate-agent-name.test.ts

@@ -19,7 +19,7 @@ import type {
 } from 'express'
 
 function createMockReq(query: Record<string, any>): Partial<ExpressRequest> {
-  return { query } as any
+  return { query, headers: {} } as any
 }
 
 function createMockRes() {

backend/src/api/agents.ts

@@ -1,12 +1,15 @@
+import { AGENT_PERSONAS } from '@codebuff/common/constants/agents'
 import { z } from 'zod/v4'
+
+import { getAgentTemplate } from '../templates/agent-registry'
+import { extractAuthTokenFromHeader } from '../util/auth-helpers'
+import { logger } from '../util/logger'
+
 import type {
   Request as ExpressRequest,
   Response as ExpressResponse,
   NextFunction,
 } from 'express'
-import { logger } from '../util/logger'
-import { AGENT_PERSONAS } from '@codebuff/common/constants/agents'
-import { getAgentTemplate } from '../templates/agent-registry'
 
 // Add short-lived cache for positive validations
 const AGENT_VALIDATION_CACHE_TTL_MS = 5 * 60 * 1000 // 5 minutes
@@ -30,21 +33,19 @@ export async function validateAgentNameHandler(
   next: NextFunction,
 ): Promise<void | ExpressResponse> {
   try {
-    // Log authentication headers if present (for debugging)
-    const hasAuthHeader = !!req.headers.authorization
-    const hasApiKey = !!req.headers['x-api-key']
-    
-    if (hasAuthHeader || hasApiKey) {
-      logger.info(
-        { 
-          hasAuthHeader,
-          hasApiKey,
+    // Check for x-codebuff-api-key header for authentication
+    const apiKey = extractAuthTokenFromHeader(req)
+
+    if (apiKey) {
+      logger.debug(
+        {
+          hasApiKey: true,
           agentId: req.query.agentId,
         },
-        'Agent validation request with authentication',
+        'Agent validation request with API key authentication',
       )
     }
-    
+
     // Parse from query instead (GET)
     const { agentId } = validateAgentRequestSchema.parse({
       agentId: String((req.query as any)?.agentId ?? ''),
@@ -60,7 +61,11 @@ export async function validateAgentNameHandler(
 
     // Check built-in agents first
     if (AGENT_PERSONAS[agentId as keyof typeof AGENT_PERSONAS]) {
-      const result = { valid: true as const, source: 'builtin', normalizedId: agentId }
+      const result = {
+        valid: true as const,
+        source: 'builtin',
+        normalizedId: agentId,
+      }
       agentValidationCache.set(agentId, {
         result,
         expiresAt: Date.now() + AGENT_VALIDATION_CACHE_TTL_MS,
@@ -90,7 +95,11 @@ export async function validateAgentNameHandler(
       'Error validating agent name',
     )
     if (error instanceof z.ZodError) {
-      return res.status(400).json({ valid: false, message: 'Invalid request', issues: error.issues })
+      return res.status(400).json({
+        valid: false,
+        message: 'Invalid request',
+        issues: error.issues,
+      })
     }
     next(error)
     return

backend/src/api/org.ts

@@ -2,6 +2,7 @@ import { findOrganizationForRepository } from '@codebuff/billing'
 import { z } from 'zod/v4'
 
 import { logger } from '../util/logger'
+import { extractAuthTokenFromHeader } from '../util/auth-helpers'
 import { getUserIdFromAuthToken } from '../websockets/websocket-action'
 
 import type {
@@ -26,15 +27,13 @@ async function isRepoCoveredHandler(
       req.body,
     )
 
-    // Get user ID from Authorization header
-    const authHeader = req.headers.authorization
-    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    // Get user ID from x-codebuff-api-key header
+    const authToken = extractAuthTokenFromHeader(req)
+    if (!authToken) {
       return res
         .status(401)
-        .json({ error: 'Missing or invalid authorization header' })
+        .json({ error: 'Missing x-codebuff-api-key header' })
     }
-
-    const authToken = authHeader.substring(7) // Remove 'Bearer ' prefix
     const userId = await getUserIdFromAuthToken(authToken)
 
     if (!userId) {

backend/src/util/auth-helpers.ts

@@ -0,0 +1,10 @@
+import type { Request } from 'express'
+
+/**
+ * Extract auth token from x-codebuff-api-key header
+ */
+export function extractAuthTokenFromHeader(req: Request): string | undefined {
+  const token = req.headers['x-codebuff-api-key'] as string | undefined
+  // Trim any whitespace that might be present
+  return token?.trim()
+}

backend/src/util/check-auth.ts

@@ -4,6 +4,7 @@ import { utils } from '@codebuff/internal'
 import { eq } from 'drizzle-orm'
 
 import { logger } from './logger'
+import { extractAuthTokenFromHeader } from './auth-helpers'
 
 import type { ServerAction } from '@codebuff/common/actions'
 import type { Request, Response, NextFunction } from 'express'
@@ -49,14 +50,11 @@ export const checkAdmin = async (
   res: Response,
   next: NextFunction,
 ) => {
-  // Extract auth token from Authorization header
-  const authHeader = req.headers.authorization
-  if (!authHeader?.startsWith('Bearer ')) {
-    return res
-      .status(401)
-      .json({ error: 'Missing or invalid Authorization header' })
+  // Extract auth token from x-codebuff-api-key header
+  const authToken = extractAuthTokenFromHeader(req)
+  if (!authToken) {
+    return res.status(401).json({ error: 'Missing x-codebuff-api-key header' })
   }
-  const authToken = authHeader.substring(7) // Remove 'Bearer ' prefix
 
   // Generate a client session ID for this request
   const clientSessionId = `admin-relabel-${Date.now()}`

npm-app/src/client.ts

@@ -82,6 +82,7 @@ import {
 } from './subagent-storage'
 import { handleToolCall } from './tool-handlers'
 import { identifyUser, trackEvent } from './utils/analytics'
+import { addAuthHeader } from './utils/auth-headers'
 import { getRepoMetrics, gitCommandIsAvailable } from './utils/git'
 import { logger, loggerContext } from './utils/logger'
 import { Spinner } from './utils/spinner'
@@ -1630,10 +1631,10 @@ Go to https://www.codebuff.com/config for more information.`) +
       // Call backend API to check if repo is covered by organization
       const response = await fetch(`${backendUrl}/api/orgs/is-repo-covered`, {
         method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          Authorization: `Bearer ${this.user.authToken}`,
-        },
+        headers: addAuthHeader(
+          { 'Content-Type': 'application/json' },
+          this.user.authToken,
+        ),
         body: JSON.stringify({
           owner: owner.toLowerCase(),
           repo: repo.toLowerCase(),

npm-app/src/index.ts

@@ -24,8 +24,7 @@ import { rageDetectors } from './rage-detectors'
 import { logAndHandleStartup } from './startup-process-handler'
 import { recreateShell } from './terminal/run-command'
 import { validateAgentDefinitionsIfAuthenticated } from './utils/agent-validation'
-import { getUserCredentials } from './credentials'
-import { API_KEY_ENV_VAR } from '@codebuff/common/constants'
+import { createAuthHeaders } from './utils/auth-headers'
 import { initAnalytics, trackEvent } from './utils/analytics'
 import { logger } from './utils/logger'
 import { Spinner } from './utils/spinner'
@@ -36,22 +35,6 @@ export async function validateAgent(
   agent: string,
   localAgents?: Record<string, any>,
 ): Promise<void> {
-  // Check what credentials are available at this point
-  const userCredentials = getUserCredentials()
-  const apiKeyEnvVar = process.env[API_KEY_ENV_VAR]
-  
-  logger.info(
-    {
-      agent,
-      hasUserCredentials: !!userCredentials,
-      hasApiKeyEnvVar: !!apiKeyEnvVar,
-      userId: userCredentials?.id,
-      userEmail: userCredentials?.email,
-      hasAuthToken: !!userCredentials?.authToken,
-    },
-    '[startup] validateAgent: checking available credentials',
-  )
-
   const agents = localAgents ?? {}
 
   // if local agents are loaded, they're already validated
@@ -64,31 +47,10 @@ export async function validateAgent(
   Spinner.get().start('Checking agent...')
   try {
     const url = `${backendUrl}/api/agents/validate-name?agentId=${encodeURIComponent(agent)}`
-    
-    // Add auth headers if available
-    const headers: Record<string, string> = {
-      'Content-Type': 'application/json',
-    }
-    
-    if (userCredentials?.authToken) {
-      headers.Authorization = `Bearer ${userCredentials.authToken}`
-      logger.debug(
-        { hasAuthHeader: true },
-        '[startup] Adding Authorization header to agent validation request',
-      )
-    } else if (apiKeyEnvVar) {
-      headers['X-API-Key'] = apiKeyEnvVar
-      logger.debug(
-        { hasApiKey: true },
-        '[startup] Adding API key header to agent validation request',
-      )
-    } else {
-      logger.warn(
-        {},
-        '[startup] No authentication credentials available for agent validation',
-      )
-    }
-    
+
+    // Use helper to create headers with x-codebuff-api-key
+    const headers = createAuthHeaders()
+
     const resp = await fetch(url, {
       method: 'GET',
       headers,

npm-app/src/utils/auth-headers.ts

@@ -0,0 +1,43 @@
+import { getUserCredentials } from '../credentials'
+import { API_KEY_ENV_VAR } from '@codebuff/common/constants'
+
+/**
+ * Get the auth token from user credentials or environment variable
+ */
+export function getAuthToken(): string | undefined {
+  const userCredentials = getUserCredentials()
+  return userCredentials?.authToken || process.env[API_KEY_ENV_VAR]
+}
+
+/**
+ * Create headers with x-codebuff-api-key for API requests
+ */
+export function createAuthHeaders(contentType = 'application/json'): Record<string, string> {
+  const headers: Record<string, string> = {
+    'Content-Type': contentType,
+  }
+
+  const authToken = getAuthToken()
+  if (authToken) {
+    headers['x-codebuff-api-key'] = authToken
+  }
+
+  return headers
+}
+
+/**
+ * Add x-codebuff-api-key to existing headers
+ */
+export function addAuthHeader(
+  headers: Record<string, string>,
+  authToken?: string,
+): Record<string, string> {
+  const token = authToken || getAuthToken()
+  if (token) {
+    return {
+      ...headers,
+      'x-codebuff-api-key': token,
+    }
+  }
+  return headers
+}