@qwickapps/server 1.5.2 → 1.6.1

package/src/plugins/auth/AuthStatusWidget.test.tsx

@@ -0,0 +1,112 @@
+/**
+ * AuthStatusWidget 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 { AuthStatusWidget } from './AuthStatusWidget';
+
+describe('AuthStatusWidget', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders loading state initially', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => new Promise(() => {})
+    );
+
+    render(<AuthStatusWidget apiPrefix="/api/auth" />);
+
+    expect(screen.getByText(/Authentication Loading/)).toBeInTheDocument();
+  });
+
+  it('fetches and displays stats successfully', async () => {
+    const mockStats = {
+      totalProviders: 5,
+      activeProviders: 4,
+      totalSessions: 150,
+      activeSessions: 120,
+      recentLogins: 45,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<AuthStatusWidget apiPrefix="/api/auth" />);
+
+    await waitFor(() => {
+      expect(screen.getByText('Authentication')).toBeInTheDocument();
+      expect(screen.getByText(/Total Providers: 5/)).toBeInTheDocument();
+      expect(screen.getByText(/Active Providers: 4/)).toBeInTheDocument();
+      expect(screen.getByText(/Active Sessions: 120/)).toBeInTheDocument();
+      expect(screen.getByText(/Recent Logins: 45/)).toBeInTheDocument();
+    });
+
+    expect(global.fetch).toHaveBeenCalledWith('/api/auth/stats');
+  });
+
+  it('handles fetch error', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error('Auth service unavailable')
+    );
+
+    render(<AuthStatusWidget apiPrefix="/api/auth" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Auth service unavailable/)).toBeInTheDocument();
+    });
+  });
+
+  it('uses custom apiPrefix', async () => {
+    const mockStats = {
+      totalProviders: 3,
+      activeProviders: 3,
+      totalSessions: 50,
+      activeSessions: 40,
+      recentLogins: 10,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<AuthStatusWidget apiPrefix="/custom/auth" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalledWith('/custom/auth/stats');
+    });
+  });
+
+  it('displays all authentication metrics correctly', async () => {
+    const mockStats = {
+      totalProviders: 6,
+      activeProviders: 5,
+      totalSessions: 200,
+      activeSessions: 180,
+      recentLogins: 60,
+      health: 'healthy' as const,
+    };
+
+    (global.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce({
+      ok: true,
+      json: async () => mockStats,
+    });
+
+    render(<AuthStatusWidget apiPrefix="/api/auth" />);
+
+    await waitFor(() => {
+      expect(screen.getByText(/Total Providers: 6/)).toBeInTheDocument();
+      expect(screen.getByText(/Active Providers: 5/)).toBeInTheDocument();
+      expect(screen.getByText(/Active Sessions: 180/)).toBeInTheDocument();
+      expect(screen.getByText(/Recent Logins: 60/)).toBeInTheDocument();
+    });
+  });
+});

package/src/plugins/auth/AuthStatusWidget.tsx

@@ -0,0 +1,53 @@
+/**
+ * AuthStatusWidget - Dashboard widget for authentication overview
+ */
+
+import React, { useEffect, useState } from 'react';
+import { PluginStatusWidget } from '@qwickapps/server/ui';
+
+export interface AuthStatusWidgetProps {
+  /** API endpoint prefix (default: '/api/auth') */
+  apiPrefix?: string;
+}
+
+export function AuthStatusWidget({ apiPrefix = '/api/auth' }: AuthStatusWidgetProps) {
+  const [stats, setStats] = useState<{
+    totalProviders: number;
+    activeProviders: number;
+    totalSessions: number;
+    activeSessions: number;
+    recentLogins: 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="Authentication"
+      stats={[
+        { label: 'Total Providers', value: stats?.totalProviders ?? 0 },
+        { label: 'Active Providers', value: stats?.activeProviders ?? 0 },
+        { label: 'Active Sessions', value: stats?.activeSessions ?? 0 },
+        { label: 'Recent Logins', value: stats?.recentLogins ?? 0, suffix: '/7d' },
+      ]}
+      health={stats?.health ?? 'error'}
+      loading={loading}
+      error={error}
+      detailsPath="/cpanel/plugins/auth"
+    />
+  );
+}

