@reldens/server-utils 0.39.0 → 0.41.0

package/CLAUDE.md

@@ -0,0 +1,235 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Package Overview
+
+**@reldens/server-utils** is a core utility package for server-side operations in Reldens. It provides:
+- File system operations (FileHandler)
+- HTTP/HTTPS server creation (AppServerFactory)
+- File encryption (Encryptor)
+- File upload handling (UploaderFactory)
+- HTTP/2 CDN server (Http2CdnServer)
+- Server configuration utilities
+
+## Key Commands
+
+```bash
+# Run tests (if configured)
+npm test
+```
+
+## Architecture
+
+### Core Classes
+
+**FileHandler** (`lib/file-handler.js`):
+- Singleton wrapper for Node.js fs and path modules
+- Used instead of direct require('fs') or require('path') throughout Reldens
+- Key file operations:
+  - `exists(filePath)` - Check if file/directory exists
+  - `readFile(filePath)` - Read file contents
+  - `writeFile(filePath, content)` - Write file
+  - `createFolder(folderPath)` - Create directory recursively
+  - `remove(fullPath)` - Remove file/folder recursively
+  - `copyFile(from, to)` - Copy file
+  - `copyFolderSync(from, to)` - Copy folder recursively
+  - `moveFile(from, to)` - Move/rename file
+- Path operations:
+  - `joinPaths(...paths)` - Join path segments
+  - `getFileName(filePath)` - Get file name (basename)
+  - `getFolderName(filePath)` - Get directory name (dirname)
+  - `getRelativePath(from, to)` - Calculate relative path
+  - `normalizePath(filePath)` - Normalize path
+  - `isAbsolutePath(filePath)` - Check if path is absolute
+- File inspection:
+  - `isFile(filePath)` - Check if path is a file
+  - `isFolder(dirPath)` - Check if path is a folder
+  - `getFileSize(filePath)` - Get file size in bytes
+  - `getFileStats(filePath)` - Get file stats
+  - `getFilesInFolder(dirPath, extensions)` - List files with optional filtering
+  - `fetchSubFoldersList(folder, options)` - Get subfolder list
+- JSON operations:
+  - `fetchFileJson(filePath)` - Read and parse JSON file
+  - `isValidJson(filePath)` - Validate JSON file
+- Security features:
+  - `generateSecureFilename(originalName)` - Generate secure random filename
+  - `validateFileType(filePath, type, allowedTypes, maxSize)` - Validate file
+  - `detectFileType(filePath)` - Detect MIME type from magic numbers
+  - `quarantineFile(filePath, reason)` - Move suspicious file to quarantine
+  - `isValidPath(filePath)` - Validate path for security
+  - `sanitizePath(filePath)` - Sanitize path string
+- Advanced operations:
+  - `walkDirectory(dirPath, callback)` - Recursively process directory tree
+  - `getDirectorySize(dirPath)` - Calculate total directory size
+  - `emptyDirectory(dirPath)` - Remove all contents from directory
+  - `compareFiles(file1, file2)` - Compare file contents
+  - `appendToFile(filePath, content)` - Append to file
+  - `prependToFile(filePath, content)` - Prepend to file
+  - `replaceInFile(filePath, searchValue, replaceValue)` - Replace in file
+- All methods include built-in error handling, no need for try/catch
+- DO NOT use FileHandler.exists to validate other FileHandler methods
+- DO NOT enclose FileHandler methods in try/catch blocks
+
+**AppServerFactory** (`lib/app-server-factory.js`):
+- Creates Express app servers with modular security components
+- Supports HTTP, HTTPS, HTTP/2
+- Key features:
+  - Virtual host management with SNI support
+  - HTTP/2 CDN server integration
+  - Reverse proxy with WebSocket support
+  - Development mode detection and configuration
+- Security configurers (modular):
+  - `DevelopmentModeDetector` - Auto-detect development environment
+  - `ProtocolEnforcer` - HTTP/HTTPS protocol enforcement
+  - `SecurityConfigurer` - Helmet integration and XSS protection
+  - `CorsConfigurer` - CORS with dynamic origin validation
+  - `RateLimitConfigurer` - Global and endpoint-specific rate limiting
+  - `ReverseProxyConfigurer` - Domain-based reverse proxy
+- Methods:
+  - `createAppServer(config)` - Create and configure server
+  - `addDomain(domainConfig)` - Add virtual host domain
+  - `addDevelopmentDomain(domain)` - Add development domain
+  - `enableServeHome(app, callback)` - Enable homepage serving
+  - `serveStatics(app, staticPath)` - Serve static files
+  - `enableCSP(cspOptions)` - Enable Content Security Policy
+  - `listen(port)` - Start server listening
+  - `close()` - Gracefully close server
+
+**Encryptor** (`lib/encryptor.js`):
+- Singleton for cryptographic operations
+- Password hashing:
+  - `encryptPassword(password)` - Hash password with PBKDF2 (100k iterations, SHA-512)
+  - `validatePassword(password, storedPassword)` - Validate password against hash
+- Data encryption:
+  - `encryptData(data, key)` - Encrypt data with AES-256-GCM
+  - `decryptData(encryptedData, key)` - Decrypt AES-256-GCM data
+  - `generateSecretKey()` - Generate 256-bit secret key
+- Token generation:
+  - `generateSecureToken(length)` - Generate cryptographically secure token
+  - `generateTOTP(secret, timeStep)` - Generate time-based OTP
+- Hashing and verification:
+  - `hashData(data, algorithm)` - Hash with SHA-256, SHA-512, or MD5
+  - `generateHMAC(data, secret, algorithm)` - Generate HMAC signature
+  - `verifyHMAC(data, secret, signature, algorithm)` - Verify HMAC signature
+  - `constantTimeCompare(a, b)` - Constant-time string comparison
+
+**UploaderFactory** (`lib/uploader-factory.js`):
+- File upload handling with Multer
+- Multi-level security validation:
+  - Filename security validation
+  - MIME type validation
+  - File extension validation
+  - File size validation
+  - Content validation using magic numbers
+  - Dangerous extension filtering
+- Features:
+  - Multiple file upload support with field mapping
+  - Secure filename generation option
+  - Automatic cleanup on validation failure
+  - Custom error response handling
+  - Per-field destination mapping
+- Methods:
+  - `createUploader(fields, buckets, allowedFileTypes)` - Create upload middleware
+  - `validateFilenameSecurity(filename)` - Validate filename
+  - `validateFile(file, allowedType, callback)` - Validate during upload
+  - `validateFileContents(file, allowedType)` - Validate after upload
+  - `convertToRegex(key)` - Convert MIME type patterns to regex
+
+**Http2CdnServer** (`lib/http2-cdn-server.js`):
+- HTTP/2 secure server for CDN-like static file serving
+- Features:
+  - Optimized for CSS, JavaScript, images, and fonts
+  - Dynamic CORS origin validation with regex pattern support
+  - Configurable cache headers per file extension
+  - Comprehensive MIME type detection
+  - HTTP/1.1 fallback support
+  - Security headers (X-Content-Type-Options, X-Frame-Options, Vary)
+  - Query string stripping for cache optimization
+- Methods:
+  - `create()` - Create HTTP/2 secure server
+  - `listen()` - Start listening on configured port
+  - `close()` - Gracefully close server
+  - `handleStream(stream, headers)` - Handle HTTP/2 stream
+  - `resolveFilePath(requestPath)` - Resolve file path from request
+
+### Utility Classes
+
+**ServerDefaultConfigurations** (`lib/server-default-configurations.js`):
+- Static class providing default configurations
+- `mimeTypes` - Comprehensive MIME type mappings for common file extensions
+- `cacheConfig` - Default cache max-age settings (1 year for CSS/JS/fonts, 30 days for images)
+
+**ServerFactoryUtils** (`lib/server-factory-utils.js`):
+- Static utility methods for server operations
+- `getCacheConfigForPath(path, cacheConfig)` - Get cache config for file path
+- `validateOrigin(origin, corsOrigins, corsAllowAll)` - Validate CORS origin (supports strings and RegExp)
+- `stripQueryString(url)` - Remove query string from URL
+
+**ServerHeaders** (`lib/server-headers.js`):
+- Centralized header management
+- HTTP/2 headers configuration
+- Express security headers
+- Cache control headers
+- Proxy forwarding headers
+- `buildCacheControlHeader(maxAge)` - Build cache control header string
+
+### Security Configurers (in `lib/app-server-factory/`)
+
+**DevelopmentModeDetector** (`development-mode-detector.js`):
+- Auto-detects development environment
+- Checks NODE_ENV, domain patterns, and configured domains
+- Built-in patterns: localhost, 127.0.0.1, .local, .test, .dev, .staging, etc.
+- `detect(config)` - Detect if in development mode
+- `matchesPattern(domain)` - Check if domain matches development pattern
+
+**ProtocolEnforcer** (`protocol-enforcer.js`):
+- Enforces HTTP/HTTPS protocol consistency
+- Development mode awareness
+- Automatic redirects when protocol doesn't match configuration
+- `setup(app, config)` - Setup protocol enforcement middleware
+
+**SecurityConfigurer** (`security-configurer.js`):
+- Helmet integration with CSP management
+- XSS protection with request body sanitization
+- Development-friendly CSP configuration
+- Supports CSP directive merging or override
+- `setupHelmet(app, config)` - Setup Helmet middleware
+- `setupXssProtection(app, config)` - Setup XSS protection
+- `enableCSP(app, cspOptions)` - Enable Content Security Policy
+- `addExternalDomainsToCsp(directives, externalDomains)` - Add external domains to CSP
+
+**CorsConfigurer** (`cors-configurer.js`):
+- Dynamic CORS origin validation
+- Development domain support with automatic port variations
+- Credential support configuration
+- `setup(app, config)` - Setup CORS middleware
+- `extractDevelopmentOrigins(domainMapping)` - Extract development origins
+- `normalizeHost(originOrHost)` - Normalize host string
+
+**RateLimitConfigurer** (`rate-limit-configurer.js`):
+- Global and endpoint-specific rate limiting
+- Development mode multiplier for lenient limits
+- IP-based key generation option
+- `setup(app, config)` - Setup global rate limiting
+- `createHomeLimiter()` - Create homepage-specific limiter
+
+**ReverseProxyConfigurer** (`reverse-proxy-configurer.js`):
+- Domain-based reverse proxy routing
+- WebSocket support
+- SSL termination
+- Header preservation (X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host)
+- Virtual host integration
+- Graceful error handling (502 Bad Gateway, 504 Gateway Timeout)
+- `setup(app, config)` - Setup reverse proxy
+- `createProxyMiddleware(rule)` - Create proxy middleware for rule
+- `handleProxyError(err, req, res)` - Handle proxy errors
+
+## Important Notes
+
+- **ALWAYS use FileHandler** instead of Node.js fs/path modules
+- FileHandler methods have built-in error handling - no try/catch needed
+- DO NOT enclose FileHandler methods in try/catch blocks
+- DO NOT use FileHandler.exists to validate other FileHandler methods (e.g., before createFolder)
+- AppServerFactory handles all Express server configuration
+- All server utilities support both HTTP and HTTPS

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@reldens/server-utils",
     "scope": "@reldens",
-    "version": "0.39.0",
+    "version": "0.41.0",
     "description": "Reldens - Server Utils",
     "author": "Damian A. Pastorini",
     "license": "MIT",
@@ -36,11 +36,11 @@
         "url": "https://github.com/damian-pastorini/reldens-server-utils/issues"
     },
     "dependencies": {
-        "body-parser": "2.2.0",
+        "body-parser": "2.2.1",
         "compression": "1.8.1",
         "cors": "2.8.5",
         "express": "4.21.2",
-        "express-rate-limit": "8.1.0",
+        "express-rate-limit": "8.2.1",
         "express-session": "1.18.2",
         "helmet": "8.1.0",
         "http-proxy-middleware": "3.0.5",