s3db.js 13.4.0 → 13.6.0

package/src/plugins/shared/error-handler.js

@@ -0,0 +1,147 @@
+/**
+ * Error Handler - Global error handling middleware
+ *
+ * Catches and formats errors from routes and middlewares
+ */
+
+import { error as formatError } from './response-formatter.js';
+
+/**
+ * Map s3db.js errors to HTTP status codes
+ */
+const errorStatusMap = {
+  'ValidationError': 400,
+  'InvalidResourceItem': 400,
+  'ResourceNotFound': 404,
+  'NoSuchKey': 404,
+  'NoSuchBucket': 404,
+  'PartitionError': 400,
+  'CryptoError': 500,
+  'SchemaError': 400,
+  'QueueError': 500,
+  'ResourceError': 500
+};
+
+/**
+ * Get HTTP status code from error
+ * @param {Error} err - Error object
+ * @returns {number} HTTP status code
+ */
+function getStatusFromError(err) {
+  // Check error name
+  if (err.name && errorStatusMap[err.name]) {
+    return errorStatusMap[err.name];
+  }
+
+  // Check error constructor name
+  if (err.constructor && err.constructor.name && errorStatusMap[err.constructor.name]) {
+    return errorStatusMap[err.constructor.name];
+  }
+
+  // Check for specific error patterns
+  if (err.message) {
+    if (err.message.includes('not found') || err.message.includes('does not exist')) {
+      return 404;
+    }
+    if (err.message.includes('validation') || err.message.includes('invalid')) {
+      return 400;
+    }
+    if (err.message.includes('unauthorized') || err.message.includes('authentication')) {
+      return 401;
+    }
+    if (err.message.includes('forbidden') || err.message.includes('permission')) {
+      return 403;
+    }
+  }
+
+  // Default to 500
+  return 500;
+}
+
+/**
+ * Global error handler middleware
+ * @param {Error} err - Error object
+ * @param {Object} c - Hono context
+ * @returns {Response} Error response
+ */
+export function errorHandler(err, c) {
+  const status = getStatusFromError(err);
+
+  // Get error code from error name or default
+  const code = err.name || 'INTERNAL_ERROR';
+
+  // Extract error details
+  const details = {};
+
+  if (err.resource) details.resource = err.resource;
+  if (err.bucket) details.bucket = err.bucket;
+  if (err.key) details.key = err.key;
+  if (err.operation) details.operation = err.operation;
+  if (err.suggestion) details.suggestion = err.suggestion;
+  if (err.availableResources) details.availableResources = err.availableResources;
+
+  // Format error response
+  const response = formatError(err, {
+    status,
+    code,
+    details
+  });
+
+  // Log error (except for expected errors like 404)
+  if (status >= 500) {
+    console.error('[API Plugin] Error:', {
+      message: err.message,
+      code,
+      status,
+      stack: err.stack,
+      details
+    });
+  } else if (status >= 400 && status < 500 && c.get('verbose')) {
+    console.warn('[API Plugin] Client error:', {
+      message: err.message,
+      code,
+      status,
+      details
+    });
+  }
+
+  return c.json(response, response._status);
+}
+
+/**
+ * Async error wrapper for route handlers
+ * @param {Function} fn - Async route handler
+ * @returns {Function} Wrapped handler with error catching
+ */
+export function asyncHandler(fn) {
+  return async (c) => {
+    try {
+      return await fn(c);
+    } catch (err) {
+      return errorHandler(err, c);
+    }
+  };
+}
+
+/**
+ * Try-catch wrapper with formatted error response
+ * @param {Function} fn - Function to execute
+ * @param {Object} c - Hono context
+ * @returns {Promise<[boolean, Error|null, any]>} [ok, error, result] tuple
+ */
+export async function tryApiCall(fn, c) {
+  try {
+    const result = await fn();
+    return [true, null, result];
+  } catch (err) {
+    const response = errorHandler(err, c);
+    return [false, err, response];
+  }
+}
+
+export default {
+  errorHandler,
+  asyncHandler,
+  tryApiCall,
+  getStatusFromError
+};

