@zintrust/core 0.1.0

package/src/microservices/ServiceHealthMonitor.js

@@ -0,0 +1,379 @@
+/**
+ * Service Health Check and Monitoring System
+ * Provides per-service and aggregated health status with detailed diagnostics
+ */
+import { Logger } from '../config/logger';
+import { validateUrl } from '../security/UrlValidator';
+/**
+ * Health Check Endpoint Handler
+ * Each service should expose this as GET /health
+ */
+export const HealthCheckHandler = Object.freeze({
+    /**
+     * Create a new health check handler instance
+     */
+    create(serviceName, version, port, domain, dependencies = [], checkDatabase) {
+        /**
+         * Perform full health check
+         */
+        const performHealthCheck = async (startTime) => {
+            const result = {
+                service: serviceName,
+                domain,
+                port,
+                status: 'healthy',
+                timestamp: new Date().toISOString(),
+                responseTime: 0,
+                version,
+                checks: {
+                    http: true,
+                    database: undefined,
+                    dependencies: {},
+                },
+            };
+            await checkDatabaseHealth(result, checkDatabase);
+            await checkDependenciesHealth(result, dependencies);
+            result.responseTime = Date.now() - startTime;
+            return result;
+        };
+        return {
+            /**
+             * Handle health check request
+             * Returns JSON with service health status
+             */
+            async handle(_req, res) {
+                const startTime = Date.now();
+                try {
+                    const result = await performHealthCheck(startTime);
+                    const statusCode = getStatusCode(result.status);
+                    res.setStatus(statusCode).json(result);
+                }
+                catch (err) {
+                    Logger.error('Health check handler error:', err);
+                    const result = {
+                        service: serviceName,
+                        domain,
+                        port,
+                        status: 'unhealthy',
+                        timestamp: new Date().toISOString(),
+                        responseTime: Date.now() - startTime,
+                        version,
+                        checks: { http: false },
+                        message: err.message,
+                    };
+                    res.setStatus(503).json(result);
+                }
+            },
+        };
+    },
+});
+/**
+ * Get status code based on health status
+ */
+function getStatusCode(status) {
+    if (status === 'healthy')
+        return 200;
+    if (status === 'degraded')
+        return 202;
+    return 503;
+}
+/**
+ * Check single dependency service
+ */
+async function checkDependencyService(depService) {
+    try {
+        // In a real environment, we would resolve the service URL
+        // For now, we assume it's on localhost with a standard port mapping or discovery
+        const url = `http://localhost:3000/health?service=${depService}`;
+        // SSRF Protection
+        validateUrl(url);
+        const depResponse = await fetch(url, {
+            signal: AbortSignal.timeout(2000),
+        });
+        return depResponse.ok;
+    }
+    catch (error) {
+        Logger.error(`Dependency health check failed for ${depService}`, error);
+        return false;
+    }
+}
+/**
+ * Check all dependencies health
+ */
+async function checkDependenciesHealth(result, dependencies) {
+    if (dependencies.length === 0)
+        return;
+    result.checks.dependencies ??= {};
+    for (const depService of dependencies) {
+        const isHealthy = await checkDependencyService(depService);
+        result.checks.dependencies[depService] = isHealthy;
+        if (!isHealthy) {
+            result.status = 'degraded';
+        }
+    }
+}
+/**
+ * Check database health
+ */
+async function checkDatabaseHealth(result, checkDatabase) {
+    if (checkDatabase === undefined)
+        return;
+    try {
+        result.checks.database = await checkDatabase();
+        if (!result.checks.database) {
+            result.status = 'degraded';
+            result.message = 'Database connection failed';
+        }
+    }
+    catch (err) {
+        Logger.error('Database health check failed:', err);
+        result.checks.database = false;
+        result.status = 'unhealthy';
+        result.message = 'Database check error';
+    }
+}
+/**
+ * Service Health Monitor
+ * Monitors multiple services and provides aggregated health status
+ */
+export const ServiceHealthMonitor = Object.freeze({
+    /**
+     * Create a new service health monitor instance
+     */
+    create(healthCheckUrls, // serviceName -> healthCheckUrl
+    intervalMs = 30000 // Check every 30 seconds
+    ) {
+        let checkIntervalId;
+        const lastResults = new Map();
+        return createMonitorObject(healthCheckUrls, intervalMs, lastResults, () => checkIntervalId, (id) => {
+            checkIntervalId = id;
+        });
+    },
+});
+/**
+ * Create the monitor object with methods
+ */
+function createMonitorObject(healthCheckUrls, intervalMs, lastResults, getIntervalId, setIntervalId) {
+    const self = {
+        /**
+         * Start continuous health monitoring
+         */
+        start() {
+            startMonitoring(intervalMs, async () => self.checkAll(), getIntervalId, setIntervalId);
+        },
+        /**
+         * Stop health monitoring
+         */
+        stop() {
+            stopMonitoring(getIntervalId, setIntervalId);
+        },
+        /**
+         * Check all services
+         */
+        async checkAll() {
+            const status = await runAllChecks(healthCheckUrls, lastResults);
+            logHealthSummary(status);
+            return status;
+        },
+        /**
+         * Get last known status of all services
+         */
+        getLastStatus() {
+            const results = Array.from(lastResults.values());
+            return calculateAggregatedStatus(results);
+        },
+        /**
+         * Get health status for specific service
+         */
+        getServiceStatus(serviceName) {
+            return lastResults.get(serviceName);
+        },
+        /**
+         * Check if all services are healthy
+         */
+        areAllHealthy() {
+            return checkAllHealthy(lastResults, healthCheckUrls);
+        },
+        /**
+         * Check if service is healthy
+         */
+        isServiceHealthy(serviceName) {
+            const status = self.getServiceStatus(serviceName);
+            return status?.status === 'healthy';
+        },
+    };
+    return self;
+}
+/**
+ * Start monitoring logic
+ */
+function startMonitoring(intervalMs, checkAll, getIntervalId, setIntervalId) {
+    if (getIntervalId() !== undefined) {
+        Logger.warn('Health monitoring already started');
+        return;
+    }
+    Logger.info('🏥 Starting service health monitoring');
+    let inFlight = false;
+    const safeCheckAll = async () => {
+        if (inFlight)
+            return;
+        inFlight = true;
+        try {
+            await checkAll();
+        }
+        catch (err) {
+            Logger.error('Service health monitoring tick failed:', err);
+        }
+        finally {
+            inFlight = false;
+        }
+    };
+    void safeCheckAll(); // Initial check
+    const id = setInterval(() => {
+        void safeCheckAll();
+    }, intervalMs);
+    // Node: allow process to exit; other runtimes may not support unref()
+    if (isUnrefableTimer(id)) {
+        id.unref();
+    }
+    setIntervalId(id);
+}
+function isUnrefableTimer(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    return 'unref' in value && typeof value.unref === 'function';
+}
+/**
+ * Stop monitoring logic
+ */
+function stopMonitoring(getIntervalId, setIntervalId) {
+    const id = getIntervalId();
+    if (id !== undefined) {
+        clearInterval(id);
+        setIntervalId(undefined);
+        Logger.info('🛑 Health monitoring stopped');
+    }
+}
+/**
+ * Check if all services are healthy
+ */
+function checkAllHealthy(lastResults, healthCheckUrls) {
+    const results = Array.from(lastResults.values());
+    if (results.length === 0 && Object.keys(healthCheckUrls).length > 0) {
+        return false;
+    }
+    return results.length > 0 && results.every((r) => r.status === 'healthy');
+}
+/**
+ * Check single service
+ */
+async function checkService(serviceName, url) {
+    const startTime = Date.now();
+    try {
+        const response = await fetch(url, {
+            signal: AbortSignal.timeout(5000),
+        });
+        await response.json();
+        return {
+            service: serviceName,
+            domain: 'unknown',
+            port: 0,
+            status: 'healthy',
+            timestamp: new Date().toISOString(),
+            responseTime: Date.now() - startTime,
+            version: 'unknown',
+            checks: { http: true },
+        };
+    }
+    catch (err) {
+        Logger.error(`Service health check failed for ${serviceName}:`, err);
+        return {
+            service: serviceName,
+            domain: 'unknown',
+            port: 0,
+            status: 'stopped',
+            timestamp: new Date().toISOString(),
+            responseTime: Date.now() - startTime,
+            version: 'unknown',
+            checks: { http: false },
+            message: `Service check failed: ${err.message}`,
+        };
+    }
+}
+/**
+ * Calculate aggregated health status from results
+ */
+function calculateAggregatedStatus(results) {
+    const healthy = results.filter((r) => r.status === 'healthy').length;
+    const degraded = results.filter((r) => r.status === 'degraded').length;
+    const unhealthy = results.filter((r) => r.status === 'unhealthy').length;
+    return {
+        timestamp: new Date().toISOString(),
+        totalServices: results.length,
+        healthy,
+        degraded,
+        unhealthy,
+        services: results,
+    };
+}
+/**
+ * Log health summary
+ */
+function logHealthSummary(status) {
+    if (status.unhealthy > 0) {
+        Logger.warn(`⚠️  Health check: ${status.healthy} healthy, ${status.degraded} degraded, ${status.unhealthy} unhealthy`);
+    }
+    else if (status.degraded > 0) {
+        Logger.warn(`⚠️  Health check: ${status.healthy} healthy, ${status.degraded} degraded`);
+    }
+    else {
+        Logger.info(`✅ All ${status.healthy} services healthy`);
+    }
+}
+/**
+ * Health Check Aggregator Endpoint
+ * Exposes aggregated health status at GET /health/services
+ */
+export const HealthCheckAggregator = Object.freeze({
+    /**
+     * Create a new health check aggregator instance
+     */
+    create(monitor) {
+        return {
+            /**
+             * Handle aggregated health check request
+             */
+            async handle(_req, res) {
+                const status = monitor.getLastStatus();
+                let statusCode;
+                if (status.unhealthy > 0) {
+                    statusCode = 503;
+                }
+                else if (status.degraded > 0) {
+                    statusCode = 202;
+                }
+                else {
+                    statusCode = 200;
+                }
+                res.setStatus(statusCode).json(status);
+            },
+        };
+    },
+});
+/**
+ * Run all service health checks
+ */
+async function runAllChecks(healthCheckUrls, lastResults) {
+    const checks = Object.entries(healthCheckUrls).map(async ([serviceName, url]) => checkService(serviceName, url));
+    const results = await Promise.all(checks);
+    // Store results
+    results.forEach((result) => {
+        lastResults.set(result.service, result);
+    });
+    return calculateAggregatedStatus(results);
+}
+export default {
+    HealthCheckHandler,
+    ServiceHealthMonitor,
+    HealthCheckAggregator,
+};

