s3db.js 13.5.1 → 13.6.1

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();
+  };
+}

package/src/plugins/shared/response-formatter.js

@@ -0,0 +1,264 @@
+/**
+ * Response Formatter - Standard JSON API responses
+ *
+ * Provides consistent response formatting across all API endpoints
+ */
+
+/**
+ * Format successful response
+ * @param {Object} data - Response data
+ * @param {Object} options - Response options
+ * @param {number} options.status - HTTP status code (default: 200)
+ * @param {Object} options.meta - Additional metadata
+ * @returns {Object} Formatted response
+ */
+export function success(data, options = {}) {
+  const { status = 200, meta = {} } = options;
+
+  return {
+    success: true,
+    data,
+    meta: {
+      timestamp: new Date().toISOString(),
+      ...meta
+    },
+    _status: status
+  };
+}
+
+/**
+ * Format error response
+ * @param {string|Error} error - Error message or Error object
+ * @param {Object} options - Error options
+ * @param {number} options.status - HTTP status code (default: 500)
+ * @param {string} options.code - Error code
+ * @param {Object} options.details - Additional error details
+ * @returns {Object} Formatted error response
+ */
+export function error(error, options = {}) {
+  const { status = 500, code = 'INTERNAL_ERROR', details = {} } = options;
+
+  const errorMessage = error instanceof Error ? error.message : error;
+  const errorStack = error instanceof Error && process.env.NODE_ENV !== 'production'
+    ? error.stack
+    : undefined;
+
+  return {
+    success: false,
+    error: {
+      message: errorMessage,
+      code,
+      details,
+      stack: errorStack
+    },
+    meta: {
+      timestamp: new Date().toISOString()
+    },
+    _status: status
+  };
+}
+
+/**
+ * Format list response with pagination
+ * @param {Array} items - List items
+ * @param {Object} pagination - Pagination info
+ * @param {number} pagination.total - Total count
+ * @param {number} pagination.page - Current page
+ * @param {number} pagination.pageSize - Items per page
+ * @param {number} pagination.pageCount - Total pages
+ * @returns {Object} Formatted list response
+ */
+export function list(items, pagination = {}) {
+  const { total, page, pageSize, pageCount } = pagination;
+
+  return {
+    success: true,
+    data: items,
+    pagination: {
+      total: total || items.length,
+      page: page || 1,
+      pageSize: pageSize || items.length,
+      pageCount: pageCount || 1
+    },
+    meta: {
+      timestamp: new Date().toISOString()
+    },
+    _status: 200
+  };
+}
+
+/**
+ * Format created response
+ * @param {Object} data - Created resource data
+ * @param {string} location - Resource location URL
+ * @returns {Object} Formatted created response
+ */
+export function created(data, location) {
+  return {
+    success: true,
+    data,
+    meta: {
+      timestamp: new Date().toISOString(),
+      location
+    },
+    _status: 201
+  };
+}
+
+/**
+ * Format no content response
+ * @returns {Object} Formatted no content response
+ */
+export function noContent() {
+  return {
+    success: true,
+    data: null,
+    meta: {
+      timestamp: new Date().toISOString()
+    },
+    _status: 204
+  };
+}
+
+/**
+ * Format validation error response
+ * @param {Array} errors - Validation errors
+ * @returns {Object} Formatted validation error response
+ */
+export function validationError(errors) {
+  return error('Validation failed', {
+    status: 400,
+    code: 'VALIDATION_ERROR',
+    details: { errors }
+  });
+}
+
+/**
+ * Format not found response
+ * @param {string} resource - Resource name
+ * @param {string} id - Resource ID
+ * @returns {Object} Formatted not found response
+ */
+export function notFound(resource, id) {
+  return error(`${resource} with id '${id}' not found`, {
+    status: 404,
+    code: 'NOT_FOUND',
+    details: { resource, id }
+  });
+}
+
+/**
+ * Format unauthorized response
+ * @param {string} message - Unauthorized message
+ * @returns {Object} Formatted unauthorized response
+ */
+export function unauthorized(message = 'Unauthorized') {
+  return error(message, {
+    status: 401,
+    code: 'UNAUTHORIZED'
+  });
+}
+
+/**
+ * Format forbidden response
+ * @param {string} message - Forbidden message
+ * @returns {Object} Formatted forbidden response
+ */
+export function forbidden(message = 'Forbidden') {
+  return error(message, {
+    status: 403,
+    code: 'FORBIDDEN'
+  });
+}
+
+/**
+ * Format rate limit exceeded response
+ * @param {number} retryAfter - Retry after seconds
+ * @returns {Object} Formatted rate limit response
+ */
+export function rateLimitExceeded(retryAfter) {
+  return error('Rate limit exceeded', {
+    status: 429,
+    code: 'RATE_LIMIT_EXCEEDED',
+    details: { retryAfter }
+  });
+}
+
+/**
+ * Format payload too large response
+ * @param {number} size - Received payload size in bytes
+ * @param {number} limit - Maximum allowed size in bytes
+ * @returns {Object} Formatted payload too large response
+ */
+export function payloadTooLarge(size, limit) {
+  return error('Request payload too large', {
+    status: 413,
+    code: 'PAYLOAD_TOO_LARGE',
+    details: {
+      receivedSize: size,
+      maxSize: limit,
+      receivedMB: (size / 1024 / 1024).toFixed(2),
+      maxMB: (limit / 1024 / 1024).toFixed(2)
+    }
+  });
+}
+
+/**
+ * Create custom formatters with override support
+ *
+ * Allows customization of response formats while maintaining fallbacks.
+ * Useful for adapting to existing API contracts or organizational standards.
+ *
+ * @param {Object} customFormatters - Custom formatter functions
+ * @param {Function} customFormatters.success - Custom success formatter
+ * @param {Function} customFormatters.error - Custom error formatter
+ * @param {Function} customFormatters.list - Custom list formatter
+ * @param {Function} customFormatters.created - Custom created formatter
+ * @returns {Object} Formatters object with custom overrides
+ *
+ * @example
+ * const formatters = createCustomFormatters({
+ *   success: (data, meta) => ({ ok: true, result: data, ...meta }),
+ *   error: (err, status) => ({ ok: false, message: err.message, code: status })
+ * });
+ *
+ * // Use in API routes:
+ * return c.json(formatters.success(user));
+ */
+export function createCustomFormatters(customFormatters = {}) {
+  // Default formatters
+  const defaults = {
+    success: (data, meta = {}) => success(data, { meta }),
+    error: (err, status, code) => error(err, { status, code }),
+    list: (items, pagination) => list(items, pagination),
+    created: (data, location) => created(data, location),
+    noContent: () => noContent(),
+    validationError: (errors) => validationError(errors),
+    notFound: (resource, id) => notFound(resource, id),
+    unauthorized: (message) => unauthorized(message),
+    forbidden: (message) => forbidden(message),
+    rateLimitExceeded: (retryAfter) => rateLimitExceeded(retryAfter),
+    payloadTooLarge: (size, limit) => payloadTooLarge(size, limit)
+  };
+
+  // Merge custom formatters with defaults
+  return {
+    ...defaults,
+    ...customFormatters
+  };
+}
+
+export default {
+  success,
+  error,
+  list,
+  created,
+  noContent,
+  validationError,
+  notFound,
+  unauthorized,
+  forbidden,
+  rateLimitExceeded,
+  payloadTooLarge,
+  createCustomFormatters
+};