@qwickapps/server 1.5.2 → 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.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,

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

@@ -88,8 +88,13 @@ export function createFrontendAppPlugin(config: FrontendAppPluginConfig): Plugin
         // 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 and control panel
-          if (req.path.startsWith('/api') || req.path.startsWith(config.mountPath || '/cpanel')) {
+          // 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();
           }
 

package/src/plugins/users/__tests__/postgres-store.test.ts

@@ -19,6 +19,7 @@ const mockUser: User = {
   external_id: 'auth0|abc123',
   provider: 'auth0',
   picture: 'https://example.com/avatar.jpg',
+  status: 'active',
   metadata: {
     identifiers: {
       auth0_user_id: 'auth0|abc123',

package/src/plugins/users/__tests__/users-plugin.test.ts

@@ -44,6 +44,7 @@ describe('Users Plugin', () => {
     external_id: 'auth0|abc123',
     provider: 'auth0',
     picture: 'https://example.com/avatar.jpg',
+    status: 'active',
     created_at: new Date('2025-01-01'),
     updated_at: new Date('2025-01-01'),
     last_login_at: new Date('2025-12-13'),
@@ -64,6 +65,8 @@ describe('Users Plugin', () => {
     delete: vi.fn().mockResolvedValue(true),
     search: vi.fn().mockResolvedValue({ users: [mockUser], total: 1, page: 1, limit: 20, totalPages: 1 }),
     updateLastLogin: vi.fn().mockResolvedValue(undefined),
+    getByInvitationToken: vi.fn().mockResolvedValue(mockUser),
+    acceptInvitation: vi.fn().mockResolvedValue(mockUser),
     shutdown: vi.fn().mockResolvedValue(undefined),
   });
 

package/src/plugins/users/stores/postgres-store.ts

@@ -72,6 +72,9 @@ export function postgresUserStore(config: PostgresUserStoreConfig): UserStore {
           external_id VARCHAR(255),
           provider VARCHAR(50),
           picture TEXT,
+          status VARCHAR(20) DEFAULT 'active',
+          invitation_token VARCHAR(255),
+          invitation_expires_at TIMESTAMPTZ,
           metadata JSONB DEFAULT '{}',
           created_at TIMESTAMPTZ DEFAULT NOW(),
           updated_at TIMESTAMPTZ DEFAULT NOW(),
@@ -80,6 +83,41 @@ export function postgresUserStore(config: PostgresUserStoreConfig): UserStore {
 
         CREATE INDEX IF NOT EXISTS idx_${usersTable}_email ON ${usersTableFull}(email);
         CREATE INDEX IF NOT EXISTS idx_${usersTable}_external_id ON ${usersTableFull}(external_id, provider);
+        CREATE INDEX IF NOT EXISTS idx_${usersTable}_invitation_token ON ${usersTableFull}(invitation_token);
+        CREATE INDEX IF NOT EXISTS idx_${usersTable}_status ON ${usersTableFull}(status);
+      `);
+
+      // Add new columns to existing tables (migration)
+      await getPool().query(`
+        DO $$
+        BEGIN
+          IF NOT EXISTS (
+            SELECT 1 FROM information_schema.columns
+            WHERE table_schema = '${schema}'
+            AND table_name = '${usersTable}'
+            AND column_name = 'status'
+          ) THEN
+            ALTER TABLE ${usersTableFull} ADD COLUMN status VARCHAR(20) DEFAULT 'active';
+          END IF;
+
+          IF NOT EXISTS (
+            SELECT 1 FROM information_schema.columns
+            WHERE table_schema = '${schema}'
+            AND table_name = '${usersTable}'
+            AND column_name = 'invitation_token'
+          ) THEN
+            ALTER TABLE ${usersTableFull} ADD COLUMN invitation_token VARCHAR(255);
+          END IF;
+
+          IF NOT EXISTS (
+            SELECT 1 FROM information_schema.columns
+            WHERE table_schema = '${schema}'
+            AND table_name = '${usersTable}'
+            AND column_name = 'invitation_expires_at'
+          ) THEN
+            ALTER TABLE ${usersTableFull} ADD COLUMN invitation_expires_at TIMESTAMPTZ;
+          END IF;
+        END $$;
       `);
     },
 
@@ -263,6 +301,7 @@ export function postgresUserStore(config: PostgresUserStoreConfig): UserStore {
       const {
         query,
         provider,
+        status,
         page = 1,
         limit = 20,
         sortBy = 'created_at',
@@ -285,6 +324,12 @@ export function postgresUserStore(config: PostgresUserStoreConfig): UserStore {
         paramIndex++;
       }
 
+      if (status) {
+        conditions.push(`status = $${paramIndex}`);
+        values.push(status);
+        paramIndex++;
+      }
+
       const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
 
       // Validate sort column to prevent SQL injection
@@ -322,6 +367,30 @@ export function postgresUserStore(config: PostgresUserStoreConfig): UserStore {
       await getPool().query(`UPDATE ${usersTableFull} SET last_login_at = NOW() WHERE id = $1`, [id]);
     },
 
+    async getByInvitationToken(token: string): Promise<User | null> {
+      const result = await getPool().query(
+        `SELECT * FROM ${usersTableFull} WHERE invitation_token = $1 AND invitation_expires_at > NOW()`,
+        [token]
+      );
+      return (result.rows[0] as User) || null;
+    },
+
+    async acceptInvitation(token: string): Promise<User | null> {
+      const result = await getPool().query(
+        `UPDATE ${usersTableFull}
+         SET status = 'active',
+             invitation_token = NULL,
+             invitation_expires_at = NULL,
+             updated_at = NOW()
+         WHERE invitation_token = $1
+           AND invitation_expires_at > NOW()
+           AND status = 'invited'
+         RETURNING *`,
+        [token]
+      );
+      return (result.rows[0] as User) || null;
+    },
+
     async shutdown(): Promise<void> {
       // Pool is managed externally, nothing to do here
     },

package/src/plugins/users/types.ts

@@ -9,6 +9,11 @@
  * Copyright (c) 2025 QwickApps.com. All rights reserved.
  */
 
+/**
+ * User status in the system
+ */
+export type UserStatus = 'invited' | 'active' | 'suspended';
+
 /**
  * User record in the database
  */
@@ -25,6 +30,12 @@ export interface User {
   provider?: string;
   /** Profile picture URL */
   picture?: string;
+  /** User status */
+  status: UserStatus;
+  /** Invitation token (set when user is invited) */
+  invitation_token?: string;
+  /** Invitation expiration timestamp */
+  invitation_expires_at?: Date;
   /** Additional metadata (JSON) */
   metadata?: Record<string, unknown>;
   /** When the user was created */
@@ -90,6 +101,8 @@ export interface UserSearchParams {
   query?: string;
   /** Filter by provider */
   provider?: string;
+  /** Filter by status */
+  status?: UserStatus;
   /** Page number (1-indexed) */
   page?: number;
   /** Items per page */
@@ -182,6 +195,18 @@ export interface UserStore {
    */
   updateLastLogin(id: string): Promise<void>;
 
+  /**
+   * Get a user by invitation token (only if invitation is valid and not expired)
+   */
+  getByInvitationToken(token: string): Promise<User | null>;
+
+  /**
+   * Accept an invitation by token.
+   * Sets status to 'active' and clears invitation token fields.
+   * Returns the updated user or null if token is invalid/expired.
+   */
+  acceptInvitation(token: string): Promise<User | null>;
+
   /**
    * Shutdown the store
    */

package/ui/src/App.tsx

@@ -18,6 +18,7 @@ import { AuthPage } from './pages/AuthPage';
 import { RateLimitPage } from './pages/RateLimitPage';
 import { NotificationsPage } from './pages/NotificationsPage';
 import { IntegrationsPage } from './pages/IntegrationsPage';
+import { APIKeysPage } from './pages/APIKeysPage';
 import { PluginPage } from './pages/PluginPage';
 import { NotFoundPage } from './pages/NotFoundPage';
 import { api, type MenuContribution } from './api/controlPanelApi';
@@ -41,10 +42,11 @@ const coreNavigationItems: NavigationItem[] = [
 // Built-in optional navigation items - shown if corresponding plugin is registered
 const builtInPluginNavItems: Record<string, NavigationItem> = {
   users: { id: 'users', label: 'Users', route: '/users', icon: 'people' },
+  'api-keys': { id: 'api-keys', label: 'API Keys', route: '/api-keys', icon: 'key' },
 };
 
 // Routes that have dedicated page components
-const dedicatedRoutes = new Set(['/', '/plugins', '/logs', '/system', '/users', '/entitlements', '/auth', '/rate-limits', '/notifications', '/integrations']);
+const dedicatedRoutes = new Set(['/', '/plugins', '/logs', '/system', '/users', '/entitlements', '/auth', '/rate-limits', '/notifications', '/integrations', '/api-keys']);
 
 // Package version - injected at build time or fallback
 const SERVER_VERSION = '1.0.0';
@@ -222,6 +224,9 @@ export function App() {
             {registeredPlugins.has('ai-proxy') && (
               <Route path="/integrations" element={<IntegrationsPage />} />
             )}
+            {registeredPlugins.has('api-keys') && (
+              <Route path="/api-keys" element={<APIKeysPage />} />
+            )}
 
             {/* Dynamic plugin routes - render generic PluginPage for non-dedicated routes */}
             {pluginMenuItems

package/ui/src/api/controlPanelApi.ts

@@ -81,10 +81,15 @@ export interface LogSource {
 // ==================
 // Users API Types
 // ==================
+export type UserStatus = 'invited' | 'active' | 'suspended';
+
 export interface User {
   id: string;
   email: string;
   name?: string;
+  status: UserStatus;
+  invitation_token?: string;
+  invitation_expires_at?: string;
   created_at?: string;
   updated_at?: string;
   last_login?: string;
@@ -98,6 +103,30 @@ export interface UsersResponse {
   limit: number;
 }
 
+export interface InviteUserRequest {
+  email: string;
+  name?: string;
+  role?: string;
+  metadata?: Record<string, unknown>;
+  expiresInDays?: number;
+}
+
+export interface InvitationResponse {
+  user: User;
+  token: string;
+  inviteLink: string;
+  expiresAt: string;
+}
+
+export interface AcceptInvitationRequest {
+  token: string;
+}
+
+export interface AcceptInvitationResponse {
+  success: boolean;
+  user: User;
+}
+
 // ==================
 // Bans API Types
 // ==================
@@ -116,6 +145,44 @@ export interface BansResponse {
   total: number;
 }
 
+// ==================
+// API Keys Types
+// ==================
+export interface ApiKey {
+  id: string;
+  name: string;
+  key_prefix: string;
+  key_type: 'm2m' | 'pat';
+  scopes: Array<'read' | 'write' | 'admin'>;
+  last_used_at: string | null;
+  expires_at: string | null;
+  is_active: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface ApiKeyWithPlaintext extends ApiKey {
+  key: string; // Only available on creation
+}
+
+export interface ApiKeysResponse {
+  keys: ApiKey[];
+}
+
+export interface CreateApiKeyRequest {
+  name: string;
+  key_type: 'm2m' | 'pat';
+  scopes: Array<'read' | 'write' | 'admin'>;
+  expires_at?: string;
+}
+
+export interface UpdateApiKeyRequest {
+  name?: string;
+  scopes?: Array<'read' | 'write' | 'admin'>;
+  expires_at?: string;
+  is_active?: boolean;
+}
+
 // ==================
 // Entitlements API Types
 // ==================
@@ -544,6 +611,40 @@ class ControlPanelApi {
     return response.json();
   }
 
+  async inviteUser(request: InviteUserRequest): Promise<InvitationResponse> {
+    const response = await this._fetch(`${this.baseUrl}/api/users/invite`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(request),
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(error.error || `Invite user failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async acceptInvitation(token: string): Promise<AcceptInvitationResponse> {
+    const response = await this._fetch(`${this.baseUrl}/api/users/accept-invitation/${encodeURIComponent(token)}`);
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(error.error || `Accept invitation failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async getInvitations(): Promise<UsersResponse> {
+    const params = new URLSearchParams();
+    params.set('status', 'invited');
+    params.set('limit', '100');
+
+    const response = await this._fetch(`${this.baseUrl}/api/users?${params}`);
+    if (!response.ok) {
+      throw new Error(`Invitations request failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
   // ==================
   // Bans API
   // ==================
@@ -930,6 +1031,62 @@ class ControlPanelApi {
     }
     return response.json();
   }
+
+  // ==================
+  // API Keys API
+  // ==================
+
+  async getApiKeys(): Promise<ApiKeysResponse> {
+    const response = await this._fetch(`${this.baseUrl}/api/api-keys`);
+    if (!response.ok) {
+      throw new Error(`API keys request failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async createApiKey(request: CreateApiKeyRequest): Promise<ApiKeyWithPlaintext> {
+    const response = await this._fetch(`${this.baseUrl}/api/api-keys`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(request),
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(error.error || `API key creation failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async getApiKey(keyId: string): Promise<ApiKey> {
+    const response = await this._fetch(`${this.baseUrl}/api/api-keys/${encodeURIComponent(keyId)}`);
+    if (!response.ok) {
+      throw new Error(`API key request failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async updateApiKey(keyId: string, updates: UpdateApiKeyRequest): Promise<ApiKey> {
+    const response = await this._fetch(`${this.baseUrl}/api/api-keys/${encodeURIComponent(keyId)}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(updates),
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(error.error || `API key update failed: ${response.statusText}`);
+    }
+    return response.json();
+  }
+
+  async deleteApiKey(keyId: string): Promise<void> {
+    const response = await this._fetch(`${this.baseUrl}/api/api-keys/${encodeURIComponent(keyId)}`, {
+      method: 'DELETE',
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(error.error || `API key deletion failed: ${response.statusText}`);
+    }
+  }
 }
 
 export const api = new ControlPanelApi();