package/src/middleware/CsrfMiddleware.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CSRF Middleware
+ * Protects against Cross-Site Request Forgery attacks
+ * Uses CsrfTokenManager for token generation and validation
+ */
+import { Middleware } from './MiddlewareStack';
+export interface CsrfOptions {
+    cookieName?: string;
+    headerName?: string;
+    bodyKey?: string;
+    ignoreMethods?: string[];
+}
+export declare const CsrfMiddleware: Readonly<{
+    /**
+     * Create CSRF protection middleware
+     */
+    create(options?: CsrfOptions): Middleware;
+}>;
+//# sourceMappingURL=CsrfMiddleware.d.ts.map

package/src/middleware/CsrfMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CsrfMiddleware.d.ts","sourceRoot":"","sources":["../../../src/middleware/CsrfMiddleware.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAGzD,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AASD,eAAO,MAAM,cAAc;IACzB;;OAEG;qBACa,WAAW,GAAQ,UAAU;EA+E7C,CAAC"}

package/src/middleware/CsrfMiddleware.js

@@ -0,0 +1,121 @@
+/**
+ * CSRF Middleware
+ * Protects against Cross-Site Request Forgery attacks
+ * Uses CsrfTokenManager for token generation and validation
+ */
+import { Logger } from '../config/logger';
+import { ErrorFactory } from '../exceptions/ZintrustError';
+import { CsrfTokenManager } from '../security/CsrfTokenManager';
+const DEFAULT_OPTIONS = {
+    cookieName: 'XSRF-TOKEN',
+    headerName: 'X-CSRF-Token',
+    bodyKey: '_csrf',
+    ignoreMethods: ['GET', 'HEAD', 'OPTIONS'],
+};
+export const CsrfMiddleware = Object.freeze({
+    /**
+     * Create CSRF protection middleware
+     */
+    create(options = {}) {
+        const config = { ...DEFAULT_OPTIONS, ...options };
+        const manager = CsrfTokenManager.create();
+        // Periodic cleanup to prevent memory leaks
+        // Run every hour (matching default token TTL)
+        const cleanupTimer = setInterval(() => {
+            manager.cleanup();
+        }, 3600000);
+        // Node: allow process to exit; other runtimes may not support unref()
+        if (isUnrefableTimer(cleanupTimer)) {
+            cleanupTimer.unref();
+        }
+        return async (req, res, next) => {
+            // We need a session ID to bind the token to.
+            // Assuming a session middleware has run before this and populated req.context.sessionId
+            // or we use a cookie for the session ID.
+            // For now, we'll try to get it from a cookie or generate a temporary one if missing (stateless fallback)
+            // Note: In a real scenario, this MUST be tied to the user's authenticated session.
+            // Here we check for a specific session cookie or header.
+            const cookies = parseCookies(req.getHeader('cookie') || '');
+            let sessionId = cookies['ZIN_SESSION_ID'] || req.context['sessionId'];
+            if (!sessionId) {
+                // If no session exists, we can't effectively bind CSRF to a session.
+                // However, for the sake of the middleware functioning in a stateless way (Double Submit Cookie pattern),
+                // we can generate a pseudo-session-id if one doesn't exist, but it's less secure.
+                // Ideally, this middleware should throw if session is missing.
+                // For this implementation, we'll skip if no session is found, but log a warning.
+                // Logger.warn('CSRF Middleware: No session ID found. Skipping CSRF check.');
+                // await next();
+                // return;
+                // Better approach: Generate a session ID if missing (Double Submit Cookie foundation)
+                // IMPORTANT: use a cryptographically secure generator (Sonar S2245).
+                sessionId = generateSecureId();
+                // We would need to set this session cookie, but we can't easily do that without a SessionManager.
+                // We'll assume the SessionMiddleware handles session creation.
+            }
+            const method = req.getMethod();
+            // 1. Token Generation (for safe methods)
+            if (config.ignoreMethods?.includes(method) ?? false) {
+                const token = manager.generateToken(sessionId);
+                // Set cookie for Double Submit Cookie pattern (readable by frontend)
+                res.setHeader('Set-Cookie', `${config.cookieName}=${token}; Path=/; SameSite=Strict`);
+                // Also expose in locals for server-side rendering
+                res.locals['csrfToken'] = token;
+                await next();
+                return;
+            }
+            // 2. Token Validation (for unsafe methods)
+            const tokenFromHeader = req.getHeader(config.headerName ?? 'X-CSRF-Token');
+            const tokenFromBody = req.getBody()?.[config.bodyKey ?? '_csrf'];
+            const tokenFromCookie = cookies[config.cookieName ?? 'XSRF-TOKEN'];
+            const token = tokenFromHeader || tokenFromBody || tokenFromCookie;
+            if (!token || !manager.validateToken(sessionId, token)) {
+                Logger.warn(`CSRF validation failed for session ${sessionId}`);
+                res.setStatus(403);
+                res.json({
+                    error: 'Forbidden',
+                    message: 'Invalid CSRF token',
+                });
+                return;
+            }
+            await next();
+        };
+    },
+});
+/**
+ * Helper to parse cookies
+ */
+function parseCookies(cookieHeader) {
+    const list = {};
+    if (!cookieHeader)
+        return list;
+    cookieHeader.split(';').forEach((cookie) => {
+        const parts = cookie.split('=');
+        const name = parts.shift()?.trim();
+        const value = parts.join('=');
+        if (name !== null && name !== undefined)
+            list[name] = decodeURIComponent(value);
+    });
+    return list;
+}
+function isUnrefableTimer(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    return 'unref' in value && typeof value.unref === 'function';
+}
+function generateSecureId() {
+    if (typeof globalThis.crypto?.randomUUID === 'function') {
+        return globalThis.crypto.randomUUID();
+    }
+    if (typeof globalThis.crypto?.getRandomValues === 'function') {
+        const bytes = new Uint8Array(32);
+        globalThis.crypto.getRandomValues(bytes);
+        return bytesToHex(bytes);
+    }
+    throw ErrorFactory.createSecurityError('CSRF Middleware: secure crypto API not available to generate a session id.');
+}
+function bytesToHex(bytes) {
+    let out = '';
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}

