@qwickapps/server 1.5.1 → 1.6.0

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

@@ -0,0 +1,243 @@
+/**
+ * API Keys Plugin Types
+ *
+ * Type definitions for API key authentication and management.
+ * Supports PostgreSQL with Row-Level Security (RLS) for data isolation.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import { z } from 'zod';
+
+/**
+ * API key scope type
+ */
+export type ApiKeyScope = 'read' | 'write' | 'admin';
+
+/**
+ * API key type (M2M = machine-to-machine, PAT = personal access token)
+ */
+export type ApiKeyType = 'm2m' | 'pat';
+
+/**
+ * API key record in the database
+ */
+export interface ApiKey {
+  /** Primary key - UUID */
+  id: string;
+  /** User ID (foreign key to users table) */
+  user_id: string;
+  /** Human-readable name for the key */
+  name: string;
+  /** Hashed API key (SHA-256) */
+  key_hash: string;
+  /** Key prefix for identification (e.g., 'qk_live_') - stored in plaintext */
+  key_prefix: string;
+  /** Key type: m2m (machine-to-machine) or pat (personal access token) */
+  key_type: ApiKeyType;
+  /** Scopes granted to this key */
+  scopes: ApiKeyScope[];
+  /** Last time this key was used */
+  last_used_at: Date | null;
+  /** Expiration date (null = never expires) */
+  expires_at: Date | null;
+  /** Whether the key is active */
+  is_active: boolean;
+  /** When the key was created */
+  created_at: Date;
+  /** When the key was last updated */
+  updated_at: Date;
+}
+
+/**
+ * API key creation parameters
+ */
+export interface CreateApiKeyParams {
+  /** User ID who owns this key */
+  user_id: string;
+  /** Human-readable name for the key */
+  name: string;
+  /** Key type: m2m or pat */
+  key_type: ApiKeyType;
+  /** Scopes to grant */
+  scopes: ApiKeyScope[];
+  /** Optional expiration date */
+  expires_at?: Date;
+}
+
+/**
+ * API key update parameters
+ */
+export interface UpdateApiKeyParams {
+  /** New name (optional) */
+  name?: string;
+  /** New scopes (optional) */
+  scopes?: ApiKeyScope[];
+  /** New expiration date (optional) */
+  expires_at?: Date;
+  /** Activate/deactivate key (optional) */
+  is_active?: boolean;
+}
+
+/**
+ * API key with plaintext key (only returned on creation)
+ */
+export interface ApiKeyWithPlaintext extends ApiKey {
+  /** Plaintext API key - only available on creation */
+  plaintext_key: string;
+}
+
+/**
+ * API key store interface - all storage backends must implement this
+ */
+export interface ApiKeyStore {
+  /** Store name (e.g., 'postgres', 'memory') */
+  name: string;
+
+  /**
+   * Initialize the store (create tables, RLS policies, etc.)
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Create a new API key
+   * Returns the key with plaintext value (only time plaintext is accessible)
+   */
+  create(params: CreateApiKeyParams): Promise<ApiKeyWithPlaintext>;
+
+  /**
+   * Get all API keys for a user
+   */
+  list(userId: string): Promise<ApiKey[]>;
+
+  /**
+   * Get a specific API key by ID
+   * Returns null if key doesn't exist or doesn't belong to user
+   */
+  get(userId: string, keyId: string): Promise<ApiKey | null>;
+
+  /**
+   * Verify an API key and return the associated key record
+   * Returns null if key is invalid, expired, or inactive
+   */
+  verify(plaintextKey: string): Promise<ApiKey | null>;
+
+  /**
+   * Update an API key
+   * Returns the updated key or null if key doesn't exist
+   */
+  update(userId: string, keyId: string, params: UpdateApiKeyParams): Promise<ApiKey | null>;
+
+  /**
+   * Delete an API key
+   * Returns true if key was deleted, false if it didn't exist
+   */
+  delete(userId: string, keyId: string): Promise<boolean>;
+
+  /**
+   * Record key usage (updates last_used_at timestamp)
+   */
+  recordUsage(keyId: string): Promise<void>;
+
+  /**
+   * Shutdown the store
+   */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * PostgreSQL API key store configuration
+ */
+export interface PostgresApiKeyStoreConfig {
+  /** PostgreSQL pool instance or a function that returns one (for lazy initialization) */
+  pool: unknown | (() => unknown);
+  /** Table name (default: 'api_keys') */
+  tableName?: string;
+  /** Schema name (default: 'public') */
+  schema?: string;
+  /** Auto-create tables on init (default: true) */
+  autoCreateTables?: boolean;
+  /** Enable RLS (default: true) */
+  enableRLS?: boolean;
+  /** Key expiration in days (default: 90, null = never expires) */
+  defaultExpirationDays?: number | null;
+  /** Environment for key prefix (default: from NODE_ENV, 'test' in non-production, 'live' in production) */
+  environment?: 'test' | 'live';
+}
+
+/**
+ * API keys API configuration
+ */
+export interface ApiKeysApiConfig {
+  /** API route prefix (default: '/api-keys') */
+  prefix?: string;
+  /** Enable API endpoints (default: true) */
+  enabled?: boolean;
+}
+
+/**
+ * API keys plugin configuration
+ */
+export interface ApiKeysPluginConfig {
+  /** API key storage backend */
+  store: ApiKeyStore;
+  /** API configuration */
+  api?: ApiKeysApiConfig;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+// ============================================================================
+// Zod Validation Schemas
+// ============================================================================
+
+/**
+ * Zod schema for API key scope
+ */
+export const ApiKeyScopeSchema = z.enum(['read', 'write', 'admin']);
+
+/**
+ * Zod schema for API key type
+ */
+export const ApiKeyTypeSchema = z.enum(['m2m', 'pat']);
+
+/**
+ * Zod schema for creating an API key
+ */
+export const CreateApiKeySchema = z.object({
+  name: z.string().min(1).max(255),
+  key_type: ApiKeyTypeSchema,
+  scopes: z.array(ApiKeyScopeSchema).min(1),
+  expires_at: z.coerce.date().optional(),
+});
+
+/**
+ * Zod schema for updating an API key
+ */
+export const UpdateApiKeySchema = z.object({
+  name: z.string().min(1).max(255).optional(),
+  scopes: z.array(ApiKeyScopeSchema).min(1).optional(),
+  expires_at: z.coerce.date().optional(),
+  is_active: z.boolean().optional(),
+}).refine(
+  (data) => Object.keys(data).length > 0,
+  { message: 'At least one field must be provided for update' }
+);
+
+/**
+ * Zod schema for API key record
+ */
+export const ApiKeySchema = z.object({
+  id: z.string().uuid(),
+  user_id: z.string().uuid(),
+  name: z.string(),
+  key_hash: z.string(),
+  key_prefix: z.string(),
+  key_type: ApiKeyTypeSchema,
+  scopes: z.array(ApiKeyScopeSchema),
+  last_used_at: z.coerce.date().nullable(),
+  expires_at: z.coerce.date().nullable(),
+  is_active: z.boolean(),
+  created_at: z.coerce.date(),
+  updated_at: z.coerce.date(),
+});

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

@@ -174,3 +174,170 @@ describe('Auth Plugin helpers', () => {
     expect(authModule.requireAnyRole).toBeDefined();
   });
 });
