@engjts/nexus 0.1.0

package/src/security/rate-limit/middleware.ts

@@ -0,0 +1,181 @@
+/**
+ * Rate Limiting Middleware
+ * 
+ * Adaptive rate limiting with various strategies
+ */
+
+import type { Context, Next, Middleware } from '../../core/types';
+import type { RateLimitConfig, RateLimitInfo } from '../types';
+import type { RateLimitAdapter } from '../adapter';
+import { MemoryRateLimiter } from './memory';
+
+/**
+ * Parse time window string to milliseconds
+ */
+function parseWindow(window: number | string): number {
+    if (typeof window === 'number') {
+        return window;
+    }
+
+    const match = window.match(/^(\d+)([smhd])$/);
+    if (!match) {
+        throw new Error('Invalid window format');
+    }
+
+    const value = parseInt(match[1]);
+    const unit = match[2];
+
+    const multipliers: Record<string, number> = {
+        s: 1000,
+        m: 60000,
+        h: 3600000,
+        d: 86400000
+    };
+
+    return value * multipliers[unit];
+}
+
+/**
+ * Default key generator - uses IP address
+ */
+function defaultKeyGenerator(ctx: Context): string {
+    // Try to get real IP from headers
+    const forwardedRaw = ctx.headers['x-forwarded-for'] || ctx.headers['X-Forwarded-For'];
+    if (forwardedRaw) {
+        const forwarded = Array.isArray(forwardedRaw) ? forwardedRaw[0] : forwardedRaw;
+        if (forwarded) {
+            return forwarded.split(',')[0].trim();
+        }
+    }
+
+    const realIpRaw = ctx.headers['x-real-ip'] || ctx.headers['X-Real-IP'];
+    if (realIpRaw) {
+        const realIp = Array.isArray(realIpRaw) ? realIpRaw[0] : realIpRaw;
+        if (realIp) {
+            return realIp;
+        }
+    }
+
+    // Fallback to generic key
+    return 'unknown';
+}
+
+/**
+ * Create rate limiting middleware
+ * 
+ * @example
+ * ```ts
+ * app.use(rateLimit({
+ *   window: '15m',
+ *   max: 100,
+ *   routes: {
+ *     'POST /api/login': { max: 5, window: '5m' }
+ *   }
+ * }));
+ * ```
+ */
+export function rateLimit(
+    config: RateLimitConfig,
+    adapter?: RateLimitAdapter
+): Middleware {
+    const store = adapter || new MemoryRateLimiter();
+    const keyGenerator = config.keyGenerator || defaultKeyGenerator;
+    const message = config.message || 'Too many requests';
+    const statusCode = config.statusCode || 429;
+
+    return async (ctx: Context, next: Next, _deps: any) => {
+        // Generate rate limit key
+        const baseKey = keyGenerator(ctx);
+
+        // Check for route-specific limits
+        let routeConfig = config;
+        if (config.routes) {
+            const routeKey = `${ctx.method} ${ctx.path}`;
+
+            // Try exact match
+            if (config.routes[routeKey]) {
+                routeConfig = {
+                    ...config,
+                    ...config.routes[routeKey]
+                };
+            } else {
+                // Try wildcard match
+                for (const [pattern, limits] of Object.entries(config.routes)) {
+                    const regex = new RegExp('^' + pattern.replace('*', '.*') + '$');
+                    if (regex.test(routeKey)) {
+                        routeConfig = {
+                            ...config,
+                            ...limits
+                        };
+                        break;
+                    }
+                }
+            }
+        }
+
+        const finalWindowMs = parseWindow(routeConfig.window);
+        const finalMax = routeConfig.max;
+        const key = `ratelimit:${baseKey}:${ctx.path}`;
+
+        // Increment counter
+        const { count, resetTime } = await store.increment(key, finalWindowMs);
+
+        // Attach rate limit info to context
+        const rateLimitInfo: RateLimitInfo = {
+            limit: finalMax,
+            remaining: Math.max(0, finalMax - count),
+            reset: Math.floor(resetTime / 1000),
+            retryAfter: count > finalMax ? Math.ceil((resetTime - Date.now()) / 1000) : undefined
+        };
+
+        (ctx as any).rateLimit = rateLimitInfo;
+
+        // Check if limit exceeded
+        if (count > finalMax) {
+            return {
+                statusCode,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-RateLimit-Limit': finalMax.toString(),
+                    'X-RateLimit-Remaining': '0',
+                    'X-RateLimit-Reset': rateLimitInfo.reset.toString(),
+                    'Retry-After': rateLimitInfo.retryAfter?.toString() || '60'
+                },
+                body: JSON.stringify({
+                    error: message,
+                    retryAfter: rateLimitInfo.retryAfter
+                })
+            };
+        }
+
+        // Add rate limit headers
+        const response = await next(ctx);
+
+        response.headers['X-RateLimit-Limit'] = finalMax.toString();
+        response.headers['X-RateLimit-Remaining'] = rateLimitInfo.remaining.toString();
+        response.headers['X-RateLimit-Reset'] = rateLimitInfo.reset.toString();
+
+        return response;
+    };
+}
+
+/**
+ * Strict rate limiting for sensitive endpoints
+ */
+export function strictRateLimit(max: number = 5, window: string | number = '5m'): Middleware {
+    return rateLimit({
+        window,
+        max,
+        message: 'Too many attempts, please try again later'
+    });
+}
+
+/**
+ * Lenient rate limiting for public endpoints
+ */
+export function lenientRateLimit(max: number = 1000, window: string | number = '15m'): Middleware {
+    return rateLimit({
+        window,
+        max
+    });
+}

