s3db.js 13.4.0 → 13.6.0

package/src/plugins/api/utils/custom-routes.js

@@ -0,0 +1,102 @@
+/**
+ * Custom Routes Utilities
+ *
+ * Parse and mount custom routes defined in resources or plugins
+ * Inspired by moleculer-js route syntax
+ */
+
+import { asyncHandler } from './error-handler.js';
+
+/**
+ * Parse route definition from key
+ * @param {string} key - Route key (e.g., 'GET /users', 'POST /custom/:id/action')
+ * @returns {Object} { method, path }
+ */
+export function parseRouteKey(key) {
+  const match = key.match(/^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(.+)$/i);
+
+  if (!match) {
+    throw new Error(`Invalid route key format: "${key}". Expected format: "METHOD /path"`);
+  }
+
+  return {
+    method: match[1].toUpperCase(),
+    path: match[2]
+  };
+}
+
+/**
+ * Mount custom routes on Hono app
+ * @param {Object} app - Hono app instance
+ * @param {Object} routes - Routes object { 'METHOD /path': handler }
+ * @param {Object} context - Context to pass to handlers (resource, database, etc.)
+ * @param {boolean} verbose - Enable verbose logging
+ */
+export function mountCustomRoutes(app, routes, context = {}, verbose = false) {
+  if (!routes || typeof routes !== 'object') {
+    return;
+  }
+
+  for (const [key, handler] of Object.entries(routes)) {
+    try {
+      const { method, path } = parseRouteKey(key);
+
+      // Wrap handler with async error handler and context
+      const wrappedHandler = asyncHandler(async (c) => {
+        // Inject context into Hono context
+        c.set('customRouteContext', context);
+
+        // Call user handler with Hono context
+        return await handler(c);
+      });
+
+      // Mount route
+      app.on(method, path, wrappedHandler);
+
+      if (verbose) {
+        console.log(`[Custom Routes] Mounted ${method} ${path}`);
+      }
+    } catch (err) {
+      console.error(`[Custom Routes] Error mounting route "${key}":`, err.message);
+    }
+  }
+}
+
+/**
+ * Validate custom routes object
+ * @param {Object} routes - Routes to validate
+ * @returns {Array} Array of validation errors
+ */
+export function validateCustomRoutes(routes) {
+  const errors = [];
+
+  if (!routes || typeof routes !== 'object') {
+    return errors;
+  }
+
+  for (const [key, handler] of Object.entries(routes)) {
+    // Validate key format
+    try {
+      parseRouteKey(key);
+    } catch (err) {
+      errors.push({ key, error: err.message });
+      continue;
+    }
+
+    // Validate handler is a function
+    if (typeof handler !== 'function') {
+      errors.push({
+        key,
+        error: `Handler must be a function, got ${typeof handler}`
+      });
+    }
+  }
+
+  return errors;
+}
+
+export default {
+  parseRouteKey,
+  mountCustomRoutes,
+  validateCustomRoutes
+};

package/src/plugins/api/utils/guards.js

