@reldens/server-utils 0.43.0 → 0.44.0

package/.claude/api-reference.md

@@ -0,0 +1,333 @@
+# API Reference
+
+Complete API documentation for @reldens/server-utils classes.
+
+## 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.
+
+**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
+- `createReadStream(filePath, options)` - Create readable stream for file
+- `getFileModificationTime(filePath)` - Get file last modification time
+
+**Important:**
+- 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.
+
+**Features:**
+- Virtual host management with SNI support
+- HTTP/2 CDN server integration
+- Reverse proxy with WebSocket support
+- Development mode detection and configuration
+- Request logging middleware
+- Lifecycle event dispatching
+
+**Configuration Properties:**
+- `onError` - Custom error handler callback for server errors
+- `onRequestSuccess` - Callback for successful requests
+- `onRequestError` - Callback for failed requests
+- `onEvent` - Callback for lifecycle events
+
+**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
+
+**Security Configurers:**
+- `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
+
+### 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.
+
+**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
+- Comprehensive error handling (server, TLS, session, stream errors)
+
+**Configuration Properties:**
+- `onError` - Custom error handler callback for server errors
+- `onRequestSuccess` - Callback for successful requests
+- `onRequestError` - Callback for failed requests
+- `onEvent` - Callback for lifecycle events
+
+**Methods:**
+- `create()` - Create HTTP/2 secure server
+- `listen()` - Start listening on configured port
+- `close()` - Gracefully close server
+- `handleStream(stream, headers)` - Handle HTTP/2 stream
+- `handleHttp1Request(req, res)` - Handle HTTP/1.1 fallback requests
+- `resolveFilePath(requestPath)` - Resolve file path from request
+- `setupEventHandlers()` - Configure server error event handlers
+
+## Utility Classes
+
+### RequestLogger
+`lib/request-logger.js`
+
+Express middleware for request logging.
+
+**Methods:**
+- `createMiddleware(onRequestSuccess, onRequestError)` - Create logging middleware
+
+Tracks request timing and invokes callbacks based on status code:
+- Status < 400: calls onRequestSuccess
+- Status >= 400: calls onRequestError
+
+### EventDispatcher
+`lib/event-dispatcher.js`
+
+Static utility for dispatching lifecycle events.
+
+**Methods:**
+- `dispatch(onEventCallback, eventType, instanceName, instance, data)` - Dispatch event
+
+Validates callback exists before invoking with structured event data.
+
+### ServerErrorHandler
+`lib/server-error-handler.js`
+
+Centralized error handling for all server components.
+
+**Methods:**
+- `handleError(onErrorCallback, instanceName, instance, key, error, context)` - Handle and delegate errors
+
+Used by Http2CdnServer, AppServerFactory, and ReverseProxyConfigurer. Provides structured error context with instance details and metadata.
+
+### ServerDefaultConfigurations
+`lib/server-default-configurations.js`
+
+Static class providing default configurations.
+
+**Properties:**
+- `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.
+
+**Methods:**
+- `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.
+
+**Headers:**
+- HTTP/2 headers configuration
+- Express security headers
+- Cache control headers
+- Proxy forwarding headers
+
+**Methods:**
+- `buildCacheControlHeader(maxAge)` - Build cache control header string
+
+## Security Configurers
+
+Located in `lib/app-server-factory/`
+
+### DevelopmentModeDetector
+`development-mode-detector.js`
+
+Auto-detects development environment.
+
+**Methods:**
+- `detect(config)` - Detect if in development mode
+- `matchesPattern(domain)` - Check if domain matches development pattern
+
+Checks NODE_ENV, domain patterns, and configured domains. Built-in patterns: localhost, 127.0.0.1, .local, .test, .dev, .staging, etc.
+
+### ProtocolEnforcer
+`protocol-enforcer.js`
+
+Enforces HTTP/HTTPS protocol consistency.
+
+**Methods:**
+- `setup(app, config)` - Setup protocol enforcement middleware
+
+Development mode awareness with automatic redirects when protocol doesn't match configuration.
+
+### SecurityConfigurer
+`security-configurer.js`
+
+Helmet integration with CSP management.
+
+**Methods:**
+- `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
+
+Features XSS protection with request body sanitization. Development-friendly CSP configuration with directive merging or override support.
+
+### CorsConfigurer
+`cors-configurer.js`
+
+Dynamic CORS origin validation.
+
+**Methods:**
+- `setup(app, config)` - Setup CORS middleware
+- `extractDevelopmentOrigins(domainMapping)` - Extract development origins
+- `normalizeHost(originOrHost)` - Normalize host string
+
+Development domain support with automatic port variations. Credential support configuration.
+
+### RateLimitConfigurer
+`rate-limit-configurer.js`
+
+Global and endpoint-specific rate limiting.
+
+**Methods:**
+- `setup(app, config)` - Setup global rate limiting
+- `createHomeLimiter()` - Create homepage-specific limiter
+
+Development mode multiplier for lenient limits. IP-based key generation option.
+
+### ReverseProxyConfigurer
+`reverse-proxy-configurer.js`
+
+Domain-based reverse proxy routing.
+
+**Methods:**
+- `setup(app, config)` - Setup reverse proxy
+- `createProxyMiddleware(rule)` - Create proxy middleware for rule
+- `handleProxyError(err, req, res)` - Handle proxy errors with status codes
+- `validateProxyRule(rule)` - Validate proxy rule configuration
+- `extractHostname(req)` - Extract hostname from request
+
+**Features:**
+- WebSocket support
+- SSL termination
+- Header preservation (X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host)
+- Virtual host integration
+- Comprehensive error handling:
+  - 502 Bad Gateway for ECONNREFUSED errors
+  - 504 Gateway Timeout for ETIMEDOUT/ESOCKETTIMEDOUT errors
+  - 500 Internal Server Error for other proxy errors
+- Custom error callback support via ServerErrorHandler