package/src/security/sanitization.ts

@@ -0,0 +1,75 @@
+/**
+ * Input Sanitization Middleware
+ * 
+ * Automatically sanitizes request inputs to prevent common attacks
+ */
+
+import type { Context, Next, Middleware } from '../core/types';
+import type { SanitizationConfig } from './types';
+import type { SanitizationAdapter } from './adapter';
+import { DefaultSanitizationAdapter } from './adapter';
+
+/**
+ * Create input sanitization middleware
+ * 
+ * @example
+ * ```ts
+ * app.use(sanitizeInput({
+ *   fields: ['body', 'query', 'params'],
+ *   strict: false
+ * }));
+ * ```
+ */
+export function sanitizeInput(
+    config: SanitizationConfig = {},
+    adapter?: SanitizationAdapter
+): Middleware {
+    const adapterInstance = adapter || new DefaultSanitizationAdapter();
+    const fields = config.fields || ['body', 'query', 'params'];
+    const enabled = config.enabled !== false;
+
+    return async (ctx: Context, next: Next) => {
+        if (!enabled) {
+            return next(ctx);
+        }
+
+        // Sanitize specified fields
+        for (const field of fields) {
+            if (field in ctx && ctx[field]) {
+                try {
+                    (ctx as any)[field] = adapterInstance.sanitize(
+                        ctx[field],
+                        config
+                    );
+                } catch (error) {
+                    // In strict mode, adapter throws on malicious input
+                    throw new Error(`Malicious input detected in ${field}`);
+                }
+            }
+        }
+
+        return next(ctx);
+    };
+}
+
+/**
+ * Strict sanitization - throws on malicious input
+ */
+export function strictSanitization(customConfig: Partial<SanitizationConfig> = {}): Middleware {
+    return sanitizeInput({
+        fields: ['body', 'query', 'params'],
+        strict: true,
+        ...customConfig
+    });
+}
+
+/**
+ * Lenient sanitization - silently removes malicious content
+ */
+export function lenientSanitization(customConfig: Partial<SanitizationConfig> = {}): Middleware {
+    return sanitizeInput({
+        fields: ['body', 'query', 'params'],
+        strict: false,
+        ...customConfig
+    });
+}

