Add API health endpoint /api/ping with authentication validation (#162)

* Initial plan

* Initial exploration and planning for /api/ping health endpoint

Co-authored-by: patrickrb <6586559+patrickrb@users.noreply.github.com>

* Implement /api/ping health endpoint with API key validation

Co-authored-by: patrickrb <6586559+patrickrb@users.noreply.github.com>

* Add detailed documentation to /api/ping endpoint

Co-authored-by: patrickrb <6586559+patrickrb@users.noreply.github.com>

* Fix API key validation in /api/ping endpoint

Co-authored-by: patrickrb <6586559+patrickrb@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: patrickrb <6586559+patrickrb@users.noreply.github.com>

Author: Copilot

package-lock.json

@@ -0,0 +1,136 @@
+// API health check endpoint
+// GET: Health check with API key validation
+// This endpoint provides a simple health check that validates API keys for client applications
+//
+// Usage:
+//   GET /api/ping
+//   Authorization: Bearer <api_key>
+//   OR X-API-Key: <api_key>
+//   OR ?api_key=<api_key>
+//
+// Response (success):
+//   {
+//     "success": true,
+//     "message": "API is healthy and API key is valid",
+//     "api_name": "Nextlog API",
+//     "api_version": "1.0.0", 
+//     "timestamp": "2025-09-19T22:45:28.588Z",
+//     "authenticated": true,
+//     "api_key_info": {
+//       "key_name": "My API Key",
+//       "is_read_only": false,
+//       "rate_limit_per_hour": 1000,
+//       "station_id": 1
+//     }
+//   }
+//
+// Response (error):
+//   {
+//     "success": false,
+//     "error": "API key is required",
+//     "timestamp": "2025-09-19T22:45:28.588Z"
+//   }
+
+import { NextRequest, NextResponse } from 'next/server';
+import { verifyApiKey } from '@/lib/api-auth';
+import { addCorsHeaders, createCorsPreflightResponse } from '@/lib/cors';
+
+// OPTIONS /api/ping - Handle CORS preflight requests
+export async function OPTIONS() {
+  return createCorsPreflightResponse();
+}
+
+// GET /api/ping - Health check with API key validation
+export async function GET(request: NextRequest) {
+  try {
+    // First, extract the API key manually to provide better error messages
+    let apiKey: string | null = null;
+
+    // 1. Check Authorization header (Bearer token format)
+    const authHeader = request.headers.get('authorization');
+    if (authHeader && authHeader.startsWith('Bearer ')) {
+      apiKey = authHeader.substring(7);
+    }
+
+    // 2. Check X-API-Key header (Cloudlog style)
+    if (!apiKey) {
+      apiKey = request.headers.get('x-api-key');
+    }
+
+    // 3. Check query parameters (for simple integrations)
+    if (!apiKey) {
+      const url = new URL(request.url);
+      apiKey = url.searchParams.get('api_key');
+    }
+
+    // Return appropriate error if no API key provided
+    if (!apiKey) {
+      const response = NextResponse.json({
+        success: false,
+        error: 'API key is required',
+        timestamp: new Date().toISOString()
+      }, { 
+        status: 401 
+      });
+      return addCorsHeaders(response);
+    }
+
+    // Check API key format
+    const isValidFormat = /^nextlog_[A-Za-z0-9]{32}$/.test(apiKey);
+    if (!isValidFormat) {
+      const response = NextResponse.json({
+        success: false,
+        error: 'Invalid API key format',
+        timestamp: new Date().toISOString()
+      }, { 
+        status: 401 
+      });
+      return addCorsHeaders(response);
+    }
+
+    // Now verify API key authentication with database
+    const authResult = await verifyApiKey(request);
+    
+    if (!authResult.success) {
+      // If we have a valid format key but database validation fails, 
+      // return the actual error from the auth system
+      const response = NextResponse.json({
+        success: false,
+        error: authResult.error || 'Authentication failed',
+        timestamp: new Date().toISOString()
+      }, { 
+        status: authResult.statusCode || 401 
+      });
+      return addCorsHeaders(response);
+    }
+
+    // API key is valid - return success response
+    const response = NextResponse.json({
+      success: true,
+      message: 'API is healthy and API key is valid',
+      api_name: 'Nextlog API',
+      api_version: '1.0.0',
+      timestamp: new Date().toISOString(),
+      authenticated: true,
+      api_key_info: {
+        key_name: authResult.auth!.keyName,
+        is_read_only: authResult.auth!.isReadOnly,
+        rate_limit_per_hour: authResult.auth!.rateLimitPerHour,
+        station_id: authResult.auth!.stationId
+      }
+    });
+    
+    return addCorsHeaders(response);
+
+  } catch (error) {
+    console.error('Ping endpoint error:', error);
+    const response = NextResponse.json({
+      success: false,
+      error: 'Internal server error',
+      timestamp: new Date().toISOString()
+    }, { 
+      status: 500 
+    });
+    return addCorsHeaders(response);
+  }
+}

src/app/api/ping/route.ts

@@ -0,0 +1,132 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('API Ping Health Endpoint', () => {
+  test('should reject requests without API key', async ({ request }) => {
+    const response = await request.get('/api/ping');
+    
+    expect(response.status()).toBe(401);
+    
+    const data = await response.json();
+    expect(data.success).toBe(false);
+    expect(data.error).toContain('API key is required');
+    expect(data.timestamp).toBeTruthy();
+  });
+
+  test('should reject requests with invalid API key format', async ({ request }) => {
+    // Test with invalid format
+    const response = await request.get('/api/ping', {
+      headers: {
+        'X-API-Key': 'invalid-key-format'
+      }
+    });
+    
+    expect(response.status()).toBe(401);
+    
+    const data = await response.json();
+    expect(data.success).toBe(false);
+    expect(data.error).toContain('Invalid API key format');
+    expect(data.timestamp).toBeTruthy();
+  });
+
+  test('should reject requests with non-existent API key', async ({ request }) => {
+    // Test with valid format but non-existent key
+    const response = await request.get('/api/ping', {
+      headers: {
+        'X-API-Key': 'nextlog_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
+      }
+    });
+    
+    // In test environment without database, expect either 401 (auth error) or 500 (db error)
+    expect([401, 500]).toContain(response.status());
+    
+    const data = await response.json();
+    expect(data.success).toBe(false);
+    expect(data.error).toBeTruthy();
+    expect(data.timestamp).toBeTruthy();
+  });
+
+  test('should support different authentication methods', async ({ request }) => {
+    const testKey = 'nextlog_test1234567890123456789012345';
+    
+    // Test X-API-Key header
+    const headerResponse = await request.get('/api/ping', {
+      headers: {
+        'X-API-Key': testKey
+      }
+    });
+    expect([401, 500]).toContain(headerResponse.status()); // Expected since key doesn't exist or no DB
+    
+    // Test Authorization Bearer header
+    const bearerResponse = await request.get('/api/ping', {
+      headers: {
+        'Authorization': `Bearer ${testKey}`
+      }
+    });
+    expect([401, 500]).toContain(bearerResponse.status()); // Expected since key doesn't exist or no DB
+    
+    // Test query parameter
+    const queryResponse = await request.get(`/api/ping?api_key=${testKey}`);
+    expect([401, 500]).toContain(queryResponse.status()); // Expected since key doesn't exist or no DB
+  });
+
+  test('should handle CORS preflight requests', async ({ request }) => {
+    const response = await request.fetch('/api/ping', {
+      method: 'OPTIONS'
+    });
+    
+    expect(response.status()).toBe(200);
+    expect(response.headers()['access-control-allow-origin']).toBe('*');
+    expect(response.headers()['access-control-allow-methods']).toContain('GET');
+    expect(response.headers()['access-control-allow-headers']).toContain('X-API-Key');
+    expect(response.headers()['access-control-allow-headers']).toContain('Authorization');
+  });
+
+  test('should include CORS headers in response', async ({ request }) => {
+    const response = await request.get('/api/ping');
+    
+    // Check CORS headers are present
+    expect(response.headers()['access-control-allow-origin']).toBe('*');
+    expect(response.headers()['access-control-allow-methods']).toContain('GET');
+    expect(response.headers()['access-control-allow-headers']).toContain('X-API-Key');
+  });
+
+  test('should return proper response structure on authentication failure', async ({ request }) => {
+    const response = await request.get('/api/ping');
+    
+    const data = await response.json();
+    
+    // Validate response structure
+    expect(data).toHaveProperty('success');
+    expect(data).toHaveProperty('error');
+    expect(data).toHaveProperty('timestamp');
+    expect(data.success).toBe(false);
+    expect(typeof data.timestamp).toBe('string');
+    
+    // Validate timestamp format (ISO 8601)
+    expect(new Date(data.timestamp).toISOString()).toBe(data.timestamp);
+  });
+
+  test('should handle server errors gracefully', async ({ request }) => {
+    // This test ensures the endpoint handles unexpected errors
+    // In a real scenario with a valid API key, it would test the success case
+    const response = await request.get('/api/ping', {
+      headers: {
+        'X-API-Key': 'nextlog_test1234567890123456789012345'
+      }
+    });
+    
+    // Should handle database connection errors gracefully
+    expect([401, 500]).toContain(response.status());
+    
+    const data = await response.json();
+    expect(data.success).toBe(false);
+    expect(data.timestamp).toBeTruthy();
+    expect(data.error).toBeTruthy();
+  });
+
+  test('should validate content type', async ({ request }) => {
+    const response = await request.get('/api/ping');
+    
+    expect(response.headers()['content-type']).toContain('application/json');
+  });
+});