servcraft 0.1.0 → 0.1.3

package/docs/modules/SECURITY.md

@@ -0,0 +1,327 @@
+# Security Module
+
+Comprehensive security features for protecting your application against common web vulnerabilities.
+
+## Features
+
+- **Input Sanitization** - XSS prevention with HTML escaping and script stripping
+- **CSRF Protection** - Token-based Cross-Site Request Forgery protection
+- **Security Headers** - Essential HTTP security headers
+- **HPP Protection** - HTTP Parameter Pollution prevention
+- **Suspicious Activity Detection** - Pattern-based attack detection
+- **Security Audit Logging** - Comprehensive security event tracking
+
+## Installation
+
+The security module is included in ServCraft by default.
+
+```typescript
+import {
+  registerSecurityMiddlewares,
+  sanitizeString,
+  sanitizeObject,
+  getSecurityAuditService,
+} from 'servcraft/modules/security';
+```
+
+## Quick Start
+
+### Register All Security Middlewares
+
+```typescript
+import Fastify from 'fastify';
+import { registerSecurityMiddlewares } from 'servcraft/modules/security';
+
+const app = Fastify();
+
+await registerSecurityMiddlewares(app, {
+  sanitize: true,           // Input sanitization
+  csrf: false,              // CSRF (disabled for API-first apps)
+  hpp: true,                // HTTP Parameter Pollution protection
+  headers: true,            // Security headers
+  sizeLimit: 10 * 1024 * 1024,  // 10MB request size limit
+  suspicionDetection: true, // Suspicious activity detection
+});
+```
+
+## Input Sanitization
+
+### Basic String Sanitization
+
+```typescript
+import { sanitizeString, escapeHtml, stripDangerousHtml } from 'servcraft/modules/security';
+
+// Escape HTML entities
+const safe = escapeHtml('<script>alert("xss")</script>');
+// Result: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+
+// Strip dangerous HTML
+const stripped = stripDangerousHtml('<div onclick="evil()">Safe text</div>');
+// Result: '<div>Safe text</div>'
+
+// Full sanitization
+const sanitized = sanitizeString(userInput, {
+  escapeHtmlChars: true,  // Escape HTML entities
+  stripScripts: true,     // Remove script tags and event handlers
+  trim: true,             // Trim whitespace
+  maxLength: 1000,        // Limit string length
+});
+```
+
+### Object Sanitization
+
+```typescript
+import { sanitizeObject } from 'servcraft/modules/security';
+
+const userInput = {
+  name: '<script>alert("xss")</script>',
+  email: 'user@example.com',
+  bio: 'Hello <img onerror="evil()" src="x">',
+};
+
+const safe = sanitizeObject(userInput, {
+  escapeHtmlChars: true,
+  stripScripts: true,
+});
+// All string values are sanitized recursively
+// Prototype pollution keys (__proto__, constructor) are removed
+```
+
+### URL Sanitization
+
+```typescript
+import { sanitizeUrl } from 'servcraft/modules/security';
+
+sanitizeUrl('https://example.com');     // Returns: 'https://example.com'
+sanitizeUrl('javascript:alert(1)');     // Returns: ''
+sanitizeUrl('data:text/html,...');      // Returns: ''
+```
+
+### Filename Sanitization
+
+```typescript
+import { sanitizeFilename } from 'servcraft/modules/security';
+
+sanitizeFilename('../../../etc/passwd');  // Returns: '______etc_passwd'
+sanitizeFilename('my file (1).pdf');      // Returns: 'my_file__1_.pdf'
+```
+
+## CSRF Protection
+
+### Setup
+
+```typescript
+import { csrfProtection, generateCsrfToken } from 'servcraft/modules/security';
+
+// Generate token for a session
+app.get('/csrf-token', async (request, reply) => {
+  const sessionId = request.headers['x-session-id'] || request.ip;
+  const token = generateCsrfToken(sessionId);
+  return { csrfToken: token };
+});
+
+// Protect routes (skip for API with JWT)
+app.addHook('preHandler', csrfProtection());
+```
+
+### Client Usage
+
+```javascript
+// Get CSRF token
+const { csrfToken } = await fetch('/csrf-token').then(r => r.json());
+
+// Include in subsequent requests
+fetch('/api/action', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-CSRF-Token': csrfToken,
+  },
+  body: JSON.stringify(data),
+});
+```
+
+## Security Headers
+
+The following headers are automatically added:
+
+| Header | Value | Purpose |
+|--------|-------|---------|
+| `X-Content-Type-Options` | `nosniff` | Prevent MIME sniffing |
+| `X-Frame-Options` | `DENY` | Prevent clickjacking |
+| `X-XSS-Protection` | `1; mode=block` | XSS filter |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` | Control referrer info |
+| `Permissions-Policy` | `camera=(), microphone=()...` | Disable dangerous features |
+| `Cache-Control` | `no-store` | Prevent caching sensitive data |
+
+## HTTP Parameter Pollution Protection
+
+```typescript
+import { hppProtection } from 'servcraft/modules/security';
+
+// Prevent array injection
+// ?user=admin&user=hacker → user=hacker (takes last value)
+app.addHook('preHandler', hppProtection());
+
+// Allow specific parameters to be arrays
+app.addHook('preHandler', hppProtection(['tags', 'categories']));
+// ?tags=a&tags=b → tags=['a', 'b'] (allowed)
+```
+
+## Suspicious Activity Detection
+
+```typescript
+import { suspiciousActivityDetection } from 'servcraft/modules/security';
+
+// Log suspicious patterns (default)
+app.addHook('preHandler', suspiciousActivityDetection());
+
+// Block suspicious requests
+app.addHook('preHandler', suspiciousActivityDetection({
+  blockSuspicious: true,
+}));
+```
+
+### Detected Patterns
+
+- Path traversal: `../`
+- Script injection: `<script`
+- SQL injection: `UNION SELECT`, `DROP TABLE`
+- Template injection: `${}`, `{{}}`
+- Code execution: `exec()`, `eval()`
+
+## Security Audit Service
+
+### Logging Security Events
+
+```typescript
+import { getSecurityAuditService } from 'servcraft/modules/security';
+
+const audit = getSecurityAuditService();
+
+// Log login success
+await audit.logLoginSuccess(userId, request);
+
+// Log login failure
+await audit.logLoginFailed(email, 'Invalid password', request);
+
+// Log suspicious activity
+await audit.logSuspiciousActivity('Multiple failed login attempts', request, {
+  attempts: 5,
+  targetEmail: 'user@example.com',
+});
+
+// Log rate limit exceeded
+await audit.logRateLimitExceeded(request, 100);
+
+// Log brute force detection
+await audit.logBruteForceDetected(request, 10, '/api/login');
+
+// Log access denied
+await audit.logAccessDenied(userId, 'admin-panel', 'view', request);
+
+// Log admin action
+await audit.logAdminAction(adminId, 'delete_user', 'users', {
+  targetUserId: deletedUserId,
+}, request);
+```
+
+### Custom Event Logging
+
+```typescript
+await audit.log({
+  type: 'auth.mfa.enabled',
+  userId: user.id,
+  request,
+  details: { method: 'totp' },
+  success: true,
+});
+```
+
+### Event Types
+
+| Type | Severity | Description |
+|------|----------|-------------|
+| `auth.login.success` | low | Successful login |
+| `auth.login.failed` | medium | Failed login attempt |
+| `auth.mfa.enabled` | medium | MFA enabled |
+| `auth.mfa.disabled` | high | MFA disabled |
+| `suspicious.activity` | high | Suspicious pattern detected |
+| `csrf.violation` | high | CSRF token mismatch |
+| `xss.attempt` | critical | XSS attack detected |
+| `sqli.attempt` | critical | SQL injection detected |
+| `brute.force.detected` | high | Brute force attack |
+| `rate.limit.exceeded` | medium | Rate limit hit |
+| `data.deletion` | critical | Data deletion |
+| `admin.action` | high | Admin action performed |
+
+### Retrieving Security Data
+
+```typescript
+const audit = getSecurityAuditService();
+
+// Get recent high/critical alerts
+const alerts = await audit.getRecentAlerts(50);
+
+// Get security events for a user
+const userEvents = await audit.getUserEvents(userId, 100);
+
+// Get security statistics
+const stats = await audit.getStats(24); // Last 24 hours
+// {
+//   totalEvents: 1250,
+//   failedLogins: 45,
+//   suspiciousActivities: 12,
+//   rateLimitExceeded: 230,
+//   criticalAlerts: 3,
+// }
+```
+
+## Storage
+
+Security audit events are stored in:
+
+1. **Redis** (real-time, 24h TTL) - For monitoring dashboards
+2. **PostgreSQL** (long-term) - For compliance and audit trails
+
+### Redis Keys
+
+| Key Pattern | TTL | Purpose |
+|-------------|-----|---------|
+| `security:audit:{id}` | 24h | Individual events |
+| `security:alerts:recent` | - | Recent high/critical alerts list |
+
+## Best Practices
+
+1. **Always sanitize user input** before storing or displaying
+2. **Enable CSRF protection** for browser-based apps
+3. **Monitor security events** regularly
+4. **Set up alerts** for critical severity events
+5. **Review audit logs** for compliance requirements
+6. **Use rate limiting** in conjunction with brute force detection
+
+## Integration with Other Modules
+
+```typescript
+// With Rate Limiting
+import { createRateLimiter } from 'servcraft/modules/rate-limit';
+
+const loginLimiter = createRateLimiter({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 5,
+  onLimitReached: async (request) => {
+    await audit.logBruteForceDetected(request, 5, '/api/login');
+  },
+});
+
+// With Auth Module
+import { authService } from 'servcraft/modules/auth';
+
+authService.on('login:success', async (user, request) => {
+  await audit.logLoginSuccess(user.id, request);
+});
+
+authService.on('login:failed', async (email, reason, request) => {
+  await audit.logLoginFailed(email, reason, request);
+});
+```

package/docs/modules/SESSION.md

@@ -0,0 +1,382 @@
+# Session Module
+
+Server-side session management with Redis storage and optional PostgreSQL persistence.
+
+## Features
+
+- **Redis-based Storage** - Fast session access with configurable TTL
+- **Sliding Expiration** - Extend session on activity
+- **Multi-device Support** - List and manage user sessions across devices
+- **Optional Persistence** - PostgreSQL backup for audit trails
+- **Session Metadata** - Store device info, IP, user agent
+
+## Installation
+
+```typescript
+import {
+  SessionService,
+  createSessionService,
+  getSessionService,
+} from 'servcraft/modules/session';
+```
+
+## Quick Start
+
+```typescript
+import { getSessionService } from 'servcraft/modules/session';
+
+const sessionService = getSessionService();
+
+// Create a session
+const session = await sessionService.create({
+  userId: 'user-123',
+  metadata: {
+    device: 'Chrome on Windows',
+    ip: request.ip,
+    userAgent: request.headers['user-agent'],
+  },
+});
+
+// Get session
+const currentSession = await sessionService.get(session.id);
+
+// Extend session (sliding expiration)
+await sessionService.touch(session.id);
+
+// Destroy session
+await sessionService.destroy(session.id);
+```
+
+## Configuration
+
+```typescript
+import { createSessionService } from 'servcraft/modules/session';
+
+const sessionService = createSessionService({
+  // Session TTL in seconds (default: 24 hours)
+  ttl: 86400,
+
+  // Enable sliding expiration (default: true)
+  slidingExpiration: true,
+
+  // Redis key prefix (default: 'session:')
+  prefix: 'session:',
+
+  // Enable PostgreSQL persistence (default: false)
+  persistToDatabase: true,
+});
+```
+
+## API Reference
+
+### Create Session
+
+```typescript
+const session = await sessionService.create({
+  userId: 'user-123',
+  metadata: {
+    device: 'Mobile Safari on iOS',
+    ip: '192.168.1.1',
+    userAgent: 'Mozilla/5.0...',
+    location: 'Paris, France',
+  },
+});
+
+// Returns:
+// {
+//   id: 'sess_abc123...',
+//   userId: 'user-123',
+//   metadata: { ... },
+//   createdAt: Date,
+//   expiresAt: Date,
+//   lastAccessedAt: Date,
+// }
+```
+
+### Get Session
+
+```typescript
+const session = await sessionService.get('sess_abc123');
+
+if (!session) {
+  // Session expired or doesn't exist
+  throw new Error('Invalid session');
+}
+```
+
+### Touch Session (Extend TTL)
+
+```typescript
+// Extend session TTL on user activity
+const extended = await sessionService.touch('sess_abc123');
+
+if (extended) {
+  // Session TTL was reset
+}
+```
+
+### Destroy Session
+
+```typescript
+// Single session (logout)
+await sessionService.destroy('sess_abc123');
+
+// All user sessions (logout everywhere)
+await sessionService.destroyUserSessions('user-123');
+```
+
+### List User Sessions
+
+```typescript
+const sessions = await sessionService.getUserSessions('user-123');
+
+// Returns array of active sessions:
+// [
+//   { id: 'sess_abc', device: 'Chrome', lastAccessedAt: Date, current: true },
+//   { id: 'sess_xyz', device: 'Mobile', lastAccessedAt: Date, current: false },
+// ]
+```
+
+### Session Statistics
+
+```typescript
+const stats = await sessionService.getStats();
+// {
+//   totalSessions: 1523,
+//   activeSessions: 342,
+//   expiredSessions: 1181,
+// }
+```
+
+## Middleware Integration
+
+### Fastify Session Middleware
+
+```typescript
+import { getSessionService } from 'servcraft/modules/session';
+
+const sessionService = getSessionService();
+
+// Session validation middleware
+app.addHook('preHandler', async (request, reply) => {
+  const sessionId = request.cookies.sessionId;
+
+  if (!sessionId) {
+    return reply.status(401).send({ error: 'No session' });
+  }
+
+  const session = await sessionService.get(sessionId);
+
+  if (!session) {
+    return reply.status(401).send({ error: 'Invalid session' });
+  }
+
+  // Extend session on activity
+  await sessionService.touch(sessionId);
+
+  // Attach to request
+  request.session = session;
+  request.userId = session.userId;
+});
+```
+
+### Login Handler
+
+```typescript
+app.post('/login', async (request, reply) => {
+  const { email, password } = request.body;
+
+  // Validate credentials
+  const user = await authService.validateCredentials(email, password);
+
+  if (!user) {
+    return reply.status(401).send({ error: 'Invalid credentials' });
+  }
+
+  // Create session
+  const session = await sessionService.create({
+    userId: user.id,
+    metadata: {
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+      loginMethod: 'password',
+    },
+  });
+
+  // Set session cookie
+  reply.setCookie('sessionId', session.id, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'strict',
+    maxAge: 86400, // 24 hours
+  });
+
+  return { user, sessionId: session.id };
+});
+```
+
+### Logout Handler
+
+```typescript
+// Logout current session
+app.post('/logout', async (request, reply) => {
+  const sessionId = request.cookies.sessionId;
+
+  if (sessionId) {
+    await sessionService.destroy(sessionId);
+  }
+
+  reply.clearCookie('sessionId');
+  return { success: true };
+});
+
+// Logout all sessions
+app.post('/logout-all', async (request, reply) => {
+  await sessionService.destroyUserSessions(request.userId);
+
+  reply.clearCookie('sessionId');
+  return { success: true };
+});
+```
+
+## Session Management UI
+
+### List Active Sessions
+
+```typescript
+app.get('/sessions', async (request, reply) => {
+  const sessions = await sessionService.getUserSessions(request.userId);
+
+  return sessions.map(session => ({
+    id: session.id,
+    device: session.metadata?.device || 'Unknown',
+    ip: session.metadata?.ip,
+    location: session.metadata?.location,
+    lastActive: session.lastAccessedAt,
+    current: session.id === request.cookies.sessionId,
+  }));
+});
+```
+
+### Revoke Specific Session
+
+```typescript
+app.delete('/sessions/:sessionId', async (request, reply) => {
+  const { sessionId } = request.params;
+
+  // Verify session belongs to user
+  const session = await sessionService.get(sessionId);
+
+  if (!session || session.userId !== request.userId) {
+    return reply.status(404).send({ error: 'Session not found' });
+  }
+
+  await sessionService.destroy(sessionId);
+  return { success: true };
+});
+```
+
+## Storage Architecture
+
+### Redis (Primary)
+
+Sessions are stored in Redis for fast access:
+
+```
+session:{sessionId} -> {
+  id: string,
+  userId: string,
+  metadata: object,
+  createdAt: timestamp,
+  expiresAt: timestamp,
+  lastAccessedAt: timestamp,
+}
+```
+
+TTL is managed automatically. Sessions expire and are removed by Redis.
+
+### PostgreSQL (Optional)
+
+When `persistToDatabase: true`, sessions are also stored in PostgreSQL:
+
+```sql
+CREATE TABLE sessions (
+  id VARCHAR(255) PRIMARY KEY,
+  user_id VARCHAR(255) NOT NULL,
+  metadata JSONB,
+  created_at TIMESTAMP DEFAULT NOW(),
+  expires_at TIMESTAMP NOT NULL,
+  last_accessed_at TIMESTAMP,
+  FOREIGN KEY (user_id) REFERENCES users(id)
+);
+```
+
+This provides:
+- Audit trail of all sessions
+- Survival across Redis restarts
+- Analytics on session patterns
+
+## Security Considerations
+
+1. **Use secure cookies** - `httpOnly`, `secure`, `sameSite`
+2. **Rotate session IDs** after sensitive operations
+3. **Limit concurrent sessions** per user if needed
+4. **Log session events** for security auditing
+5. **Implement idle timeout** in addition to absolute timeout
+
+### Session Rotation
+
+```typescript
+app.post('/change-password', async (request, reply) => {
+  // Change password logic...
+
+  // Destroy all other sessions
+  const currentSessionId = request.cookies.sessionId;
+  const sessions = await sessionService.getUserSessions(request.userId);
+
+  for (const session of sessions) {
+    if (session.id !== currentSessionId) {
+      await sessionService.destroy(session.id);
+    }
+  }
+
+  return { success: true };
+});
+```
+
+## Integration with Auth Module
+
+```typescript
+import { authService } from 'servcraft/modules/auth';
+import { getSessionService } from 'servcraft/modules/session';
+
+const sessionService = getSessionService();
+
+// On successful login
+authService.on('login:success', async (user, request) => {
+  const session = await sessionService.create({
+    userId: user.id,
+    metadata: {
+      ip: request.ip,
+      userAgent: request.headers['user-agent'],
+    },
+  });
+  return session;
+});
+
+// On logout
+authService.on('logout', async (sessionId) => {
+  await sessionService.destroy(sessionId);
+});
+
+// On password change
+authService.on('password:changed', async (userId, currentSessionId) => {
+  // Destroy all other sessions
+  const sessions = await sessionService.getUserSessions(userId);
+  for (const session of sessions) {
+    if (session.id !== currentSessionId) {
+      await sessionService.destroy(session.id);
+    }
+  }
+});
+```