package/src/security/types.ts

@@ -0,0 +1,240 @@
+/**
+ * Security Layer Type Definitions
+ * 
+ * Core types for security features including auth, RBAC, rate limiting
+ */
+
+import type { Context } from '../core/types';
+
+/**
+ * User type for authenticated contexts
+ */
+export interface User {
+    id: string | number;
+    email?: string;
+    username?: string;
+    roles?: string[];
+    permissions?: string[];
+    [key: string]: any;
+}
+
+/**
+ * Context with authenticated user
+ */
+export interface AuthContext extends Context {
+    user: User;
+}
+
+/**
+ * Security headers configuration
+ */
+export interface SecurityHeadersConfig {
+    /** Preset mode: 'strict' | 'moderate' | 'loose' */
+    mode?: 'strict' | 'moderate' | 'loose';
+
+    /** Custom headers to add/override */
+    customHeaders?: Record<string, string>;
+
+    /** Content Security Policy configuration */
+    csp?: {
+        directives?: Record<string, string[]>;
+        reportUri?: string;
+        reportOnly?: boolean;
+    };
+
+    /** Enable auto-nonce generation for CSP */
+    autoNonce?: boolean;
+}
+
+/**
+ * Sanitization pattern configuration
+ */
+export interface SanitizationPattern {
+    name: string;
+    pattern: RegExp;
+    replacement?: string;
+}
+
+/**
+ * Input sanitization configuration
+ */
+export interface SanitizationConfig {
+    /** Enable auto-sanitization */
+    enabled?: boolean;
+
+    /** Custom patterns to detect */
+    patterns?: SanitizationPattern[];
+
+    /** Fields to sanitize (body, query, params) */
+    fields?: ('body' | 'query' | 'params')[];
+
+    /** Throw error on detection vs silent sanitization */
+    strict?: boolean;
+}
+
+/**
+ * JWT authentication configuration
+ */
+export interface JWTConfig {
+    /** Secret key for signing */
+    secret: string;
+
+    /** Algorithm (default: HS256) */
+    algorithm?: 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512';
+
+    /** Token expiration */
+    expiresIn?: string | number;
+
+    /** Refresh token configuration */
+    refresh?: {
+        enabled: boolean;
+        expiresIn?: string | number;
+        rotateSecret?: boolean;
+    };
+
+    /** Token extraction strategy */
+    getToken?: (ctx: Context) => string | null;
+}
+
+/**
+ * OAuth configuration (placeholder for future implementation)
+ */
+export interface OAuthConfig {
+    provider: 'google' | 'github' | 'facebook' | string;
+    clientId: string;
+    clientSecret: string;
+    callbackUrl: string;
+    scope?: string[];
+}
+
+/**
+ * Session configuration (placeholder for future implementation)
+ */
+export interface SessionConfig {
+    store: 'memory' | 'redis' | string;
+    secret: string;
+    cookie?: {
+        secure?: boolean;
+        httpOnly?: boolean;
+        sameSite?: 'strict' | 'lax' | 'none';
+        maxAge?: number;
+    };
+}
+
+/**
+ * Authentication strategies
+ */
+export interface AuthStrategies {
+    jwt?: JWTConfig;
+    oauth?: OAuthConfig;
+    session?: SessionConfig;
+}
+
+/**
+ * Role definition for RBAC
+ */
+export interface RoleDefinition {
+    name: string;
+    permissions: string[];
+    inherits?: string[];
+}
+
+/**
+ * Permission check result
+ */
+export interface PermissionCheckResult {
+    allowed: boolean;
+    missing?: string[];
+}
+
+/**
+ * Rate limit configuration
+ */
+export interface RateLimitConfig {
+    /** Time window in milliseconds or string format (e.g., '15m', '1h') */
+    window: number | string;
+
+    /** Maximum requests per window */
+    max: number;
+
+    /** Storage backend */
+    store?: 'memory' | 'redis' | string;
+
+    /** Key generator function */
+    keyGenerator?: (ctx: Context) => string;
+
+    /** Per-route limits */
+    routes?: Record<string, { max: number; window: number | string }>;
+
+    /** Suspicious behavior detection */
+    suspicious?: {
+        failedLogins?: {
+            max: number;
+            window: number | string;
+            action: 'captcha' | 'block' | 'throttle';
+        };
+        rapidRequests?: {
+            threshold: number;
+            window: number | string;
+            action: 'throttle' | 'block';
+        };
+    };
+
+    /** Message to send when rate limited */
+    message?: string;
+
+    /** Status code to send when rate limited */
+    statusCode?: number;
+}
+
+/**
+ * Rate limit info attached to context
+ */
+export interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    reset: number; // timestamp
+    retryAfter?: number; // seconds
+}
+
+/**
+ * CSRF protection configuration
+ */
+export interface CSRFConfig {
+    /** Enable automatic token generation and validation */
+    auto?: boolean;
+
+    /** Cookie configuration */
+    cookie?: {
+        name?: string;
+        sameSite?: 'strict' | 'lax' | 'none';
+        secure?: boolean;
+        httpOnly?: boolean;
+    };
+
+    /** Token field name in body */
+    tokenField?: string;
+
+    /** Header field name */
+    headerField?: string;
+
+    /** Methods to exclude from CSRF check */
+    excludeMethods?: string[];
+
+    /** Routes to exclude from CSRF check */
+    excludeRoutes?: string[];
+
+    /** Token length */
+    tokenLength?: number;
+}
+
+/**
+ * Security event for logging/monitoring
+ */
+export interface SecurityEvent {
+    type: 'auth_failed' | 'rate_limit' | 'csrf_failed' | 'xss_detected' | 'sql_injection_detected';
+    timestamp: number;
+    ip: string;
+    path: string;
+    details?: any;
+}

