s3db.js 13.4.0 → 13.6.0

package/src/plugins/api/utils/path-matcher.js

@@ -0,0 +1,173 @@
+/**
+ * Path Matcher - Wildcard-based path matching with specificity sorting
+ *
+ * Supports:
+ * - `*` - Match single path segment (e.g., /api/v1/* → /api/v1/users ✅, /api/v1/users/123 ❌)
+ * - `**` - Match multiple segments (e.g., /api/** → /api/v1/users ✅, /api/v1/users/123 ✅)
+ *
+ * Precedence: Most specific path wins (exact > * > **)
+ */
+
+/**
+ * Convert wildcard pattern to regex
+ * @param {string} pattern - Path pattern with wildcards (*, **)
+ * @returns {RegExp} Compiled regex
+ * @private
+ */
+function patternToRegex(pattern) {
+  // Escape regex special chars except * and /
+  let escaped = pattern
+    .replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+
+  // Replace ** with a placeholder first (to avoid conflict with *)
+  escaped = escaped.replace(/\*\*/g, '__DOUBLE_STAR__');
+
+  // Replace * with regex that matches any characters except /
+  escaped = escaped.replace(/\*/g, '([^/]+)');
+
+  // Replace placeholder with regex that matches any characters including /
+  escaped = escaped.replace(/__DOUBLE_STAR__/g, '(.*)');
+
+  // Anchor to start and end
+  return new RegExp(`^${escaped}$`);
+}
+
+/**
+ * Check if a path matches a pattern
+ * @param {string} pattern - Path pattern with wildcards
+ * @param {string} path - Actual request path
+ * @returns {boolean} True if path matches pattern
+ * @example
+ * matchPath('/api/v1/*', '/api/v1/users') // true
+ * matchPath('/api/v1/*', '/api/v1/users/123') // false
+ * matchPath('/api/v1/**', '/api/v1/users/123') // true
+ */
+export function matchPath(pattern, path) {
+  const regex = patternToRegex(pattern);
+  return regex.test(path);
+}
+
+/**
+ * Calculate specificity score for a pattern
+ * Higher score = more specific = higher precedence
+ *
+ * Scoring:
+ * - Each exact segment: +1000
+ * - Each * wildcard: +100
+ * - Each ** wildcard: +10
+ *
+ * @param {string} pattern - Path pattern
+ * @returns {number} Specificity score
+ * @private
+ * @example
+ * calculateSpecificity('/api/v1/admin/users') // 4000 (4 exact segments)
+ * calculateSpecificity('/api/v1/admin/*') // 3100 (3 exact + 1 *)
+ * calculateSpecificity('/api/v1/**') // 2010 (2 exact + 1 **)
+ * calculateSpecificity('/api/**') // 1010 (1 exact + 1 **)
+ */
+function calculateSpecificity(pattern) {
+  const segments = pattern.split('/').filter(s => s !== '');
+
+  let score = 0;
+
+  for (const segment of segments) {
+    if (segment === '**') {
+      score += 10; // Lowest precedence
+    } else if (segment === '*') {
+      score += 100; // Medium precedence
+    } else {
+      score += 1000; // Highest precedence (exact match)
+    }
+  }
+
+  return score;
+}
+
+/**
+ * Find the best matching rule for a given path
+ * Returns the most specific rule that matches the path
+ *
+ * @param {Array<Object>} rules - Array of path auth rules
+ * @param {string} rules[].pattern - Path pattern
+ * @param {Array<string>} rules[].drivers - Auth drivers
+ * @param {boolean} rules[].required - Whether auth is required
+ * @param {string} path - Request path
+ * @returns {Object|null} Best matching rule or null if no match
+ * @example
+ * const rules = [
+ *   { pattern: '/api/**', drivers: ['jwt'], required: true },
+ *   { pattern: '/api/v1/admin/**', drivers: ['jwt', 'apiKey'], required: true },
+ *   { pattern: '/health/*', required: false }
+ * ];
+ *
+ * findBestMatch(rules, '/api/v1/admin/users');
+ * // Returns { pattern: '/api/v1/admin/**', ... } (most specific)
+ *
+ * findBestMatch(rules, '/health/liveness');
+ * // Returns { pattern: '/health/*', required: false }
+ */
+export function findBestMatch(rules, path) {
+  if (!rules || rules.length === 0) {
+    return null;
+  }
+
+  // Find all matching rules
+  const matches = rules
+    .map(rule => ({
+      rule,
+      specificity: calculateSpecificity(rule.pattern)
+    }))
+    .filter(({ rule }) => matchPath(rule.pattern, path))
+    .sort((a, b) => b.specificity - a.specificity); // Descending (highest first)
+
+  // Return most specific match
+  return matches.length > 0 ? matches[0].rule : null;
+}
+
+/**
+ * Validate pathAuth configuration
+ * @param {Array<Object>} pathAuth - Path auth rules
+ * @throws {Error} If configuration is invalid
+ */
+export function validatePathAuth(pathAuth) {
+  if (!Array.isArray(pathAuth)) {
+    throw new Error('pathAuth must be an array of rules');
+  }
+
+  for (const [index, rule] of pathAuth.entries()) {
+    if (!rule.pattern || typeof rule.pattern !== 'string') {
+      throw new Error(`pathAuth[${index}]: pattern is required and must be a string`);
+    }
+
+    if (!rule.pattern.startsWith('/')) {
+      throw new Error(`pathAuth[${index}]: pattern must start with / (got: ${rule.pattern})`);
+    }
+
+    if (rule.drivers !== undefined && !Array.isArray(rule.drivers)) {
+      throw new Error(`pathAuth[${index}]: drivers must be an array (got: ${typeof rule.drivers})`);
+    }
+
+    if (rule.required !== undefined && typeof rule.required !== 'boolean') {
+      throw new Error(`pathAuth[${index}]: required must be a boolean (got: ${typeof rule.required})`);
+    }
+
+    // Validate drivers (if specified)
+    const validDrivers = ['jwt', 'apiKey', 'basic', 'oauth2', 'oidc'];
+    if (rule.drivers) {
+      for (const driver of rule.drivers) {
+        if (!validDrivers.includes(driver)) {
+          throw new Error(
+            `pathAuth[${index}]: invalid driver '${driver}'. ` +
+            `Valid drivers: ${validDrivers.join(', ')}`
+          );
+        }
+      }
+    }
+  }
+}
+
+export default {
+  matchPath,
+  findBestMatch,
+  validatePathAuth
+};