+
+describe('onAuthenticated callback', () => {
+  // Mock adapter that always authenticates
+  function createMockAdapter(user: AuthenticatedUser | null): ReturnType<typeof basicAdapter> {
+    return {
+      name: 'mock',
+      initialize: () => (_req: Request, _res: Response, next: NextFunction) => next(),
+      isAuthenticated: () => user !== null,
+      getUser: () => user,
+    };
+  }
+
+  it('should call onAuthenticated callback after successful authentication', async () => {
+    const { createAuthPlugin } = await import('./auth-plugin.js');
+    const mockUser: AuthenticatedUser = {
+      id: 'user-123',
+      email: 'test@example.com',
+      name: 'Test User',
+    };
+    const onAuthenticated = vi.fn().mockResolvedValue(undefined);
+
+    const plugin = createAuthPlugin({
+      adapter: createMockAdapter(mockUser),
+      authRequired: false,
+      onAuthenticated,
+    });
+
+    // Create mock registry
+    const mockApp = {
+      use: vi.fn(),
+    };
+    const mockRegistry = {
+      getApp: () => mockApp,
+      addRoute: vi.fn(),
+    };
+
+    // Start the plugin to register middleware
+    await plugin.onStart?.({} as never, mockRegistry as never);
+
+    // Get the auth middleware (last middleware added)
+    const authMiddleware = mockApp.use.mock.calls[mockApp.use.mock.calls.length - 1][0];
+
+    // Call middleware
+    const req = createMockRequest();
+    const res = createMockResponse();
+    const next = vi.fn();
+
+    await authMiddleware(req, res, next);
+
+    expect(onAuthenticated).toHaveBeenCalledWith(mockUser);
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('should not call onAuthenticated when authentication fails', async () => {
+    const { createAuthPlugin } = await import('./auth-plugin.js');
+    const onAuthenticated = vi.fn().mockResolvedValue(undefined);
+
+    const plugin = createAuthPlugin({
+      adapter: createMockAdapter(null), // null user = not authenticated
+      authRequired: false,
+      onAuthenticated,
+    });
+
+    const mockApp = {
+      use: vi.fn(),
+    };
+    const mockRegistry = {
+      getApp: () => mockApp,
+      addRoute: vi.fn(),
+    };
+
+    await plugin.onStart?.({} as never, mockRegistry as never);
+
+    const authMiddleware = mockApp.use.mock.calls[mockApp.use.mock.calls.length - 1][0];
+
+    const req = createMockRequest();
+    const res = createMockResponse();
+    const next = vi.fn();
+
+    await authMiddleware(req, res, next);
+
+    expect(onAuthenticated).not.toHaveBeenCalled();
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('should not fail authentication when onAuthenticated throws an error', async () => {
+    const { createAuthPlugin } = await import('./auth-plugin.js');
+    const mockUser: AuthenticatedUser = {
+      id: 'user-123',
+      email: 'test@example.com',
+      name: 'Test User',
+    };
+    const onAuthenticated = vi.fn().mockRejectedValue(new Error('Sync failed'));
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    const plugin = createAuthPlugin({
+      adapter: createMockAdapter(mockUser),
+      authRequired: false,
+      onAuthenticated,
+    });
+
+    const mockApp = {
+      use: vi.fn(),
+    };
+    const mockRegistry = {
+      getApp: () => mockApp,
+      addRoute: vi.fn(),
+    };
+
+    await plugin.onStart?.({} as never, mockRegistry as never);
+
+    const authMiddleware = mockApp.use.mock.calls[mockApp.use.mock.calls.length - 1][0];
+
+    const req = createMockRequest();
+    const res = createMockResponse();
+    const next = vi.fn();
+
+    await authMiddleware(req, res, next);
+
+    // Callback was called
+    expect(onAuthenticated).toHaveBeenCalledWith(mockUser);
+    // Error was logged
+    expect(consoleSpy).toHaveBeenCalled();
+    // Request still proceeds
+    expect(next).toHaveBeenCalled();
+    // Auth info is still set correctly
+    expect((req as unknown as { auth: { isAuthenticated: boolean } }).auth.isAuthenticated).toBe(true);
+
+    consoleSpy.mockRestore();
+  });
+
+  it('should not call onAuthenticated when callback is not provided', async () => {
+    const { createAuthPlugin } = await import('./auth-plugin.js');
+    const mockUser: AuthenticatedUser = {
+      id: 'user-123',
+      email: 'test@example.com',
+      name: 'Test User',
+    };
+
+    const plugin = createAuthPlugin({
+      adapter: createMockAdapter(mockUser),
+      authRequired: false,
+      // No onAuthenticated callback
+    });
+
+    const mockApp = {
+      use: vi.fn(),
+    };
+    const mockRegistry = {
+      getApp: () => mockApp,
+      addRoute: vi.fn(),
+    };
+
+    await plugin.onStart?.({} as never, mockRegistry as never);
+
+    const authMiddleware = mockApp.use.mock.calls[mockApp.use.mock.calls.length - 1][0];
+
+    const req = createMockRequest();
+    const res = createMockResponse();
+    const next = vi.fn();
+
+    // Should not throw
+    await authMiddleware(req, res, next);
+
+    expect(next).toHaveBeenCalled();
+  });
+});

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

@@ -38,6 +38,7 @@ export function createAuthPlugin(config: AuthPluginConfig): Plugin {
     id: 'auth',
     name: 'Auth Plugin',
     version: '1.0.0',
+    type: 'system' as const,
 
     async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
       const app = registry.getApp();
@@ -77,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({
@@ -181,6 +182,21 @@ export function createAuthPlugin(config: AuthPluginConfig): Plugin {
         accessToken: activeAdapter.getAccessToken?.(req) || undefined,
       };
 
+      // Call onAuthenticated callback if provided and user is authenticated
+      if (authenticated && user && config.onAuthenticated) {
+        try {
+          await config.onAuthenticated(user);
+          log('onAuthenticated callback completed', { userId: user.id, email: user.email });
+        } catch (error) {
+          // Log error but don't fail the request - auth succeeded, sync is optional
+          console.error('[AuthPlugin] onAuthenticated callback error:', {
+            userId: user.id,
+            email: user.email,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+
       // Check if auth is required but user is not authenticated
       if (authRequired && !authenticated) {
         log('Auth required but not authenticated', { path: req.path });

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,
@@ -403,6 +403,7 @@ export function createAuthPluginFromEnv(options?: AuthEnvPluginOptions): Plugin
     authRequired,
     debug,
     onUnauthorized: options?.onUnauthorized,
+    onAuthenticated: options?.onAuthenticated,
   };
 
   // Update status
@@ -418,6 +419,7 @@ export function createAuthPluginFromEnv(options?: AuthEnvPluginOptions): Plugin
   // Wrap to add config status routes
   return {
     ...basePlugin,
+    type: 'system' as const,  // Explicit system type (auth can handle any path)
     async onStart(pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
       // Call base plugin onStart
       await basePlugin.onStart?.(pluginConfig, registry);
@@ -825,6 +827,7 @@ function createDisabledPlugin(): Plugin {
     id: 'auth',
     name: 'Auth Plugin (Disabled)',
     version: '1.0.0',
+    type: 'system' as const,
 
     async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
       const logger = registry.getLogger('auth');
@@ -848,6 +851,7 @@ function createErrorPlugin(error: string): Plugin {
     id: 'auth',
     name: 'Auth Plugin (Error)',
     version: '1.0.0',
+    type: 'system' as const,
 
     async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
       const logger = registry.getLogger('auth');

package/src/plugins/auth/types.ts

@@ -182,6 +182,11 @@ export interface AuthPluginConfig {
   authRequired?: boolean;
   /** Custom unauthorized handler */
   onUnauthorized?: (req: Request, res: Response) => void;
+  /**
+   * Callback invoked after successful authentication.
+   * Use this to sync users to a local database on first login.
+   */
+  onAuthenticated?: (user: AuthenticatedUser) => Promise<void>;
   /** Enable debug logging */
   debug?: boolean;
 }
@@ -226,6 +231,11 @@ export interface AuthEnvPluginOptions {
   debug?: boolean;
   /** Custom unauthorized handler */
   onUnauthorized?: (req: Request, res: Response) => void;
+  /**
+   * Callback invoked after successful authentication.
+   * Use this to sync users to a local database on first login.
+   */
+  onAuthenticated?: (user: AuthenticatedUser) => Promise<void>;
 }
 
 /**

package/src/plugins/devices/__tests__/token-utils.test.ts

@@ -24,13 +24,15 @@ describe('Token Utilities', () => {
 
     it('should generate a 43-character secret after prefix', async () => {
       const result = await generateDeviceToken('mob');
-      const secret = result.token.split('_')[1];
+      // Use slice to get everything after 'mob_' since base64url can contain '_'
+      const secret = result.token.slice(4); // 'mob_'.length = 4
       expect(secret.length).toBe(43);
     });
 
     it('should generate base64url-safe characters', async () => {
       const result = await generateDeviceToken('test');
-      const secret = result.token.split('_')[1];
+      // Use slice to get everything after 'test_' since base64url can contain '_'
+      const secret = result.token.slice(5); // 'test_'.length = 5
       expect(secret).toMatch(/^[A-Za-z0-9_-]+$/);
     });
 

package/src/plugins/frontend-app-plugin.ts

@@ -50,6 +50,7 @@ export function createFrontendAppPlugin(config: FrontendAppPluginConfig): Plugin
     id: 'frontend-app',
     name: 'Frontend App Plugin',
     version: '1.0.0',
+    type: 'system' as const,
 
     async onStart(_pluginConfig: PluginConfig, registry: PluginRegistry): Promise<void> {
       const logger = registry.getLogger('frontend-app');
@@ -80,11 +81,30 @@ export function createFrontendAppPlugin(config: FrontendAppPluginConfig): Plugin
       // Priority 2: Serve static files
       if (config.staticPath && existsSync(config.staticPath)) {
         logger.info(`Frontend app: Serving static files from ${config.staticPath}`);
-        app.use('/', express.static(config.staticPath));
 
-        // SPA fallback
-        app.get('/', (_req, res) => {
-          res.sendFile(resolve(config.staticPath!, 'index.html'));
+        // Serve static assets first
+        app.use(express.static(config.staticPath, { index: false }));
+
+        // SPA fallback for all non-API routes
+        // This must be registered after static files but handles routes that don't match files
+        app.get('*', (req, res, next) => {
+          // Skip API routes, control panel, auth, and MCP endpoints
+          if (
+            req.path.startsWith('/api') ||
+            req.path.startsWith(config.mountPath || '/cpanel') ||
+            req.path.startsWith('/auth') ||
+            req.path.startsWith('/mcp')
+          ) {
+            return next();
+          }
+
+          // Serve index.html for all other routes (SPA routing)
+          const indexPath = resolve(config.staticPath!, 'index.html');
+          if (existsSync(indexPath)) {
+            res.sendFile(indexPath);
+          } else {
+            next();
+          }
         });
         return;
       }

package/src/plugins/index.ts

@@ -423,3 +423,18 @@ export type {
   ConnectionHealth,
   NotificationsManagerInterface,
 } from './notifications/index.js';
+
+// QwickBrain MCP plugin
+export {
+  createQwickBrainPlugin,
+  getConnectionStatus,
+  isConnected,
+} from './qwickbrain/index.js';
+export type {
+  QwickBrainPluginConfig,
+  MCPToolDefinition,
+  MCPToolCallRequest,
+  MCPToolCallResponse,
+  QwickBrainConnectionStatus,
+  MCPRateLimitConfig,
+} from './qwickbrain/index.js';

package/src/plugins/qwickbrain/index.ts

@@ -0,0 +1,33 @@
+/**
+ * QwickBrain Plugin
+ *
+ * MCP proxy plugin for exposing QwickBrain tools to external AI clients.
+ *
+ * @example
+ * ```typescript
+ * import { createControlPanel } from '@qwickapps/server';
+ * import { createQwickBrainPlugin } from '@qwickapps/server/plugins';
+ *
+ * const panel = await createControlPanel({
+ *   plugins: [
+ *     createQwickBrainPlugin({
+ *       qwickbrainUrl: 'http://macmini.tailnet-xxx.ts.net:8080',
+ *       exposedTools: '*', // or ['search_codebase', 'get_document', ...]
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { createQwickBrainPlugin, getConnectionStatus, isConnected } from './qwickbrain-plugin.js';
+
+export type {
+  QwickBrainPluginConfig,
+  MCPToolDefinition,
+  MCPToolCallRequest,
+  MCPToolCallResponse,
+  QwickBrainConnectionStatus,
+  MCPRateLimitConfig,
+} from './types.js';