package/.claude/package-architecture.md

@@ -0,0 +1,177 @@
+# Package Architecture
+
+## Design Philosophy
+
+**@reldens/server-utils** is an independent utility package that provides server infrastructure without coupling to other Reldens packages (like @reldens/utils).
+
+## Core Principles
+
+### 1. Independence
+- No dependencies on @reldens/utils or other Reldens packages
+- Self-contained utility classes
+- Can be used standalone or integrated into Reldens
+
+### 2. Callback-Based Extensibility
+The package provides **hooks via callbacks** instead of direct implementations.
+
+**Pattern:**
+- Package provides callback properties
+- Package calls these callbacks at specific points
+- Application provides callback implementations
+- Application wires callbacks to their own logging/monitoring systems
+
+### 3. Separation of Concerns
+- **reldens-server-utils**: Provides server infrastructure and callback hooks
+- **Application**: Provides implementations (logging, monitoring, error handling)
+- **@reldens/utils**: Provides shared utilities (Logger, Shortcuts, etc.)
+
+The package does NOT import Logger. Applications import Logger and wire it to package callbacks.
+
+## Available Callbacks
+
+### onError
+Custom error handler for server errors.
+
+**Called by:** ServerErrorHandler static class
+
+**Data structure:**
+- `instanceName` - Which server component had the error
+- `instance` - The component instance
+- `key` - Error type identifier
+- `error` - The error object
+- `context` - Additional contextual data
+
+**Error points:**
+- Virtual host resolution errors
+- SNI certificate loading errors
+- Server creation errors
+- Stream errors
+- TLS client errors
+- Session errors
+- HTTP/1 fallback errors
+- Reverse proxy errors
+
+**Example:**
+```javascript
+let config = {
+    onError: (errorData) => {
+        Logger.error('Server error:', errorData.key, errorData.error.message);
+    }
+};
+```
+
+### onRequestSuccess
+Called for successful HTTP requests (status code < 400).
+
+**Called by:** RequestLogger middleware
+
+**Data structure:**
+- `method` - HTTP method (GET, POST, etc.)
+- `path` - Request path
+- `statusCode` - HTTP status code
+- `responseTime` - Response time in milliseconds
+- `ip` - Client IP address
+- `userAgent` - Client user agent
+- `timestamp` - ISO timestamp
+
+**Example:**
+```javascript
+let config = {
+    onRequestSuccess: (requestData) => {
+        Logger.info('Request:', requestData.method, requestData.path, requestData.statusCode, requestData.responseTime+'ms');
+    }
+};
+```
+
+### onRequestError
+Called for failed HTTP requests (status code >= 400).
+
+**Called by:** RequestLogger middleware
+
+**Data structure:**
+- `method` - HTTP method
+- `path` - Request path
+- `statusCode` - HTTP status code
+- `responseTime` - Response time in milliseconds
+- `ip` - Client IP address
+- `userAgent` - Client user agent
+- `timestamp` - ISO timestamp
+
+**Example:**
+```javascript
+let config = {
+    onRequestError: (errorData) => {
+        Logger.error('Request error:', errorData.method, errorData.path, errorData.statusCode);
+    }
+};
+```
+
+### onEvent
+Generic lifecycle event callback for server initialization and configuration events.
+
+**Called by:** EventDispatcher static class
+
+**Data structure:**
+- `eventType` - Event type identifier
+- `instanceName` - Which component dispatched the event
+- `instance` - The component instance
+- `data` - Event-specific data
+- `timestamp` - ISO timestamp
+
+**Event types:**
+- `app-server-created` - Express app server created
+- `http2-cdn-created` - HTTP/2 CDN server created
+- `app-server-listening` - Server started listening
+- `http-server-created` - HTTP server created
+- `https-server-created` - HTTPS server created
+- `sni-server-created` - SNI server created
+- `domain-added` - Virtual host domain added
+- `protocol-enforcement-enabled` - Protocol enforcement configured
+- `helmet-configured` - Helmet security configured
+- `xss-protection-enabled` - XSS protection configured
+- `cors-configured` - CORS configured
+- `rate-limiting-configured` - Rate limiting configured
+- `reverse-proxy-configured` - Reverse proxy configured
+- `development-mode-detected` - Development mode detected
+- `cdn-server-created` - CDN server instance created
+- `cdn-handlers-setup` - CDN event handlers configured
+- `cdn-server-listening` - CDN server started listening
+
+**Example:**
+```javascript
+let config = {
+    onEvent: (eventData) => {
+        Logger.debug('Event:', eventData.eventType, eventData.instanceName);
+    }
+};
+```
+
+## Integration Pattern
+
+**Application Setup:**
+```javascript
+const { AppServerFactory } = require('@reldens/server-utils');
+const { Logger } = require('@reldens/utils');
+
+let factory = new AppServerFactory();
+
+let config = {
+    port: 8080,
+    onError: (errorData) => {
+        Logger.error('Server error:', errorData.key, errorData.error.message);
+    },
+    onRequestSuccess: (requestData) => {
+        Logger.info('Request:', requestData.method, requestData.path, requestData.statusCode);
+    },
+    onRequestError: (errorData) => {
+        Logger.error('Request error:', errorData.method, errorData.path, errorData.statusCode);
+    },
+    onEvent: (eventData) => {
+        Logger.debug('Event:', eventData.eventType);
+    }
+};
+
+let serverResult = factory.createAppServer(config);
+```
+
+This pattern keeps the utility package independent while allowing full integration with application-specific logging and monitoring systems.