package/src/plugins/shared/index.js

@@ -0,0 +1,9 @@
+/**
+ * Shared Plugin Utilities
+ *
+ * Common code shared between API Plugin and Identity Plugin
+ */
+
+export { errorHandler } from './error-handler.js';
+export * as formatter from './response-formatter.js';
+export * as middlewares from './middlewares/index.js';

package/src/plugins/shared/middlewares/compression.js

@@ -0,0 +1,117 @@
+/**
+ * Compression Middleware
+ *
+ * Compresses HTTP responses using gzip or brotli compression.
+ * Automatically skips already compressed content and small payloads.
+ */
+
+import { gzip, brotliCompress } from 'zlib';
+import { promisify } from 'util';
+
+const gzipAsync = promisify(gzip);
+const brotliAsync = promisify(brotliCompress);
+
+/**
+ * Create compression middleware
+ * @param {Object} config - Compression configuration
+ * @param {number} config.threshold - Minimum size in bytes to compress
+ * @param {number} config.level - Compression level (1-9)
+ * @param {boolean} config.verbose - Enable verbose logging
+ * @returns {Function} Hono middleware
+ */
+export function createCompressionMiddleware(config = {}) {
+  const {
+    threshold = 1024, // 1KB
+    level = 6,
+    verbose = false
+  } = config;
+
+  // 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();
+
+    // 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 (verbose) {
+        console.error('[Compression] Error:', err.message);
+      }
+    }
+  };
+}

package/src/plugins/shared/middlewares/cors.js

@@ -0,0 +1,49 @@
+/**
+ * CORS Middleware
+ *
+ * Handles Cross-Origin Resource Sharing (CORS) headers and preflight requests.
+ * Supports wildcard origins, credential-based requests, and OPTIONS preflight.
+ */
+
+/**
+ * Create CORS middleware
+ * @param {Object} config - CORS configuration
+ * @param {string} config.origin - Allowed origin ('*' or specific domain)
+ * @param {Array<string>} config.methods - Allowed HTTP methods
+ * @param {Array<string>} config.allowedHeaders - Allowed request headers
+ * @param {Array<string>} config.exposedHeaders - Exposed response headers
+ * @param {boolean} config.credentials - Allow credentials
+ * @param {number} config.maxAge - Preflight cache duration
+ * @returns {Function} Hono middleware
+ */
+export function createCorsMiddleware(config = {}) {
+  const {
+    origin = '*',
+    methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+    allowedHeaders = ['Content-Type', 'Authorization', 'X-API-Key'],
+    exposedHeaders = ['X-Total-Count', 'X-Page-Count'],
+    credentials = true,
+    maxAge = 86400
+  } = config;
+
+  return async (c, next) => {
+    // Set CORS headers
+    c.header('Access-Control-Allow-Origin', origin);
+    c.header('Access-Control-Allow-Methods', methods.join(', '));
+    c.header('Access-Control-Allow-Headers', allowedHeaders.join(', '));
+    c.header('Access-Control-Expose-Headers', exposedHeaders.join(', '));
+
+    if (credentials) {
+      c.header('Access-Control-Allow-Credentials', 'true');
+    }
+
+    c.header('Access-Control-Max-Age', maxAge.toString());
+
+    // Handle OPTIONS preflight
+    if (c.req.method === 'OPTIONS') {
+      return c.body(null, 204);
+    }
+
+    await next();
+  };
+}

package/src/plugins/shared/middlewares/index.js

@@ -0,0 +1,11 @@
+/**
+ * Shared Middlewares
+ *
+ * Common HTTP middlewares used by multiple plugins (API Plugin, Identity Plugin)
+ */
+
+export { createCorsMiddleware } from './cors.js';
+export { createRateLimitMiddleware } from './rate-limit.js';
+export { createLoggingMiddleware } from './logging.js';
+export { createCompressionMiddleware } from './compression.js';
+export { createSecurityMiddleware } from './security.js';

package/src/plugins/shared/middlewares/logging.js

