yinzerflow 0.1.18 → 0.2.0

package/docs/advanced-configuration-options.md

@@ -0,0 +1,175 @@
+# Advanced Configuration Options
+
+YinzerFlow provides advanced configuration options for fine-tuning security, performance, and functionality. These options allow you to customize the framework's behavior for specific use cases while maintaining robust security defaults.
+
+## Body Parser Configuration
+
+Body parsing handles all incoming request data with built-in security protections against DoS attacks, prototype pollution, and memory exhaustion vulnerabilities. See [Body Parsing Documentation](./body-parsing.md) for detailed setup, configuration options, and security considerations.
+
+```typescript
+const app = new YinzerFlow({
+  port: 3000,
+  bodyParser: {
+    json: {
+      maxSize: 262144, // 256KB
+      maxDepth: 10,
+      allowPrototypeProperties: false, // Security protection
+      maxKeys: 1000
+    },
+    fileUploads: {
+      maxFileSize: 10485760, // 10MB per file
+      maxFiles: 10,
+      allowedExtensions: ['.jpg', '.png', '.pdf']
+    },
+    urlEncoded: {
+      maxSize: 1048576, // 1MB
+      maxFields: 1000
+    }
+  }
+});
+```
+
+## CORS Configuration
+
+Cross-Origin Resource Sharing (CORS) configuration for browser security. See [CORS Documentation](./cors.md) for detailed setup and security considerations.
+
+```typescript
+const app = new YinzerFlow({
+  port: 3000,
+  cors: {
+    enabled: true,
+    origin: ['https://yourdomain.com'],
+    methods: ['GET', 'POST', 'PUT', 'DELETE'],
+    allowedHeaders: ['Content-Type', 'Authorization'],
+    credentials: true
+  }
+});
+```
+
+## IP Security Configuration
+
+IP address validation and spoofing protection for accurate client identification. See [IP Security Documentation](./ip-security.md) for detailed setup, security considerations, and advanced use cases.
+
+```typescript
+const app = new YinzerFlow({
+  port: 3000,
+  ipSecurity: {
+    trustedProxies: ['127.0.0.1', '::1', '192.168.1.10'],
+    allowPrivateIps: true,
+    headerPreference: ['x-forwarded-for', 'x-real-ip', 'cf-connecting-ip'],
+    maxChainLength: 10,
+    detectSpoofing: true
+  }
+});
+```
+
+## Server Configuration
+
+### Connection Options
+
+Fine-tune server connection behavior and timeouts:
+
+```typescript
+const app = new YinzerFlow({
+  port: 3000,
+  host: '0.0.0.0', // Bind address
+  // IP extraction is now handled by ipSecurity configuration
+  connectionOptions: {
+    socketTimeout: 30000, // 30 seconds
+    gracefulShutdownTimeout: 30000,
+    keepAliveTimeout: 65000,
+    headersTimeout: 66000
+  }
+});
+```
+
+| Option | Type | Default | Description |
+|-----|---|---|---|
+| `socketTimeout` | `number` | `30000` | Socket timeout in milliseconds |
+| `gracefulShutdownTimeout` | `number` | `30000` | Graceful shutdown timeout |
+| `keepAliveTimeout` | `number` | `65000` | Keep-alive timeout |
+| `headersTimeout` | `number` | `66000` | Headers timeout (should be > keep-alive) |
+
+### Logging Configuration
+
+Control framework logging output:
+
+```typescript
+const app = new YinzerFlow({
+  port: 3000,
+  logLevel: 'info' // 'off', 'error', 'warn', 'info', 'verbose'
+});
+```
+
+
+
+## Common Configuration Patterns
+
+### High-Security API
+```typescript
+const secureApi = new YinzerFlow({
+  port: 443,
+  bodyParser: {
+    json: { maxSize: 32768, maxDepth: 3, maxKeys: 50 }, // Very strict
+    fileUploads: { maxFileSize: 0, maxFiles: 0 }, // No uploads
+    urlEncoded: { maxSize: 8192, maxFields: 20 } // Minimal forms
+  },
+  cors: { enabled: false } // No CORS for security
+});
+```
+
+### File Processing Service
+```typescript
+const fileService = new YinzerFlow({
+  port: 3000,
+  bodyParser: {
+    json: { maxSize: 8192 }, // Minimal JSON for metadata
+    fileUploads: {
+      maxFileSize: 2147483648, // 2GB files
+      maxTotalSize: 10737418240, // 10GB total
+      maxFiles: 50,
+      allowedExtensions: ['.zip', '.tar', '.gz', '.7z', '.rar']
+    }
+  }
+});
+```
+
+### Development/Testing Environment
+```typescript
+const devApp = new YinzerFlow({
+  port: 3000,
+  logLevel: 'verbose', // Verbose logging
+  bodyParser: {
+    json: { maxSize: 10485760 }, // 10MB for testing
+    fileUploads: { 
+      maxFileSize: 104857600, // 100MB files
+      allowedExtensions: [] // Allow all for development
+    }
+  },
+  cors: { 
+    enabled: true,
+    origin: '*' // Open CORS for dev (⚠️ Never use in production)
+  }
+});
+```
+
+## Configuration Best Practices
+
+### Security First
+- **Never enable `allowPrototypeProperties`** unless absolutely necessary
+- **Use allowlists over blocklists** for file extensions when possible
+- **Set conservative limits initially** and increase as needed
+- **Enable CORS carefully** with specific origins in production
+
+### Performance Optimization
+- **Match limits to your use case** - don't use defaults blindly
+- **Consider memory usage** when setting maxSize limits
+- **Balance security vs. functionality** based on your threat model
+
+### Monitoring and Maintenance
+- **Watch for security warnings** in your logs
+- **Monitor actual usage patterns** to optimize limits
+- **Review configuration regularly** as your application evolves
+- **Test edge cases** with your specific limits
+
+These advanced configuration options provide fine-grained control over YinzerFlow's behavior while maintaining security best practices and preventing common vulnerabilities.

