@engjts/nexus 0.1.0

package/src/security/auth/middleware.ts

@@ -0,0 +1,188 @@
+/**
+ * Authentication Middleware
+ * 
+ * Provides authentication and authorization middleware
+ */
+
+import type { Context, Next, Middleware } from '../../core/types';
+import type { User, AuthContext, AuthStrategies } from '../types';
+import type { AuthAdapter, PermissionAdapter } from '../adapter';
+import { DefaultPermissionAdapter } from '../adapter';
+import { JWTAuthAdapter } from './jwt';
+
+/**
+ * Authentication middleware factory
+ * 
+ * @example
+ * ```ts
+ * // JWT authentication
+ * app.use(authenticate({
+ *   jwt: {
+ *     secret: process.env.JWT_SECRET,
+ *     expiresIn: '15m'
+ *   }
+ * }));
+ * 
+ * // Optional authentication
+ * app.use(authenticate({ jwt: config }, { required: false }));
+ * ```
+ */
+export function authenticate(
+    strategies: AuthStrategies,
+    options: {
+        required?: boolean;
+        strategies?: ('jwt' | 'oauth' | 'session')[];
+    } = {}
+): Middleware<Context, AuthContext> {
+    const adapters = new Map<string, AuthAdapter>();
+    const required = options.required !== false;
+    const strategyOrder = options.strategies || ['jwt', 'oauth', 'session'];
+
+    // Initialize adapters
+    if (strategies.jwt) {
+        adapters.set('jwt', new JWTAuthAdapter());
+    }
+    // OAuth and Session will be added in future
+    // if (strategies.oauth) adapters.set('oauth', new OAuthAdapter());
+    // if (strategies.session) adapters.set('session', new SessionAdapter());
+
+    return (async (ctx: Context, next: Next, _deps: any) => {
+        let user: User | null = null;
+
+        // Try each strategy in order
+        for (const strategyName of strategyOrder) {
+            const adapter = adapters.get(strategyName);
+            const config = (strategies as any)[strategyName];
+
+            if (adapter && config) {
+                try {
+                    user = await adapter.verify(ctx, config);
+                    if (user) {
+                        break;
+                    }
+                } catch (error) {
+                    // Try next strategy
+                    continue;
+                }
+            }
+        }
+
+        // If no user found and auth is required
+        if (!user && required) {
+            return {
+                statusCode: 401,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ error: 'Unauthorized' })
+            };
+        }
+
+        // Attach user to context
+        (ctx as unknown as AuthContext).user = user!;
+
+        return next(ctx as unknown as AuthContext);
+    }) as Middleware<Context, AuthContext>;
+}
+
+/**
+ * Optional authentication - doesn't throw if no auth provided
+ */
+export function optionalAuth(strategies: AuthStrategies): Middleware<Context, Partial<AuthContext>> {
+    return authenticate(strategies, { required: false }) as any;
+}
+
+/**
+ * Require authentication - throws 401 if not authenticated
+ */
+export function requireAuth(strategies: AuthStrategies): Middleware<Context, AuthContext> {
+    return authenticate(strategies, { required: true });
+}
+
+/**
+ * Permission-based authorization middleware
+ * 
+ * @example
+ * ```ts
+ * app.post('/admin/users', 
+ *   authenticate({ jwt: config }),
+ *   requirePermissions(['admin', 'write:users']),
+ *   handler
+ * );
+ * ```
+ */
+export function requirePermissions(
+    permissions: string[],
+    adapter?: PermissionAdapter
+): Middleware<AuthContext, AuthContext> {
+    const permissionChecker = adapter || new DefaultPermissionAdapter();
+
+    return (async (ctx: AuthContext, next: Next, _deps: any) => {
+        if (!ctx.user) {
+            return {
+                statusCode: 401,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ error: 'Unauthorized' })
+            };
+        }
+
+        const result = permissionChecker.checkPermissions(ctx.user, permissions);
+
+        if (!result.allowed) {
+            return {
+                statusCode: 403,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    error: 'Forbidden',
+                    message: 'Insufficient permissions',
+                    missing: result.missing
+                })
+            };
+        }
+
+        return next(ctx);
+    }) as Middleware<AuthContext, AuthContext>;
+}
+
+/**
+ * Role-based authorization middleware
+ * 
+ * @example
+ * ```ts
+ * app.get('/admin/*', 
+ *   authenticate({ jwt: config }),
+ *   requireRoles(['admin']),
+ *   handler
+ * );
+ * ```
+ */
+export function requireRoles(
+    roles: string[],
+    adapter?: PermissionAdapter
+): Middleware<AuthContext, AuthContext> {
+    const permissionChecker = adapter || new DefaultPermissionAdapter();
+
+    return (async (ctx: AuthContext, next: Next, _deps: any) => {
+        if (!ctx.user) {
+            return {
+                statusCode: 401,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ error: 'Unauthorized' })
+            };
+        }
+
+        const hasRole = permissionChecker.checkRoles(ctx.user, roles);
+
+        if (!hasRole) {
+            return {
+                statusCode: 403,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    error: 'Forbidden',
+                    message: 'Insufficient roles',
+                    required: roles
+                })
+            };
+        }
+
+        return next(ctx);
+    }) as Middleware<AuthContext, AuthContext>;
+}

