@qwickapps/server 1.5.2 → 1.6.1

package/src/plugins/api-keys/middleware/bearer-token-auth.ts

@@ -0,0 +1,250 @@
+/**
+ * Bearer Token Authentication Middleware
+ *
+ * Middleware for authenticating API requests using Bearer tokens (API keys).
+ * Verifies the token, checks expiration and active status, and attaches
+ * the authenticated key info to the request.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response, NextFunction } from 'express';
+import type { ApiKey, ApiKeyScope } from '../types.js';
+import { getApiKeysStore } from '../api-keys-plugin.js';
+import { incrementLimit, isLimited } from '../../rate-limit/rate-limit-service.js';
+
+/**
+ * Extended Express Request with API key authentication info
+ */
+export interface ApiKeyAuthenticatedRequest extends Request {
+  apiKey?: {
+    id: string;
+    user_id: string;
+    scopes: ApiKeyScope[];
+    key_type: 'm2m' | 'pat';
+  };
+}
+
+/**
+ * Options for bearer token authentication middleware
+ */
+export interface BearerTokenAuthOptions {
+  /** Required scopes (all must be present) */
+  requiredScopes?: ApiKeyScope[];
+  /** Allow only specific key types */
+  allowedKeyTypes?: ('m2m' | 'pat')[];
+  /** Custom error handler */
+  onUnauthorized?: (req: Request, res: Response, reason: string) => void;
+}
+
+/**
+ * Extract Bearer token from Authorization header
+ *
+ * @param req Express request
+ * @returns Bearer token or null if not found
+ */
+function extractBearerToken(req: Request): string | null {
+  const authHeader = req.headers.authorization;
+
+  if (!authHeader) {
+    return null;
+  }
+
+  // Check for "Bearer <token>" format
+  const parts = authHeader.split(' ');
+  if (parts.length !== 2 || parts[0] !== 'Bearer') {
+    return null;
+  }
+
+  return parts[1];
+}
+
+/**
+ * Check if API key has all required scopes
+ *
+ * @param keyScopes Scopes granted to the API key
+ * @param requiredScopes Scopes required for the endpoint
+ * @returns True if key has all required scopes
+ */
+function hasRequiredScopes(keyScopes: ApiKeyScope[], requiredScopes: ApiKeyScope[]): boolean {
+  return requiredScopes.every(required => keyScopes.includes(required));
+}
+
+/**
+ * Default unauthorized handler
+ */
+function defaultUnauthorizedHandler(req: Request, res: Response, reason: string): void {
+  res.status(401).json({
+    error: 'Unauthorized',
+    message: reason,
+  });
+}
+
+/**
+ * Get rate limit identifier for API key authentication
+ * Uses IP address as the identifier
+ */
+function getRateLimitIdentifier(req: Request): string {
+  const ip = req.ip ||
+    req.headers['x-forwarded-for']?.toString().split(',')[0].trim() ||
+    req.socket?.remoteAddress ||
+    'unknown';
+  return `api-key-auth:${ip}`;
+}
+
+/**
+ * Check if rate limit has been exceeded
+ * Uses the existing rate-limit plugin with specific limits for API key auth
+ */
+async function checkRateLimit(identifier: string): Promise<boolean> {
+  try {
+    // Check rate limit: 100 requests per 15 minutes
+    return await isLimited(identifier, {
+      maxRequests: 100,
+      windowMs: 15 * 60 * 1000, // 15 minutes
+      strategy: 'sliding-window',
+    });
+  } catch (error) {
+    // If rate limit service not available, allow the request
+    // (fail open - let other security measures handle it)
+    console.warn('[bearerTokenAuth] Rate limit service unavailable:', error);
+    return false;
+  }
+}
+
+/**
+ * Record a failed authentication attempt
+ * Increments the rate limit counter
+ */
+async function recordFailedAttempt(identifier: string): Promise<void> {
+  try {
+    await incrementLimit(identifier, {
+      maxRequests: 100,
+      windowMs: 15 * 60 * 1000, // 15 minutes
+      strategy: 'sliding-window',
+    });
+  } catch (error) {
+    // Non-critical - log and continue
+    console.warn('[bearerTokenAuth] Failed to record attempt:', error);
+  }
+}
+
+/**
+ * Bearer Token Authentication Middleware
+ *
+ * Validates API keys sent as Bearer tokens in the Authorization header.
+ * Attaches authenticated key info to the request for downstream handlers.
+ *
+ * @param options Configuration options
+ * @returns Express middleware function
+ *
+ * @example
+ * ```ts
+ * import { bearerTokenAuth } from '@qwickapps/server';
+ *
+ * // Require authentication
+ * app.get('/api/data', bearerTokenAuth(), (req, res) => {
+ *   const { apiKey } = req as ApiKeyAuthenticatedRequest;
+ *   res.json({ user_id: apiKey?.user_id });
+ * });
+ *
+ * // Require specific scopes
+ * app.post('/api/data', bearerTokenAuth({
+ *   requiredScopes: ['write'],
+ * }), (req, res) => {
+ *   // Handler code
+ * });
+ *
+ * // Allow only M2M keys
+ * app.post('/api/admin', bearerTokenAuth({
+ *   allowedKeyTypes: ['m2m'],
+ *   requiredScopes: ['admin'],
+ * }), (req, res) => {
+ *   // Handler code
+ * });
+ * ```
+ */
+export function bearerTokenAuth(options: BearerTokenAuthOptions = {}) {
+  const {
+    requiredScopes = [],
+    allowedKeyTypes,
+    onUnauthorized = defaultUnauthorizedHandler,
+  } = options;
+
+  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    try {
+      // Check rate limit first
+      const rateLimitId = getRateLimitIdentifier(req);
+      if (await checkRateLimit(rateLimitId)) {
+        res.status(429).json({
+          error: 'Too Many Requests',
+          message: 'Too many authentication attempts. Please try again later.',
+        });
+        return;
+      }
+
+      // Extract token from Authorization header
+      const token = extractBearerToken(req);
+
+      if (!token) {
+        recordFailedAttempt(rateLimitId);
+        onUnauthorized(req, res, 'Missing or invalid Authorization header');
+        return;
+      }
+
+      // Get store instance
+      const store = getApiKeysStore();
+      if (!store) {
+        console.error('[bearerTokenAuth] API Keys plugin not initialized');
+        res.status(500).json({ error: 'Authentication service unavailable' });
+        return;
+      }
+
+      // Verify the token
+      const apiKey = await store.verify(token);
+
+      if (!apiKey) {
+        recordFailedAttempt(rateLimitId);
+        onUnauthorized(req, res, 'Invalid, expired, or inactive API key');
+        return;
+      }
+
+      // Check key type if restrictions apply
+      if (allowedKeyTypes && !allowedKeyTypes.includes(apiKey.key_type)) {
+        onUnauthorized(req, res, `This endpoint requires ${allowedKeyTypes.join(' or ')} keys`);
+        return;
+      }
+
+      // Check scopes if required
+      if (requiredScopes.length > 0 && !hasRequiredScopes(apiKey.scopes, requiredScopes)) {
+        onUnauthorized(req, res, `Insufficient scopes. Required: ${requiredScopes.join(', ')}`);
+        return;
+      }
+
+      // Record usage (non-blocking)
+      store.recordUsage(apiKey.id).catch(err => {
+        console.error('[bearerTokenAuth] Failed to record key usage:', err);
+      });
+
+      // Attach authenticated key info to request
+      (req as ApiKeyAuthenticatedRequest).apiKey = {
+        id: apiKey.id,
+        user_id: apiKey.user_id,
+        scopes: apiKey.scopes,
+        key_type: apiKey.key_type,
+      };
+
+      next();
+    } catch (error) {
+      console.error('[bearerTokenAuth] Authentication error:', error);
+      res.status(500).json({ error: 'Authentication failed' });
+    }
+  };
+}
+
+/**
+ * Helper type guard for API key authenticated requests
+ */
+export function isApiKeyAuthenticated(req: Request): req is ApiKeyAuthenticatedRequest {
+  return 'apiKey' in req && (req as ApiKeyAuthenticatedRequest).apiKey !== undefined;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * API Keys Middleware Index
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export {
+  bearerTokenAuth,
+  isApiKeyAuthenticated,
+  type ApiKeyAuthenticatedRequest,
+  type BearerTokenAuthOptions,
+} from './bearer-token-auth.js';
+export {
+  createUsageLoggingMiddleware,
+} from './usage-logging.js';

package/src/plugins/api-keys/middleware/usage-logging.ts

@@ -0,0 +1,78 @@
+/**
+ * Usage Logging Middleware
+ *
+ * Logs all API key requests for audit trails and usage analytics.
+ * Logging is asynchronous and non-blocking to avoid performance impact.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Request, Response, NextFunction, RequestHandler } from 'express';
+import type { UsageLogStore } from '../stores/usage-log-store.js';
+
+/**
+ * Extended request interface with API key info
+ */
+interface ApiKeyRequest extends Request {
+  apiKey?: {
+    id: string;
+    user_id: string;
+    name: string;
+    scopes: string[];
+  };
+}
+
+/**
+ * Create usage logging middleware
+ *
+ * Logs all requests made with API key authentication to the usage log store.
+ * Logging happens asynchronously after the response is sent to avoid latency.
+ *
+ * @param store Usage log storage backend
+ * @returns Express middleware
+ */
+export function createUsageLoggingMiddleware(store: UsageLogStore): RequestHandler {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const apiKeyReq = req as ApiKeyRequest;
+
+    // Skip if not API key authentication
+    if (!apiKeyReq.apiKey) {
+      return next();
+    }
+
+    // Capture request details
+    const keyId = apiKeyReq.apiKey.id;
+    const endpoint = req.path;
+    const method = req.method;
+    const ipAddress = (req.ip ||
+      (req.headers['x-forwarded-for'] as string)?.split(',')[0].trim() ||
+      req.socket?.remoteAddress) as string | undefined;
+    const userAgent = req.get('user-agent');
+
+    // Intercept response to capture status code
+    const originalSend = res.send;
+    res.send = function (data?: unknown): Response {
+      const statusCode = res.statusCode;
+
+      // Log asynchronously after response is sent (non-blocking)
+      setImmediate(() => {
+        store.log({
+          key_id: keyId,
+          endpoint,
+          method,
+          status_code: statusCode,
+          ip_address: ipAddress,
+          user_agent: userAgent,
+        }).catch((error: Error) => {
+          // Log error but don't fail the request
+          console.error('[UsageLogging] Failed to log API key usage:', error);
+        });
+      });
+
+      // Call original send
+      return originalSend.call(this, data);
+    };
+
+    next();
+  };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * API Keys Stores Index
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+export { postgresApiKeyStore } from './postgres-store.js';
+export {
+  createPostgresPluginScopeStore,
+  type PluginScope,
+  type PluginScopeStore,
+  type PostgresPluginScopeStoreConfig,
+} from './plugin-scope-store.js';
+export {
+  createPostgresUsageLogStore,
+  type UsageLogEntry,
+  type UsageLogQueryOptions,
+  type UsageLogStats,
+  type UsageLogStore,
+  type PostgresUsageLogStoreConfig,
+} from './usage-log-store.js';

package/src/plugins/api-keys/stores/plugin-scope-store.ts

@@ -0,0 +1,280 @@
+/**
+ * Plugin Scope Store - PostgreSQL Implementation
+ *
+ * Manages plugin-declared scopes for fine-grained API key authorization.
+ * Plugins register their scopes during initialization, which are then available
+ * for selection during API key creation.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import type { Pool } from 'pg';
+
+/**
+ * Plugin scope definition
+ */
+export interface PluginScope {
+  /** Scope name in format 'plugin-id:action' (e.g., 'qwickbrain:execute') */
+  name: string;
+  /** Plugin ID that declares this scope */
+  plugin_id: string;
+  /** Human-readable description for UI */
+  description: string;
+  /** Optional category for grouping (read, write, admin) */
+  category?: 'read' | 'write' | 'admin';
+  /** When scope was registered */
+  created_at?: Date;
+  /** When scope was last updated */
+  updated_at?: Date;
+}
+
+/**
+ * Plugin scope store interface
+ */
+export interface PluginScopeStore {
+  /** Store name */
+  name: string;
+
+  /**
+   * Initialize the store (create tables, indexes, etc.)
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Register scopes for a plugin (upsert operation)
+   * Existing scopes are updated, new scopes are inserted, removed scopes are deleted
+   */
+  registerScopes(pluginId: string, scopes: Omit<PluginScope, 'plugin_id' | 'created_at' | 'updated_at'>[]): Promise<void>;
+
+  /**
+   * Get all scopes for a specific plugin
+   */
+  getPluginScopes(pluginId: string): Promise<PluginScope[]>;
+
+  /**
+   * Get all available scopes across all plugins
+   */
+  getAllScopes(): Promise<PluginScope[]>;
+
+  /**
+   * Verify a scope exists
+   */
+  isValidScope(scopeName: string): Promise<boolean>;
+
+  /**
+   * Delete all scopes for a plugin
+   */
+  deletePluginScopes(pluginId: string): Promise<void>;
+
+  /**
+   * Shutdown the store
+   */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * PostgreSQL plugin scope store configuration
+ */
+export interface PostgresPluginScopeStoreConfig {
+  /** PostgreSQL pool instance or a function that returns one (for lazy initialization) */
+  pool: Pool | (() => Pool);
+  /** Table name (default: 'plugin_scopes') */
+  tableName?: string;
+  /** Schema name (default: 'public') */
+  schema?: string;
+  /** Auto-create tables on init (default: true) */
+  autoCreateTables?: boolean;
+}
+
+/**
+ * PostgreSQL implementation of PluginScopeStore
+ */
+export function createPostgresPluginScopeStore(
+  config: PostgresPluginScopeStoreConfig
+): PluginScopeStore {
+  const tableName = config.tableName || 'plugin_scopes';
+  const schema = config.schema || 'public';
+  const tableFullName = `"${schema}"."${tableName}"`;
+  const autoCreateTables = config.autoCreateTables !== false;
+
+  // In-memory cache for fast validation
+  const scopeCache = new Set<string>();
+  let cacheInitialized = false;
+
+  /**
+   * Get PostgreSQL pool (lazy initialization support)
+   */
+  function getPool(): Pool {
+    if (typeof config.pool === 'function') {
+      return config.pool();
+    }
+    return config.pool;
+  }
+
+  /**
+   * Initialize scope cache
+   */
+  async function initializeCache(): Promise<void> {
+    if (cacheInitialized) return;
+
+    const pool = getPool();
+    const result = await pool.query<{ name: string }>(
+      `SELECT name FROM ${tableFullName}`
+    );
+
+    scopeCache.clear();
+    result.rows.forEach(row => scopeCache.add(row.name));
+    cacheInitialized = true;
+  }
+
+  /**
+   * Refresh cache after modifications
+   */
+  async function refreshCache(): Promise<void> {
+    cacheInitialized = false;
+    await initializeCache();
+  }
+
+  return {
+    name: 'postgres',
+
+    async initialize(): Promise<void> {
+      if (!autoCreateTables) return;
+
+      const pool = getPool();
+
+      // Create plugin_scopes table
+      await pool.query(`
+        CREATE TABLE IF NOT EXISTS ${tableFullName} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          plugin_id VARCHAR(255) NOT NULL,
+          name VARCHAR(255) NOT NULL UNIQUE,
+          description TEXT NOT NULL,
+          category VARCHAR(50),
+          created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+          updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+          -- Enforce naming convention: plugin-id:action
+          CONSTRAINT scope_name_format CHECK (name ~ '^[a-z0-9-]+:[a-z0-9-]+$')
+        );
+
+        -- Indexes for performance
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_plugin_id ON ${tableFullName}(plugin_id);
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_category ON ${tableFullName}(category);
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_name ON ${tableFullName}(name);
+      `);
+
+      // Insert system scopes for backwards compatibility
+      await pool.query(`
+        INSERT INTO ${tableFullName} (plugin_id, name, description, category)
+        VALUES
+          ('system', 'system:read', 'Read access to system resources', 'read'),
+          ('system', 'system:write', 'Write access to system resources', 'write'),
+          ('system', 'system:admin', 'Administrative access to system resources', 'admin')
+        ON CONFLICT (name) DO NOTHING;
+      `);
+
+      // Initialize cache
+      await initializeCache();
+    },
+
+    async registerScopes(
+      pluginId: string,
+      scopes: Omit<PluginScope, 'plugin_id' | 'created_at' | 'updated_at'>[]
+    ): Promise<void> {
+      const pool = getPool();
+
+      // Start transaction for atomic upsert
+      const client = await pool.connect();
+      try {
+        await client.query('BEGIN');
+
+        // Get existing scopes for this plugin
+        const existingResult = await client.query<{ name: string }>(
+          `SELECT name FROM ${tableFullName} WHERE plugin_id = $1`,
+          [pluginId]
+        );
+        const existingScopes = new Set(existingResult.rows.map(r => r.name));
+        const newScopes = new Set(scopes.map(s => s.name));
+
+        // Delete scopes that are no longer declared
+        const scopesToDelete = [...existingScopes].filter(name => !newScopes.has(name));
+        if (scopesToDelete.length > 0) {
+          await client.query(
+            `DELETE FROM ${tableFullName} WHERE plugin_id = $1 AND name = ANY($2)`,
+            [pluginId, scopesToDelete]
+          );
+        }
+
+        // Upsert scopes (insert new, update existing)
+        for (const scope of scopes) {
+          await client.query(
+            `INSERT INTO ${tableFullName} (plugin_id, name, description, category)
+             VALUES ($1, $2, $3, $4)
+             ON CONFLICT (name) DO UPDATE SET
+               description = EXCLUDED.description,
+               category = EXCLUDED.category,
+               updated_at = NOW()`,
+            [pluginId, scope.name, scope.description, scope.category || null]
+          );
+        }
+
+        await client.query('COMMIT');
+
+        // Refresh cache
+        await refreshCache();
+      } catch (error) {
+        await client.query('ROLLBACK');
+        throw error;
+      } finally {
+        client.release();
+      }
+    },
+
+    async getPluginScopes(pluginId: string): Promise<PluginScope[]> {
+      const pool = getPool();
+      const result = await pool.query<PluginScope>(
+        `SELECT plugin_id, name, description, category, created_at, updated_at
+         FROM ${tableFullName}
+         WHERE plugin_id = $1
+         ORDER BY name`,
+        [pluginId]
+      );
+
+      return result.rows;
+    },
+
+    async getAllScopes(): Promise<PluginScope[]> {
+      const pool = getPool();
+      const result = await pool.query<PluginScope>(
+        `SELECT plugin_id, name, description, category, created_at, updated_at
+         FROM ${tableFullName}
+         ORDER BY plugin_id, name`
+      );
+
+      return result.rows;
+    },
+
+    async isValidScope(scopeName: string): Promise<boolean> {
+      // Use cache for fast validation
+      await initializeCache();
+      return scopeCache.has(scopeName);
+    },
+
+    async deletePluginScopes(pluginId: string): Promise<void> {
+      const pool = getPool();
+      await pool.query(
+        `DELETE FROM ${tableFullName} WHERE plugin_id = $1`,
+        [pluginId]
+      );
+
+      // Refresh cache
+      await refreshCache();
+    },
+
+    async shutdown(): Promise<void> {
+      scopeCache.clear();
+      cacheInitialized = false;
+    },
+  };
+}