package/docs/body-parsing.md

@@ -0,0 +1,294 @@
+# Body Parsing
+
+YinzerFlow provides comprehensive body parsing with built-in security protections against DoS attacks, prototype pollution, and memory exhaustion vulnerabilities. The body parser automatically handles JSON, file uploads, and URL-encoded form data with configurable security limits.
+
+## Configuration
+
+Body parsing is automatically enabled with secure defaults that protect against common attack vectors:
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({
+  port: 3000,
+  bodyParser: {
+    json: {
+      maxSize: 262144, // 256KB (reasonable for JSON APIs)
+      maxDepth: 10,
+      allowPrototypeProperties: false, // Blocks prototype pollution
+      maxKeys: 1000,
+      maxStringLength: 1048576, // 1MB per string
+      maxArrayLength: 10000
+    },
+    fileUploads: {
+      maxFileSize: 10485760, // 10MB per file
+      maxTotalSize: 52428800, // 50MB total
+      maxFiles: 10,
+      allowedExtensions: [], // Empty = allow all
+      blockedExtensions: ['.exe', '.bat', '.cmd', '.scr', '.pif', '.com'],
+      maxFilenameLength: 255
+    },
+    urlEncoded: {
+      maxSize: 1048576, // 1MB
+      maxFields: 1000,
+      maxFieldNameLength: 100,
+      maxFieldLength: 1048576 // 1MB per field
+    }
+  }
+});
+```
+
+### Configuration Options
+
+#### JSON Parser Configuration
+
+Controls how JSON request bodies are parsed and validated:
+
+| Option | Type | Default | Description |
+|-----|---|---|---|
+| `maxSize` | `number` | `262144` (256KB) | Maximum JSON body size in bytes |
+| `maxDepth` | `number` | `10` | Maximum nesting depth to prevent stack overflow |
+| `allowPrototypeProperties` | `boolean` | `false` | Allow dangerous prototype properties (⚠️ Security Risk) |
+| `maxKeys` | `number` | `1000` | Maximum object keys to prevent memory exhaustion |
+| `maxStringLength` | `number` | `1048576` (1MB) | Maximum string length per property |
+| `maxArrayLength` | `number` | `10000` | Maximum array elements per property |
+
+#### File Upload Configuration
+
+Controls file upload processing and security:
+
+| Option | Type | Default | Description |
+|-----|---|---|---|
+| `maxFileSize` | `number` | `10485760` (10MB) | Maximum size per individual file |
+| `maxTotalSize` | `number` | `52428800` (50MB) | Maximum total upload size per request |
+| `maxFiles` | `number` | `10` | Maximum number of files per request |
+| `allowedExtensions` | `string[]` | `[]` | Allowed file extensions (empty = allow all) |
+| `blockedExtensions` | `string[]` | `['.exe', '.bat', ...]` | Blocked file extensions for security |
+| `maxFilenameLength` | `number` | `255` | Maximum filename length |
+
+#### URL-Encoded Form Configuration
+
+Controls form data parsing and validation:
+
+| Option | Type | Default | Description |
+|-----|---|---|---|
+| `maxSize` | `number` | `1048576` (1MB) | Maximum form data size |
+| `maxFields` | `number` | `1000` | Maximum form fields to prevent DoS |
+| `maxFieldNameLength` | `number` | `100` | Maximum field name length |
+| `maxFieldLength` | `number` | `1048576` (1MB) | Maximum field value length |
+
+## Examples
+
+#### Strict API Configuration
+```typescript
+const strictApiApp = new YinzerFlow({
+  port: 3000,
+  bodyParser: {
+    json: {
+      maxSize: 131072, // 128KB - smaller for strict APIs
+      maxDepth: 5, // Shallow nesting only
+      allowPrototypeProperties: false, // Always keep false!
+      maxKeys: 100, // Fewer keys allowed
+      maxStringLength: 10240, // 10KB strings max
+      maxArrayLength: 100 // Small arrays only
+    },
+    fileUploads: {
+      maxFileSize: 1048576, // 1MB files only
+      maxFiles: 3, // Very few files
+      allowedExtensions: ['.jpg', '.png', '.pdf'], // Specific types only
+      maxFilenameLength: 50 // Short filenames
+    }
+  }
+});
+```
+
+#### Media Upload Configuration
+```typescript
+const mediaApp = new YinzerFlow({
+  port: 3000,
+  bodyParser: {
+    json: {
+      maxSize: 512000, // 500KB for metadata
+      maxDepth: 3, // Simple metadata only
+      allowPrototypeProperties: false
+    },
+    fileUploads: {
+      maxFileSize: 104857600, // 100MB per file for media
+      maxTotalSize: 524288000, // 500MB total
+      maxFiles: 20,
+      allowedExtensions: ['.jpg', '.jpeg', '.png', '.gif', '.mp4', '.webm', '.pdf'],
+      blockedExtensions: [], // Using allowlist instead
+      maxFilenameLength: 200
+    }
+  }
+});
+```
+
+#### High-Security Configuration
+```typescript
+const secureApp = new YinzerFlow({
+  port: 443,
+  bodyParser: {
+    json: { 
+      maxSize: 32768, // 32KB only
+      maxDepth: 3, 
+      maxKeys: 50 
+    },
+    fileUploads: { 
+      maxFileSize: 0, // No file uploads
+      maxFiles: 0 
+    },
+    urlEncoded: { 
+      maxSize: 8192, // 8KB forms only
+      maxFields: 20 
+    }
+  }
+});
+```
+
+## Common Use Cases
+
+- **API Data Processing**: Parse JSON payloads with automatic security validation and DoS protection
+- **File Upload Handling**: Secure file upload processing with size, type, and count restrictions
+- **Form Data Processing**: Handle HTML form submissions with field validation and memory protection
+- **Content Type Detection**: Automatic parsing based on Content-Type headers with fallback handling
+- **Security Compliance**: Built-in protection against common web vulnerabilities and attack vectors
+- **Memory Protection**: Prevent DoS attacks through configurable size and complexity limits
+
+## API Reference
+
+### Request Body Properties
+
+When body parsing is successful, the parsed data is available on `request.body`:
+
+#### JSON Requests
+```typescript
+// Content-Type: application/json
+request.body: unknown // Parsed JSON object or array
+```
+
+#### File Upload Requests
+```typescript
+// Content-Type: multipart/form-data
+request.body: {
+  fields: Record<string, string | string[]>; // Form fields
+  files: Array<{
+    fieldname: string;
+    filename: string;
+    mimetype: string;
+    size: number;
+    buffer: Buffer;
+  }>;
+}
+```
+
+#### URL-Encoded Form Requests
+```typescript
+// Content-Type: application/x-www-form-urlencoded
+request.body: Record<string, string | string[]> // Parsed form data
+```
+
+### Configuration Methods
+
+Body parser configuration is set during YinzerFlow initialization:
+
+```typescript
+const app = new YinzerFlow({
+  bodyParser: {
+    json: JsonParserOptions,
+    fileUploads: FileUploadOptions,
+    urlEncoded: UrlEncodedOptions
+  }
+});
+```
+
+## Configuration Validation and Warnings
+
+YinzerFlow validates all body parser configuration options and provides security warnings for potentially risky settings:
+
+### Automatic Validation
+- **Minimum limits**: Prevents broken configurations (e.g., maxSize: 0)
+- **Type checking**: Ensures proper data types for all options
+- **Logical validation**: Checks for contradictory settings
+
+### Security Warnings
+YinzerFlow will log warnings (but not block) potentially risky configurations:
+
+```typescript
+// This will trigger security warnings
+const riskyApp = new YinzerFlow({
+  bodyParser: {
+    json: {
+      maxSize: 52428800, // 50MB JSON - warning about memory risk
+      allowPrototypeProperties: true, // Warning about prototype pollution
+      maxDepth: 100 // Warning about stack overflow risk
+    },
+    fileUploads: {
+      maxFileSize: 1073741824, // 1GB files - warning about resources
+      allowedExtensions: ['.exe'] // Warning about dangerous file types
+    }
+  }
+});
+```
+
+## Error Handling
+
+YinzerFlow automatically handles body parsing errors and provides clear error messages:
+
+**JSON parsing errors:**
+- `Invalid JSON in request body: Unexpected token at position X`
+- `JSON body too large: maximum 256KB allowed`
+- `JSON nesting too deep: maximum 10 levels allowed`
+- `JSON object has too many keys: maximum 1000 allowed`
+
+**File upload errors:**
+- `File too large: maximum 10MB per file allowed`
+- `Too many files: maximum 10 files per request`
+- `File type not allowed: .exe files are blocked`
+- `Total upload size exceeded: maximum 50MB total allowed`
+
+**URL-encoded form errors:**
+- `Form data too large: maximum 1MB allowed`
+- `Too many form fields: maximum 1000 fields allowed`
+- `Form field name too long: maximum 100 characters`
+- `Form field value too large: maximum 1MB per field`
+
+These errors automatically result in appropriate HTTP status codes (400 Bad Request) and prevent malformed or malicious requests from reaching your application handlers.
+
+## Security Considerations
+
+YinzerFlow implements comprehensive security measures to prevent body parsing vulnerabilities:
+
+### 🛡️ JSON DoS Attack Prevention
+- **Problem**: Large or deeply nested JSON can cause memory exhaustion and stack overflow attacks
+- **YinzerFlow Solution**: Configurable size limits, nesting depth limits, key count restrictions, and string/array length limits prevent resource exhaustion
+
+### 🛡️ Prototype Pollution Protection
+- **Problem**: Malicious JSON can pollute JavaScript prototypes using `__proto__`, `constructor`, and `prototype` properties
+- **YinzerFlow Solution**: Blocks dangerous properties by default with `allowPrototypeProperties: false` and validates all object keys
+
+### 🛡️ File Upload Security
+- **Problem**: Malicious file uploads can execute code, consume server resources, or bypass security controls
+- **YinzerFlow Solution**: File type filtering, size limits, filename validation, and extension-based security controls
+
+### 🛡️ Memory Exhaustion Protection
+- **Problem**: Large form data, arrays, or objects can exhaust server memory and cause crashes
+- **YinzerFlow Solution**: Configurable limits on strings, arrays, fields, object keys, and total request sizes
+
+### 🛡️ Request Size Validation
+- **Problem**: Extremely large requests can cause DoS through resource exhaustion
+- **YinzerFlow Solution**: Content-type specific size limits with early validation before full parsing
+
+### 🛡️ Malformed Data Handling
+- **Problem**: Invalid or malformed data can crash parsers, cause security issues, or bypass validation
+- **YinzerFlow Solution**: Graceful error handling with detailed security context and safe fallback parsing
+
+### 🛡️ Filename Injection Prevention
+- **Problem**: Malicious filenames can contain path traversal attacks or dangerous characters
+- **YinzerFlow Solution**: Filename length validation, character sanitization, and path traversal prevention
+
+### 🛡️ MIME Type Validation
+- **Problem**: Spoofed or incorrect MIME types can bypass security filters
+- **YinzerFlow Solution**: Content-Type header validation and file extension cross-checking for uploaded files
+
+These security measures ensure YinzerFlow's body parsing implementation follows security best practices and prevents common attack vectors while maintaining spec compliance. 

package/docs/cors.md

@@ -0,0 +1,187 @@
+# CORS (Cross-Origin Resource Sharing)
+
+YinzerFlow provides built-in CORS support to handle cross-origin requests securely and efficiently.
+
+## Configuration
+
+Configure CORS in your YinzerFlow setup:
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({
+  cors: {
+    enabled: true,
+    origin: 'https://myapp.com',
+    credentials: true,
+    methods: ['GET', 'POST', 'PUT', 'DELETE'],
+    allowedHeaders: ['Content-Type', 'Authorization'],
+    exposedHeaders: ['X-Total-Count'],
+    maxAge: 86400,
+    optionsSuccessStatus: 204,
+    preflightContinue: false,
+  }
+});
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `false` | Enable/disable CORS |
+| `origin` | `string \| string[] \| RegExp \| function \| '*'` | `'*'` | Allowed origins |
+| `credentials` | `boolean` | `false` | Allow credentials (cookies, auth headers) |
+| `methods` | `string[]` | `['GET', 'POST', 'PUT', 'DELETE']` | Allowed HTTP methods |
+| `allowedHeaders` | `string \| string[]` | `['Content-Type', 'Authorization']` | Allowed request headers |
+| `exposedHeaders` | `string[]` | `[]` | Headers exposed to client |
+| `maxAge` | `number` | `86400` | Preflight cache duration (seconds) |
+| `optionsSuccessStatus` | `number` | `204` | Status code for successful OPTIONS |
+| `preflightContinue` | `boolean` | `false` | Pass control to next handler after preflight |
+
+## Common Use Cases
+
+- **Secure Web Applications**: Configure CORS for authenticated browser apps with specific domains and credentials
+- **Public APIs**: Enable broad access for public data APIs while maintaining security controls
+- **Development Environments**: Set up flexible CORS for local development with multiple frontend ports
+- **Microservices**: Configure cross-service communication with controlled origin validation
+- **Mobile App Backends**: Handle native mobile app requests with appropriate CORS settings
+- **Third-Party Integrations**: Allow controlled access from partner domains with validation functions
+
+## Origin Configuration Examples
+
+### Wildcard (Public APIs)
+```typescript
+cors: {
+  enabled: true,
+}
+```
+
+### Single Domain
+```typescript
+cors: {
+  enabled: true,
+  origin: 'https://myapp.com',
+  credentials: true,
+}
+```
+
+### Multiple Domains
+```typescript
+cors: {
+  enabled: true,
+  origin: [
+    'https://myapp.com',
+    'https://admin.myapp.com',
+    'https://mobile.myapp.com'
+  ],
+  credentials: true,
+}
+```
+
+### RegExp Pattern
+```typescript
+cors: {
+  enabled: true,
+  origin: /^https:\/\/.*\.myapp\.com$/,
+  credentials: true,
+}
+```
+
+### Dynamic Function
+```typescript
+cors: {
+  enabled: true,
+  origin: (origin, request): boolean => {
+    // Custom validation logic
+    const allowedDomains = ['myapp.com', 'partner.com'];
+    if (!origin) return false; // Reject: no origin header
+    
+    try {
+      const url = new URL(origin);
+      return allowedDomains.includes(url.hostname); // true = allow, false = reject
+    } catch {
+      return false; // Reject: malformed URL
+    }
+  },
+  credentials: true,
+}
+```
+
+**Function Return Values:**
+- `true` - Allow the origin (request proceeds with CORS headers)
+- `false` - Reject the origin (403 Forbidden response)
+
+## Request Flow
+
+### Simple Requests
+For simple requests (GET, POST with basic content types), CORS headers are added directly:
+
+```
+Client Request:
+Origin: https://myapp.com
+
+Server Response:
+Access-Control-Allow-Origin: https://myapp.com
+Access-Control-Allow-Credentials: true
+```
+
+### Preflight Requests
+For complex requests, browsers send an OPTIONS preflight:
+
+```
+Client Preflight:
+OPTIONS /api/data HTTP/1.1
+Origin: https://myapp.com
+Access-Control-Request-Method: PUT
+Access-Control-Request-Headers: Content-Type, Authorization
+
+Server Preflight Response:
+HTTP/1.1 204 No Content
+Access-Control-Allow-Origin: https://myapp.com
+Access-Control-Allow-Methods: GET, POST, PUT, DELETE
+Access-Control-Allow-Headers: Content-Type, Authorization
+Access-Control-Allow-Credentials: true
+Access-Control-Max-Age: 86400
+```
+
+## Error Handling
+
+YinzerFlow automatically handles CORS errors
+
+## Security Considerations
+
+YinzerFlow implements several security measures to prevent common CORS vulnerabilities:
+
+### 🛡️ Origin Validation Enforcement
+- **Problem**: Many frameworks validate origins but don't enforce the validation result
+- **YinzerFlow Solution**: Origin validation results are actually used - unauthorized requests get 403 Forbidden
+
+### 🛡️ No Origin Echo-back for Wildcards
+- **Problem**: Some implementations echo back the request origin when using wildcards, defeating CORS protection
+- **YinzerFlow Solution**: Wildcard origins always return literal `'*'`, never echo back request origins
+
+### 🛡️ Spec Compliance Enforcement
+- **Problem**: CORS spec forbids `origin: '*'` with `credentials: true`, but many frameworks allow this dangerous combination
+- **YinzerFlow Solution**: This combination throws a security error at startup, preventing deployment of vulnerable configurations
+
+### 🛡️ Proper Preflight Rejection
+- **Problem**: Some frameworks set CORS headers even for rejected requests, or let request handlers override CORS rejections
+- **YinzerFlow Solution**: Unauthorized preflight requests get 403 with no CORS headers, and the rejection cannot be overridden
+
+### 🛡️ Case-Insensitive Origin Matching
+- **Problem**: Inconsistent case handling can lead to bypass attempts
+- **YinzerFlow Solution**: All origin validation is case-insensitive but preserves original case in responses
+
+### 🛡️ Malformed Origin Protection
+- **Problem**: Malformed origins (like `javascript:`, `data:`, or invalid URLs) can cause security issues
+- **YinzerFlow Solution**: All malformed origins are safely rejected with 403 status
+
+### 🛡️ Function Validation Safety
+- **Problem**: Custom origin validation functions might throw errors or behave unpredictably
+- **YinzerFlow Solution**: Function results are safely coerced to boolean, preventing exceptions from bypassing security
+
+### 🛡️ No Information Leakage
+- **Problem**: Error responses might leak information about internal origins or configurations
+- **YinzerFlow Solution**: Rejection responses only include the rejected origin, no internal configuration details
+
+These security measures ensure YinzerFlow's CORS implementation follows security best practices and prevents common attack vectors while maintaining spec compliance. If you come up with any other security implementation's that hadn't been addressed, Please open a PR and follow our contribution guides.