package/src/security/csrf.ts

@@ -0,0 +1,220 @@
+/**
+ * CSRF Protection Middleware
+ * 
+ * Implements Cross-Site Request Forgery protection
+ */
+
+import type { Context, Next, Middleware } from '../core/types';
+import type { CSRFConfig } from './types';
+import type { CSRFAdapter } from './adapter';
+
+/**
+ * Default CSRF token adapter
+ * Uses double-submit cookie pattern
+ */
+class DefaultCSRFAdapter implements CSRFAdapter {
+    private readonly tokenLength: number;
+
+    constructor(tokenLength: number = 32) {
+        this.tokenLength = tokenLength;
+    }
+
+    generateToken(_ctx: Context): string {
+        // Generate random token
+        const bytes = crypto.getRandomValues(new Uint8Array(this.tokenLength));
+        return Array.from(bytes)
+            .map(b => b.toString(16).padStart(2, '0'))
+            .join('');
+    }
+
+    validateToken(ctx: Context, token: string): boolean {
+        // In double-submit cookie pattern, token in cookie should match token in header/body
+        const cookieToken = this.extractTokenFromCookie(ctx);
+
+        if (!cookieToken) {
+            return false;
+        }
+
+        // Constant-time comparison to prevent timing attacks
+        return this.constantTimeCompare(token, cookieToken);
+    }
+
+    extractToken(ctx: Context): string | null {
+        // Try header first
+        const csrfHeader = ctx.headers['x-csrf-token'] || ctx.headers['X-CSRF-Token'];
+        if (csrfHeader) {
+            return Array.isArray(csrfHeader) ? csrfHeader[0] : csrfHeader;
+        }
+
+        const csrfTokenHeader = ctx.headers['csrf-token'] || ctx.headers['CSRF-Token'];
+        if (csrfTokenHeader) {
+            return Array.isArray(csrfTokenHeader) ? csrfTokenHeader[0] : csrfTokenHeader;
+        }
+
+        // Try body
+        if (ctx.body && typeof ctx.body === 'object') {
+            return (ctx.body as any)._csrf || (ctx.body as any).csrf_token || null;
+        }
+
+        return null;
+    }
+
+    private extractTokenFromCookie(ctx: Context): string | null {
+        const cookieHeaderRaw = ctx.headers['cookie'] || ctx.headers['Cookie'];
+        if (!cookieHeaderRaw) {
+            return null;
+        }
+
+        const cookieHeader = Array.isArray(cookieHeaderRaw) ? cookieHeaderRaw[0] : cookieHeaderRaw;
+
+        const match = cookieHeader.match(/_csrf=([^;]+)/);
+        return match ? match[1] : null;
+    }
+
+    private constantTimeCompare(a: string, b: string): boolean {
+        if (a.length !== b.length) {
+            return false;
+        }
+
+        let result = 0;
+        for (let i = 0; i < a.length; i++) {
+            result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+        }
+
+        return result === 0;
+    }
+}
+
+/**
+ * CSRF protection middleware
+ * 
+ * @example
+ * ```ts
+ * app.use(csrf({
+ *   cookie: { sameSite: 'strict' },
+ *   excludeRoutes: ['/api/webhook/*']
+ * }));
+ * ```
+ */
+export function csrf(
+    config: CSRFConfig = {},
+    adapter?: CSRFAdapter
+): Middleware {
+    const csrfAdapter = adapter || new DefaultCSRFAdapter(config.tokenLength);
+    const auto = config.auto !== false;
+    const excludeMethods = config.excludeMethods || ['GET', 'HEAD', 'OPTIONS'];
+    const excludeRoutes = config.excludeRoutes || [];
+
+    return async (ctx: Context, next: Next, _deps: any) => {
+        // Skip safe methods
+        if (excludeMethods.includes(ctx.method)) {
+            return next(ctx);
+        }
+
+        // Skip excluded routes
+        for (const pattern of excludeRoutes) {
+            const regex = new RegExp('^' + pattern.replace('*', '.*') + '$');
+            if (regex.test(ctx.path)) {
+                return next(ctx);
+            }
+        }
+
+        // Validate CSRF token
+        if (auto) {
+            const token = csrfAdapter.extractToken(ctx);
+
+            if (!token) {
+                return {
+                    statusCode: 403,
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        error: 'CSRF token missing'
+                    })
+                };
+            }
+
+            const valid = csrfAdapter.validateToken(ctx, token);
+
+            if (!valid) {
+                return {
+                    statusCode: 403,
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        error: 'CSRF token invalid'
+                    })
+                };
+            }
+        }
+
+        return next(ctx);
+    };
+}
+
+/**
+ * Generate CSRF token middleware
+ * Attaches token to context and sets cookie
+ * 
+ * @example
+ * ```ts
+ * app.use(generateCSRFToken());
+ * 
+ * // In handler
+ * app.get('/form', async (ctx) => {
+ *   const token = ctx.csrfToken;
+ *   return ctx.html(`<input type="hidden" name="_csrf" value="${token}">`);
+ * });
+ * ```
+ */
+export function generateCSRFToken(
+    config: CSRFConfig = {},
+    adapter?: CSRFAdapter
+): Middleware {
+    const csrfAdapter = adapter || new DefaultCSRFAdapter(config.tokenLength);
+    const cookieName = config.cookie?.name || '_csrf';
+    const cookieOptions = {
+        sameSite: config.cookie?.sameSite || 'strict',
+        secure: config.cookie?.secure !== false,
+        httpOnly: config.cookie?.httpOnly !== false
+    };
+
+    return async (ctx: Context, next: Next, _deps: any) => {
+        // Generate token
+        const token = csrfAdapter.generateToken(ctx);
+
+        // Attach to context
+        (ctx as any).csrfToken = token;
+
+        // Execute handler
+        const response = await next(ctx);
+
+        // Set cookie
+        const cookieValue = `${cookieName}=${token}; SameSite=${cookieOptions.sameSite}${cookieOptions.secure ? '; Secure' : ''}${cookieOptions.httpOnly ? '; HttpOnly' : ''}; Path=/`;
+
+        // Append cookie to response headers
+        if (!response.headers['Set-Cookie']) {
+            response.headers['Set-Cookie'] = cookieValue;
+        } else if (Array.isArray(response.headers['Set-Cookie'])) {
+            response.headers['Set-Cookie'].push(cookieValue);
+        } else {
+            response.headers['Set-Cookie'] = [response.headers['Set-Cookie'], cookieValue];
+        }
+
+        return response;
+    };
+}
+
+/**
+ * Combined CSRF middleware - generates and validates tokens
+ */
+export function csrfProtection(config: CSRFConfig = {}): Middleware {
+    const generateMiddleware = generateCSRFToken(config);
+    const validateMiddleware = csrf(config);
+
+    return async (ctx: Context, next: Next, deps: any) => {
+        // First generate token
+        return generateMiddleware(ctx, async (ctxWithToken: Context) => {
+            // Then validate on unsafe methods
+            return validateMiddleware(ctxWithToken, next, deps);
+        }, deps);
+    };
+}