@@ -0,0 +1,54 @@
+/**
+ * Logging Middleware
+ *
+ * Logs HTTP requests with customizable format and tokens.
+ *
+ * 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'
+ */
+
+/**
+ * Create logging middleware
+ * @param {Object} config - Logging configuration
+ * @param {string} config.format - Log format string with tokens
+ * @param {boolean} config.verbose - Enable verbose logging
+ * @returns {Function} Hono middleware
+ */
+export function createLoggingMiddleware(config = {}) {
+  const {
+    format = ':method :path :status :response-time ms',
+    verbose = false
+  } = config;
+
+  return async (c, next) => {
+    const start = Date.now();
+    const method = c.req.method;
+    const path = c.req.path;
+    const requestId = c.get('requestId');
+
+    await next();
+
+    const duration = Date.now() - start;
+    const status = c.res.status;
+    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(`[HTTP] ${logMessage}`);
+  };
+}

package/src/plugins/shared/middlewares/rate-limit.js

@@ -0,0 +1,73 @@
+/**
+ * Rate Limiting Middleware
+ *
+ * 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.
+ */
+
+/**
+ * Create rate limiting middleware
+ * @param {Object} config - Rate limiting configuration
+ * @param {number} config.windowMs - Time window in milliseconds
+ * @param {number} config.maxRequests - Maximum requests per window
+ * @param {Function} config.keyGenerator - Custom key generator function
+ * @returns {Function} Hono middleware
+ */
+export function createRateLimitMiddleware(config = {}) {
+  const {
+    windowMs = 60000, // 1 minute
+    maxRequests = 100,
+    keyGenerator = null
+  } = config;
+
+  const requests = new Map();
+
+  return async (c, next) => {
+    // Generate key (IP or custom)
+    const key = keyGenerator
+      ? keyGenerator(c)
+      : c.req.header('x-forwarded-for') || c.req.header('cf-connecting-ip') || 'unknown';
+
+    // Get or create request count
+    if (!requests.has(key)) {
+      requests.set(key, { count: 0, resetAt: Date.now() + windowMs });
+    }
+
+    const record = requests.get(key);
+
+    // Reset if window expired
+    if (Date.now() > record.resetAt) {
+      record.count = 0;
+      record.resetAt = Date.now() + windowMs;
+    }
+
+    // Check limit
+    if (record.count >= maxRequests) {
+      const retryAfter = Math.ceil((record.resetAt - Date.now()) / 1000);
+      c.header('Retry-After', retryAfter.toString());
+      c.header('X-RateLimit-Limit', maxRequests.toString());
+      c.header('X-RateLimit-Remaining', '0');
+      c.header('X-RateLimit-Reset', record.resetAt.toString());
+
+      return c.json({
+        success: false,
+        error: {
+          message: 'Rate limit exceeded',
+          code: 'RATE_LIMIT_EXCEEDED',
+          details: { retryAfter }
+        }
+      }, 429);
+    }
+
+    // Increment count
+    record.count++;
+
+    // Set rate limit headers
+    c.header('X-RateLimit-Limit', maxRequests.toString());
+    c.header('X-RateLimit-Remaining', (maxRequests - record.count).toString());
+    c.header('X-RateLimit-Reset', record.resetAt.toString());
+
+    await next();
+  };
+}

package/src/plugins/shared/middlewares/security.js