package/src/security/utils.ts

@@ -0,0 +1,52 @@
+/**
+ * Security Utility Helpers
+ * 
+ * Helper functions for working with security features
+ */
+
+import type { Context } from '../core/types';
+
+/**
+ * Get header value as string (handles string | string[] | undefined)
+ */
+export function getHeader(ctx: Context, name: string): string | null {
+    const value = ctx.headers[name.toLowerCase()];
+
+    if (!value) {
+        return null;
+    }
+
+    if (Array.isArray(value)) {
+        return value[0] || null;
+    }
+
+    return value;
+}
+
+/**
+ * Get all header values as array
+ */
+export function getHeaderValues(ctx: Context, name: string): string[] {
+    const value = ctx.headers[name.toLowerCase()];
+
+    if (!value) {
+        return [];
+    }
+
+    if (Array.isArray(value)) {
+        return value;
+    }
+
+    return [value];
+}
+
+/**
+ * Set response header safely
+ */
+export function setResponseHeader(
+    headers: Record<string, string>,
+    name: string,
+    value: string
+): void {
+    headers[name] = value;
+}

package/tsconfig.json

@@ -0,0 +1,39 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "commonjs",
+        "lib": [
+            "ES2022"
+        ],
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "strict": false,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "moduleResolution": "node",
+        "resolveJsonModule": true,
+        "allowSyntheticDefaultImports": true,
+        "noUnusedLocals": false,
+        "noUnusedParameters": false,
+        "noImplicitReturns": false,
+        "noFallthroughCasesInSwitch": true,
+        "strictNullChecks": false,
+        "strictFunctionTypes": false,
+        "strictBindCallApply": false,
+        "strictPropertyInitialization": false,
+        "noImplicitThis": false,
+        "alwaysStrict": false
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist",
+        "**/*.test.ts"
+    ]
+}