package/src/security/headers.ts

@@ -0,0 +1,108 @@
+/**
+ * Security Headers Middleware
+ * 
+ * Automatically applies security headers to responses
+ */
+
+import type { Context, Next, Middleware } from '../core/types';
+import type { SecurityHeadersConfig } from './types';
+import type { SecurityHeadersAdapter } from './adapter';
+import { DefaultSecurityHeadersAdapter } from './adapter';
+
+/**
+ * Create security headers middleware
+ * 
+ * @example
+ * ```ts
+ * app.use(securityHeaders({
+ *   mode: 'strict',
+ *   csp: {
+ *     directives: {
+ *       'default-src': ["'self'"],
+ *       'script-src': ["'self'", "'nonce'"]
+ *     }
+ *   }
+ * }));
+ * ```
+ */
+export function securityHeaders(
+    config: SecurityHeadersConfig = {},
+    adapter?: SecurityHeadersAdapter
+): Middleware {
+    const adapterInstance = adapter || new DefaultSecurityHeadersAdapter();
+    const nonces = new WeakMap<Context, string>();
+
+    return async (ctx: Context, next: Next, _deps: any) => {
+        // Generate nonce if CSP uses it
+        if (config.autoNonce && config.csp) {
+            const nonce = adapterInstance.generateNonce?.() || crypto.randomUUID();
+            nonces.set(ctx, nonce);
+
+            // Replace 'nonce' placeholder in CSP directives
+            if (config.csp.directives) {
+                for (const [key, values] of Object.entries(config.csp.directives)) {
+                    config.csp.directives[key] = values.map(v =>
+                        v === "'nonce'" ? `'nonce-${nonce}'` : v
+                    );
+                }
+            }
+
+            // Attach nonce to context for use in templates
+            (ctx as any).nonce = nonce;
+        }
+
+        // Generate headers
+        const headers = adapterInstance.generateHeaders(ctx, config);
+
+        // Execute handler
+        const response = await next(ctx);
+
+        // Apply headers to response
+        for (const [name, value] of Object.entries(headers)) {
+            response.headers[name] = value;
+        }
+
+        return response;
+    };
+}
+
+/**
+ * Strict security headers preset
+ */
+export function strictSecurityHeaders(customConfig: Partial<SecurityHeadersConfig> = {}): Middleware {
+    return securityHeaders({
+        mode: 'strict',
+        csp: {
+            directives: {
+                'default-src': ["'self'"],
+                'script-src': ["'self'"],
+                'style-src': ["'self'"],
+                'img-src': ["'self'", 'data:', 'https:'],
+                'font-src': ["'self'"],
+                'connect-src': ["'self'"],
+                'frame-ancestors': ["'none'"],
+                'base-uri': ["'self'"],
+                'form-action': ["'self'"]
+            }
+        },
+        ...customConfig
+    });
+}
+
+/**
+ * Moderate security headers preset
+ */
+export function moderateSecurityHeaders(customConfig: Partial<SecurityHeadersConfig> = {}): Middleware {
+    return securityHeaders({
+        mode: 'moderate',
+        csp: {
+            directives: {
+                'default-src': ["'self'"],
+                'script-src': ["'self'", "'unsafe-inline'"],
+                'style-src': ["'self'", "'unsafe-inline'"],
+                'img-src': ["'self'", 'data:', 'https:']
+            }
+        },
+        ...customConfig
+    });
+}

