balda-js 0.0.1

package/docs/docs/plugins/helmet.md

@@ -0,0 +1,388 @@
+---
+sidebar_position: 6
+---
+
+# Helmet Plugin
+
+The Helmet plugin sets various HTTP headers to help protect your Balda.js application from well-known web vulnerabilities. It's a security middleware that helps secure your app by setting several HTTP headers.
+
+## Features
+
+- **Security Headers**: Sets various security-related HTTP headers
+- **Configurable Options**: Customize which headers to enable/disable
+- **Production Ready**: Optimized security settings for production
+- **Easy Integration**: Simple configuration with sensible defaults
+- **Comprehensive Protection**: Covers multiple attack vectors
+
+## Basic Configuration
+
+### Simple Setup
+
+```typescript
+import { Server } from 'balda-js';
+
+const server = new Server({
+  port: 3000,
+  plugins: {
+    helmet: {}
+  }
+});
+```
+
+### Disable Helmet
+
+```typescript
+const server = new Server({
+  port: 3000,
+  plugins: {
+    helmet: false
+  }
+});
+```
+
+## Configuration Options
+
+### Default Configuration
+
+```typescript
+helmet: {
+  dnsPrefetchControl: true,
+  frameguard: { action: "SAMEORIGIN" },
+  hsts: { maxAge: 15552000, includeSubDomains: true, preload: false },
+  contentTypeOptions: true,
+  ieNoOpen: true,
+  xssFilter: true,
+  referrerPolicy: "no-referrer",
+  crossOriginResourcePolicy: "same-origin",
+  crossOriginOpenerPolicy: "same-origin",
+  crossOriginEmbedderPolicy: "require-corp",
+  contentSecurityPolicy: false
+}
+```
+
+### Custom Configuration
+
+```typescript
+const server = new Server({
+  port: 3000,
+  plugins: {
+    helmet: {
+      contentSecurityPolicy: {
+        directives: {
+          defaultSrc: ["'self'"],
+          styleSrc: ["'self'", "'unsafe-inline'"],
+          scriptSrc: ["'self'"],
+          imgSrc: ["'self'", "data:", "https:"]
+        }
+      },
+      hsts: {
+        maxAge: 31536000, // 1 year
+        includeSubDomains: true,
+        preload: true
+      }
+    }
+  }
+});
+```
+
+## Security Headers Explained
+
+### Content Security Policy (CSP)
+
+```typescript
+helmet: {
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      styleSrc: ["'self'", "'unsafe-inline'", "https://fonts.googleapis.com"],
+      scriptSrc: ["'self'", "https://cdn.jsdelivr.net"],
+      imgSrc: ["'self'", "data:", "https:"],
+      fontSrc: ["'self'", "https://fonts.gstatic.com"],
+      connectSrc: ["'self'", "https://api.example.com"],
+      frameSrc: ["'none'"],
+      objectSrc: ["'none'"],
+      mediaSrc: ["'self'"],
+      manifestSrc: ["'self'"]
+    }
+  }
+}
+```
+
+### HTTP Strict Transport Security (HSTS)
+
+```typescript
+helmet: {
+  hsts: {
+    maxAge: 31536000,        // 1 year
+    includeSubDomains: true, // Apply to subdomains
+    preload: true            // Include in browser preload lists
+  }
+}
+```
+
+### Frame Options
+
+```typescript
+helmet: {
+  frameguard: {
+    action: "DENY" // Prevent embedding in frames
+  }
+}
+
+// Or use string values
+helmet: {
+  frameguard: "DENY" // Same as above
+}
+```
+
+### XSS Protection
+
+```typescript
+helmet: {
+  xssFilter: true // Enable XSS protection
+}
+```
+
+### Content Type Options
+
+```typescript
+helmet: {
+  contentTypeOptions: true // Prevent MIME type sniffing
+}
+```
+
+## Usage Examples
+
+### Basic Security Setup
+
+```typescript
+const server = new Server({
+  port: 3000,
+  plugins: {
+    helmet: {
+      contentSecurityPolicy: false, // Disable CSP for development
+      hsts: false // Disable HSTS for HTTP
+    }
+  }
+});
+```
+
+### Production Security Configuration
+
+```typescript
+const isProduction = process.env.NODE_ENV === 'production';
+
+const server = new Server({
+  port: 3000,
+  plugins: {
+    helmet: {
+      contentSecurityPolicy: isProduction ? {
+        directives: {
+          defaultSrc: ["'self'"],
+          styleSrc: ["'self'", "'unsafe-inline'"],
+          scriptSrc: ["'self'"],
+          imgSrc: ["'self'", "data:", "https:"],
+          fontSrc: ["'self'", "https://fonts.gstatic.com"],
+          connectSrc: ["'self'"],
+          frameSrc: ["'none'"],
+          objectSrc: ["'none'"]
+        }
+      } : false,
+      hsts: isProduction ? {
+        maxAge: 31536000,
+        includeSubDomains: true,
+        preload: true
+      } : false,
+      frameguard: { action: "DENY" },
+      xssFilter: true,
+      contentTypeOptions: true,
+      referrerPolicy: "strict-origin-when-cross-origin"
+    }
+  }
+});
+```
+
+### API-Focused Configuration
+
+```typescript
+const server = new Server({
+  port: 3000,
+  plugins: {
+    helmet: {
+      contentSecurityPolicy: false, // APIs don't need CSP
+      hsts: {
+        maxAge: 31536000,
+        includeSubDomains: true
+      },
+      frameguard: { action: "DENY" },
+      xssFilter: true,
+      contentTypeOptions: true,
+      referrerPolicy: "no-referrer"
+    }
+  }
+});
+```
+
+### Web Application Configuration
+
+```typescript
+const server = new Server({
+  port: 3000,
+  plugins: {
+    helmet: {
+      contentSecurityPolicy: {
+        directives: {
+          defaultSrc: ["'self'"],
+          styleSrc: ["'self'", "'unsafe-inline'", "https://fonts.googleapis.com"],
+          scriptSrc: ["'self'", "https://cdn.jsdelivr.net"],
+          imgSrc: ["'self'", "data:", "https:"],
+          fontSrc: ["'self'", "https://fonts.gstatic.com"],
+          connectSrc: ["'self'", "wss:"],
+          frameSrc: ["'self'"],
+          objectSrc: ["'none'"],
+          mediaSrc: ["'self'"],
+          manifestSrc: ["'self'"]
+        }
+      },
+      hsts: {
+        maxAge: 31536000,
+        includeSubDomains: true,
+        preload: true
+      },
+      frameguard: { action: "SAMEORIGIN" },
+      xssFilter: true,
+      contentTypeOptions: true,
+      referrerPolicy: "strict-origin-when-cross-origin"
+    }
+  }
+});
+```
+
+## Individual Header Configuration
+
+### DNS Prefetch Control
+
+```typescript
+helmet: {
+  dnsPrefetchControl: true // Disable DNS prefetching
+}
+```
+
+### Frame Guard
+
+```typescript
+helmet: {
+  frameguard: {
+    action: "DENY" // Prevent all framing
+  }
+}
+
+// Available actions:
+// "DENY" - Prevent all framing
+// "SAMEORIGIN" - Allow same-origin framing
+// "ALLOW-FROM uri" - Allow framing from specific URI
+```
+
+### HSTS Configuration
+
+```typescript
+helmet: {
+  hsts: {
+    maxAge: 31536000,        // Time in seconds
+    includeSubDomains: true, // Apply to subdomains
+    preload: true            // Include in preload lists
+  }
+}
+```
+
+### Content Type Options
+
+```typescript
+helmet: {
+  contentTypeOptions: true // Prevent MIME type sniffing
+}
+```
+
+### IE No Open
+
+```typescript
+helmet: {
+  ieNoOpen: true // Prevent IE from executing downloads
+}
+```
+
+### XSS Filter
+
+```typescript
+helmet: {
+  xssFilter: true // Enable XSS protection
+}
+```
+
+### Referrer Policy
+
+```typescript
+helmet: {
+  referrerPolicy: "strict-origin-when-cross-origin"
+}
+
+// Available policies:
+// "no-referrer"
+// "no-referrer-when-downgrade"
+// "origin"
+// "origin-when-cross-origin"
+// "same-origin"
+// "strict-origin"
+// "strict-origin-when-cross-origin"
+// "unsafe-url"
+```
+
+### Cross-Origin Policies
+
+```typescript
+helmet: {
+  crossOriginResourcePolicy: "same-origin",
+  crossOriginOpenerPolicy: "same-origin",
+  crossOriginEmbedderPolicy: "require-corp"
+}
+```
+
+## Environment-Based Configuration
+
+### Development vs Production
+
+```typescript
+const isProduction = process.env.NODE_ENV === 'production';
+
+const helmetConfig = isProduction ? {
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+      scriptSrc: ["'self'"],
+      imgSrc: ["'self'", "data:", "https:"]
+    }
+  },
+  hsts: {
+    maxAge: 31536000,
+    includeSubDomains: true,
+    preload: true
+  },
+  frameguard: { action: "DENY" },
+  xssFilter: true,
+  contentTypeOptions: true
+} : {
+  contentSecurityPolicy: false,
+  hsts: false,
+  frameguard: { action: "SAMEORIGIN" },
+  xssFilter: true,
+  contentTypeOptions: true
+};
+
+const server = new Server({
+  port: 3000,
+  plugins: {
+    helmet: helmetConfig
+  }
+});
+```

