@qwickapps/server 1.6.0 → 1.6.1

package/src/plugins/api-keys/API_ROUTES.md

@@ -0,0 +1,165 @@
+# API Keys Plugin API Routes
+
+This document describes the API routes needed to support the ApiKeysStatusWidget and ApiKeysManagementPage UI components.
+
+## Routes to Implement
+
+### 1. GET /api/api-keys/stats
+
+Returns API key statistics for the status widget.
+
+**Response:**
+```typescript
+{
+  totalKeys: number;
+  activeKeys: number;
+  expiredKeys: number;
+  revokedKeys: number;
+  recentlyUsed: number;  // Last 7 days
+  health: 'healthy' | 'warning' | 'error';
+}
+```
+
+### 2. GET /api/api-keys
+
+Returns paginated list of API keys.
+
+**Query Parameters:**
+- `limit` - Max keys to return (default: 100)
+- `offset` - Pagination offset
+- `status` - Filter by status ('active', 'expired', 'revoked')
+- `userId` - Filter by user ID
+
+**Response:**
+```typescript
+{
+  keys: Array<{
+    id: string;
+    name: string;
+    key: string;
+    userId?: string;
+    status: 'active' | 'expired' | 'revoked';
+    permissions: string[];
+    createdAt: string;
+    expiresAt?: string;
+    lastUsedAt?: string;
+    usageCount: number;
+  }>;
+  total: number;
+}
+```
+
+### 3. GET /api/api-keys/:id
+
+Returns detailed information for a specific API key.
+
+**Response:**
+```typescript
+{
+  id: string;
+  name: string;
+  key: string;
+  userId?: string;
+  status: 'active' | 'expired' | 'revoked';
+  permissions: string[];
+  createdAt: string;
+  expiresAt?: string;
+  lastUsedAt?: string;
+  usageCount: number;
+  metadata?: Record<string, unknown>;
+}
+```
+
+### 4. POST /api/api-keys
+
+Creates a new API key.
+
+**Request Body:**
+```typescript
+{
+  name: string;
+  userId?: string;
+  permissions: string[];
+  expiresAt?: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+**Response:**
+```typescript
+{
+  id: string;
+  name: string;
+  key: string;  // Full key shown only once
+  createdAt: string;
+}
+```
+
+### 5. PATCH /api/api-keys/:id
+
+Updates an API key (permissions, name, etc.).
+
+**Request Body:**
+```typescript
+{
+  name?: string;
+  permissions?: string[];
+  status?: 'active' | 'revoked';
+}
+```
+
+**Response:**
+```typescript
+{
+  id: string;
+  name: string;
+  status: string;
+  updatedAt: string;
+}
+```
+
+### 6. DELETE /api/api-keys/:id
+
+Revokes (soft deletes) an API key.
+
+**Response:**
+```typescript
+{
+  success: boolean;
+  message: string;
+}
+```
+
+### 7. POST /api/api-keys/revoke
+
+Bulk revoke multiple API keys.
+
+**Request Body:**
+```typescript
+{
+  keyIds: string[];
+}
+```
+
+**Response:**
+```typescript
+{
+  success: boolean;
+  revokedCount: number;
+}
+```
+
+## Security Considerations
+
+1. **Authentication**: All endpoints require authentication
+2. **Authorization**: Only authorized users can manage API keys
+3. **Key Storage**: Store hashed versions of keys, never plaintext
+4. **Key Display**: Show full key only once at creation
+5. **Rate Limiting**: Strict limits on key creation and usage
+6. **Audit Logging**: Log all key operations (create, revoke, usage)
+7. **Permissions**: Implement fine-grained permission checks
+8. **Expiration**: Enforce key expiration policies
+
+---
+
+Copyright (c) 2025 QwickApps.com. All rights reserved.

package/src/plugins/api-keys/ApiKeysManagementPage.test.tsx

@@ -0,0 +1,58 @@
+/**
+ * ApiKeysManagementPage Tests
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import { ApiKeysManagementPage } from './ApiKeysManagementPage';
+
+describe('ApiKeysManagementPage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders page title', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<ApiKeysManagementPage apiPrefix="/api/api-keys" />);
+
+    expect(screen.getByText('API Keys Management')).toBeInTheDocument();
+  });
+
+  it('fetches API keys on mount', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<ApiKeysManagementPage apiPrefix="/api/api-keys" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalled();
+    });
+  });
+
+  it('renders with custom apiPrefix', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<ApiKeysManagementPage apiPrefix="/custom/api-keys" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalled();
+    });
+  });
+});

package/src/plugins/api-keys/ApiKeysManagementPage.tsx

@@ -0,0 +1,131 @@
+/**
+ * ApiKeysManagementPage - Full management interface for API keys
+ */
+
+import React, { useState, useEffect } from 'react';
+import { PluginManagementPage } from '@qwickapps/server/ui';
+import { DataTable, Column } from '@qwickapps/react-framework';
+
+export interface ApiKeysManagementPageProps {
+  /** API endpoint prefix (default: '/api/api-keys') */
+  apiPrefix?: string;
+}
+
+interface ApiKey {
+  id: string;
+  name: string;
+  key: string;
+  userId?: string;
+  status: 'active' | 'expired' | 'revoked';
+  permissions: string[];
+  createdAt: string;
+  expiresAt?: string;
+  lastUsedAt?: string;
+  usageCount: number;
+}
+
+export function ApiKeysManagementPage({ apiPrefix = '/api/api-keys' }: ApiKeysManagementPageProps) {
+  const [activeTab, setActiveTab] = useState<'all' | 'active' | 'expired' | 'config'>('all');
+  const [keys, setKeys] = useState<ApiKey[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const status = activeTab === 'all' ? undefined : activeTab;
+    const url = status ? `${apiPrefix}?status=${status}` : `${apiPrefix}`;
+
+    fetch(url)
+      .then((res) => res.json())
+      .then((data) => {
+        setKeys(data.keys || []);
+        setLoading(false);
+      })
+      .catch(() => setLoading(false));
+  }, [activeTab, apiPrefix]);
+
+  const columns: Column<ApiKey>[] = [
+    { key: 'name', label: 'Name', sortable: true },
+    {
+      key: 'key',
+      label: 'API Key',
+      render: (val) => (
+        <code className="text-xs bg-gray-100 dark:bg-gray-800 px-2 py-1 rounded">
+          {String(val).substring(0, 20)}...
+        </code>
+      ),
+    },
+    {
+      key: 'status',
+      label: 'Status',
+      sortable: true,
+      render: (val) => (
+        <span
+          className={`px-2 py-1 rounded text-xs font-medium ${
+            val === 'active'
+              ? 'bg-green-100 dark:bg-green-900 text-green-800 dark:text-green-100'
+              : val === 'expired'
+              ? 'bg-yellow-100 dark:bg-yellow-900 text-yellow-800 dark:text-yellow-100'
+              : 'bg-red-100 dark:bg-red-900 text-red-800 dark:text-red-100'
+          }`}
+        >
+          {String(val)}
+        </span>
+      ),
+    },
+    {
+      key: 'permissions',
+      label: 'Permissions',
+      render: (val) => (
+        <span className="text-xs text-gray-600 dark:text-gray-400">
+          {Array.isArray(val) ? val.join(', ') : ''}
+        </span>
+      ),
+    },
+    { key: 'usageCount', label: 'Usage', sortable: true },
+    { key: 'lastUsedAt', label: 'Last Used', sortable: true },
+    { key: 'expiresAt', label: 'Expires', sortable: true },
+  ];
+
+  const handleRevoke = (selectedKeys: ApiKey[]) => {
+    console.log('Revoke keys:', selectedKeys);
+  };
+
+  const tabs = [
+    { id: 'all', label: 'All Keys' },
+    { id: 'active', label: 'Active' },
+    { id: 'expired', label: 'Expired' },
+    { id: 'config', label: 'Configuration' },
+  ];
+
+  return (
+    <PluginManagementPage
+      title="API Keys Management"
+      tabs={tabs}
+      activeTab={activeTab}
+      onTabChange={(tab) => setActiveTab(tab as typeof activeTab)}
+    >
+      {activeTab === 'config' ? (
+        <div className="space-y-4">
+          <div className="p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg">
+            <p className="text-sm text-blue-900 dark:text-blue-100">
+              API key configuration settings and security policies.
+            </p>
+          </div>
+        </div>
+      ) : (
+        <DataTable
+          columns={columns}
+          data={keys}
+          loading={loading}
+          emptyMessage="No API keys found"
+          bulkActions={[
+            {
+              label: 'Revoke Selected',
+              onClick: handleRevoke,
+              variant: 'danger',
+            },
+          ]}
+        />
+      )}
+    </PluginManagementPage>
+  );
+}

package/src/plugins/api-keys/ApiKeysStatusWidget.test.tsx

@@ -0,0 +1,112 @@
+/**
+ * ApiKeysStatusWidget Tests
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import { ApiKeysStatusWidget } from './ApiKeysStatusWidget';
+
+describe('ApiKeysStatusWidget', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders loading state initially', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => new Promise(() => {})
+    );
+
+    render(<ApiKeysStatusWidget apiPrefix="/api/api-keys" />);
+
+    expect(screen.getByText(/API Keys Loading/)).toBeInTheDocument();
+  });
+
+  it('fetches and displays stats successfully', async () => {
+    const mockStats = {
+      totalKeys: 100,
+      activeKeys: 85,
+      expiredKeys: 10,
+      revokedKeys: 5,
+      recentlyUsed: 45,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<ApiKeysStatusWidget apiPrefix="/api/api-keys" />);
+
+    await waitFor(() => {
+      expect(screen.getByText('API Keys')).toBeInTheDocument();
+      expect(screen.getByText(/Total Keys: 100/)).toBeInTheDocument();
+      expect(screen.getByText(/Active: 85/)).toBeInTheDocument();
+      expect(screen.getByText(/Expired: 10/)).toBeInTheDocument();
+      expect(screen.getByText(/Recently Used: 45/)).toBeInTheDocument();
+    });
+
+    expect(global.fetch).toHaveBeenCalledWith('/api/api-keys/stats');
+  });
+
+  it('handles fetch error', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error('API keys service error')
+    );
+
+    render(<ApiKeysStatusWidget apiPrefix="/api/api-keys" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/API keys service error/)).toBeInTheDocument();
+    });
+  });
+
+  it('uses custom apiPrefix', async () => {
+    const mockStats = {
+      totalKeys: 50,
+      activeKeys: 40,
+      expiredKeys: 5,
+      revokedKeys: 5,
+      recentlyUsed: 20,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<ApiKeysStatusWidget apiPrefix="/custom/api-keys" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalledWith('/custom/api-keys/stats');
+    });
+  });
+
+  it('displays all API key metrics correctly', async () => {
+    const mockStats = {
+      totalKeys: 150,
+      activeKeys: 120,
+      expiredKeys: 20,
+      revokedKeys: 10,
+      recentlyUsed: 80,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<ApiKeysStatusWidget apiPrefix="/api/api-keys" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Total Keys: 150/)).toBeInTheDocument();
+      expect(screen.getByText(/Active: 120/)).toBeInTheDocument();
+      expect(screen.getByText(/Expired: 20/)).toBeInTheDocument();
+      expect(screen.getByText(/Recently Used: 80/)).toBeInTheDocument();
+    });
+  });
+});

package/src/plugins/api-keys/ApiKeysStatusWidget.tsx

@@ -0,0 +1,53 @@
+/**
+ * ApiKeysStatusWidget - Dashboard widget for API keys overview
+ */
+
+import React, { useEffect, useState } from 'react';
+import { PluginStatusWidget } from '@qwickapps/server/ui';
+
+export interface ApiKeysStatusWidgetProps {
+  /** API endpoint prefix (default: '/api/api-keys') */
+  apiPrefix?: string;
+}
+
+export function ApiKeysStatusWidget({ apiPrefix = '/api/api-keys' }: ApiKeysStatusWidgetProps) {
+  const [stats, setStats] = useState<{
+    totalKeys: number;
+    activeKeys: number;
+    expiredKeys: number;
+    revokedKeys: number;
+    recentlyUsed: number;
+    health: 'healthy' | 'warning' | 'error';
+  } | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    fetch(`${apiPrefix}/stats`)
+      .then((res) => res.json())
+      .then((data) => {
+        setStats(data);
+        setLoading(false);
+      })
+      .catch((err) => {
+        setError(err.message);
+        setLoading(false);
+      });
+  }, [apiPrefix]);
+
+  return (
+    <PluginStatusWidget
+      title="API Keys"
+      stats={[
+        { label: 'Total Keys', value: stats?.totalKeys ?? 0 },
+        { label: 'Active', value: stats?.activeKeys ?? 0 },
+        { label: 'Expired', value: stats?.expiredKeys ?? 0 },
+        { label: 'Recently Used', value: stats?.recentlyUsed ?? 0, suffix: '/7d' },
+      ]}
+      health={stats?.health ?? 'error'}
+      loading={loading}
+      error={error}
+      detailsPath="/cpanel/plugins/api-keys"
+    />
+  );
+}

package/src/plugins/api-keys/api-keys-plugin.ts

@@ -32,8 +32,8 @@ let currentStore: ApiKeyStore | null = null;
  */
 export function createApiKeysPlugin(config: ApiKeysPluginConfig): Plugin {
   const debug = config.debug || false;
-  // Routes are mounted under /api by the control panel, so don't include /api in prefix
-  const apiPrefix = config.api?.prefix || '/api-keys';
+  // Framework automatically prefixes routes with plugin slug, so use root path
+  const apiPrefix = config.api?.prefix || '/';
   const apiEnabled = config.api?.enabled !== false;
 
   function log(message: string, data?: Record<string, unknown>) {
@@ -57,7 +57,18 @@ export function createApiKeysPlugin(config: ApiKeysPluginConfig): Plugin {
 
       // Initialize the store (creates tables and RLS policies if needed)
       await config.store.initialize();
-      log('API keys plugin migrations complete');
+      log('API keys store initialized');
+
+      // Initialize optional Phase 2 stores
+      if (config.scopeStore) {
+        await config.scopeStore.initialize();
+        log('Plugin scope store initialized');
+      }
+
+      if (config.usageStore) {
+        await config.usageStore.initialize();
+        log('Usage log store initialized');
+      }
 
       // Store reference for helper access
       currentStore = config.store;
@@ -289,6 +300,107 @@ export function createApiKeysPlugin(config: ApiKeysPluginConfig): Plugin {
             }
           },
         });
+
+        // Phase 2: GET /scopes - List all available scopes
+        if (config.scopeStore) {
+          registry.addRoute({
+            method: 'get',
+            path: '/scopes',
+            pluginId: 'api-keys',
+            handler: async (_req: Request, res: Response) => {
+              try {
+                const scopes = await config.scopeStore!.getAllScopes();
+
+                // Group by plugin
+                const grouped = scopes.reduce((acc, scope) => {
+                  if (!acc[scope.plugin_id]) {
+                    acc[scope.plugin_id] = [];
+                  }
+                  acc[scope.plugin_id].push({
+                    name: scope.name,
+                    description: scope.description,
+                    category: scope.category,
+                  });
+                  return acc;
+                }, {} as Record<string, Array<{ name: string; description: string; category?: string }>>);
+
+                // Convert to array format
+                const result = Object.entries(grouped).map(([pluginId, pluginScopes]) => ({
+                  pluginId,
+                  scopes: pluginScopes,
+                }));
+
+                res.json({ scopes: result });
+              } catch (error) {
+                console.error('[ApiKeysPlugin] Get scopes error:', error);
+                res.status(500).json({ error: 'Failed to retrieve scopes' });
+              }
+            },
+          });
+        }
+
+        // Phase 2: GET /api-keys/:id/usage - Get usage logs for a specific key
+        if (config.usageStore) {
+          registry.addRoute({
+            method: 'get',
+            path: `${apiPrefix}/:id/usage`,
+            pluginId: 'api-keys',
+            handler: async (req: Request, res: Response) => {
+              try {
+                const authReq = req as AuthenticatedRequest;
+                const userId = authReq.auth?.user?.id;
+
+                if (!userId) {
+                  return res.status(401).json({ error: 'Authentication required' });
+                }
+
+                const { id: keyId } = req.params;
+
+                // Verify key belongs to user
+                const key = await config.store.get(userId, keyId);
+                if (!key) {
+                  return res.status(404).json({ error: 'API key not found' });
+                }
+
+                // Parse query parameters
+                const limit = parseInt(req.query.limit as string) || 100;
+                const offset = parseInt(req.query.offset as string) || 0;
+                const since = req.query.since ? new Date(req.query.since as string) : undefined;
+                const until = req.query.until ? new Date(req.query.until as string) : undefined;
+                const endpoint = req.query.endpoint as string | undefined;
+                const method = req.query.method as string | undefined;
+                const statusCode = req.query.statusCode ? parseInt(req.query.statusCode as string) : undefined;
+
+                // Get usage logs
+                const logs = await config.usageStore!.getKeyUsage(keyId, {
+                  limit,
+                  offset,
+                  since,
+                  until,
+                  endpoint,
+                  method,
+                  statusCode,
+                });
+
+                // Get stats
+                const stats = await config.usageStore!.getKeyStats(keyId, { since, until });
+
+                res.json({
+                  keyId,
+                  keyName: key.name,
+                  totalCalls: stats.totalCalls,
+                  lastUsed: stats.lastUsed,
+                  callsByStatus: stats.callsByStatus,
+                  callsByEndpoint: stats.callsByEndpoint,
+                  logs,
+                });
+              } catch (error) {
+                console.error('[ApiKeysPlugin] Get usage error:', error);
+                res.status(500).json({ error: 'Failed to retrieve usage logs' });
+              }
+            },
+          });
+        }
       }
 
       log('API keys plugin started');
@@ -299,9 +411,33 @@ export function createApiKeysPlugin(config: ApiKeysPluginConfig): Plugin {
       if (currentStore) {
         await currentStore.shutdown();
       }
+      if (config.scopeStore) {
+        await config.scopeStore.shutdown();
+      }
+      if (config.usageStore) {
+        await config.usageStore.shutdown();
+      }
       currentStore = null;
       log('API keys plugin stopped');
     },
+
+    async onPluginEvent(event): Promise<void> {
+      // Automatically register plugin scopes when plugins start
+      if (event.type === 'plugin:started' && config.scopeStore) {
+        const { plugin } = event;
+
+        if (plugin.scopes && plugin.scopes.length > 0) {
+          try {
+            await config.scopeStore.registerScopes(plugin.id, plugin.scopes);
+            log(`Registered ${plugin.scopes.length} scopes for plugin: ${plugin.id}`, {
+              scopes: plugin.scopes.map(s => s.name),
+            });
+          } catch (error) {
+            console.error(`[ApiKeysPlugin] Failed to register scopes for ${plugin.id}:`, error);
+          }
+        }
+      }
+    },
   };
 }
 

package/src/plugins/api-keys/index.ts

@@ -47,3 +47,9 @@ export { postgresApiKeyStore } from './stores/index.js';
 
 // Middleware
 export { bearerTokenAuth } from './middleware/index.js';
+
+// UI Components
+export { ApiKeysStatusWidget } from './ApiKeysStatusWidget.js';
+export type { ApiKeysStatusWidgetProps } from './ApiKeysStatusWidget.js';
+export { ApiKeysManagementPage } from './ApiKeysManagementPage.js';
+export type { ApiKeysManagementPageProps } from './ApiKeysManagementPage.js';