balda-js 0.0.1 → 0.0.3

package/docs/docs/plugins/helmet.md

@@ -1,388 +0,0 @@
----
-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

@@ -1,338 +0,0 @@
----
-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
-  }
-}
-```