s3db.js 13.5.1 → 13.6.1

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