@nextsparkjs/core 0.1.0-beta.82 → 0.1.0-beta.83

package/templates/app/api/v1/api-keys/[id]/route.ts

@@ -1,303 +0,0 @@
-/**
- * API Key Detail Routes
- * 
- * Core system endpoints for individual API key management.
- * Supports dual authentication (API Keys + Sessions).
- * 
- * Features:
- * - Get detailed API key information with usage stats
- * - Update API key name and status
- * - Revoke (soft delete) API keys
- * - Admin-only access control
- */
-
-import { NextRequest, NextResponse } from 'next/server';
-import { queryOneWithRLS, mutateWithRLS } from '@nextsparkjs/core/lib/db';
-import { 
-  createApiResponse, 
-  createApiError,
-  withApiLogging,
-  handleCorsPreflightRequest,
-  addCorsHeaders
-} from '@nextsparkjs/core/lib/api/helpers';
-import { authenticateRequest, hasRequiredScope } from '@nextsparkjs/core/lib/api/auth/dual-auth';
-
-// Handle CORS preflight
-export async function OPTIONS() {
-  return handleCorsPreflightRequest();
-}
-
-// GET /api/v1/api-keys/:id - Get specific API key details
-export const GET = withApiLogging(async (
-  req: NextRequest,
-  { params }: { params: Promise<{ id: string }> }
-): Promise<NextResponse> => {
-  try {
-    // Authenticate using dual auth
-    const authResult = await authenticateRequest(req);
-    
-    if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
-        { status: 401 }
-      );
-    }
-
-    if (authResult.rateLimitResponse) {
-      return authResult.rateLimitResponse as NextResponse;
-    }
-
-    // Check required permissions - session users have admin access, API key users need specific scope
-    const hasPermission = authResult.type === 'session' || 
-      (authResult.type === 'api-key' && hasRequiredScope(authResult, 'admin:api-keys'));
-
-    if (!hasPermission) {
-      const response = createApiError('Insufficient permissions. Admin access required for API key management.', 403);
-      return addCorsHeaders(response);
-    }
-
-    const { id } = await params;
-
-    if (!id || id.trim() === '') {
-      const response = createApiError('API key ID is required', 400, null, 'MISSING_API_KEY_ID');
-      return addCorsHeaders(response);
-    }
-
-    const apiKey = await queryOneWithRLS(
-      `SELECT id, "keyPrefix", name, scopes, status, "lastUsedAt", "expiresAt", "createdAt", "updatedAt"
-       FROM "api_key" 
-       WHERE id = $1 AND "userId" = $2`,
-      [id, authResult.user!.id],
-      authResult.user!.id
-    );
-
-    if (!apiKey) {
-      const response = createApiError('API key not found', 404, null, 'API_KEY_NOT_FOUND');
-      return addCorsHeaders(response);
-    }
-
-    // Get detailed usage statistics
-    let usageStats: {
-      total_requests: number;
-      last_24h: number;
-      last_7d: number;
-      last_30d: number;
-      avg_response_time: number;
-      success_rate: number;
-    } | null = null;
-    
-    try {
-      usageStats = await queryOneWithRLS<{
-        total_requests: number;
-        last_24h: number;
-        last_7d: number;
-        last_30d: number;
-        avg_response_time: number;
-        success_rate: number;
-      }>(
-        `SELECT 
-           COUNT(*) as total_requests,
-           COUNT(CASE WHEN "createdAt" > NOW() - INTERVAL '24 hours' THEN 1 END) as last_24h,
-           COUNT(CASE WHEN "createdAt" > NOW() - INTERVAL '7 days' THEN 1 END) as last_7d,
-           COUNT(CASE WHEN "createdAt" > NOW() - INTERVAL '30 days' THEN 1 END) as last_30d,
-           AVG("responseTime") as avg_response_time,
-           (COUNT(CASE WHEN "statusCode" < 400 THEN 1 END) * 100.0 / NULLIF(COUNT(*), 0)) as success_rate
-         FROM "api_audit_log" 
-         WHERE "apiKeyId" = $1`,
-        [id],
-        authResult.user!.id
-      );
-    } catch (error: unknown) {
-      // If api_audit_log table doesn't exist, use default stats
-      if (error && typeof error === 'object' && 'code' in error && error.code === '42P01') {
-        console.warn('api_audit_log table does not exist, returning default stats');
-        usageStats = null;
-      } else {
-        throw error;
-      }
-    }
-
-    const response = createApiResponse({
-      ...apiKey,
-      usage_stats: usageStats || {
-        total_requests: 0,
-        last_24h: 0,
-        last_7d: 0,
-        last_30d: 0,
-        avg_response_time: null,
-        success_rate: null
-      }
-    });
-    return addCorsHeaders(response);
-  } catch (error) {
-    console.error('Error fetching API key:', error);
-    const response = createApiError('Internal server error', 500);
-    return addCorsHeaders(response);
-  }
-});
-
-// PATCH /api/v1/api-keys/:id - Update API key (only name and active status)
-export const PATCH = withApiLogging(async (
-  req: NextRequest,
-  { params }: { params: Promise<{ id: string }> }
-): Promise<NextResponse> => {
-  try {
-    // Authenticate using dual auth
-    const authResult = await authenticateRequest(req);
-    
-    if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
-        { status: 401 }
-      );
-    }
-
-    if (authResult.rateLimitResponse) {
-      return authResult.rateLimitResponse as NextResponse;
-    }
-
-    // Check required permissions - session users have admin access, API key users need specific scope
-    const hasPermission = authResult.type === 'session' || 
-      (authResult.type === 'api-key' && hasRequiredScope(authResult, 'admin:api-keys'));
-
-    if (!hasPermission) {
-      const response = createApiError('Insufficient permissions. Admin access required for API key management.', 403);
-      return addCorsHeaders(response);
-    }
-
-    const { id } = await params;
-
-    if (!id || id.trim() === '') {
-      const response = createApiError('API key ID is required', 400, null, 'MISSING_API_KEY_ID');
-      return addCorsHeaders(response);
-    }
-
-    const body = await req.json();
-    
-    // Only allow updating name and status
-    const allowedUpdates = ['name', 'status'];
-    const updates = [];
-    const values = [];
-    let paramCount = 1;
-
-    for (const field of allowedUpdates) {
-      if (body[field] !== undefined) {
-        if (field === 'name' && typeof body[field] !== 'string') {
-          const response = createApiError('Name must be a string', 400, null, 'INVALID_NAME_TYPE');
-          return addCorsHeaders(response);
-        }
-        if (field === 'status' && !['active', 'inactive', 'expired'].includes(body[field])) {
-          const response = createApiError('status must be active, inactive, or expired', 400, null, 'INVALID_STATUS_TYPE');
-          return addCorsHeaders(response);
-        }
-        
-        updates.push(`"${field}" = $${paramCount++}`);
-        values.push(body[field]);
-      }
-    }
-
-    if (updates.length === 0) {
-      const response = createApiError('No valid fields to update', 400, null, 'NO_FIELDS');
-      return addCorsHeaders(response);
-    }
-
-    updates.push(`"updatedAt" = CURRENT_TIMESTAMP`);
-    values.push(id, authResult.user!.id);
-
-    const query = `
-      UPDATE "api_key" 
-      SET ${updates.join(", ")}
-      WHERE id = $${paramCount} AND "userId" = $${paramCount + 1}
-      RETURNING id, "keyPrefix", name, scopes, status, "lastUsedAt", "expiresAt", "createdAt", "updatedAt"
-    `;
-
-    const result = await mutateWithRLS(query, values, authResult.user!.id);
-
-    if (result.rows.length === 0) {
-      const response = createApiError('API key not found', 404, null, 'API_KEY_NOT_FOUND');
-      return addCorsHeaders(response);
-    }
-
-    const response = createApiResponse(result.rows[0]);
-    return addCorsHeaders(response);
-  } catch (error) {
-    console.error('Error updating API key:', error);
-    const response = createApiError('Internal server error', 500);
-    return addCorsHeaders(response);
-  }
-});
-
-// DELETE /api/v1/api-keys/:id - Revoke API key
-export const DELETE = withApiLogging(async (
-  req: NextRequest,
-  { params }: { params: Promise<{ id: string }> }
-): Promise<NextResponse> => {
-  try {
-    // Authenticate using dual auth
-    const authResult = await authenticateRequest(req);
-    
-    if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
-        { status: 401 }
-      );
-    }
-
-    if (authResult.rateLimitResponse) {
-      return authResult.rateLimitResponse as NextResponse;
-    }
-
-    // Check required permissions - session users have admin access, API key users need specific scope
-    const hasPermission = authResult.type === 'session' || 
-      (authResult.type === 'api-key' && hasRequiredScope(authResult, 'admin:api-keys'));
-
-    if (!hasPermission) {
-      const response = createApiError('Insufficient permissions. Admin access required for API key management.', 403);
-      return addCorsHeaders(response);
-    }
-
-    const { id } = await params;
-
-    if (!id || id.trim() === '') {
-      const response = createApiError('API key ID is required', 400, null, 'MISSING_API_KEY_ID');
-      return addCorsHeaders(response);
-    }
-
-    // For API key auth, prevent deletion of the current API key being used
-    if (authResult.type === 'api-key' && 'keyId' in authResult && id === authResult.keyId) {
-      const response = createApiError(
-        'Cannot revoke the API key currently being used', 
-        403, 
-        null, 
-        'SELF_REVOKE_FORBIDDEN'
-      );
-      return addCorsHeaders(response);
-    }
-
-    // Soft delete - just mark as inactive
-    const result = await mutateWithRLS(
-      `UPDATE "api_key" 
-       SET status = 'inactive', "updatedAt" = CURRENT_TIMESTAMP
-       WHERE id = $1 AND "userId" = $2
-       RETURNING id, name`,
-      [id, authResult.user!.id],
-      authResult.user!.id
-    );
-
-    if (result.rows.length === 0) {
-      const response = createApiError('API key not found', 404, null, 'API_KEY_NOT_FOUND');
-      return addCorsHeaders(response);
-    }
-
-    const response = createApiResponse({ 
-      revoked: true, 
-      id,
-      name: (result.rows[0] as { name: string }).name
-    });
-    return addCorsHeaders(response);
-  } catch (error) {
-    console.error('Error revoking API key:', error);
-    const response = createApiError('Internal server error', 500);
-    return addCorsHeaders(response);
-  }
-});