@@ -0,0 +1,158 @@
+/**
+ * Security Headers Middleware (Helmet-like)
+ *
+ * Adds security headers to HTTP responses:
+ * - Content-Security-Policy (CSP)
+ * - X-Frame-Options (clickjacking)
+ * - X-Content-Type-Options (MIME sniffing)
+ * - Strict-Transport-Security (HSTS)
+ * - Referrer-Policy
+ * - X-DNS-Prefetch-Control
+ * - X-Download-Options
+ * - X-Permitted-Cross-Domain-Policies
+ * - X-XSS-Protection
+ * - Permissions-Policy
+ */
+
+/**
+ * Create security headers middleware
+ * @param {Object} config - Security configuration
+ * @returns {Function} Hono middleware
+ */
+export function createSecurityMiddleware(config = {}) {
+  const {
+    contentSecurityPolicy = {
+      enabled: true,
+      directives: {
+        'default-src': ["'self'"],
+        'script-src': ["'self'", "'unsafe-inline'"],
+        'style-src': ["'self'", "'unsafe-inline'"],
+        'img-src': ["'self'", 'data:', 'https:']
+      },
+      reportOnly: false,
+      reportUri: null
+    },
+    frameguard = { action: 'deny' },
+    noSniff = true,
+    hsts = {
+      maxAge: 15552000, // 180 days
+      includeSubDomains: true,
+      preload: false
+    },
+    referrerPolicy = { policy: 'no-referrer' },
+    dnsPrefetchControl = { allow: false },
+    ieNoOpen = true,
+    permittedCrossDomainPolicies = { policy: 'none' },
+    xssFilter = { mode: 'block' },
+    permissionsPolicy = {
+      features: {
+        geolocation: [],
+        microphone: [],
+        camera: [],
+        payment: [],
+        usb: []
+      }
+    }
+  } = config;
+
+  return async (c, next) => {
+    // X-Content-Type-Options: nosniff (MIME sniffing protection)
+    if (noSniff) {
+      c.header('X-Content-Type-Options', 'nosniff');
+    }
+
+    // X-Frame-Options (clickjacking protection)
+    if (frameguard) {
+      const action = 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 (hsts) {
+      const parts = [`max-age=${hsts.maxAge}`];
+      if (hsts.includeSubDomains) {
+        parts.push('includeSubDomains');
+      }
+      if (hsts.preload) {
+        parts.push('preload');
+      }
+      c.header('Strict-Transport-Security', parts.join('; '));
+    }
+
+    // Referrer-Policy (privacy)
+    if (referrerPolicy) {
+      c.header('Referrer-Policy', referrerPolicy.policy);
+    }
+
+    // X-DNS-Prefetch-Control (DNS leak protection)
+    if (dnsPrefetchControl) {
+      const value = dnsPrefetchControl.allow ? 'on' : 'off';
+      c.header('X-DNS-Prefetch-Control', value);
+    }
+
+    // X-Download-Options (IE8+ download security)
+    if (ieNoOpen) {
+      c.header('X-Download-Options', 'noopen');
+    }
+
+    // X-Permitted-Cross-Domain-Policies (Flash/PDF security)
+    if (permittedCrossDomainPolicies) {
+      c.header('X-Permitted-Cross-Domain-Policies', permittedCrossDomainPolicies.policy);
+    }
+
+    // X-XSS-Protection (legacy XSS filter)
+    if (xssFilter) {
+      const mode = xssFilter.mode;
+      c.header('X-XSS-Protection', mode === 'block' ? '1; mode=block' : '0');
+    }
+
+    // Permissions-Policy (modern feature policy)
+    if (permissionsPolicy && permissionsPolicy.features) {
+      const features = 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)
+    if (contentSecurityPolicy && contentSecurityPolicy.enabled !== false && contentSecurityPolicy.directives) {
+      const cspParts = [];
+      for (const [directive, values] of Object.entries(contentSecurityPolicy.directives)) {
+        if (Array.isArray(values) && values.length > 0) {
+          cspParts.push(`${directive} ${values.join(' ')}`);
+        } else if (typeof values === 'string') {
+          cspParts.push(`${directive} ${values}`);
+        }
+      }
+
+      if (contentSecurityPolicy.reportUri) {
+        cspParts.push(`report-uri ${contentSecurityPolicy.reportUri}`);
+      }
+
+      if (cspParts.length > 0) {
+        const cspValue = cspParts.join('; ');
+        const headerName = contentSecurityPolicy.reportOnly
+          ? 'Content-Security-Policy-Report-Only'
+          : 'Content-Security-Policy';
+        c.header(headerName, cspValue);
+      }
+    }
+
+    await next();
+  };
+}