package/src/security/index.ts

@@ -0,0 +1,60 @@
+/**
+ * Security Module Entry Point
+ * 
+ * Exports all security features
+ */
+
+// Types
+export * from './types';
+
+// Adapters
+export * from './adapter';
+
+// Security Headers
+export {
+    securityHeaders,
+    strictSecurityHeaders,
+    moderateSecurityHeaders
+} from './headers';
+
+// Input Sanitization
+export {
+    sanitizeInput,
+    strictSanitization,
+    lenientSanitization
+} from './sanitization';
+
+// Authentication
+export {
+    authenticate,
+    optionalAuth,
+    requireAuth,
+    requirePermissions,
+    requireRoles
+} from './auth/middleware';
+
+export { JWTAuthAdapter } from './auth/jwt';
+
+// JWT Provider (for DI)
+export { JWTProvider, createJWTProvider } from './auth/JWTProvider';
+export type { JWTProviderConfig, TokenPayload, VerifyResult } from './auth/JWTProvider';
+
+// JWT Plugin
+export { jwtPlugin } from './auth/JWTPlugin';
+export type { JWTPluginConfig, JWTPluginExports } from './auth/JWTPlugin';
+
+// Rate Limiting
+export {
+    rateLimit,
+    strictRateLimit,
+    lenientRateLimit
+} from './rate-limit/middleware';
+
+export { MemoryRateLimiter } from './rate-limit/memory';
+
+// CSRF Protection
+export {
+    csrf,
+    generateCSRFToken,
+    csrfProtection
+} from './csrf';

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