package/src/plugins/api/utils/static-filesystem.js

@@ -0,0 +1,262 @@
+/**
+ * Filesystem Static File Driver
+ *
+ * Serves static files from local filesystem with:
+ * - ETag support (304 Not Modified)
+ * - Range requests (partial content)
+ * - Directory index files
+ * - Security (path traversal prevention)
+ * - Cache-Control headers
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { createReadStream } from 'fs';
+import crypto from 'crypto';
+import { getContentType, isCompressible } from './mime-types.js';
+
+/**
+ * Create filesystem static file handler
+ * @param {Object} config - Configuration
+ * @param {string} config.root - Root directory to serve files from
+ * @param {Array<string>} [config.index] - Index files (e.g., ['index.html'])
+ * @param {string|boolean} [config.fallback] - Fallback file for SPA routing (e.g., 'index.html', true uses index[0], false disables)
+ * @param {number} [config.maxAge] - Cache max-age in milliseconds
+ * @param {string} [config.dotfiles] - How to handle dotfiles ('ignore', 'allow', 'deny')
+ * @param {boolean} [config.etag] - Enable ETag generation
+ * @param {boolean} [config.cors] - Enable CORS headers
+ * @returns {Function} Hono middleware
+ */
+export function createFilesystemHandler(config = {}) {
+  const {
+    root,
+    index = ['index.html'],
+    fallback = false,
+    maxAge = 0,
+    dotfiles = 'ignore',
+    etag = true,
+    cors = false
+  } = config;
+
+  if (!root) {
+    throw new Error('Filesystem static handler requires "root" directory');
+  }
+
+  // Resolve root to absolute path
+  const absoluteRoot = path.resolve(root);
+
+  // Determine fallback file
+  let fallbackFile = null;
+  if (fallback === true) {
+    fallbackFile = index[0]; // Use first index file
+  } else if (typeof fallback === 'string') {
+    fallbackFile = fallback;
+  }
+
+  return async (c) => {
+    try {
+      // Get requested path (remove leading slash)
+      let requestPath = c.req.path.replace(/^\//, '');
+
+      // Security: Prevent path traversal
+      const safePath = path.normalize(requestPath).replace(/^(\.\.(\/|\\|$))+/, '');
+      const fullPath = path.join(absoluteRoot, safePath);
+
+      // Ensure path is within root directory
+      if (!fullPath.startsWith(absoluteRoot)) {
+        return c.json({ success: false, error: { message: 'Forbidden' } }, 403);
+      }
+
+      // Check if path exists
+      let stats;
+      let useFallback = false;
+      try {
+        stats = await fs.stat(fullPath);
+      } catch (err) {
+        if (err.code === 'ENOENT' && fallbackFile) {
+          // File not found, try fallback
+          useFallback = true;
+        } else if (err.code === 'ENOENT') {
+          return c.json({ success: false, error: { message: 'Not Found' } }, 404);
+        } else {
+          throw err;
+        }
+      }
+
+      // Use fallback file if needed
+      let filePath = fullPath;
+      if (useFallback) {
+        filePath = path.join(absoluteRoot, fallbackFile);
+        try {
+          stats = await fs.stat(filePath);
+        } catch (err) {
+          // Fallback file doesn't exist
+          return c.json({ success: false, error: { message: 'Not Found' } }, 404);
+        }
+      }
+
+      // Handle directories
+      if (!useFallback && stats.isDirectory()) {
+        // Try index files
+        let indexFound = false;
+        for (const indexFile of index) {
+          const indexPath = path.join(fullPath, indexFile);
+          try {
+            const indexStats = await fs.stat(indexPath);
+            if (indexStats.isFile()) {
+              filePath = indexPath;
+              stats = indexStats;
+              indexFound = true;
+              break;
+            }
+          } catch (err) {
+            // Continue to next index file
+          }
+        }
+
+        if (!indexFound) {
+          // Directory with no index file, try fallback for SPA routing
+          if (fallbackFile) {
+            filePath = path.join(absoluteRoot, fallbackFile);
+            try {
+              stats = await fs.stat(filePath);
+            } catch (err) {
+              return c.json({ success: false, error: { message: 'Forbidden' } }, 403);
+            }
+          } else {
+            return c.json({ success: false, error: { message: 'Forbidden' } }, 403);
+          }
+        }
+      }
+
+      // Handle dotfiles
+      const filename = path.basename(filePath);
+      if (filename.startsWith('.')) {
+        if (dotfiles === 'deny') {
+          return c.json({ success: false, error: { message: 'Forbidden' } }, 403);
+        } else if (dotfiles === 'ignore') {
+          return c.json({ success: false, error: { message: 'Not Found' } }, 404);
+        }
+        // 'allow' - continue
+      }
+
+      // Generate ETag (based on mtime + size)
+      const etagValue = etag
+        ? `"${crypto.createHash('md5').update(`${stats.mtime.getTime()}-${stats.size}`).digest('hex')}"`
+        : null;
+
+      // Check If-None-Match header (ETag)
+      if (etagValue) {
+        const ifNoneMatch = c.req.header('If-None-Match');
+        if (ifNoneMatch === etagValue) {
+          return c.body(null, 304, {
+            'ETag': etagValue,
+            'Cache-Control': maxAge > 0 ? `public, max-age=${Math.floor(maxAge / 1000)}` : 'no-cache'
+          });
+        }
+      }
+
+      // Get content type
+      const contentType = getContentType(filename);
+
+      // Build headers
+      const headers = {
+        'Content-Type': contentType,
+        'Content-Length': stats.size.toString(),
+        'Last-Modified': stats.mtime.toUTCString()
+      };
+
+      if (etagValue) {
+        headers['ETag'] = etagValue;
+      }
+
+      if (maxAge > 0) {
+        headers['Cache-Control'] = `public, max-age=${Math.floor(maxAge / 1000)}`;
+      } else {
+        headers['Cache-Control'] = 'no-cache';
+      }
+
+      if (cors) {
+        headers['Access-Control-Allow-Origin'] = '*';
+        headers['Access-Control-Allow-Methods'] = 'GET, HEAD, OPTIONS';
+      }
+
+      // Handle Range requests (partial content)
+      const rangeHeader = c.req.header('Range');
+      if (rangeHeader) {
+        const parts = rangeHeader.replace(/bytes=/, '').split('-');
+        const start = parseInt(parts[0], 10);
+        const end = parts[1] ? parseInt(parts[1], 10) : stats.size - 1;
+
+        if (start >= stats.size || end >= stats.size) {
+          return c.body(null, 416, {
+            'Content-Range': `bytes */${stats.size}`
+          });
+        }
+
+        const chunkSize = (end - start) + 1;
+        const stream = createReadStream(filePath, { start, end });
+
+        headers['Content-Range'] = `bytes ${start}-${end}/${stats.size}`;
+        headers['Content-Length'] = chunkSize.toString();
+        headers['Accept-Ranges'] = 'bytes';
+
+        return c.body(stream, 206, headers);
+      }
+
+      // Handle HEAD requests
+      if (c.req.method === 'HEAD') {
+        return c.body(null, 200, headers);
+      }
+
+      // Stream file
+      const stream = createReadStream(filePath);
+
+      return c.body(stream, 200, headers);
+
+    } catch (err) {
+      console.error('[Static Filesystem] Error:', err);
+      return c.json({ success: false, error: { message: 'Internal Server Error' } }, 500);
+    }
+  };
+}
+
+/**
+ * Validate filesystem config
+ * @param {Object} config - Filesystem config
+ * @throws {Error} If config is invalid
+ */
+export function validateFilesystemConfig(config) {
+  if (!config.root || typeof config.root !== 'string') {
+    throw new Error('Filesystem static config requires "root" directory (string)');
+  }
+
+  if (config.index !== undefined && !Array.isArray(config.index)) {
+    throw new Error('Filesystem static "index" must be an array');
+  }
+
+  if (config.fallback !== undefined && typeof config.fallback !== 'string' && typeof config.fallback !== 'boolean') {
+    throw new Error('Filesystem static "fallback" must be a string (filename) or boolean');
+  }
+
+  if (config.maxAge !== undefined && typeof config.maxAge !== 'number') {
+    throw new Error('Filesystem static "maxAge" must be a number');
+  }
+
+  if (config.dotfiles !== undefined && !['ignore', 'allow', 'deny'].includes(config.dotfiles)) {
+    throw new Error('Filesystem static "dotfiles" must be "ignore", "allow", or "deny"');
+  }
+
+  if (config.etag !== undefined && typeof config.etag !== 'boolean') {
+    throw new Error('Filesystem static "etag" must be a boolean');
+  }
+
+  if (config.cors !== undefined && typeof config.cors !== 'boolean') {
+    throw new Error('Filesystem static "cors" must be a boolean');
+  }
+}
+
+export default {
+  createFilesystemHandler,
+  validateFilesystemConfig
+};

package/src/plugins/api/utils/static-s3.js

@@ -0,0 +1,231 @@
+/**
+ * S3 Static File Driver
+ *
+ * Serves static files from S3 bucket with:
+ * - Streaming mode (proxy through server)
+ * - Presigned URL mode (redirect to S3)
+ * - ETag support (304 Not Modified)
+ * - Range requests (partial content)
+ * - Cache-Control headers
+ */
+
+import { GetObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { getContentType } from './mime-types.js';
+
+/**
+ * Create S3 static file handler
+ * @param {Object} config - Configuration
+ * @param {Object} config.s3Client - AWS S3 Client instance
+ * @param {string} config.bucket - S3 bucket name
+ * @param {string} [config.prefix] - S3 key prefix (e.g., 'static/')
+ * @param {boolean} [config.streaming] - Stream files through server (true) or redirect to presigned URL (false)
+ * @param {number} [config.signedUrlExpiry] - Presigned URL expiry in seconds (default: 300)
+ * @param {number} [config.maxAge] - Cache max-age in milliseconds
+ * @param {string} [config.cacheControl] - Custom Cache-Control header
+ * @param {string} [config.contentDisposition] - Content-Disposition header
+ * @param {boolean} [config.etag] - Enable ETag support
+ * @param {boolean} [config.cors] - Enable CORS headers
+ * @returns {Function} Hono middleware
+ */
+export function createS3Handler(config = {}) {
+  const {
+    s3Client,
+    bucket,
+    prefix = '',
+    streaming = true,
+    signedUrlExpiry = 300,
+    maxAge = 0,
+    cacheControl,
+    contentDisposition = 'inline',
+    etag = true,
+    cors = false
+  } = config;
+
+  if (!s3Client) {
+    throw new Error('S3 static handler requires "s3Client"');
+  }
+
+  if (!bucket) {
+    throw new Error('S3 static handler requires "bucket" name');
+  }
+
+  return async (c) => {
+    try {
+      // Get requested path (remove leading slash)
+      let requestPath = c.req.path.replace(/^\//, '');
+
+      // Build S3 key
+      const key = prefix ? `${prefix}${requestPath}` : requestPath;
+
+      // Security: Prevent path traversal in key
+      if (key.includes('..') || key.includes('//')) {
+        return c.json({ success: false, error: { message: 'Forbidden' } }, 403);
+      }
+
+      // Get object metadata (HEAD request)
+      let metadata;
+      try {
+        const headCommand = new HeadObjectCommand({ Bucket: bucket, Key: key });
+        metadata = await s3Client.send(headCommand);
+      } catch (err) {
+        if (err.name === 'NotFound' || err.$metadata?.httpStatusCode === 404) {
+          return c.json({ success: false, error: { message: 'Not Found' } }, 404);
+        }
+        throw err;
+      }
+
+      // Check ETag (If-None-Match)
+      if (etag && metadata.ETag) {
+        const ifNoneMatch = c.req.header('If-None-Match');
+        if (ifNoneMatch === metadata.ETag) {
+          const headers = {
+            'ETag': metadata.ETag,
+            'Cache-Control': cacheControl || (maxAge > 0 ? `public, max-age=${Math.floor(maxAge / 1000)}` : 'no-cache')
+          };
+
+          if (cors) {
+            headers['Access-Control-Allow-Origin'] = '*';
+            headers['Access-Control-Allow-Methods'] = 'GET, HEAD, OPTIONS';
+          }
+
+          return c.body(null, 304, headers);
+        }
+      }
+
+      // MODE 1: Presigned URL (redirect)
+      if (!streaming) {
+        const getCommand = new GetObjectCommand({ Bucket: bucket, Key: key });
+        const signedUrl = await getSignedUrl(s3Client, getCommand, { expiresIn: signedUrlExpiry });
+
+        return c.redirect(signedUrl, 302);
+      }
+
+      // MODE 2: Streaming (proxy through server)
+
+      // Determine content type
+      const contentType = metadata.ContentType || getContentType(key);
+
+      // Build headers
+      const headers = {
+        'Content-Type': contentType,
+        'Content-Length': metadata.ContentLength?.toString() || '0',
+        'Last-Modified': metadata.LastModified?.toUTCString() || new Date().toUTCString()
+      };
+
+      if (metadata.ETag && etag) {
+        headers['ETag'] = metadata.ETag;
+      }
+
+      if (cacheControl) {
+        headers['Cache-Control'] = cacheControl;
+      } else if (maxAge > 0) {
+        headers['Cache-Control'] = `public, max-age=${Math.floor(maxAge / 1000)}`;
+      } else {
+        headers['Cache-Control'] = 'no-cache';
+      }
+
+      if (contentDisposition) {
+        const filename = key.split('/').pop();
+        headers['Content-Disposition'] = `${contentDisposition}; filename="${filename}"`;
+      }
+
+      if (cors) {
+        headers['Access-Control-Allow-Origin'] = '*';
+        headers['Access-Control-Allow-Methods'] = 'GET, HEAD, OPTIONS';
+      }
+
+      // Handle Range requests
+      const rangeHeader = c.req.header('Range');
+      let getCommand;
+
+      if (rangeHeader) {
+        // Parse range header
+        const parts = rangeHeader.replace(/bytes=/, '').split('-');
+        const start = parseInt(parts[0], 10);
+        const end = parts[1] ? parseInt(parts[1], 10) : metadata.ContentLength - 1;
+
+        if (start >= metadata.ContentLength || end >= metadata.ContentLength) {
+          return c.body(null, 416, {
+            'Content-Range': `bytes */${metadata.ContentLength}`
+          });
+        }
+
+        const range = `bytes=${start}-${end}`;
+        getCommand = new GetObjectCommand({ Bucket: bucket, Key: key, Range: range });
+
+        const chunkSize = (end - start) + 1;
+        headers['Content-Range'] = `bytes ${start}-${end}/${metadata.ContentLength}`;
+        headers['Content-Length'] = chunkSize.toString();
+        headers['Accept-Ranges'] = 'bytes';
+
+        const response = await s3Client.send(getCommand);
+
+        return c.body(response.Body, 206, headers);
+      }
+
+      // Handle HEAD requests
+      if (c.req.method === 'HEAD') {
+        return c.body(null, 200, headers);
+      }
+
+      // Stream full file
+      getCommand = new GetObjectCommand({ Bucket: bucket, Key: key });
+      const response = await s3Client.send(getCommand);
+
+      return c.body(response.Body, 200, headers);
+
+    } catch (err) {
+      console.error('[Static S3] Error:', err);
+      return c.json({ success: false, error: { message: 'Internal Server Error' } }, 500);
+    }
+  };
+}
+
+/**
+ * Validate S3 config
+ * @param {Object} config - S3 config
+ * @throws {Error} If config is invalid
+ */
+export function validateS3Config(config) {
+  if (!config.bucket || typeof config.bucket !== 'string') {
+    throw new Error('S3 static config requires "bucket" name (string)');
+  }
+
+  if (config.prefix !== undefined && typeof config.prefix !== 'string') {
+    throw new Error('S3 static "prefix" must be a string');
+  }
+
+  if (config.streaming !== undefined && typeof config.streaming !== 'boolean') {
+    throw new Error('S3 static "streaming" must be a boolean');
+  }
+
+  if (config.signedUrlExpiry !== undefined && typeof config.signedUrlExpiry !== 'number') {
+    throw new Error('S3 static "signedUrlExpiry" must be a number');
+  }
+
+  if (config.maxAge !== undefined && typeof config.maxAge !== 'number') {
+    throw new Error('S3 static "maxAge" must be a number');
+  }
+
+  if (config.cacheControl !== undefined && typeof config.cacheControl !== 'string') {
+    throw new Error('S3 static "cacheControl" must be a string');
+  }
+
+  if (config.contentDisposition !== undefined && typeof config.contentDisposition !== 'string') {
+    throw new Error('S3 static "contentDisposition" must be a string');
+  }
+
+  if (config.etag !== undefined && typeof config.etag !== 'boolean') {
+    throw new Error('S3 static "etag" must be a boolean');
+  }
+
+  if (config.cors !== undefined && typeof config.cors !== 'boolean') {
+    throw new Error('S3 static "cors" must be a boolean');
+  }
+}
+
+export default {
+  createS3Handler,
+  validateS3Config
+};