package/templates/app/api/v1/api-keys/docs.md

@@ -1,101 +0,0 @@
-# API Keys API
-
-Manage API keys for programmatic access to your team's resources.
-
-## Overview
-
-The API Keys API allows you to create, list, and revoke API keys. API keys provide server-to-server authentication and are scoped to a specific team.
-
-## Authentication
-
-All endpoints require authentication via:
-- **Session cookie** (for browser-based requests)
-
-Note: API key management requires session authentication for security.
-
-## Endpoints
-
-### List API Keys
-`GET /api/v1/api-keys`
-
-Returns all API keys for the current team.
-
-**Example Response:**
-```json
-{
-  "data": [
-    {
-      "id": "key_123",
-      "name": "Production API Key",
-      "prefix": "nsk_prod_",
-      "lastUsedAt": "2024-01-20T15:30:00Z",
-      "createdAt": "2024-01-15T10:30:00Z"
-    }
-  ]
-}
-```
-
-### Create API Key
-`POST /api/v1/api-keys`
-
-Create a new API key. The full key is only returned once on creation.
-
-**Request Body:**
-```json
-{
-  "name": "My API Key"
-}
-```
-
-**Response:**
-```json
-{
-  "id": "key_456",
-  "name": "My API Key",
-  "key": "nsk_prod_abc123xyz...",
-  "prefix": "nsk_prod_",
-  "createdAt": "2024-01-21T10:30:00Z"
-}
-```
-
-**Important:** Save the full `key` value immediately - it cannot be retrieved again.
-
-### Delete API Key
-`DELETE /api/v1/api-keys/[id]`
-
-Revoke an API key. This action is immediate and irreversible.
-
-**Path Parameters:**
-- `id` (string, required): API Key ID
-
-## Using API Keys
-
-Include the API key in the `x-api-key` header:
-
-```bash
-curl -H "x-api-key: nsk_prod_abc123xyz..." \
-     https://api.example.com/api/v1/customers
-```
-
-## Security Best Practices
-
-- Store API keys securely (environment variables, secrets manager)
-- Rotate keys periodically
-- Use different keys for different environments
-- Revoke keys immediately if compromised
-
-## Error Responses
-
-| Status | Description |
-|--------|-------------|
-| 400 | Bad Request - Invalid parameters |
-| 401 | Unauthorized - Session required |
-| 403 | Forbidden - Insufficient permissions |
-| 404 | Not Found - API key doesn't exist |
-
-## Related APIs
-
-- **[Auth](/api/v1/auth)** - Session-based authentication for browser requests
-- **[Teams](/api/v1/teams)** - API keys are scoped to teams
-- **[Dynamic Entities](/api/v1/{entity})** - Use API keys to access entity CRUD endpoints
-- **[Media](/api/v1/media)** - API keys support `media:read` and `media:write` scopes

