yinzerflow 0.1.18 → 0.2.0

package/docs/ip-security.md

@@ -0,0 +1,232 @@
+# IP Address Security
+
+YinzerFlow provides comprehensive IP address validation and security protection against IP spoofing attacks, supporting multiple header formats with trusted proxy validation.
+
+## Configuration
+
+Configure IP security settings in your YinzerFlow application:
+
+```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
+  }
+});
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|-----|---|---|---|
+| `trustedProxies` | `string[]` | `['127.0.0.1', '::1']` | List of trusted proxy IP addresses |
+| `allowPrivateIps` | `boolean` | `true` | Allow private IP addresses (RFC 1918, etc.) |
+| `headerPreference` | `string[]` | `['x-forwarded-for', 'x-real-ip', 'cf-connecting-ip', 'x-client-ip', 'true-client-ip']` | Header preference order |
+| `maxChainLength` | `number` | `10` | Maximum IP chain length |
+| `detectSpoofing` | `boolean` | `true` | Enable spoofing pattern detection |
+
+## Examples
+
+### Basic Example
+
+Access client IP address with automatic security validation:
+
+```typescript
+app.get('/api/user-info', ({ request }) => {
+  const clientIp = request.ipAddress;
+  
+  return {
+    message: `Hello from ${clientIp}`,
+    userAgent: request.headers['user-agent']
+  };
+});
+```
+
+### Advanced Example
+
+Configure IP security for your application:
+
+```typescript
+app.post('/api/secure-endpoint', ({ request }) => {
+  // YinzerFlow automatically applies IP security configuration
+  const clientIp = request.ipAddress; // Uses configured IP security rules
+  
+  if (!clientIp) {
+    return {
+      error: 'Unable to determine client IP address',
+      message: 'Request may be from untrusted proxy or invalid source'
+    };
+  }
+  
+  return {
+    clientIp,
+    message: 'Secure endpoint accessed successfully'
+  };
+});
+```
+
+## Common Use Cases
+
+- **Load Balancer Integration**: Configure trusted proxies to get real client IPs behind Nginx, HAProxy, or cloud load balancers
+- **CDN Support**: Handle Cloudflare and other CDN headers like `CF-Connecting-IP` with proper validation
+- **Reverse Proxy Security**: Validate proxy chains to prevent IP spoofing in complex network topologies
+- **Complex Infrastructure**: Use wildcard (`'*'`) for Kubernetes ingress, unknown CDN configurations, or dynamic proxy setups
+- **Rate Limiting**: Get accurate client IPs for rate limiting and abuse prevention systems
+- **Geolocation Services**: Ensure IP addresses are valid before passing to geolocation APIs
+- **Security Logging**: Log real client IPs for security monitoring and incident response
+
+### Load Balancer Behind Nginx
+
+```typescript
+const app = new YinzerFlow({
+  port: 3000,
+  ipSecurity: {
+    trustedProxies: ['192.168.1.10'], // Your Nginx server
+    headerPreference: ['x-forwarded-for'],
+    detectSpoofing: true
+  }
+});
+```
+
+### Cloudflare CDN Integration
+
+```typescript
+const app = new YinzerFlow({
+  port: 3000,
+  ipSecurity: {
+    trustedProxies: [
+      // Cloudflare IP ranges
+      '173.245.48.0/20', '103.21.244.0/22', '103.22.200.0/22'
+    ],
+    headerPreference: ['cf-connecting-ip', 'x-forwarded-for'],
+    allowPrivateIps: false // Only real client IPs
+  }
+});
+```
+
+### High-Security Environment
+
+```typescript
+const app = new YinzerFlow({
+  port: 3000,
+  ipSecurity: {
+    trustedProxies: ['10.0.1.100'], // Only specific proxy
+    maxChainLength: 2, // Short chains only
+    detectSpoofing: true,
+    allowPrivateIps: false
+  }
+});
+```
+
+### Complex Infrastructure (Unknown Proxies)
+
+```typescript
+const app = new YinzerFlow({
+  port: 3000,
+  ipSecurity: {
+    trustedProxies: ['*'], // Trust any proxy - useful for Kubernetes, unknown CDNs
+    detectSpoofing: true, // Still detect attack patterns
+    maxChainLength: 10,
+    allowPrivateIps: false
+  }
+});
+```
+
+## Error Handling
+
+YinzerFlow handles IP parsing errors gracefully and applies security validation automatically:
+
+**Common behaviors:**
+- Invalid IP formats result in empty `request.ipAddress` 
+- Untrusted proxy chains are rejected when strict validation is enabled
+- Spoofing patterns are detected and suspicious headers are ignored automatically
+- Private IPs are filtered when `allowPrivateIps: false` is configured
+
+```typescript
+app.get('/api/user-location', ({ request }) => {
+  const clientIp = request.ipAddress;
+  
+  if (!clientIp) {
+    // YinzerFlow couldn't determine a valid, trusted IP
+    return { 
+      error: 'Unable to determine client location',
+      message: 'IP address validation failed' 
+    };
+  }
+  
+  // Safe to use clientIp - YinzerFlow has validated it
+  return await getLocationForIp(clientIp);
+});
+```
+
+## Security Considerations
+
+YinzerFlow implements several security measures to prevent IP spoofing attacks and ensure accurate client identification:
+
+### 🛡️ Trusted Proxy Validation
+- **Problem**: Attackers can spoof `X-Forwarded-For` headers to hide their real IP address or impersonate other clients
+- **YinzerFlow Solution**: Only accepts forwarded headers from explicitly configured trusted proxy IPs, preventing spoofing from untrusted sources
+
+#### How Trusted Proxies Work
+
+When using `X-Forwarded-For` headers, YinzerFlow validates proxy chains by checking if the **rightmost IP** (the proxy that sent the request) is in your trusted proxies list:
+
+```
+X-Forwarded-For: 203.0.113.1, 198.51.100.1, 127.0.0.1
+                 ^client IP    ^proxy 1     ^proxy 2 (rightmost - must be trusted)
+```
+
+**Key Points:**
+- **Only the rightmost IP needs to be trusted** - this is the proxy that directly sent the request to your server
+- **Client IP is extracted** - YinzerFlow extracts the leftmost IP (203.0.113.1) as the real client
+- **Chain validation** - If the rightmost IP isn't in your `trustedProxies` list, the entire header is rejected
+- **Wildcard support** - Use `['*']` to trust any proxy (useful for Kubernetes/unknown infrastructure)
+
+**Examples:**
+```typescript
+// ✅ Valid: 127.0.0.1 is trusted, extracts 203.0.113.1 as client
+trustedProxies: ['127.0.0.1']
+X-Forwarded-For: 203.0.113.1, 127.0.0.1
+
+// ❌ Invalid: 192.168.1.1 is not trusted, header rejected
+trustedProxies: ['127.0.0.1'] 
+X-Forwarded-For: 203.0.113.1, 192.168.1.1
+
+// ✅ Valid: Wildcard trusts any proxy
+trustedProxies: ['*']
+X-Forwarded-For: 203.0.113.1, any.proxy.ip
+```
+
+### 🛡️ Multiple Header Support
+- **Problem**: Different proxies and CDNs use different headers (X-Real-IP, CF-Connecting-IP, etc.), making it hard to get consistent client IPs
+- **YinzerFlow Solution**: Configurable header preference order with validation for each header type based on its expected format and source
+
+### 🛡️ IP Format Validation
+- **Problem**: Malformed IP addresses can cause application errors or bypass security controls
+- **YinzerFlow Solution**: Comprehensive IPv4 and IPv6 validation with named capture groups for precise format checking
+
+### 🛡️ Spoofing Pattern Detection
+- **Problem**: Sophisticated attacks use patterns like duplicate IPs, overly long chains, or mixed valid/invalid IPs to confuse parsing
+- **YinzerFlow Solution**: Advanced pattern detection identifies suspicious IP chains and automatically rejects them
+
+### 🛡️ Private IP Filtering
+- **Problem**: Internal network IPs might leak information about network topology or be used in certain attacks
+- **YinzerFlow Solution**: Configurable private IP filtering with RFC 1918, RFC 4193, and RFC 3927 range detection
+
+### 🛡️ Chain Length Limits
+- **Problem**: Extremely long IP chains can cause DoS attacks through memory exhaustion or processing delays
+- **YinzerFlow Solution**: Configurable maximum chain length prevents amplification attacks while allowing legitimate proxy chains
+
+### 🛡️ Fallback Protection
+- **Problem**: When strict validation fails, applications might fall back to unsafe IP extraction methods
+- **YinzerFlow Solution**: Controlled fallback behavior that maintains security when trusted proxies are configured
+
+### 🛡️ IPv6 Security
+- **Problem**: IPv6 addresses have complex formats that can be exploited for parsing attacks or validation bypasses
+- **YinzerFlow Solution**: Robust IPv6 validation including compression rules, zone identifiers, and IPv4-mapped addresses
+
+These security measures ensure YinzerFlow's IP parsing implementation follows security best practices and prevents common attack vectors while maintaining compatibility with standard proxy configurations. 

package/docs/request.md

@@ -0,0 +1,145 @@
+# Request Object
+
+YinzerFlow provides a comprehensive request object containing parsed headers, body, query parameters, route parameters, and metadata with built-in security protections and validation.
+
+## Configuration
+
+Request parsing is automatically enabled and requires no configuration for basic usage:
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({ port: 3000 });
+
+// Request object is automatically parsed and available in handlers
+app.get('/api/data', ({ request }) => {
+  const userAgent = request.headers['user-agent'];
+  const queryParam = request.query.search;
+  
+  return { 
+    message: 'Request parsed successfully',
+    userAgent,
+    queryParam 
+  };
+});
+```
+
+### Configuration Options
+
+YinzerFlow's request parsing includes built-in security limits that are automatically applied:
+
+| Security Limit | Default Value | Description |
+|-----|---|---|
+| `MAX_HEADERS` | `100` | Maximum number of headers per request |
+| `MAX_HEADER_NAME_LENGTH` | `200` | Maximum length of header names |
+| `MAX_HEADER_VALUE_LENGTH` | `8192` | Maximum length of header values |
+
+These limits are built into the framework and cannot be disabled, ensuring consistent security across all YinzerFlow applications.
+
+## Basic Example
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({ port: 3000 });
+
+app.post('/api/users/:id', ({ request }) => {
+  // Access route parameters
+  const userId = request.params.id;
+  
+  // Access query parameters
+  const includeProfile = request.query.include_profile;
+  
+  // Access headers
+  const contentType = request.headers['content-type'];
+  const authorization = request.headers['authorization'];
+  
+  // Access request body
+  const userData = request.body;
+
+  const clientIp = request.ipAddress
+  
+  return {
+    message: 'Request processed successfully',
+    userId,
+    includeProfile,
+    contentType,
+    hasAuth: !!authorization,
+    receivedData: userData
+  };
+});
+  ```
+
+## Common Use Cases
+
+- **Authentication**: Extract and validate Bearer tokens, API keys, and session headers
+- **Content Negotiation**: Handle Accept, Accept-Encoding, and Content-Type headers for proper response formatting
+- **File Uploads**: Process multipart form data with automatic parsing and validation
+- **API Filtering**: Use query parameters for pagination, sorting, and filtering
+- **Route Parameters**: Extract dynamic URL segments with automatic parsing
+- **Request Logging**: Access client IP, user agent, and request metadata for logging
+
+## Error Handling
+
+YinzerFlow automatically handles request parsing errors and provides clear error messages:
+
+**Header-related errors:**
+- `Too many headers: maximum 100 allowed`
+- `Invalid header name: Invalid@Header`
+- `Header name too long: maximum 200 characters allowed`
+- `Header value too long: maximum 8192 characters allowed`
+- `Header value contains invalid control characters`
+
+**Body parsing errors:** See [Body Parsing Documentation](./body-parsing.md) for detailed error handling
+
+These errors automatically result in appropriate HTTP status codes (400 Bad Request) and prevent malformed requests from reaching your application handlers.
+
+## Security Considerations
+
+YinzerFlow implements several security measures to prevent common request-based vulnerabilities:
+
+### 🛡️ RFC 7230 Header Compliance
+- **Problem**: Invalid header names can bypass security filters and cause parsing inconsistencies
+- **YinzerFlow Solution**: Strict validation against RFC 7230 specification - only valid header characters are allowed (letters, digits, hyphens, and specific symbols)
+
+### 🛡️ DoS Protection Through Limits
+- **Problem**: Unlimited headers, names, or values can cause memory exhaustion and server crashes
+- **YinzerFlow Solution**: Built-in limits prevent abuse: maximum 100 headers, 200-character names, and 8KB values
+
+### 🛡️ Control Character Sanitization
+- **Problem**: Control characters in headers can cause parsing errors and bypass security filters
+- **YinzerFlow Solution**: Automatic removal of dangerous control characters while preserving legitimate characters like horizontal tabs
+
+### 🛡️ Body Parsing Protection
+- **Problem**: Malformed request bodies can cause parsing errors, memory exhaustion, or security vulnerabilities
+- **YinzerFlow Solution**: Comprehensive body parsing security with size limits, validation, and protection against common attacks - see [Body Parsing Documentation](./body-parsing.md)
+
+### 🛡️ Parameter Pollution Prevention
+- **Problem**: Duplicate query parameters can bypass validation or cause unexpected behavior
+- **YinzerFlow Solution**: Consistent parameter handling - last value wins for duplicates, preventing pollution attacks
+
+### 🛡️ Path Traversal Protection
+- **Problem**: Directory traversal attacks through URL paths can access unauthorized files
+- **YinzerFlow Solution**: Comprehensive path normalization and validation prevents traversal attempts while maintaining route functionality
+
+### 🛡️ IP Address Validation
+- **Problem**: Spoofed proxy headers can bypass IP-based security controls
+- **YinzerFlow Solution**: Secure IP address extraction with proxy header validation prevents spoofing attacks
+
+## Body Parsing
+
+YinzerFlow automatically parses request bodies (JSON, file uploads, forms) with built-in security protections. Parsed data is available on `request.body` - see [Body Parsing Documentation](./body-parsing.md) for detailed configuration options, examples, and security considerations.
+
+```typescript
+app.post('/api/users', ({ request, response }) => {
+  // Body is automatically parsed based on Content-Type
+  const userData = request.body;
+  
+  return {
+    message: 'User created successfully',
+    data: userData
+  };
+});
+```
+
+These security measures ensure YinzerFlow's request implementation follows security best practices and prevents common attack vectors while maintaining RFC compliance and performance. 

package/docs/response.md

@@ -0,0 +1,251 @@
+# Response Object
+
+YinzerFlow provides a powerful response object for sending HTTP responses with automatic content type detection, header validation, and built-in security protections.
+
+## Configuration
+
+Response handling is automatically enabled and requires no configuration for basic usage:
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({ port: 3000 });
+
+// Response object is automatically available in handlers
+app.get('/api/data', ({ response }) => {
+  // Set status code
+  response.setStatusCode(200);
+  
+  // Add headers
+  response.addHeaders({
+    'Content-Type': 'application/json',
+    'Cache-Control': 'no-cache'
+  });
+  
+  return { message: 'Response sent successfully' };
+});
+```
+
+YinzerFlow's response handling includes built-in security protections that are automatically applied to prevent common vulnerabilities, including automatic security headers on all responses.
+
+## Basic Example
+
+```typescript
+import { YinzerFlow } from 'yinzerflow';
+
+const app = new YinzerFlow({ port: 3000 });
+
+app.get('/api/users/:id', ({ request, response }) => {
+  const userId = request.params.id;
+  
+  // Set successful status code
+  response.setStatusCode(200);
+  
+  // Add custom headers
+  response.addHeaders({
+    'X-User-ID': userId,
+    'Cache-Control': 'max-age=3600',
+    'X-API-Version': '1.0'
+  });
+  
+  // Return JSON response body (Content-Type automatically set)
+  return {
+    id: userId,
+    name: 'John Doe',
+    email: 'john@example.com',
+    timestamp: new Date().toISOString()
+  };
+});
+
+app.post('/api/files', ({ request, response }) => {
+  // Set created status
+  response.setStatusCode(201);
+  
+  // Add location header for created resource
+  response.addHeaders({
+    'Location': '/api/files/12345',
+    'X-Upload-Size': request.headers['content-length'] || '0'
+  });
+  
+  return { fileId: '12345', status: 'uploaded' };
+});
+```
+
+## Response Body Handling
+
+YinzerFlow automatically processes response bodies based on their type:
+
+### JSON Objects and Arrays
+
+Objects and arrays are automatically JSON stringified with `Content-Type: application/json`:
+
+```typescript
+// Automatically becomes JSON
+return { message: 'Hello', data: [1, 2, 3] };
+// Content-Type: application/json
+// Body: {"message":"Hello","data":[1,2,3]}
+
+return [{ id: 1 }, { id: 2 }];
+// Content-Type: application/json  
+// Body: [{"id":1},{"id":2}]
+```
+
+### Strings
+
+String responses get intelligent content type detection:
+
+```typescript
+// JSON string
+return '{"message": "Hello"}';
+// Content-Type: application/json
+
+// Form data
+return 'name=John&email=john@example.com';
+// Content-Type: application/x-www-form-urlencoded
+
+// Plain text
+return 'Hello, world!';
+// Content-Type: text/plain
+```
+
+### Binary Data
+
+Binary data is handled with appropriate encoding:
+
+```typescript
+// Buffer/Uint8Array/ArrayBuffer
+const imageBuffer = Buffer.from(imageData);
+return imageBuffer;
+// Content-Type: application/octet-stream (for binary)
+// Content-Type: text/plain (for text-like content)
+
+// Base64 encoding for true binary
+response.addHeaders({ 'Content-Transfer-Encoding': 'base64' });
+return imageBuffer; // Automatically encoded as base64
+```
+
+### Primitives
+
+Numbers, booleans, and other primitives are converted to strings:
+
+```typescript
+return 42;          // "42", Content-Type: text/plain
+return true;        // "true", Content-Type: text/plain
+return new Date();  // ISO string, Content-Type: text/plain
+```
+
+## API Reference
+
+### setStatusCode(statusCode)
+
+Sets the HTTP status code for the response.
+
+```typescript
+response.setStatusCode(200);  // OK
+response.setStatusCode(201);  // Created
+response.setStatusCode(400);  // Bad Request
+response.setStatusCode(404);  // Not Found
+response.setStatusCode(500);  // Internal Server Error
+```
+
+### addHeaders(headers)
+
+Adds or updates response headers. Headers are validated for security before being set.
+
+```typescript
+// Single header
+response.addHeaders({ 'X-Custom-Header': 'value' });
+
+// Multiple headers
+response.addHeaders({
+  'Cache-Control': 'max-age=3600',
+  'X-API-Version': '2.0',
+  'Access-Control-Allow-Origin': '*'
+});
+
+// Security headers
+response.addHeaders({
+  'X-Content-Type-Options': 'nosniff',
+  'X-Frame-Options': 'DENY',
+  'X-XSS-Protection': '1; mode=block'
+});
+```
+
+### removeHeaders(headerNames)
+
+Removes headers from the response.
+
+```typescript
+// Remove single header
+response.removeHeaders(['X-Powered-By']);
+
+// Remove multiple headers
+response.removeHeaders(['Server', 'X-Debug-Info', 'X-Internal-ID']);
+```
+
+## Common Use Cases
+
+- **Set Status Codes**: Configure HTTP status codes (200, 404, 500, etc.) to communicate request results to clients
+- **Add Custom Headers**: Include metadata, caching directives, and API versioning information in responses
+- **Handle File Downloads**: Stream binary data with proper Content-Type and Content-Disposition headers for file downloads
+- **Configure CORS**: Enable cross-origin requests by adding Access-Control headers for browser security
+- **Implement Redirects**: Send location headers with 301/302 status codes to redirect clients to new resources
+- **Process Error Responses**: Return appropriate error status codes and structured error messages for client debugging
+
+## Error Handling
+
+YinzerFlow automatically handles response processing errors and provides clear error messages:
+
+**Header-related errors:**
+- `Invalid header value: contains CRLF characters`
+- `Suspicious header pattern detected: potential injection attempt`
+- `Header validation failed: invalid characters in header name`
+
+**Body processing errors:**
+- `Failed to stringify response body: circular reference detected`
+- `Binary data encoding error: invalid buffer format`
+- `Response body too large: exceeds maximum size limit`
+
+These errors are automatically logged and result in appropriate HTTP status codes (500 Internal Server Error) to prevent malformed responses from being sent to clients.
+
+## Security Considerations
+
+YinzerFlow implements several security measures to prevent common response-based vulnerabilities:
+
+### 🛡️ CRLF Injection Prevention
+- **Problem**: Injecting carriage return (`\r`) or line feed (`\n`) characters in header values can allow attackers to inject additional headers or even HTTP response splitting attacks
+- **YinzerFlow Solution**: Comprehensive validation detects and blocks CRLF characters in header values before they are set, preventing header injection attacks
+
+### 🛡️ Response Header Validation
+- **Problem**: Invalid header names or values can cause parsing errors in clients or bypass security controls
+- **YinzerFlow Solution**: All response headers are validated against HTTP specifications and security patterns before being sent
+
+### 🛡️ Suspicious Pattern Detection
+- **Problem**: Attackers may try to inject malicious headers like `Set-Cookie` or create HTTP response splitting attacks
+- **YinzerFlow Solution**: Advanced pattern detection identifies and blocks suspicious header values that could indicate injection attempts
+
+### 🛡️ Safe Header Filtering
+- **Problem**: Undefined or null header values can cause unexpected behavior or security bypasses
+- **YinzerFlow Solution**: Automatic filtering removes undefined values and validates all headers before they reach the response
+
+### 🛡️ Content-Type Security
+- **Problem**: Missing or incorrect Content-Type headers can lead to MIME sniffing attacks or content confusion
+- **YinzerFlow Solution**: Intelligent content type detection ensures appropriate Content-Type headers are set based on response body content
+
+### 🛡️ JSON Stringification Safety
+- **Problem**: Circular references or non-serializable objects can crash the server or leak sensitive information
+- **YinzerFlow Solution**: Safe JSON stringification with error handling prevents crashes and provides fallback string conversion
+
+### 🛡️ Binary Data Handling
+- **Problem**: Improper binary data encoding can corrupt files or expose server internals
+- **YinzerFlow Solution**: Proper binary data detection and encoding ensures files are transmitted correctly and securely
+
+### 🛡️ Status Code Validation
+- **Problem**: Invalid HTTP status codes can confuse clients or indicate server errors
+- **YinzerFlow Solution**: Automatic mapping of status codes to standard HTTP status messages ensures consistent and valid responses
+
+### 🛡️ Automatic Security Headers
+- **Problem**: Missing security headers leave applications vulnerable to clickjacking, MIME sniffing, and XSS attacks
+- **YinzerFlow Solution**: Automatically adds essential security headers to every response unless explicitly overridden by the application
+
+These security measures ensure YinzerFlow's response implementation follows security best practices and prevents common attack vectors while maintaining HTTP compliance and performance.