package/src/plugins/auth/adapters/basic-adapter.ts

@@ -2,19 +2,73 @@
  * Basic Auth Adapter
  *
  * Provides HTTP Basic authentication for simple use cases.
+ * Supports both Authorization header and session cookies.
  *
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 
+import { createHmac, timingSafeEqual } from 'node:crypto';
 import type { Request, Response, RequestHandler } from 'express';
 import type { AuthAdapter, AuthenticatedUser, BasicAdapterConfig } from '../types.js';
 
+// Session cookie configuration
+const SESSION_COOKIE_NAME = 'cpanel_session';
+
+/**
+ * Verify a session token and check expiration
+ */
+function verifySessionToken(token: string, secret: string): boolean {
+  const parts = token.split(':');
+  if (parts.length !== 3 || parts[0] !== 'cpanel') {
+    return false;
+  }
+
+  const [prefix, expiresAt, signature] = parts;
+  const payload = `${prefix}:${expiresAt}`;
+
+  // Verify signature
+  const expectedSignature = createHmac('sha256', secret).update(payload).digest('hex');
+  try {
+    if (!timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
+      return false;
+    }
+  } catch {
+    return false;
+  }
+
+  // Check expiration
+  const expires = parseInt(expiresAt, 10);
+  if (isNaN(expires) || Date.now() > expires) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Parse cookies from Cookie header
+ */
+function parseCookies(cookieHeader: string | undefined): Record<string, string> {
+  const cookies: Record<string, string> = {};
+  if (!cookieHeader) return cookies;
+
+  cookieHeader.split(';').forEach((cookie) => {
+    const [name, ...rest] = cookie.trim().split('=');
+    if (name && rest.length > 0) {
+      cookies[name] = rest.join('=');
+    }
+  });
+
+  return cookies;
+}
+
 /**
  * Create a Basic authentication adapter
  */
 export function basicAdapter(config: BasicAdapterConfig): AuthAdapter {
   const expectedAuth = `Basic ${Buffer.from(`${config.username}:${config.password}`).toString('base64')}`;
   const realm = config.realm || 'Protected';
+  const sessionSecret = config.password; // Use password as session secret
 
   // Create a static user for basic auth
   const staticUser: AuthenticatedUser = {
@@ -34,6 +88,14 @@ export function basicAdapter(config: BasicAdapterConfig): AuthAdapter {
     },
 
     isAuthenticated(req: Request): boolean {
+      // Check for valid session cookie first
+      const cookies = parseCookies(req.headers.cookie);
+      const sessionToken = cookies[SESSION_COOKIE_NAME];
+      if (sessionToken && verifySessionToken(sessionToken, sessionSecret)) {
+        return true;
+      }
+
+      // Fall back to Authorization header
       const authHeader = req.headers.authorization;
       return authHeader === expectedAuth;
     },

package/src/plugins/auth/auth-plugin.ts

@@ -78,7 +78,7 @@ export function createAuthPlugin(config: AuthPluginConfig): Plugin {
       // Register auth status route
       registry.addRoute({
         method: 'get',
-        path: '/api/auth/status',
+        path: '/auth/status',
         handler: (_req: Request, res: Response) => {
           const authReq = _req as AuthenticatedRequest;
           res.json({

package/src/plugins/auth/env-config.ts

@@ -323,8 +323,8 @@ type AdapterName = (typeof VALID_ADAPTERS)[number];
 export function createAuthPluginFromEnv(options?: AuthEnvPluginOptions): Plugin {
   const adapterName = getEnv('AUTH_ADAPTER')?.toLowerCase();
 
-  // No adapter specified - return disabled plugin
-  if (!adapterName) {
+  // No adapter specified OR explicitly disabled - return disabled plugin
+  if (!adapterName || adapterName === 'none') {
     currentStatus = {
       state: 'disabled',
       adapter: null,
@@ -425,7 +425,7 @@ export function createAuthPluginFromEnv(options?: AuthEnvPluginOptions): Plugin
       await basePlugin.onStart?.(pluginConfig, registry);
 
       // Add config status routes
-      registerConfigRoutes(registry);
+      registerAuthConfigRoutes(registry);
     },
   };
 }
@@ -493,8 +493,18 @@ function getMaskedConfig(adapter: AdapterName): Record<string, string> {
 
 /**
  * Register config API routes
+ *
+ * IMPORTANT: These routes should be registered even when auth is disabled or in error state.
+ * This allows administrators to:
+ * - View current auth configuration status
+ * - See error messages for misconfigured auth
+ * - Update auth configuration at runtime
+ * - Test auth adapter connections
+ *
+ * Can be called from plugin onStart() to add auth configuration management endpoints.
+ * These routes allow viewing and updating auth configuration at runtime.
  */
-function registerConfigRoutes(registry: PluginRegistry): void {
+export function registerAuthConfigRoutes(registry: PluginRegistry): void {
   // GET /auth/config/status - Get current auth status
   registry.addRoute({
     method: 'get',
@@ -834,7 +844,7 @@ function createDisabledPlugin(): Plugin {
       logger.info('Auth plugin disabled - AUTH_ADAPTER not set');
 
       // Register status routes even when disabled
-      registerConfigRoutes(registry);
+      registerAuthConfigRoutes(registry);
     },
 
     async onStop(): Promise<void> {
@@ -858,7 +868,7 @@ function createErrorPlugin(error: string): Plugin {
       logger.error(`Auth plugin error: ${error}`);
 
       // Register status routes so admin can see the error
-      registerConfigRoutes(registry);
+      registerAuthConfigRoutes(registry);
     },
 
     async onStop(): Promise<void> {

package/src/plugins/auth/index.ts

@@ -21,6 +21,9 @@ export {
   getAuthStatus,
   setAuthConfigStore,
   getAdapterWrapper,
+  // Export for applications using createAuthPlugin directly (e.g., QwickSecrets)
+  // Allows them to add config routes without using createAuthPluginFromEnv wrapper
+  registerAuthConfigRoutes,
 } from './env-config.js';
 export type { AuthEnvPluginOptionsExtended } from './env-config.js';
 
@@ -61,3 +64,9 @@ export { auth0Adapter } from './adapters/auth0-adapter.js';
 export { basicAdapter } from './adapters/basic-adapter.js';
 export { supabaseAdapter } from './adapters/supabase-adapter.js';
 export { supertokensAdapter } from './adapters/supertokens-adapter.js';
+
+// UI Components
+export { AuthStatusWidget } from './AuthStatusWidget.js';
+export type { AuthStatusWidgetProps } from './AuthStatusWidget.js';
+export { AuthManagementPage } from './AuthManagementPage.js';
+export type { AuthManagementPageProps } from './AuthManagementPage.js';

package/src/plugins/bans/API_ROUTES.md

@@ -0,0 +1,183 @@
+# Bans Plugin API Routes
+
+This document describes the API routes needed to support the BansStatusWidget and BansManagementPage UI components.
+
+## Routes to Implement
+
+### 1. GET /api/bans/stats
+
+Returns ban statistics for the status widget.
+
+**Response:**
+```typescript
+{
+  totalBans: number;
+  activeBans: number;
+  permanentBans: number;
+  temporaryBans: number;
+  recentBans: number;  // Last 7 days
+  health: 'healthy' | 'warning' | 'error';
+}
+```
+
+### 2. GET /api/bans
+
+Returns paginated list of bans.
+
+**Query Parameters:**
+- `limit` - Max bans to return (default: 100)
+- `offset` - Pagination offset
+- `status` - Filter by status ('active', 'expired', 'lifted')
+- `type` - Filter by type ('permanent', 'temporary')
+- `userId` - Filter by user ID
+
+**Response:**
+```typescript
+{
+  bans: Array<{
+    id: string;
+    userId: string;
+    userEmail: string;
+    reason: string;
+    type: 'permanent' | 'temporary';
+    status: 'active' | 'expired' | 'lifted';
+    createdAt: string;
+    expiresAt?: string;
+    createdBy?: string;
+    metadata?: Record<string, unknown>;
+  }>;
+  total: number;
+}
+```
+
+### 3. GET /api/bans/:id
+
+Returns detailed information for a specific ban.
+
+**Response:**
+```typescript
+{
+  id: string;
+  userId: string;
+  userEmail: string;
+  reason: string;
+  type: 'permanent' | 'temporary';
+  status: 'active' | 'expired' | 'lifted';
+  createdAt: string;
+  expiresAt?: string;
+  liftedAt?: string;
+  createdBy?: string;
+  liftedBy?: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+### 4. POST /api/bans
+
+Creates a new ban.
+
+**Request Body:**
+```typescript
+{
+  userId: string;
+  reason: string;
+  type: 'permanent' | 'temporary';
+  expiresAt?: string;  // Required for temporary bans
+  metadata?: Record<string, unknown>;
+}
+```
+
+**Response:**
+```typescript
+{
+  id: string;
+  userId: string;
+  status: 'active';
+  createdAt: string;
+}
+```
+
+### 5. PATCH /api/bans/:id
+
+Updates a ban (lift, extend, modify reason).
+
+**Request Body:**
+```typescript
+{
+  status?: 'lifted';
+  reason?: string;
+  expiresAt?: string;
+}
+```
+
+**Response:**
+```typescript
+{
+  id: string;
+  status: string;
+  updatedAt: string;
+}
+```
+
+### 6. DELETE /api/bans/:id
+
+Permanently removes a ban record (admin only).
+
+**Response:**
+```typescript
+{
+  success: boolean;
+  message: string;
+}
+```
+
+### 7. POST /api/bans/lift
+
+Bulk lift multiple bans.
+
+**Request Body:**
+```typescript
+{
+  banIds: string[];
+  reason?: string;
+}
+```
+
+**Response:**
+```typescript
+{
+  success: boolean;
+  liftedCount: number;
+}
+```
+
+### 8. GET /api/bans/check/:userId
+
+Check if a user is currently banned.
+
+**Response:**
+```typescript
+{
+  isBanned: boolean;
+  ban?: {
+    id: string;
+    reason: string;
+    type: 'permanent' | 'temporary';
+    expiresAt?: string;
+  };
+}
+```
+
+## Security Considerations
+
+1. **Authentication**: All endpoints require admin authentication
+2. **Authorization**: Only admin roles can create and manage bans
+3. **Audit Logging**: Log all ban operations (create, lift, delete)
+4. **User Notification**: Notify users when banned or unbanned
+5. **Appeal Process**: Consider implementing ban appeal workflow
+6. **Escalation**: Track repeated ban violations
+7. **Privacy**: Handle ban reasons according to privacy regulations
+
+---
+
+Copyright (c) 2025 QwickApps.com. All rights reserved.

package/src/plugins/bans/BansManagementPage.test.tsx

@@ -0,0 +1,58 @@
+/**
+ * BansManagementPage 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 { BansManagementPage } from './BansManagementPage';
+
+describe('BansManagementPage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders page title', () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<BansManagementPage apiPrefix="/api/bans" />);
+
+    expect(screen.getByText('User Bans Management')).toBeInTheDocument();
+  });
+
+  it('fetches bans on mount', async () => {
+    (global.fetch as ReturnType<typeof vi.fn>).mockImplementation(
+      () => Promise.resolve({
+        ok: true,
+        json: async () => ([]),
+      })
+    );
+
+    render(<BansManagementPage apiPrefix="/api/bans" />);
+
+    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(<BansManagementPage apiPrefix="/custom/bans" />);
+
+    await waitFor(() => {
+      expect(global.fetch).toHaveBeenCalled();
+    });
+  });
+});