package/src/middleware/MiddlewareStack.d.ts

@@ -0,0 +1,27 @@
+import { IRequest } from '../http/Request';
+import { IResponse } from '../http/Response';
+/**
+ * Middleware Stack
+ * Manages middleware execution pipeline
+ */
+export type Middleware = (req: IRequest, res: IResponse, next: () => Promise<void>) => Promise<void>;
+export interface IMiddlewareStack {
+    register(name: string, handler: Middleware): void;
+    execute(request: IRequest, response: IResponse, only?: string[] | Middleware[]): Promise<void>;
+    getMiddlewares(): Array<{
+        name: string;
+        handler: Middleware;
+    }>;
+}
+/**
+ * Middleware Stack
+ * Refactored to Functional Object pattern
+ */
+export declare const MiddlewareStack: Readonly<{
+    /**
+     * Create a new middleware stack instance
+     */
+    create(): IMiddlewareStack;
+}>;
+export default MiddlewareStack;
+//# sourceMappingURL=MiddlewareStack.d.ts.map

package/src/middleware/MiddlewareStack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MiddlewareStack.d.ts","sourceRoot":"","sources":["../../../src/middleware/MiddlewareStack.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;GAGG;AAEH,MAAM,MAAM,UAAU,GAAG,CACvB,GAAG,EAAE,QAAQ,EACb,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KACtB,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAClD,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/F,cAAc,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;CAChE;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe;IAC1B;;OAEG;cACO,gBAAgB;EAsC1B,CAAC;AAEH,eAAe,eAAe,CAAC"}