@@ -0,0 +1,7 @@
+/**
+ * Rate Limit Adapter Interface
+ * 
+ * Extensible rate limiting storage backends
+ */
+
+export type { RateLimitAdapter } from '../adapter';

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

@@ -0,0 +1,108 @@
+/**
+ * In-Memory Rate Limiter
+ * 
+ * Simple in-memory rate limiting implementation
+ */
+
+import type { RateLimitAdapter } from '../adapter';
+import type { RateLimitInfo } from '../types';
+
+interface RateLimitEntry {
+    count: number;
+    resetTime: number;
+    firstRequest: number;
+}
+
+/**
+ * In-memory rate limit storage
+ * Uses sliding window algorithm
+ */
+export class MemoryRateLimiter implements RateLimitAdapter {
+    private store = new Map<string, RateLimitEntry>();
+    private cleanupInterval: NodeJS.Timeout | null = null;
+
+    constructor(cleanupIntervalMs: number = 60000) {
+        // Periodic cleanup of expired entries
+        this.cleanupInterval = setInterval(() => {
+            this.cleanup();
+        }, cleanupIntervalMs);
+    }
+
+    async increment(key: string, windowMs: number): Promise<{
+        count: number;
+        resetTime: number;
+    }> {
+        const now = Date.now();
+        const entry = this.store.get(key);
+
+        // No existing entry or expired
+        if (!entry || now >= entry.resetTime) {
+            const newEntry: RateLimitEntry = {
+                count: 1,
+                resetTime: now + windowMs,
+                firstRequest: now
+            };
+            this.store.set(key, newEntry);
+
+            return {
+                count: 1,
+                resetTime: newEntry.resetTime
+            };
+        }
+
+        // Increment existing entry
+        entry.count++;
+
+        return {
+            count: entry.count,
+            resetTime: entry.resetTime
+        };
+    }
+
+    async get(key: string): Promise<RateLimitInfo | null> {
+        const entry = this.store.get(key);
+
+        if (!entry) {
+            return null;
+        }
+
+        const now = Date.now();
+
+        // Expired
+        if (now >= entry.resetTime) {
+            this.store.delete(key);
+            return null;
+        }
+
+        return {
+            limit: -1, // Will be set by middleware
+            remaining: -1, // Will be calculated by middleware
+            reset: Math.floor(entry.resetTime / 1000),
+            retryAfter: Math.ceil((entry.resetTime - now) / 1000)
+        };
+    }
+
+    async reset(key: string): Promise<void> {
+        this.store.delete(key);
+    }
+
+    async cleanup(): Promise<void> {
+        const now = Date.now();
+
+        for (const [key, entry] of this.store.entries()) {
+            if (now >= entry.resetTime) {
+                this.store.delete(key);
+            }
+        }
+    }
+
+    /**
+     * Stop cleanup interval
+     */
+    destroy(): void {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+    }
+}