package/templates/app/api/v1/api-keys/presets.ts

@@ -1,31 +0,0 @@
-/**
- * API Presets for API Keys
- *
- * These presets appear in the DevTools API Explorer's "Presets" tab.
- */
-
-import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
-
-export default defineApiEndpoint({
-  endpoint: '/api/v1/api-keys',
-  summary: 'Manage API keys for programmatic access',
-  presets: [
-    {
-      id: 'list-all',
-      title: 'List API Keys',
-      description: 'Fetch all API keys for the current team',
-      method: 'GET',
-      tags: ['read', 'list']
-    },
-    {
-      id: 'create-key',
-      title: 'Create API Key',
-      description: 'Create a new API key for the team',
-      method: 'POST',
-      payload: {
-        name: 'My New API Key'
-      },
-      tags: ['write', 'create']
-    }
-  ]
-})

package/templates/app/api/v1/api-keys/route.ts

@@ -1,250 +0,0 @@
-import { NextRequest, NextResponse } from 'next/server';
-import { queryWithRLS, mutateWithRLS } from '@nextsparkjs/core/lib/db';
-import { 
-  createApiResponse, 
-  createApiError,
-  withApiLogging,
-  handleCorsPreflightRequest,
-  addCorsHeaders
-} from '@nextsparkjs/core/lib/api/helpers';
-import { authenticateRequest, hasRequiredScope } from '@nextsparkjs/core/lib/api/auth/dual-auth';
-import { ApiKeyManager, API_SCOPES, API_KEY_LIMITS } from '@nextsparkjs/core/lib/api/keys';
-import { validateScopesForUser } from '@nextsparkjs/core/lib/api/auth';
-import { z } from 'zod';
-
-const createApiKeySchema = z.object({
-  name: z.string().min(1, 'Name is required').max(API_KEY_LIMITS.maxKeyNameLength, 'Name too long'),
-  scopes: z.array(z.string()).min(1, 'At least one scope is required'),
-  expiresAt: z.string().datetime().optional()
-});
-
-// Handle CORS preflight
-export async function OPTIONS() {
-  return handleCorsPreflightRequest();
-}
-
-// GET /api/v1/api-keys - List user's API keys with dual auth
-export const GET = withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
-  try {
-    // Authenticate using dual auth
-    const authResult = await authenticateRequest(req);
-    
-    if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
-        { status: 401 }
-      );
-    }
-
-    if (authResult.rateLimitResponse) {
-      return authResult.rateLimitResponse as NextResponse;
-    }
-
-    // Check required permissions - session users have admin access, API key users need specific scope
-    const hasPermission = authResult.type === 'session' || 
-      (authResult.type === 'api-key' && hasRequiredScope(authResult, 'admin:api-keys'));
-
-    if (!hasPermission) {
-      const response = createApiError('Insufficient permissions. Admin access required for API key management.', 403);
-      return addCorsHeaders(response);
-    }
-
-    const apiKeys = await queryWithRLS<{
-      id: string;
-      keyPrefix: string;
-      name: string;
-      scopes: string[];
-      status: 'active' | 'inactive' | 'expired';
-      lastUsedAt: string | null;
-      expiresAt: string | null;
-      createdAt: string;
-      updatedAt: string;
-    }>(
-      `SELECT id, "keyPrefix", name, scopes, status, "lastUsedAt", "expiresAt", "createdAt", "updatedAt"
-       FROM "api_key" 
-       WHERE "userId" = $1 
-       ORDER BY "createdAt" DESC`,
-      [authResult.user!.id],
-      authResult.user!.id
-    );
-
-    // Optimización: Una sola consulta para todas las estadísticas (evita N+1)
-    const keyIds = apiKeys.map(key => key.id);
-    let allStats: { 
-      apiKeyId: string;
-      total_requests: number; 
-      last_24h: number;
-      avg_response_time: number;
-    }[] = [];
-    
-    // Intentar obtener estadísticas si existe la tabla api_audit_log
-    if (keyIds.length > 0) {
-      try {
-        allStats = await queryWithRLS<{ 
-          apiKeyId: string;
-          total_requests: number; 
-          last_24h: number;
-          avg_response_time: number;
-        }>(
-          `SELECT 
-             "apiKeyId",
-             COUNT(*) as total_requests,
-             COUNT(CASE WHEN "createdAt" > NOW() - INTERVAL '24 hours' THEN 1 END) as last_24h,
-             AVG("responseTime") as avg_response_time
-           FROM "api_audit_log" 
-           WHERE "apiKeyId" = ANY($1)
-           GROUP BY "apiKeyId"`,
-          [keyIds],
-          authResult.user!.id
-        );
-      } catch (error: unknown) {
-        // Si la tabla api_audit_log no existe, simplemente usar estadísticas vacías
-        if (error && typeof error === 'object' && 'code' in error && error.code === '42P01') {
-          console.warn('api_audit_log table does not exist, returning empty stats');
-          allStats = [];
-        } else {
-          throw error;
-        }
-      }
-    }
-
-    // Crear mapa de estadísticas para lookup O(1)
-    const statsMap = new Map(
-      allStats.map(stat => [stat.apiKeyId, stat])
-    );
-
-    // Combinar datos con estadísticas
-    const keysWithStats = apiKeys.map((key) => ({
-      ...key,
-      usage_stats: statsMap.get(key.id) || { 
-        total_requests: 0, 
-        last_24h: 0, 
-        avg_response_time: null 
-      }
-    }));
-
-    const response = createApiResponse(keysWithStats);
-    return addCorsHeaders(response);
-  } catch (error) {
-    console.error('Error fetching API keys:', error);
-    const response = createApiError('Internal server error', 500);
-    return addCorsHeaders(response);
-  }
-});
-
-// POST /api/v1/api-keys - Create new API key with dual auth
-export const POST = withApiLogging(async (req: NextRequest): Promise<NextResponse> => {
-  try {
-    // Authenticate using dual auth
-    const authResult = await authenticateRequest(req);
-    
-    if (!authResult.success) {
-      return NextResponse.json(
-        { success: false, error: 'Authentication required', code: 'AUTHENTICATION_FAILED' },
-        { status: 401 }
-      );
-    }
-
-    if (authResult.rateLimitResponse) {
-      return authResult.rateLimitResponse as NextResponse;
-    }
-
-    // Check required permissions - session users have admin access, API key users need specific scope
-    const hasPermission = authResult.type === 'session' || 
-      (authResult.type === 'api-key' && hasRequiredScope(authResult, 'admin:api-keys'));
-
-    if (!hasPermission) {
-      const response = createApiError('Insufficient permissions. Admin access required for API key management.', 403);
-      return addCorsHeaders(response);
-    }
-
-    const body = await req.json();
-    const validatedData = createApiKeySchema.parse(body);
-
-    // Validar que los scopes sean válidos
-    const scopeValidation = ApiKeyManager.validateScopes(validatedData.scopes);
-    if (!scopeValidation.valid) {
-      const response = createApiError(
-        'Invalid scopes provided', 
-        400, 
-        { 
-          invalidScopes: scopeValidation.invalidScopes,
-          validScopes: Object.keys(API_SCOPES)
-        },
-        'INVALID_SCOPES'
-      );
-      return addCorsHeaders(response);
-    }
-
-    // Validar que el usuario pueda crear API keys con estos scopes
-    const userScopeValidation = await validateScopesForUser(authResult.user!.id, validatedData.scopes);
-    if (!userScopeValidation.valid) {
-      const response = createApiError(
-        'You do not have permission to create API keys with these scopes', 
-        403, 
-        { 
-          deniedScopes: userScopeValidation.deniedScopes,
-          allowedScopes: userScopeValidation.allowedScopes
-        },
-        'INSUFFICIENT_SCOPE_PERMISSIONS'
-      );
-      return addCorsHeaders(response);
-    }
-
-    // Verificar límite de API keys por usuario (máximo 10)
-    const existingKeysCount = await queryWithRLS<{ count: number }>(
-      'SELECT COUNT(*) as count FROM "api_key" WHERE "userId" = $1 AND status = $2',
-      [authResult.user!.id, 'active'],
-      authResult.user!.id
-    );
-
-    if ((existingKeysCount[0]?.count || 0) >= API_KEY_LIMITS.maxKeysPerUser) {
-      const response = createApiError(
-        `Maximum number of API keys reached (${API_KEY_LIMITS.maxKeysPerUser})`, 
-        429, 
-        null,
-        'API_KEY_LIMIT_REACHED'
-      );
-      return addCorsHeaders(response);
-    }
-
-    // Generar API key
-    const { key, hash, prefix } = await ApiKeyManager.generateApiKey();
-
-    // Guardar en DB
-    const result = await mutateWithRLS(
-      `INSERT INTO "api_key" (id, "keyHash", "keyPrefix", name, "userId", scopes, "expiresAt")
-       VALUES ($1, $2, $3, $4, $5, $6, $7) 
-       RETURNING id, "keyPrefix", name, scopes, status, "expiresAt", "createdAt"`,
-      [
-        globalThis.crypto.randomUUID(),
-        hash,
-        prefix,
-        validatedData.name,
-        authResult.user!.id,
-        validatedData.scopes,
-        validatedData.expiresAt || null
-      ],
-      authResult.user!.id
-    );
-
-    // Retornar la key completa SOLO una vez
-    const responseData = {
-      ...(result.rows[0] as Record<string, unknown>),
-      key, // Esta es la única vez que se muestra la key completa
-      warning: 'Save this API key now. You will not be able to see it again.'
-    };
-
-    const response = createApiResponse(responseData, { created: true }, 201);
-    return addCorsHeaders(response);
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      const response = createApiError('Validation error', 400, error.issues, 'VALIDATION_ERROR');
-      return addCorsHeaders(response);
-    }
-    
-    console.error('Error creating API key:', error);
-    const response = createApiError('Internal server error', 500);
-    return addCorsHeaders(response);
-  }
-});