@zintrust/core 0.1.28 → 0.1.30

package/src/microservices/ServiceHealthMonitor.js

@@ -0,0 +1,383 @@
+/**
+ * Service Health Check and Monitoring System
+ * Provides per-service and aggregated health status with detailed diagnostics
+ */
+import { Logger } from '../config/logger.js';
+import { validateUrl } from '../security/UrlValidator.js';
+/**
+ * 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:7777/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 ??= {};
+    const checks = await Promise.all(dependencies.map(async (depService) => ({
+        depService,
+        isHealthy: await checkDependencyService(depService),
+    })));
+    for (const { depService, isHealthy } of checks) {
+        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
+             */
+            // eslint-disable-next-line @typescript-eslint/require-await
+            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/AuthMiddleware.d.ts

@@ -0,0 +1,10 @@
+import type { Middleware } from './MiddlewareStack';
+export interface AuthOptions {
+    headerName?: string;
+    message?: string;
+}
+export declare const AuthMiddleware: Readonly<{
+    create(options?: AuthOptions): Middleware;
+}>;
+export default AuthMiddleware;
+//# sourceMappingURL=AuthMiddleware.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AuthMiddleware.d.ts","sourceRoot":"","sources":["../../../src/middleware/AuthMiddleware.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,cAAc;qBACT,WAAW,GAAQ,UAAU;EAgB7C,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/src/middleware/AuthMiddleware.js

@@ -0,0 +1,16 @@
+export const AuthMiddleware = Object.freeze({
+    create(options = {}) {
+        const headerName = (options.headerName ?? 'authorization').toLowerCase();
+        const message = options.message ?? 'Unauthorized';
+        return async (req, res, next) => {
+            const header = req.getHeader(headerName);
+            const value = Array.isArray(header) ? header[0] : header;
+            if (typeof value !== 'string' || value.trim() === '') {
+                res.setStatus(401).json({ error: message });
+                return;
+            }
+            await next();
+        };
+    },
+});
+export default AuthMiddleware;

package/src/middleware/CsrfMiddleware.d.ts