package/src/middleware/MiddlewareStack.js

@@ -0,0 +1,43 @@
+/**
+ * Middleware Stack
+ * Refactored to Functional Object pattern
+ */
+export const MiddlewareStack = Object.freeze({
+    /**
+     * Create a new middleware stack instance
+     */
+    create() {
+        const middlewares = [];
+        return {
+            /**
+             * Register middleware
+             */
+            register(name, handler) {
+                middlewares.push({ name, handler });
+            },
+            /**
+             * Execute middleware stack
+             */
+            async execute(request, response, only) {
+                const filteredMiddlewares = only
+                    ? middlewares.filter((m) => only.includes(m.name))
+                    : middlewares;
+                let index = 0;
+                const next = async () => {
+                    if (index >= filteredMiddlewares.length)
+                        return;
+                    const middleware = filteredMiddlewares[index++];
+                    await middleware.handler(request, response, next);
+                };
+                await next();
+            },
+            /**
+             * Get all middleware
+             */
+            getMiddlewares() {
+                return middlewares;
+            },
+        };
+    },
+});
+export default MiddlewareStack;

package/src/middleware/RateLimiter.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Rate Limiter Middleware
+ * Token bucket implementation for request rate limiting
+ * Zero-dependency implementation
+ */
+import { IRequest } from '../http/Request';
+import { Middleware } from './MiddlewareStack';
+export interface RateLimitOptions {
+    windowMs: number;
+    max: number;
+    message?: string;
+    statusCode?: number;
+    headers?: boolean;
+    keyGenerator?: (req: IRequest) => string;
+}
+export declare const RateLimiter: Readonly<{
+    /**
+     * Create rate limiter middleware
+     */
+    create(options?: RateLimitOptions): Middleware;
+}>;
+//# sourceMappingURL=RateLimiter.d.ts.map

package/src/middleware/RateLimiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RateLimiter.d.ts","sourceRoot":"","sources":["../../../src/middleware/RateLimiter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,MAAM,CAAC;CAC1C;AAoBD,eAAO,MAAM,WAAW;IACtB;;OAEG;qBACa,gBAAgB,GAAqB,UAAU;EA4D/D,CAAC"}