@@ -0,0 +1,213 @@
+/**
+ * Guards - Authorization checks for resources
+ *
+ * Guards determine if a user can perform an operation on a resource.
+ * Supports: functions, scopes, roles, and combined logic.
+ */
+
+/**
+ * Check if user passes guard
+ * @param {Object} user - Authenticated user object
+ * @param {Function|string|Array|Object|null} guard - Guard configuration
+ * @param {Object} context - Additional context (data, resourceName, operation)
+ * @returns {boolean} True if authorized
+ */
+export function checkGuard(user, guard, context = {}) {
+  // No guard = public access
+  if (!guard) {
+    return true;
+  }
+
+  // No user = unauthorized (unless guard explicitly allows)
+  if (!user && guard !== true) {
+    return false;
+  }
+
+  // Guard is boolean
+  if (typeof guard === 'boolean') {
+    return guard;
+  }
+
+  // Guard is function: (user, context) => boolean
+  if (typeof guard === 'function') {
+    try {
+      return guard(user, context);
+    } catch (err) {
+      console.error('[Guards] Error executing guard function:', err);
+      return false;
+    }
+  }
+
+  // Guard is string: scope name (e.g., 'read:users')
+  if (typeof guard === 'string') {
+    return hasScope(user, guard);
+  }
+
+  // Guard is array: any scope matches (OR logic)
+  if (Array.isArray(guard)) {
+    return guard.some(scope => hasScope(user, scope));
+  }
+
+  // Guard is object: check properties
+  if (typeof guard === 'object') {
+    // Check role
+    if (guard.role) {
+      if (Array.isArray(guard.role)) {
+        if (!guard.role.includes(user.role)) {
+          return false;
+        }
+      } else if (user.role !== guard.role) {
+        return false;
+      }
+    }
+
+    // Check scopes (all must match - AND logic)
+    if (guard.scopes) {
+      const requiredScopes = Array.isArray(guard.scopes) ? guard.scopes : [guard.scopes];
+      if (!requiredScopes.every(scope => hasScope(user, scope))) {
+        return false;
+      }
+    }
+
+    // Check custom function
+    if (guard.check && typeof guard.check === 'function') {
+      try {
+        return guard.check(user, context);
+      } catch (err) {
+        console.error('[Guards] Error executing guard.check function:', err);
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  // Unknown guard type = deny
+  return false;
+}
+
+/**
+ * Check if user has specific scope
+ * @param {Object} user - User object
+ * @param {string} scope - Scope name (e.g., 'read:users')
+ * @returns {boolean} True if user has scope
+ */
+export function hasScope(user, scope) {
+  if (!user || !user.scopes) {
+    return false;
+  }
+
+  if (!Array.isArray(user.scopes)) {
+    return false;
+  }
+
+  // Direct match
+  if (user.scopes.includes(scope)) {
+    return true;
+  }
+
+  // Wildcard match (e.g., 'admin:*' matches 'admin:users')
+  const wildcards = user.scopes.filter(s => s.endsWith(':*'));
+  for (const wildcard of wildcards) {
+    const prefix = wildcard.slice(0, -2); // Remove ':*'
+    if (scope.startsWith(prefix + ':')) {
+      return true;
+    }
+  }
+
+  // Super admin wildcard ('*' matches everything)
+  if (user.scopes.includes('*')) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Get operation-specific guard from guards config
+ * @param {Object} guards - Guards configuration
+ * @param {string} operation - Operation name ('list', 'get', 'create', 'update', 'delete')
+ * @returns {Function|string|Array|Object|null} Guard for operation
+ */
+export function getOperationGuard(guards, operation) {
+  if (!guards) {
+    return null;
+  }
+
+  // If guards is a function/string/array, apply to all operations
+  if (typeof guards === 'function' || typeof guards === 'string' || Array.isArray(guards)) {
+    return guards;
+  }
+
+  // If guards is object, get operation-specific guard
+  if (typeof guards === 'object') {
+    // Check for specific operation
+    if (guards[operation] !== undefined) {
+      return guards[operation];
+    }
+
+    // Fallback to 'all' or default
+    if (guards.all !== undefined) {
+      return guards.all;
+    }
+
+    // Map operation aliases
+    const aliases = {
+      list: 'read',
+      get: 'read',
+      create: 'write',
+      update: 'write',
+      delete: 'write'
+    };
+
+    if (aliases[operation] && guards[aliases[operation]] !== undefined) {
+      return guards[aliases[operation]];
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Create guard middleware for Hono
+ * @param {Object} guards - Guards configuration
+ * @param {string} operation - Operation name
+ * @returns {Function} Hono middleware
+ */
+export function guardMiddleware(guards, operation) {
+  return async (c, next) => {
+    const user = c.get('user');
+    const guard = getOperationGuard(guards, operation);
+
+    // Check guard
+    const authorized = checkGuard(user, guard, {
+      operation,
+      resourceName: c.req.param('resource'),
+      data: c.req.method !== 'GET' ? await c.req.json().catch(() => ({})) : {}
+    });
+
+    if (!authorized) {
+      return c.json({
+        success: false,
+        error: {
+          message: 'Forbidden: Insufficient permissions',
+          code: 'FORBIDDEN',
+          details: {
+            operation,
+            user: user ? { id: user.id, role: user.role } : null
+          }
+        },
+        _status: 403
+      }, 403);
+    }
+
+    await next();
+  };
+}
+
+export default {
+  checkGuard,
+  hasScope,
+  getOperationGuard,
+  guardMiddleware
+};

package/src/plugins/api/utils/mime-types.js

@@ -0,0 +1,154 @@
+/**
+ * MIME Type Detection
+ *
+ * Lightweight MIME type detection based on file extensions
+ */
+
+/**
+ * Common MIME types mapped by extension
+ */
+const MIME_TYPES = {
+  // Text
+  'txt': 'text/plain',
+  'html': 'text/html',
+  'htm': 'text/html',
+  'css': 'text/css',
+  'js': 'text/javascript',
+  'mjs': 'text/javascript',
+  'json': 'application/json',
+  'xml': 'application/xml',
+  'csv': 'text/csv',
+  'md': 'text/markdown',
+
+  // Images
+  'jpg': 'image/jpeg',
+  'jpeg': 'image/jpeg',
+  'png': 'image/png',
+  'gif': 'image/gif',
+  'webp': 'image/webp',
+  'svg': 'image/svg+xml',
+  'ico': 'image/x-icon',
+  'bmp': 'image/bmp',
+  'tiff': 'image/tiff',
+  'tif': 'image/tiff',
+
+  // Audio
+  'mp3': 'audio/mpeg',
+  'wav': 'audio/wav',
+  'ogg': 'audio/ogg',
+  'flac': 'audio/flac',
+  'm4a': 'audio/mp4',
+
+  // Video
+  'mp4': 'video/mp4',
+  'webm': 'video/webm',
+  'ogv': 'video/ogg',
+  'avi': 'video/x-msvideo',
+  'mov': 'video/quicktime',
+  'mkv': 'video/x-matroska',
+
+  // Documents
+  'pdf': 'application/pdf',
+  'doc': 'application/msword',
+  'docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  'xls': 'application/vnd.ms-excel',
+  'xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  'ppt': 'application/vnd.ms-powerpoint',
+  'pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+
+  // Archives
+  'zip': 'application/zip',
+  'tar': 'application/x-tar',
+  'gz': 'application/gzip',
+  'bz2': 'application/x-bzip2',
+  '7z': 'application/x-7z-compressed',
+  'rar': 'application/vnd.rar',
+
+  // Fonts
+  'ttf': 'font/ttf',
+  'otf': 'font/otf',
+  'woff': 'font/woff',
+  'woff2': 'font/woff2',
+  'eot': 'application/vnd.ms-fontobject',
+
+  // Application
+  'wasm': 'application/wasm',
+  'bin': 'application/octet-stream'
+};
+
+/**
+ * Get MIME type from filename
+ * @param {string} filename - Filename with extension
+ * @returns {string} MIME type (defaults to 'application/octet-stream')
+ * @example
+ * getMimeType('image.png') // 'image/png'
+ * getMimeType('document.pdf') // 'application/pdf'
+ * getMimeType('unknown.xyz') // 'application/octet-stream'
+ */
+export function getMimeType(filename) {
+  if (!filename || typeof filename !== 'string') {
+    return 'application/octet-stream';
+  }
+
+  // Extract extension (lowercase)
+  const ext = filename.split('.').pop().toLowerCase();
+
+  return MIME_TYPES[ext] || 'application/octet-stream';
+}
+
+/**
+ * Check if MIME type is compressible
+ * @param {string} mimeType - MIME type
+ * @returns {boolean} True if compressible
+ */
+export function isCompressible(mimeType) {
+  if (!mimeType) return false;
+
+  // Text-based content is compressible
+  if (mimeType.startsWith('text/')) return true;
+  if (mimeType.includes('javascript')) return true;
+  if (mimeType.includes('json')) return true;
+  if (mimeType.includes('xml')) return true;
+  if (mimeType.includes('svg')) return true;
+
+  return false;
+}
+
+/**
+ * Get charset for MIME type
+ * @param {string} mimeType - MIME type
+ * @returns {string|null} Charset or null
+ */
+export function getCharset(mimeType) {
+  if (!mimeType) return null;
+
+  // Text types should have UTF-8 charset
+  if (mimeType.startsWith('text/')) return 'utf-8';
+  if (mimeType.includes('javascript')) return 'utf-8';
+  if (mimeType.includes('json')) return 'utf-8';
+  if (mimeType.includes('xml')) return 'utf-8';
+
+  return null;
+}
+
+/**
+ * Build complete Content-Type header
+ * @param {string} filename - Filename
+ * @returns {string} Complete Content-Type header
+ * @example
+ * getContentType('file.html') // 'text/html; charset=utf-8'
+ * getContentType('image.png') // 'image/png'
+ */
+export function getContentType(filename) {
+  const mimeType = getMimeType(filename);
+  const charset = getCharset(mimeType);
+
+  return charset ? `${mimeType}; charset=${charset}` : mimeType;
+}
+
+export default {
+  getMimeType,
+  isCompressible,
+  getCharset,
+  getContentType
+};

package/src/plugins/api/utils/openapi-generator.js

@@ -185,7 +185,20 @@ function generateResourceSchema(resource) {
  */
 function generateResourcePaths(resource, version, config = {}) {
   const resourceName = resource.name;
-  const basePath = `/${version}/${resourceName}`;
+
+  // Determine version prefix (same logic as server.js)
+  let versionPrefixConfig = config.versionPrefix !== undefined ? config.versionPrefix : false;
+
+  let prefix = '';
+  if (versionPrefixConfig === true) {
+    prefix = version;
+  } else if (versionPrefixConfig === false) {
+    prefix = '';
+  } else if (typeof versionPrefixConfig === 'string') {
+    prefix = versionPrefixConfig;
+  }
+
+  const basePath = prefix ? `/${prefix}/${resourceName}` : `/${resourceName}`;
   const schema = generateResourceSchema(resource);
   const methods = config.methods || ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
   const authMethods = config.auth || [];
@@ -820,11 +833,14 @@ The response includes pagination metadata in the \`pagination\` object with tota
  * @param {Object} relationConfig - Relation configuration
  * @param {string} version - Resource version
  * @param {Object} relatedSchema - OpenAPI schema for related resource
+ * @param {string} versionPrefix - Version prefix to use (empty string for no prefix)
  * @returns {Object} OpenAPI paths for relation
  */
-function generateRelationalPaths(resource, relationName, relationConfig, version, relatedSchema) {
+function generateRelationalPaths(resource, relationName, relationConfig, version, relatedSchema, versionPrefix = '') {
   const resourceName = resource.name;
-  const basePath = `/${version}/${resourceName}/{id}/${relationName}`;
+  const basePath = versionPrefix
+    ? `/${versionPrefix}/${resourceName}/{id}/${relationName}`
+    : `/${resourceName}/{id}/${relationName}`;
   const relatedResourceName = relationConfig.resource;
   const isToMany = relationConfig.type === 'hasMany' || relationConfig.type === 'belongsToMany';
 
@@ -933,14 +949,22 @@ export function generateOpenAPISpec(database, config = {}) {
     description = 'Auto-generated REST API documentation for s3db.js resources',
     serverUrl = 'http://localhost:3000',
     auth = {},
-    resources: resourceConfigs = {}
+    resources: resourceConfigs = {},
+    versionPrefix: globalVersionPrefix
   } = config;
 
   // Build resources table for description
   const resourcesTableRows = [];
   for (const [name, resource] of Object.entries(database.resources)) {
+    const rawConfig = resourceConfigs[name];
+
+    // Skip resources explicitly disabled
+    if (rawConfig?.enabled === false) {
+      continue;
+    }
+
     // Skip plugin resources unless explicitly configured
-    if (name.startsWith('plg_') && !resourceConfigs[name]) {
+    if (name.startsWith('plg_') && !rawConfig) {
       continue;
     }
 
@@ -950,7 +974,31 @@ export function generateOpenAPISpec(database, config = {}) {
       ? resourceDescription.resource
       : resourceDescription || 'No description';
 
-    resourcesTableRows.push(`| ${name} | ${descText} | \`/${version}/${name}\` |`);
+    // Check version prefix for this resource (same logic as server.js)
+    const resourceConfig = rawConfig && typeof rawConfig === 'object' ? rawConfig : {};
+    let versionPrefixConfig;
+    if (resourceConfig.versionPrefix !== undefined) {
+      versionPrefixConfig = resourceConfig.versionPrefix;
+    } else if (resource.config && resource.config.versionPrefix !== undefined) {
+      versionPrefixConfig = resource.config.versionPrefix;
+    } else if (globalVersionPrefix !== undefined) {
+      versionPrefixConfig = globalVersionPrefix;
+    } else {
+      versionPrefixConfig = false; // Default to no prefix
+    }
+
+    let prefix = '';
+    if (versionPrefixConfig === true) {
+      prefix = version;
+    } else if (versionPrefixConfig === false) {
+      prefix = '';
+    } else if (typeof versionPrefixConfig === 'string') {
+      prefix = versionPrefixConfig;
+    }
+
+    const basePath = prefix ? `/${prefix}/${name}` : `/${name}`;
+
+    resourcesTableRows.push(`| ${name} | ${descText} | \`${basePath}\` |`);
   }
 
   // Build enhanced description with resources table
@@ -1070,13 +1118,19 @@ For detailed information about each endpoint, see the sections below.`;
   const relationsPlugin = database.plugins?.relation || database.plugins?.RelationPlugin || null;
 
   for (const [name, resource] of Object.entries(resources)) {
+    const rawConfig = resourceConfigs[name];
+
+    if (rawConfig?.enabled === false) {
+      continue;
+    }
+
     // Skip plugin resources unless explicitly configured
-    if (name.startsWith('plg_') && !resourceConfigs[name]) {
+    if (name.startsWith('plg_') && !rawConfig) {
       continue;
     }
 
     // Get resource configuration
-    const config = resourceConfigs[name] || {
+    const resourceConfig = rawConfig && typeof rawConfig === 'object' ? { ...rawConfig } : {
       methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
       auth: false
     };
@@ -1084,8 +1138,32 @@ For detailed information about each endpoint, see the sections below.`;
     // Determine version
     const version = resource.config?.currentVersion || resource.version || 'v1';
 
+    // Determine version prefix (same logic as server.js)
+    let versionPrefixConfig;
+    if (resourceConfig.versionPrefix !== undefined) {
+      versionPrefixConfig = resourceConfig.versionPrefix;
+    } else if (resource.config && resource.config.versionPrefix !== undefined) {
+      versionPrefixConfig = resource.config.versionPrefix;
+    } else if (globalVersionPrefix !== undefined) {
+      versionPrefixConfig = globalVersionPrefix;
+    } else {
+      versionPrefixConfig = false;
+    }
+
+    let prefix = '';
+    if (versionPrefixConfig === true) {
+      prefix = version;
+    } else if (versionPrefixConfig === false) {
+      prefix = '';
+    } else if (typeof versionPrefixConfig === 'string') {
+      prefix = versionPrefixConfig;
+    }
+
     // Generate paths
-    const paths = generateResourcePaths(resource, version, config);
+    const paths = generateResourcePaths(resource, version, {
+      ...resourceConfig,
+      versionPrefix: versionPrefixConfig
+    });
 
     // Merge paths
     Object.assign(spec.paths, paths);
@@ -1115,7 +1193,7 @@ For detailed information about each endpoint, see the sections below.`;
         }
 
         // Check if relation should be exposed (default: yes)
-        const exposeRelation = config?.relations?.[relationName]?.expose !== false;
+        const exposeRelation = resourceConfig?.relations?.[relationName]?.expose !== false;
         if (!exposeRelation) {
           continue;
         }
@@ -1128,13 +1206,14 @@ For detailed information about each endpoint, see the sections below.`;
 
         const relatedSchema = generateResourceSchema(relatedResource);
 
-        // Generate relational paths
+        // Generate relational paths (using the same prefix calculated above)
         const relationalPaths = generateRelationalPaths(
           resource,
           relationName,
           relationConfig,
           version,
-          relatedSchema
+          relatedSchema,
+          prefix
         );
 
         // Merge relational paths