s3db.js 13.5.1 → 13.6.0

package/src/plugins/api/index.js

@@ -36,6 +36,86 @@ import { Plugin } from '../plugin.class.js';
 import { requirePluginDependency } from '../concerns/plugin-dependencies.js';
 import tryFn from '../../concerns/try-fn.js';
 import { ApiServer } from './server.js';
+import { idGenerator } from '../../concerns/id.js';
+
+const AUTH_DRIVER_KEYS = ['jwt', 'apiKey', 'basic', 'oidc', 'oauth2'];
+
+function normalizeAuthConfig(authOptions = {}) {
+  if (!authOptions) {
+    return {
+      drivers: [],
+      pathRules: [],
+      pathAuth: undefined,
+      strategy: 'any',
+      priorities: {},
+      resource: 'users',
+      usernameField: 'email',
+      passwordField: 'password',
+      driver: null
+    };
+  }
+
+  const normalized = {
+    drivers: [],
+    pathRules: Array.isArray(authOptions.pathRules) ? authOptions.pathRules : [],
+    pathAuth: authOptions.pathAuth,
+    strategy: authOptions.strategy || 'any',
+    priorities: authOptions.priorities || {},
+    resource: authOptions.resource || 'users',
+    usernameField: authOptions.usernameField || 'email',
+    passwordField: authOptions.passwordField || 'password'
+  };
+
+  const seen = new Set();
+
+  const addDriver = (name, driverConfig = {}) => {
+    if (!name) return;
+    const driverName = String(name).trim();
+    if (!driverName || seen.has(driverName)) return;
+    seen.add(driverName);
+    normalized.drivers.push({
+      driver: driverName,
+      config: driverConfig || {}
+    });
+  };
+
+  // Drivers provided as array
+  if (Array.isArray(authOptions.drivers)) {
+    for (const entry of authOptions.drivers) {
+      if (typeof entry === 'string') {
+        addDriver(entry, {});
+      } else if (entry && typeof entry === 'object') {
+        addDriver(entry.driver, entry.config || {});
+      }
+    }
+  }
+
+  // Single driver shortcut
+  if (authOptions.driver) {
+    if (typeof authOptions.driver === 'string') {
+      addDriver(authOptions.driver, authOptions.config || {});
+    } else if (typeof authOptions.driver === 'object') {
+      addDriver(authOptions.driver.driver, authOptions.driver.config || authOptions.config || {});
+    }
+  }
+
+  // Support legacy per-driver objects (jwt: {...}, apiKey: {...})
+  for (const driverName of AUTH_DRIVER_KEYS) {
+    if (authOptions[driverName] === undefined) continue;
+
+    const value = authOptions[driverName];
+    if (!value || value.enabled === false) continue;
+
+    const config = typeof value === 'object' ? { ...value } : {};
+    if (config.enabled !== undefined) {
+      delete config.enabled;
+    }
+    addDriver(driverName, config);
+  }
+
+  normalized.driver = normalized.drivers.length > 0 ? normalized.drivers[0].driver : null;
+  return normalized;
+}
 
 /**
  * API Plugin class
@@ -50,6 +130,8 @@ export class ApiPlugin extends Plugin {
   constructor(options = {}) {
     super(options);
 
+    const normalizedAuth = normalizeAuthConfig(options.auth);
+
     this.config = {
       // Server configuration
       port: options.port || 3000,
@@ -68,27 +150,22 @@ export class ApiPlugin extends Plugin {
         description: options.docs?.description || options.apiDescription || 'Auto-generated REST API for s3db.js resources'
       },
 
-      // Authentication configuration (driver-based)
-      auth: options.auth ? {
-        driver: options.auth.driver || null,             // 'jwt' or 'basic'
-        resource: options.auth.resource || 'users',      // Resource that manages auth
-        usernameField: options.auth.usernameField || 'email',   // Default: email
-        passwordField: options.auth.passwordField || 'password', // Default: password
-        config: options.auth.config || {}                // Driver-specific config
-      } : {
-        driver: null,
-        resource: 'users',
-        usernameField: 'email',
-        passwordField: 'password',
-        config: {}
-      },
-
-      // Resource configuration
-      resources: options.resources || {},
+      // Authentication configuration (multiple drivers)
+      auth: normalizedAuth,
 
       // Custom routes (plugin-level)
       routes: options.routes || {},
 
+      // Template engine configuration
+      templates: {
+        enabled: options.templates?.enabled || false,
+        engine: options.templates?.engine || 'jsx', // 'jsx' (default), 'ejs', 'custom'
+        templatesDir: options.templates?.templatesDir || './views',
+        layout: options.templates?.layout || null,
+        engineOptions: options.templates?.engineOptions || {},
+        customRenderer: options.templates?.customRenderer || null
+      },
+
       // CORS configuration
       cors: {
         enabled: options.cors?.enabled || false,
@@ -130,19 +207,83 @@ export class ApiPlugin extends Plugin {
         returnValidationErrors: options.validation?.returnValidationErrors !== false
       },
 
-      // Content Security Policy (CSP) configuration
+      // Security Headers (Helmet-like configuration)
+      security: {
+        enabled: options.security?.enabled !== false, // Enabled by default
+
+        // Content Security Policy (CSP)
+        contentSecurityPolicy: options.security?.contentSecurityPolicy !== false ? {
+          enabled: options.security?.contentSecurityPolicy?.enabled !== false,
+          directives: options.security?.contentSecurityPolicy?.directives || options.csp?.directives || {
+            'default-src': ["'self'"],
+            'script-src': ["'self'", "'unsafe-inline'", 'https://cdn.redoc.ly/redoc/v2.5.1/'],
+            'style-src': ["'self'", "'unsafe-inline'", 'https://cdn.redoc.ly/redoc/v2.5.1/', 'https://fonts.googleapis.com'],
+            'font-src': ["'self'", 'https://fonts.gstatic.com'],
+            'img-src': ["'self'", 'data:', 'https:'],
+            'connect-src': ["'self'"]
+          },
+          reportOnly: options.security?.contentSecurityPolicy?.reportOnly || options.csp?.reportOnly || false,
+          reportUri: options.security?.contentSecurityPolicy?.reportUri || options.csp?.reportUri || null
+        } : false,
+
+        // X-Frame-Options (clickjacking protection)
+        frameguard: options.security?.frameguard !== false ? {
+          action: options.security?.frameguard?.action || 'deny' // 'deny' or 'sameorigin'
+        } : false,
+
+        // X-Content-Type-Options (MIME sniffing protection)
+        noSniff: options.security?.noSniff !== false, // Enabled by default
+
+        // Strict-Transport-Security (HSTS - force HTTPS)
+        hsts: options.security?.hsts !== false ? {
+          maxAge: options.security?.hsts?.maxAge || 15552000, // 180 days (Helmet default)
+          includeSubDomains: options.security?.hsts?.includeSubDomains !== false,
+          preload: options.security?.hsts?.preload || false
+        } : false,
+
+        // Referrer-Policy (privacy)
+        referrerPolicy: options.security?.referrerPolicy !== false ? {
+          policy: options.security?.referrerPolicy?.policy || 'no-referrer'
+        } : false,
+
+        // X-DNS-Prefetch-Control (DNS leak protection)
+        dnsPrefetchControl: options.security?.dnsPrefetchControl !== false ? {
+          allow: options.security?.dnsPrefetchControl?.allow || false
+        } : false,
+
+        // X-Download-Options (IE8+ download security)
+        ieNoOpen: options.security?.ieNoOpen !== false, // Enabled by default
+
+        // X-Permitted-Cross-Domain-Policies (Flash/PDF security)
+        permittedCrossDomainPolicies: options.security?.permittedCrossDomainPolicies !== false ? {
+          policy: options.security?.permittedCrossDomainPolicies?.policy || 'none'
+        } : false,
+
+        // X-XSS-Protection (legacy XSS filter)
+        xssFilter: options.security?.xssFilter !== false ? {
+          mode: options.security?.xssFilter?.mode || 'block'
+        } : false,
+
+        // Permissions-Policy (modern feature policy)
+        permissionsPolicy: options.security?.permissionsPolicy !== false ? {
+          features: options.security?.permissionsPolicy?.features || {
+            geolocation: [],
+            microphone: [],
+            camera: [],
+            payment: [],
+            usb: [],
+            magnetometer: [],
+            gyroscope: [],
+            accelerometer: []
+          }
+        } : false
+      },
+
+      // Legacy CSP config (backward compatibility)
       csp: {
         enabled: options.csp?.enabled || false,
-        // Default CSP that works with Redoc v2.5.1 (allows CDN scripts/styles)
-        directives: options.csp?.directives || {
-          'default-src': ["'self'"],
-          'script-src': ["'self'", "'unsafe-inline'", 'https://cdn.redoc.ly/redoc/v2.5.1/'],
-          'style-src': ["'self'", "'unsafe-inline'", 'https://cdn.redoc.ly/redoc/v2.5.1/', 'https://fonts.googleapis.com'],
-          'font-src': ["'self'", 'https://fonts.gstatic.com'],
-          'img-src': ["'self'", 'data:', 'https:'],
-          'connect-src': ["'self'"]
-        },
-        reportOnly: options.csp?.reportOnly || false, // If true, uses Content-Security-Policy-Report-Only
+        directives: options.csp?.directives || {},
+        reportOnly: options.csp?.reportOnly || false,
         reportUri: options.csp?.reportUri || null
       },
 
@@ -150,10 +291,78 @@ export class ApiPlugin extends Plugin {
       middlewares: options.middlewares || []
     };
 
+    this.config.resources = this._normalizeResourcesConfig(options.resources);
+
     this.server = null;
     this.usersResource = null;
   }
 
+  /**
+   * Normalize resources config so array/string inputs become object map
+   * @private
+   * @param {Object|Array<string|Object>} resources
+   * @returns {Object<string, Object>}
+   */
+  _normalizeResourcesConfig(resources) {
+    if (!resources) {
+      return {};
+    }
+
+    const normalized = {};
+    const verbose = this.options?.verbose;
+
+    const addResourceConfig = (name, config = {}) => {
+      if (typeof name !== 'string' || !name.trim()) {
+        if (verbose) {
+          console.warn('[API Plugin] Ignoring resource config with invalid name:', name);
+        }
+        return;
+      }
+
+      normalized[name] = { ...config };
+    };
+
+    if (Array.isArray(resources)) {
+      for (const entry of resources) {
+        if (typeof entry === 'string') {
+          addResourceConfig(entry);
+        } else if (entry && typeof entry === 'object' && typeof entry.name === 'string') {
+          const { name, ...config } = entry;
+          addResourceConfig(name, config);
+        } else {
+          if (verbose) {
+            console.warn('[API Plugin] Ignoring invalid resource config entry (expected string or object with name):', entry);
+          }
+        }
+      }
+      return normalized;
+    }
+
+    if (typeof resources === 'object') {
+      for (const [name, config] of Object.entries(resources)) {
+        if (config === false) {
+          addResourceConfig(name, { enabled: false });
+        } else if (config === true || config === undefined || config === null) {
+          addResourceConfig(name);
+        } else if (typeof config === 'object') {
+          addResourceConfig(name, config);
+        } else {
+          if (verbose) {
+            console.warn('[API Plugin] Coercing resource config to empty object for', name);
+          }
+          addResourceConfig(name);
+        }
+      }
+      return normalized;
+    }
+
+    if (verbose) {
+      console.warn('[API Plugin] Invalid resources configuration. Expected object or array, received:', typeof resources);
+    }
+
+    return {};
+  }
+
   /**
    * Validate plugin dependencies
    * @private
@@ -181,8 +390,8 @@ export class ApiPlugin extends Plugin {
       throw err;
     }
 
-    // Create users resource if authentication driver is configured
-    const authEnabled = this.config.auth.driver !== null;
+    // Create users resource if authentication drivers are configured
+    const authEnabled = this.config.auth.drivers.length > 0;
 
     if (authEnabled) {
       await this._createUsersResource();
@@ -207,11 +416,12 @@ export class ApiPlugin extends Plugin {
         attributes: {
           id: 'string|required',
           username: 'string|required|minlength:3',
-          email: 'string|optional|email',
+          email: 'string|required|email',  // Required to support email-based auth
           password: 'secret|required|minlength:8',
           apiKey: 'string|optional',
           jwtSecret: 'string|optional',
           role: 'string|default:user',
+          scopes: 'array|items:string|optional',  // Authorization scopes (e.g., ['read:users', 'write:cars'])
           active: 'boolean|default:true',
           createdAt: 'string|optional',
           lastLoginAt: 'string|optional',
@@ -238,7 +448,6 @@ export class ApiPlugin extends Plugin {
       throw err;
     }
   }
-
   /**
    * Setup middlewares
    * @private
@@ -248,19 +457,26 @@ export class ApiPlugin extends Plugin {
 
     // Add request ID middleware
     middlewares.push(async (c, next) => {
-      c.set('requestId', crypto.randomUUID());
+      c.set('requestId', idGenerator());
       c.set('verbose', this.config.verbose);
       await next();
     });
 
+    // Add security headers middleware (FIRST - most critical)
+    if (this.config.security.enabled) {
+      const securityMiddleware = await this._createSecurityMiddleware();
+      middlewares.push(securityMiddleware);
+    }
+
     // Add CORS middleware
     if (this.config.cors.enabled) {
       const corsMiddleware = await this._createCorsMiddleware();
       middlewares.push(corsMiddleware);
     }
 
-    // Add CSP middleware
-    if (this.config.csp.enabled) {
+    // Add legacy CSP middleware (deprecated - use security.contentSecurityPolicy instead)
+    // This is kept for backward compatibility with old configs
+    if (this.config.csp.enabled && !this.config.security.contentSecurityPolicy) {
       const cspMiddleware = await this._createCSPMiddleware();
       middlewares.push(cspMiddleware);
     }
@@ -291,8 +507,11 @@ export class ApiPlugin extends Plugin {
   }
 
   /**
-   * Create CORS middleware (placeholder)
+   * Create CORS middleware
    * @private
+   *
+   * Handles Cross-Origin Resource Sharing (CORS) headers and preflight requests.
+   * Supports wildcard origins, credential-based requests, and OPTIONS preflight.
    */
   async _createCorsMiddleware() {
     return async (c, next) => {
@@ -356,8 +575,12 @@ export class ApiPlugin extends Plugin {
   }
 
   /**
-   * Create rate limiting middleware (placeholder)
+   * Create rate limiting middleware
    * @private
+   *
+   * Implements sliding window rate limiting with configurable window size and max requests.
+   * Returns 429 status code with Retry-After header when limit is exceeded.
+   * Uses IP address or custom key generator to track request counts.
    */
   async _createRateLimitMiddleware() {
     const requests = new Map();
@@ -413,10 +636,23 @@ export class ApiPlugin extends Plugin {
   }
 
   /**
-   * Create logging middleware (placeholder)
+   * Create logging middleware with customizable format
    * @private
+   *
+   * Supported tokens:
+   * - :method - HTTP method (GET, POST, etc)
+   * - :path - Request path
+   * - :status - HTTP status code
+   * - :response-time - Response time in milliseconds
+   * - :user - Username or 'anonymous'
+   * - :requestId - Request ID (UUID)
+   *
+   * Example format: ':method :path :status :response-time ms - :user'
+   * Output: 'GET /api/v1/cars 200 45ms - john'
    */
   async _createLoggingMiddleware() {
+    const { format } = this.config.logging;
+
     return async (c, next) => {
       const start = Date.now();
       const method = c.req.method;
@@ -427,32 +663,236 @@ export class ApiPlugin extends Plugin {
 
       const duration = Date.now() - start;
       const status = c.res.status;
-      const user = c.get('user')?.username || 'anonymous';
-
-      console.log(`[API Plugin] ${requestId} - ${method} ${path} ${status} ${duration}ms - ${user}`);
+      const user = c.get('user')?.username || c.get('user')?.email || 'anonymous';
+
+      // Parse format string with token replacement
+      let logMessage = format
+        .replace(':method', method)
+        .replace(':path', path)
+        .replace(':status', status)
+        .replace(':response-time', duration)
+        .replace(':user', user)
+        .replace(':requestId', requestId);
+
+      console.log(`[API Plugin] ${logMessage}`);
     };
   }
 
   /**
-   * Create compression middleware (placeholder)
+   * Create compression middleware (using Node.js zlib)
    * @private
    */
   async _createCompressionMiddleware() {
+    const { gzip, brotliCompress } = await import('zlib');
+    const { promisify } = await import('util');
+
+    const gzipAsync = promisify(gzip);
+    const brotliAsync = promisify(brotliCompress);
+
+    const { threshold, level } = this.config.compression;
+
+    // Content types that should NOT be compressed (already compressed)
+    const skipContentTypes = [
+      'image/', 'video/', 'audio/',
+      'application/zip', 'application/gzip',
+      'application/x-gzip', 'application/x-bzip2'
+    ];
+
     return async (c, next) => {
       await next();
 
-      // TODO: Implement actual compression using zlib
-      // For now, this is a no-op placeholder to avoid ERR_CONTENT_DECODING_FAILED errors
-      //
-      // WARNING: Do NOT set Content-Encoding headers without actually compressing!
-      // Setting these headers without compression causes browsers to fail with:
-      // net::ERR_CONTENT_DECODING_FAILED 200 (OK)
-      //
-      // Real implementation would require:
-      // 1. Check Accept-Encoding header
-      // 2. Compress response body with zlib.gzip() or zlib.deflate()
-      // 3. Set Content-Encoding header
-      // 4. Update Content-Length header
+      // Skip if response has no body
+      if (!c.res || !c.res.body) {
+        return;
+      }
+
+      // Skip if already compressed
+      if (c.res.headers.has('content-encoding')) {
+        return;
+      }
+
+      // Skip if content-type should not be compressed
+      const contentType = c.res.headers.get('content-type') || '';
+      if (skipContentTypes.some(type => contentType.startsWith(type))) {
+        return;
+      }
+
+      // Check Accept-Encoding header
+      const acceptEncoding = c.req.header('accept-encoding') || '';
+      const supportsBrotli = acceptEncoding.includes('br');
+      const supportsGzip = acceptEncoding.includes('gzip');
+
+      if (!supportsBrotli && !supportsGzip) {
+        return; // Client doesn't support compression
+      }
+
+      // Get response body as buffer
+      let body;
+      try {
+        const text = await c.res.text();
+        body = Buffer.from(text, 'utf-8');
+      } catch (err) {
+        // If body is already consumed or not text, skip compression
+        return;
+      }
+
+      // Skip if body is too small
+      if (body.length < threshold) {
+        return;
+      }
+
+      // Compress with brotli (better) or gzip (fallback)
+      let compressed;
+      let encoding;
+
+      try {
+        if (supportsBrotli) {
+          compressed = await brotliAsync(body);
+          encoding = 'br';
+        } else {
+          compressed = await gzipAsync(body, { level });
+          encoding = 'gzip';
+        }
+
+        // Only use compressed if it's actually smaller
+        if (compressed.length >= body.length) {
+          return; // Compression didn't help, use original
+        }
+
+        // Create new response with compressed body
+        const headers = new Headers(c.res.headers);
+        headers.set('Content-Encoding', encoding);
+        headers.set('Content-Length', compressed.length.toString());
+        headers.set('Vary', 'Accept-Encoding');
+
+        // Replace response
+        c.res = new Response(compressed, {
+          status: c.res.status,
+          statusText: c.res.statusText,
+          headers
+        });
+
+      } catch (err) {
+        // Compression failed, log and continue with uncompressed response
+        if (this.config.verbose) {
+          console.error('[API Plugin] Compression error:', err.message);
+        }
+      }
+    };
+  }
+
+  /**
+   * Create security headers middleware (Helmet-like)
+   * @private
+   */
+  async _createSecurityMiddleware() {
+    const { security } = this.config;
+
+    return async (c, next) => {
+      // X-Content-Type-Options: nosniff (MIME sniffing protection)
+      if (security.noSniff) {
+        c.header('X-Content-Type-Options', 'nosniff');
+      }
+
+      // X-Frame-Options (clickjacking protection)
+      if (security.frameguard) {
+        const action = security.frameguard.action.toUpperCase();
+        if (action === 'DENY') {
+          c.header('X-Frame-Options', 'DENY');
+        } else if (action === 'SAMEORIGIN') {
+          c.header('X-Frame-Options', 'SAMEORIGIN');
+        }
+      }
+
+      // Strict-Transport-Security (HSTS - force HTTPS)
+      if (security.hsts) {
+        const parts = [`max-age=${security.hsts.maxAge}`];
+        if (security.hsts.includeSubDomains) {
+          parts.push('includeSubDomains');
+        }
+        if (security.hsts.preload) {
+          parts.push('preload');
+        }
+        c.header('Strict-Transport-Security', parts.join('; '));
+      }
+
+      // Referrer-Policy (privacy)
+      if (security.referrerPolicy) {
+        c.header('Referrer-Policy', security.referrerPolicy.policy);
+      }
+
+      // X-DNS-Prefetch-Control (DNS leak protection)
+      if (security.dnsPrefetchControl) {
+        const value = security.dnsPrefetchControl.allow ? 'on' : 'off';
+        c.header('X-DNS-Prefetch-Control', value);
+      }
+
+      // X-Download-Options (IE8+ download security)
+      if (security.ieNoOpen) {
+        c.header('X-Download-Options', 'noopen');
+      }
+
+      // X-Permitted-Cross-Domain-Policies (Flash/PDF security)
+      if (security.permittedCrossDomainPolicies) {
+        c.header('X-Permitted-Cross-Domain-Policies', security.permittedCrossDomainPolicies.policy);
+      }
+
+      // X-XSS-Protection (legacy XSS filter)
+      if (security.xssFilter) {
+        const mode = security.xssFilter.mode;
+        c.header('X-XSS-Protection', mode === 'block' ? '1; mode=block' : '0');
+      }
+
+      // Permissions-Policy (modern feature policy)
+      if (security.permissionsPolicy && security.permissionsPolicy.features) {
+        const features = security.permissionsPolicy.features;
+        const policies = [];
+
+        for (const [feature, allowList] of Object.entries(features)) {
+          if (Array.isArray(allowList)) {
+            const value = allowList.length === 0
+              ? `${feature}=()`
+              : `${feature}=(${allowList.join(' ')})`;
+            policies.push(value);
+          }
+        }
+
+        if (policies.length > 0) {
+          c.header('Permissions-Policy', policies.join(', '));
+        }
+      }
+
+      // Content-Security-Policy (CSP)
+      // Note: This is also handled by _createCSPMiddleware for backward compatibility
+      // We check if legacy csp.enabled is true, otherwise use security.contentSecurityPolicy
+      const cspConfig = this.config.csp.enabled
+        ? this.config.csp
+        : security.contentSecurityPolicy;
+
+      if (cspConfig && cspConfig.enabled !== false && cspConfig.directives) {
+        const cspParts = [];
+        for (const [directive, values] of Object.entries(cspConfig.directives)) {
+          if (Array.isArray(values) && values.length > 0) {
+            cspParts.push(`${directive} ${values.join(' ')}`);
+          } else if (typeof values === 'string') {
+            cspParts.push(`${directive} ${values}`);
+          }
+        }
+
+        if (cspConfig.reportUri) {
+          cspParts.push(`report-uri ${cspConfig.reportUri}`);
+        }
+
+        if (cspParts.length > 0) {
+          const cspValue = cspParts.join('; ');
+          const headerName = cspConfig.reportOnly
+            ? 'Content-Security-Policy-Report-Only'
+            : 'Content-Security-Policy';
+          c.header(headerName, cspValue);
+        }
+      }
+
+      await next();
     };
   }
 
@@ -469,8 +909,10 @@ export class ApiPlugin extends Plugin {
       port: this.config.port,
       host: this.config.host,
       database: this.database,
+      versionPrefix: this.config.versionPrefix,
       resources: this.config.resources,
       routes: this.config.routes,
+      templates: this.config.templates,
       middlewares: this.compiledMiddlewares,
       verbose: this.config.verbose,
       auth: this.config.auth,
@@ -546,3 +988,10 @@ export class ApiPlugin extends Plugin {
     return this.server ? this.server.getApp() : null;
   }
 }
+
+// Export auth utilities (OIDCClient, guards helpers, etc.)
+export { OIDCClient } from './auth/oidc-client.js';
+export * from './concerns/guards-helpers.js';
+
+// Export template engine utilities
+export { setupTemplateEngine, ejsEngine, jsxEngine } from './utils/template-engine.js';