yinzerflow 0.4.4 → 0.5.0

package/docs/security/cors.md

@@ -1,189 +0,0 @@
-# CORS Security
-
-YinzerFlow provides built-in CORS support to handle cross-origin requests securely and efficiently.
-
-For an overview of all security features, see [Security Overview](./security-overview.md).
-
-## 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.

package/docs/security/ip-security.md

@@ -1,234 +0,0 @@
-# IP Security
-
-YinzerFlow provides comprehensive IP address validation and security protection against IP spoofing attacks, supporting multiple header formats with trusted proxy validation.
-
-For an overview of all security features, see [Security Overview](./security-overview.md).
-
-## 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.