@@ -0,0 +1,29 @@
+/**
+ * CSRF Middleware
+ * Protects against Cross-Site Request Forgery attacks
+ * Uses CsrfTokenManager for token generation and validation
+ */
+import type { Middleware } from './MiddlewareStack';
+export interface CsrfOptions {
+    cookieName?: string;
+    headerName?: string;
+    bodyKey?: string;
+    ignoreMethods?: string[];
+    /**
+     * Optional path patterns to bypass CSRF entirely.
+     *
+     * Supports simple glob-style matching where `*` matches any characters.
+     * Examples:
+     * - `/api/*`
+     * - `/webhooks/*`
+     * - `/api/v1/auth/login`
+     */
+    skipPaths?: 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;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAI9D,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;IACzB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AASD,eAAO,MAAM,cAAc;IACzB;;OAEG;qBACa,WAAW,GAAQ,UAAU;EAiE7C,CAAC"}

package/src/middleware/CsrfMiddleware.js

@@ -0,0 +1,132 @@
+/**
+ * CSRF Middleware
+ * Protects against Cross-Site Request Forgery attacks
+ * Uses CsrfTokenManager for token generation and validation
+ */
+import { Logger } from '../config/logger.js';
+import { CsrfTokenManager } from '../security/CsrfTokenManager.js';
+import { SessionManager } from '../session/SessionManager.js';
+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();
+        const sessions = SessionManager.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) => {
+            if (shouldSkipCsrfForRequest(req, config)) {
+                await next();
+                return;
+            }
+            const cookieHeader = req.getHeader('cookie');
+            const cookies = parseCookies(typeof cookieHeader === 'string' ? cookieHeader : '');
+            // Guarantee a session id exists and a session cookie is set if missing.
+            // This allows CSRF tokens to be bound to a stable session identifier.
+            const sessionId = await sessions.ensureSessionId(req, res);
+            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)
+                appendSetCookie(res, `${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();
+        };
+    },
+});
+function shouldSkipCsrfForRequest(req, config) {
+    const patterns = config.skipPaths;
+    if (patterns === undefined || patterns.length === 0)
+        return false;
+    const path = req.getPath();
+    for (const pattern of patterns) {
+        const trimmed = pattern.trim();
+        if (trimmed === '')
+            continue;
+        if (pathMatchesPattern(path, trimmed))
+            return true;
+    }
+    return false;
+}
+function pathMatchesPattern(path, pattern) {
+    if (pattern === '*')
+        return true;
+    if (pattern === path)
+        return true;
+    // Fast path: treat trailing "/*" as a prefix match.
+    if (pattern.endsWith('/*')) {
+        const prefix = pattern.slice(0, -1); // keep the trailing '/'
+        return path.startsWith(prefix);
+    }
+    // Generic glob-to-regex conversion where '*' matches any characters.
+    const escaped = pattern.replaceAll(/[.+?^${}()|[\]\\]/g, String.raw `\$&`);
+    const regex = new RegExp(`^${escaped.replaceAll('*', '.*')}$`);
+    return regex.test(path);
+}
+function appendSetCookie(res, cookie) {
+    const existing = res.getHeader('Set-Cookie');
+    if (existing === undefined) {
+        res.setHeader('Set-Cookie', cookie);
+        return;
+    }
+    if (Array.isArray(existing)) {
+        res.setHeader('Set-Cookie', [...existing, cookie]);
+        return;
+    }
+    res.setHeader('Set-Cookie', [existing, cookie]);
+}
+/**
+ * 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';
+}

package/src/middleware/ErrorHandlerMiddleware.d.ts

@@ -0,0 +1,6 @@
+import type { Middleware } from './MiddlewareStack';
+export declare const ErrorHandlerMiddleware: Readonly<{
+    create(): Middleware;
+}>;
+export default ErrorHandlerMiddleware;
+//# sourceMappingURL=ErrorHandlerMiddleware.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorHandlerMiddleware.d.ts","sourceRoot":"","sources":["../../../src/middleware/ErrorHandlerMiddleware.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAU9D,eAAO,MAAM,sBAAsB;cACvB,UAAU;EA+BpB,CAAC;AAEH,eAAe,sBAAsB,CAAC"}

package/src/middleware/ErrorHandlerMiddleware.js

@@ -0,0 +1,41 @@
+import { Env } from '../config/env.js';
+import { Logger } from '../config/logger.js';
+import ErrorRouting from '../routes/error.js';
+import { ErrorResponse } from '../http/ErrorResponse.js';
+import { RequestContext } from '../http/RequestContext.js';
+const isWritableEnded = (res) => {
+    if (typeof res.getRaw !== 'function')
+        return false;
+    const raw = res.getRaw();
+    if (typeof raw !== 'object' || raw === null)
+        return false;
+    if (!('writableEnded' in raw))
+        return false;
+    return Boolean(raw.writableEnded);
+};
+export const ErrorHandlerMiddleware = Object.freeze({
+    create() {
+        return async (req, res, next) => {
+            try {
+                await next();
+            }
+            catch (error) {
+                Logger.error('Unhandled request error:', error);
+                const requestId = RequestContext.get(req)?.requestId ?? req.context['requestId'];
+                const includeStack = Env.NODE_ENV !== 'production';
+                if (!isWritableEnded(res)) {
+                    const errorMode = Env.get('ERROR_MODE', 'html');
+                    res.setStatus(500);
+                    if (errorMode === 'html') {
+                        // Use HTML error page instead of JSON
+                        ErrorRouting.handleInternalServerErrorWithWrappers(req, res, error, requestId);
+                    }
+                    else {
+                        res.json(ErrorResponse.internalServerError('Internal server error', requestId, includeStack ? error?.stack : undefined));
+                    }
+                }
+            }
+        };
+    },
+});
+export default ErrorHandlerMiddleware;

package/src/middleware/JwtAuthMiddleware.d.ts

@@ -0,0 +1,11 @@
+import type { Middleware } from './MiddlewareStack';
+import type { JwtAlgorithm } from '../security/JwtManager';
+export interface JwtAuthOptions {
+    algorithm?: JwtAlgorithm;
+    secret?: string;
+}
+export declare const JwtAuthMiddleware: Readonly<{
+    create(options?: JwtAuthOptions): Middleware;
+}>;
+export default JwtAuthMiddleware;
+//# sourceMappingURL=JwtAuthMiddleware.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"JwtAuthMiddleware.d.ts","sourceRoot":"","sources":["../../../src/middleware/JwtAuthMiddleware.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAItE,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA2BD,eAAO,MAAM,iBAAiB;qBACZ,cAAc,GAAQ,UAAU;EAwDhD,CAAC;AAEH,eAAe,iBAAiB,CAAC"}