@qwickapps/server 1.5.2 → 1.6.1

package/src/index.ts

@@ -76,9 +76,11 @@ export type {
 export {
   createHealthPlugin,
   createLogsPlugin,
+  createMaintenancePlugin,
   createConfigPlugin,
   createDiagnosticsPlugin,
   createFrontendAppPlugin,
+  createCMSPlugin,
   // Postgres plugin
   createPostgresPlugin,
   getPostgres,
@@ -92,6 +94,7 @@ export {
   createAuthPluginFromEnv,
   getAuthStatus,
   setAuthConfigStore,
+  registerAuthConfigRoutes,
   postgresAuthConfigStore,
   isAuthenticated,
   getAuthenticatedUser,
@@ -123,6 +126,17 @@ export {
   unbanUser,
   listActiveBans,
   postgresBanStore,
+  // API Keys plugin (M2M authentication, depends on Users)
+  createApiKeysPlugin,
+  getApiKeysStore,
+  verifyApiKey,
+  createApiKey,
+  listApiKeys,
+  getApiKey,
+  updateApiKey,
+  deleteApiKey,
+  postgresApiKeyStore,
+  bearerTokenAuth,
   // Entitlements plugin
   createEntitlementsPlugin,
   getEntitlementSource,
@@ -270,9 +284,11 @@ export {
 export type {
   HealthPluginConfig,
   LogsPluginConfig,
+  MaintenancePluginConfig,
   ConfigPluginConfig,
   DiagnosticsPluginConfig,
   FrontendAppPluginConfig,
+  CMSPluginConfig,
   // Postgres plugin types
   PostgresPluginConfig,
   PostgresInstance,
@@ -316,6 +332,17 @@ export type {
   RemoveBanInput,
   BanCallbacks,
   PostgresBanStoreConfig,
+  // API Keys plugin types
+  ApiKeysPluginConfig,
+  ApiKeyStore,
+  ApiKey,
+  ApiKeyWithPlaintext,
+  ApiKeyScope,
+  ApiKeyType,
+  CreateApiKeyParams,
+  UpdateApiKeyParams,
+  PostgresApiKeyStoreConfig,
+  ApiKeysApiConfig,
   // Entitlements plugin types
   EntitlementsPluginConfig,
   EntitlementSource,

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"
+    />
+  );
+}