package/docs/docs/plugins/json.md

@@ -0,0 +1,338 @@
+---
+sidebar_position: 3
+---
+
+# JSON Plugin
+
+The JSON plugin parses incoming JSON request bodies and populates `req.body` with the parsed data. It automatically handles content-type detection and provides configurable size limits and error handling.
+
+## Features
+
+- **Automatic Content-Type Detection**: Parses requests with `application/json` content type
+- **Configurable Size Limits**: Set maximum body size to prevent memory issues
+- **Encoding Support**: Support for various text encodings
+- **Error Handling**: Graceful handling of malformed JSON
+- **Empty Body Handling**: Configurable behavior for empty request bodies
+
+## Basic Configuration
+
+### Simple Setup
+
+```typescript
+import { Server } from 'balda-js';
+
+const server = new Server({
+  port: 3000,
+  plugins: {
+    json: {
+      sizeLimit: '10mb'
+    }
+  }
+});
+```
+
+### Default Configuration
+
+```typescript
+const server = new Server({
+  port: 3000,
+  plugins: {
+    json: {
+      sizeLimit: 5 * 1024 * 1024, // 5MB
+      parseEmptyBodyAsObject: false,
+      encoding: 'utf-8'
+    }
+  }
+});
+```
+
+## Configuration Options
+
+### Size Limit
+
+```typescript
+// Using bytes
+json: {
+  sizeLimit: 1024 * 1024 // 1MB
+}
+
+// Using string notation
+json: {
+  sizeLimit: '10mb'
+}
+
+// Large payloads
+json: {
+  sizeLimit: 50 * 1024 * 1024 // 50MB
+}
+```
+
+### Empty Body Handling
+
+```typescript
+// Default behavior - empty body becomes undefined
+json: {
+  parseEmptyBodyAsObject: false
+}
+
+// Empty body becomes empty object
+json: {
+  parseEmptyBodyAsObject: true
+}
+```
+
+### Custom Error Messages
+
+```typescript
+json: {
+  sizeLimit: '10mb',
+  customErrorMessage: {
+    status: 413,
+    message: 'Request body too large'
+  }
+}
+```
+
+### Encoding Configuration
+
+```typescript
+// UTF-8 (default)
+json: {
+  encoding: 'utf-8'
+}
+
+// UTF-16
+json: {
+  encoding: 'utf-16le'
+}
+
+// Other encodings
+json: {
+  encoding: 'iso-8859-1'
+}
+```
+
+## Usage Examples
+
+### Basic JSON Parsing
+
+```typescript
+@controller('/api')
+export class ApiController {
+  @post('/users')
+  async createUser(req: Request, res: Response) {
+    // req.body is automatically parsed JSON
+    const { name, email, age } = req.body;
+
+    const user = await createUser({ name, email, age });
+    res.created(user);
+  }
+}
+```
+
+### Handling Large Payloads
+
+```typescript
+const server = new Server({
+  port: 3000,
+  plugins: {
+    json: {
+      sizeLimit: '50mb', // Allow large file uploads
+      customErrorMessage: {
+        status: 413,
+        message: 'File too large'
+      }
+    }
+  }
+});
+
+@controller('/api')
+export class FileController {
+  @post('/upload')
+  async uploadFile(req: Request, res: Response) {
+    // Handle large JSON payloads
+    const fileData = req.body;
+    res.json({ message: 'File uploaded successfully' });
+  }
+}
+```
+
+### Empty Body Scenarios
+
+```typescript
+@controller('/api')
+export class HealthController {
+  @post('/health')
+  async healthCheck(req: Request, res: Response) {
+    if (req.body === undefined) {
+      // Empty body with parseEmptyBodyAsObject: false
+      res.json({ status: 'ok', body: 'empty' });
+    } else if (Object.keys(req.body).length === 0) {
+      // Empty body with parseEmptyBodyAsObject: true
+      res.json({ status: 'ok', body: 'empty object' });
+    } else {
+      res.json({ status: 'ok', body: req.body });
+    }
+  }
+}
+```
+
+## Error Handling
+
+### Size Limit Exceeded
+
+```typescript
+// Request with body larger than sizeLimit
+// Response: 413 Payload Too Large
+{
+  "error": "ERR_REQUEST_BODY_TOO_LARGE"
+}
+
+// With custom error message
+{
+  "error": "Request body too large"
+}
+```
+
+### Invalid JSON
+
+```typescript
+// Request with malformed JSON
+// POST /api/users
+// Content-Type: application/json
+// Body: { "name": "John", "email": "john@example.com" }
+
+// Response: 400 Bad Request
+{
+  "error": "Invalid JSON syntax"
+}
+```
+
+### Invalid Encoding
+
+```typescript
+// Request with unsupported encoding
+// Response: 400 Bad Request
+{
+  "error": "Invalid request body encoding"
+}
+```
+
+## Content-Type Detection
+
+The JSON plugin automatically detects and parses requests with the following content types:
+
+- `application/json`
+- `application/json; charset=utf-8`
+- `application/json; charset=UTF-8`
+
+### Non-JSON Requests
+
+Requests without `application/json` content type are ignored:
+
+```typescript
+// This request will NOT be parsed by the JSON plugin
+// POST /api/users
+// Content-Type: application/x-www-form-urlencoded
+// Body: name=John&email=john@example.com
+
+@post('/users')
+async createUser(req: Request, res: Response) {
+  // req.body will be undefined or handled by another parser
+  console.log(req.body); // undefined
+}
+```
+
+## HTTP Method Restrictions
+
+The JSON plugin only parses bodies for methods that can have a body:
+
+- **Parsed**: POST, PUT, PATCH
+- **Ignored**: GET, DELETE, HEAD, OPTIONS
+
+```typescript
+@controller('/api')
+export class UsersController {
+  @get('/users')
+  async getUsers(req: Request, res: Response) {
+    // req.body will be undefined (GET request)
+    res.json({ users: [] });
+  }
+
+  @post('/users')
+  async createUser(req: Request, res: Response) {
+    // req.body will be parsed JSON
+    res.created(req.body);
+  }
+}
+```
+
+## Advanced Configuration
+
+### Production vs Development
+
+```typescript
+const isProduction = process.env.NODE_ENV === 'production';
+
+const server = new Server({
+  port: 3000,
+  plugins: {
+    json: {
+      sizeLimit: isProduction ? '1mb' : '10mb',
+      parseEmptyBodyAsObject: false,
+      encoding: 'utf-8',
+      customErrorMessage: isProduction ? {
+        status: 413,
+        message: 'Request too large'
+      } : undefined
+    }
+  }
+});
+```
+
+### Multiple Content Types
+
+```typescript
+// JSON plugin handles application/json
+// URL-encoded plugin handles application/x-www-form-urlencoded
+const server = new Server({
+  port: 3000,
+  plugins: {
+    json: {
+      sizeLimit: '10mb'
+    },
+    urlencoded: {
+      extended: true
+    }
+  }
+});
+```
+
+## Performance Considerations
+
+### Memory Usage
+
+```typescript
+// Be careful with large size limits
+json: {
+  sizeLimit: '100mb' // Could cause memory issues
+}
+
+// Recommended for most applications
+json: {
+  sizeLimit: '10mb' // Reasonable limit
+}
+```
+
+### Streaming for Large Files
+
+For very large files, consider using the file upload plugin instead:
+
+```typescript
+// For large files, use file upload plugin
+plugins: {
+  file: {
+    maxFileSize: 50 * 1024 * 1024 // 50MB
+  }
+}
+```