@vorionsys/platform-core 0.1.0

package/dist/common/debug-auth-middleware.js

@@ -0,0 +1,285 @@
+/**
+ * Debug Authentication Middleware
+ *
+ * Secures debug endpoints by:
+ * - Restricting access to localhost only (127.0.0.1)
+ * - Requiring a debug authentication token
+ * - Logging all access attempts
+ *
+ * @packageDocumentation
+ */
+import { createLogger } from './logger.js';
+import { getSecurityConfig, getSecurityMode, isDevelopmentMode } from './security-mode.js';
+import { timingSafeEqual } from 'crypto';
+const logger = createLogger({ component: 'debug-auth' });
+/**
+ * Default header name for debug token
+ */
+const DEFAULT_DEBUG_TOKEN_HEADER = 'X-Debug-Token';
+/**
+ * Environment variable name for debug token
+ */
+const DEBUG_TOKEN_ENV_VAR = 'VORION_DEBUG_TOKEN';
+/**
+ * Allowed localhost addresses
+ */
+const LOCALHOST_ADDRESSES = new Set([
+    '127.0.0.1',
+    '::1',
+    '::ffff:127.0.0.1',
+    'localhost',
+]);
+/**
+ * Get the configured debug token from environment
+ *
+ * @returns The debug token or null if not configured
+ */
+export function getDebugToken() {
+    const token = process.env[DEBUG_TOKEN_ENV_VAR];
+    if (!token || token.trim() === '') {
+        return null;
+    }
+    return token;
+}
+/**
+ * Extract client IP address from request
+ *
+ * Handles various proxy headers and direct connections
+ */
+export function getClientIp(req) {
+    // Check for forwarded headers (in order of preference)
+    const forwardedFor = req.headers['x-forwarded-for'];
+    if (forwardedFor) {
+        // x-forwarded-for can contain multiple IPs, take the first (original client)
+        const ips = Array.isArray(forwardedFor)
+            ? forwardedFor[0]
+            : forwardedFor.split(',')[0];
+        return ips?.trim() || 'unknown';
+    }
+    const realIp = req.headers['x-real-ip'];
+    if (realIp) {
+        return Array.isArray(realIp) ? realIp[0] : realIp;
+    }
+    // Fall back to socket remote address
+    const socketAddress = req.socket?.remoteAddress;
+    if (socketAddress) {
+        return socketAddress;
+    }
+    return 'unknown';
+}
+/**
+ * Check if the request is from localhost
+ */
+export function isLocalhost(clientIp) {
+    // Normalize IPv6-mapped IPv4 addresses
+    const normalizedIp = clientIp.replace(/^::ffff:/, '');
+    return LOCALHOST_ADDRESSES.has(normalizedIp) || LOCALHOST_ADDRESSES.has(clientIp);
+}
+/**
+ * Securely compare two strings using timing-safe comparison
+ */
+function secureCompare(a, b) {
+    if (typeof a !== 'string' || typeof b !== 'string') {
+        return false;
+    }
+    // Use Buffer for timing-safe comparison
+    const bufA = Buffer.from(a, 'utf8');
+    const bufB = Buffer.from(b, 'utf8');
+    // Length must match for timingSafeEqual
+    if (bufA.length !== bufB.length) {
+        // Still perform comparison to avoid timing attack on length
+        const paddedB = Buffer.alloc(bufA.length);
+        bufB.copy(paddedB, 0, 0, Math.min(bufA.length, bufB.length));
+        timingSafeEqual(bufA, paddedB);
+        return false;
+    }
+    return timingSafeEqual(bufA, bufB);
+}
+/**
+ * Validate debug authentication token
+ *
+ * @param providedToken - Token provided in request
+ * @param expectedToken - Expected token from configuration
+ * @returns true if tokens match
+ */
+export function validateDebugToken(providedToken, expectedToken) {
+    if (!providedToken || !expectedToken) {
+        return false;
+    }
+    return secureCompare(providedToken, expectedToken);
+}
+/**
+ * Check if debug endpoints are allowed for this request
+ *
+ * Validates:
+ * 1. Debug endpoints are enabled in current security mode
+ * 2. Request comes from localhost (if bind address is restricted)
+ * 3. Valid debug token is provided (if required)
+ *
+ * @param req - The incoming HTTP request
+ * @param requestId - Optional request ID for logging
+ * @returns Access result indicating if request is allowed
+ */
+export function checkDebugAccess(req, requestId) {
+    const config = getSecurityConfig();
+    const mode = getSecurityMode();
+    const clientIp = getClientIp(req);
+    // Create base result
+    const createResult = (allowed, reason) => ({
+        allowed,
+        reason,
+        clientIp,
+        requestId,
+    });
+    // Check if debug endpoints are allowed
+    if (!config.allowDebugEndpoints) {
+        logger.warn({ clientIp, mode, requestId }, 'Debug endpoint access denied: debug endpoints disabled in current mode');
+        return createResult(false, `Debug endpoints are disabled in ${mode} mode`);
+    }
+    // Check localhost restriction (development mode)
+    const bindAddress = config.debugEndpointBindAddress;
+    if (bindAddress === '127.0.0.1' && !isLocalhost(clientIp)) {
+        logger.warn({ clientIp, bindAddress, requestId }, 'Debug endpoint access denied: request not from localhost');
+        return createResult(false, 'Debug endpoints are only accessible from localhost');
+    }
+    // Check debug token authentication
+    if (config.requireDebugAuth) {
+        const expectedToken = getDebugToken();
+        if (!expectedToken) {
+            logger.error({ requestId }, 'Debug authentication required but VORION_DEBUG_TOKEN not configured');
+            return createResult(false, 'Debug authentication not configured');
+        }
+        const headerName = DEFAULT_DEBUG_TOKEN_HEADER.toLowerCase();
+        const providedToken = req.headers[headerName];
+        if (!providedToken) {
+            logger.warn({ clientIp, requestId }, 'Debug endpoint access denied: missing debug token');
+            return createResult(false, 'Debug authentication required');
+        }
+        if (!validateDebugToken(providedToken, expectedToken)) {
+            logger.warn({ clientIp, requestId }, 'Debug endpoint access denied: invalid debug token');
+            return createResult(false, 'Invalid debug token');
+        }
+    }
+    // Access granted - log successful access
+    logger.info({ clientIp, mode, requestId, path: req.url }, 'Debug endpoint access granted');
+    return createResult(true);
+}
+/**
+ * Express-style middleware for debug endpoint authentication
+ *
+ * @example
+ * ```typescript
+ * import { debugAuthMiddleware } from './debug-auth-middleware';
+ *
+ * app.use('/debug', debugAuthMiddleware);
+ * app.get('/debug/info', (req, res) => {
+ *   res.json({ status: 'ok' });
+ * });
+ * ```
+ */
+export function debugAuthMiddleware(req, res, next) {
+    const result = checkDebugAccess(req, req.requestId);
+    if (!result.allowed) {
+        res.statusCode = 401;
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify({
+            error: 'Unauthorized',
+            message: result.reason || 'Debug access denied',
+            requestId: result.requestId,
+        }));
+        return;
+    }
+    next();
+}
+/**
+ * Create a debug endpoint handler with built-in authentication
+ *
+ * @param handler - The actual debug handler to wrap
+ * @returns Wrapped handler with authentication
+ */
+export function createSecureDebugHandler(handler) {
+    return async (req, res) => {
+        const requestId = req.requestId;
+        const result = checkDebugAccess(req, requestId);
+        if (!result.allowed) {
+            res.statusCode = 401;
+            res.setHeader('Content-Type', 'application/json');
+            res.end(JSON.stringify({
+                error: 'Unauthorized',
+                message: result.reason || 'Debug access denied',
+                requestId: result.requestId,
+            }));
+            return;
+        }
+        await handler(req, res);
+    };
+}
+/**
+ * Configuration for debug server binding
+ *
+ * Returns the appropriate bind address based on security mode
+ */
+export function getDebugBindAddress() {
+    const config = getSecurityConfig();
+    // Always bind to localhost in development (if configured)
+    if (config.debugEndpointBindAddress) {
+        return config.debugEndpointBindAddress;
+    }
+    // Default to localhost for safety
+    if (isDevelopmentMode()) {
+        return '127.0.0.1';
+    }
+    // In production/staging, debug endpoints should be disabled
+    // but if they're somehow enabled, still bind to localhost
+    logger.warn('Debug bind address requested in non-development mode, defaulting to localhost');
+    return '127.0.0.1';
+}
+/**
+ * Validate debug configuration at startup
+ *
+ * Checks that debug endpoints are properly configured
+ */
+export function validateDebugConfig() {
+    const config = getSecurityConfig();
+    const mode = getSecurityMode();
+    const warnings = [];
+    if (config.allowDebugEndpoints) {
+        // Check if debug token is configured when auth is required
+        if (config.requireDebugAuth && !getDebugToken()) {
+            warnings.push(`Debug authentication is required but ${DEBUG_TOKEN_ENV_VAR} is not set. ` +
+                'Debug endpoints will be inaccessible.');
+        }
+        // Warn if debug endpoints are enabled in staging/production
+        if (mode === 'staging') {
+            warnings.push('Debug endpoints are enabled in staging mode. ' +
+                'Consider disabling them for better security.');
+        }
+        else if (mode === 'production') {
+            warnings.push('WARNING: Debug endpoints are enabled in production mode. ' +
+                'This is a security risk and should be disabled.');
+        }
+        // Check bind address configuration
+        if (!config.debugEndpointBindAddress || config.debugEndpointBindAddress !== '127.0.0.1') {
+            warnings.push('Debug endpoints are not restricted to localhost. ' +
+                'Set debugEndpointBindAddress to "127.0.0.1" for security.');
+        }
+    }
+    // Log warnings
+    for (const warning of warnings) {
+        logger.warn({ mode }, warning);
+    }
+    return {
+        valid: warnings.length === 0,
+        warnings,
+    };
+}
+/**
+ * Generate a secure debug token for configuration
+ *
+ * @returns A random 32-byte hex string suitable for use as debug token
+ */
+export function generateDebugToken() {
+    const { randomBytes } = require('crypto');
+    return randomBytes(32).toString('hex');
+}
+//# sourceMappingURL=debug-auth-middleware.js.map

package/dist/common/debug-auth-middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-auth-middleware.js","sourceRoot":"","sources":["../../src/common/debug-auth-middleware.ts"],"names":[],"mappings":"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"}

package/dist/common/di.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Dependency Injection Utilities
+ *
+ * Provides interfaces and factory helpers for dependency injection,
+ * replacing service locator anti-pattern with explicit dependency injection.
+ *
+ * @packageDocumentation
+ */
+import type { Pool } from 'pg';
+import type { Redis } from 'ioredis';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type { Config } from './config.js';
+/**
+ * Database dependency interface
+ */
+export interface IDatabase {
+    /** Drizzle ORM database instance */
+    db: NodePgDatabase;
+    /** Raw PostgreSQL pool (optional, for low-level operations) */
+    pool?: Pool | null;
+}
+/**
+ * Redis dependency interface
+ */
+export interface IRedis {
+    /** Redis client instance */
+    client: Redis;
+    /** Create a duplicate connection for workers */
+    duplicate(): Redis;
+}
+/**
+ * Configuration dependency interface
+ */
+export interface IConfig {
+    /** Full application configuration */
+    config: Config;
+}
+/**
+ * Core dependencies bundle - combines all common dependencies
+ */
+export interface CoreDependencies {
+    /** Database connection */
+    database: NodePgDatabase;
+    /** Redis client */
+    redis: Redis;
+    /** Application configuration */
+    config: Config;
+    /** Optional raw database pool */
+    pool?: Pool | null;
+}
+/**
+ * Partial dependencies for services that don't need everything
+ */
+export type PartialDependencies = Partial<CoreDependencies>;
+/**
+ * Dependency container for managing application dependencies.
+ *
+ * This is a simple container that allows registering and retrieving dependencies.
+ * For most use cases, prefer passing dependencies directly to constructors.
+ *
+ * Use this container only when:
+ * - Multiple services need the same dependencies
+ * - You need late binding of dependencies
+ * - You're migrating from service locators incrementally
+ */
+export declare class DependencyContainer {
+    private dependencies;
+    /**
+     * Register a dependency
+     */
+    register<T>(key: string, dependency: T): void;
+    /**
+     * Get a dependency
+     * @throws Error if dependency not found
+     */
+    get<T>(key: string): T;
+    /**
+     * Get a dependency or undefined if not found
+     */
+    getOptional<T>(key: string): T | undefined;
+    /**
+     * Check if a dependency is registered
+     */
+    has(key: string): boolean;
+    /**
+     * Clear all dependencies (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Get all registered dependency keys
+     */
+    keys(): string[];
+}
+/**
+ * Well-known dependency keys for type-safe registration
+ */
+export declare const DependencyKeys: {
+    readonly DATABASE: "database";
+    readonly REDIS: "redis";
+    readonly CONFIG: "config";
+    readonly POOL: "pool";
+    readonly LOGGER: "logger";
+};
+export type DependencyKey = (typeof DependencyKeys)[keyof typeof DependencyKeys];
+/**
+ * Creates a factory function with pre-bound dependencies.
+ *
+ * This is useful for creating services that need dependencies but also
+ * want to allow overrides for testing.
+ *
+ * @example
+ * ```typescript
+ * const createService = withDependencies(
+ *   (deps: CoreDependencies) => new MyService(deps.database, deps.redis),
+ *   () => getDefaultDependencies()
+ * );
+ *
+ * // Use with defaults
+ * const service = createService();
+ *
+ * // Override for testing
+ * const testService = createService({ redis: mockRedis });
+ * ```
+ */
+export declare function withDependencies<T, D extends PartialDependencies>(factory: (deps: D) => T, getDefaults: () => D): (overrides?: Partial<D>) => T;
+/**
+ * Type guard to check if an object has all required dependencies
+ */
+export declare function hasRequiredDependencies<K extends string>(deps: PartialDependencies, required: readonly K[]): deps is PartialDependencies & Record<K, NonNullable<unknown>>;
+/**
+ * Creates a lazy-initialized dependency.
+ *
+ * The factory function is called only once on first access.
+ * Subsequent accesses return the cached value.
+ *
+ * @example
+ * ```typescript
+ * const lazyDb = lazy(() => getDatabase());
+ *
+ * // First call initializes
+ * const db1 = lazyDb();
+ *
+ * // Subsequent calls return cached value
+ * const db2 = lazyDb();
+ * ```
+ */
+export declare function lazy<T>(factory: () => T): () => T;
+/**
+ * Creates an async lazy-initialized dependency.
+ *
+ * @example
+ * ```typescript
+ * const lazyConnection = lazyAsync(async () => connectToDatabase());
+ *
+ * // First call initializes
+ * const conn1 = await lazyConnection();
+ *
+ * // Subsequent calls return cached promise
+ * const conn2 = await lazyConnection();
+ * ```
+ */
+export declare function lazyAsync<T>(factory: () => Promise<T>): () => Promise<T>;
+/**
+ * Creates a mock dependency container for testing.
+ *
+ * @example
+ * ```typescript
+ * const mocks = createMockDependencies({
+ *   database: mockDatabase,
+ *   redis: mockRedis,
+ * });
+ * ```
+ */
+export declare function createMockDependencies(overrides?: PartialDependencies): CoreDependencies;
+/**
+ * Verify that all required dependencies are provided.
+ * Throws descriptive error if any are missing.
+ */
+export declare function validateDependencies<K extends string>(deps: Record<string, unknown>, required: readonly K[], serviceName: string): void;
+/**
+ * Default global container instance.
+ *
+ * IMPORTANT: Prefer explicit dependency injection over using this container.
+ * This is provided for gradual migration from service locators.
+ */
+export declare const defaultContainer: DependencyContainer;
+/**
+ * Marker interface for injectable classes.
+ * Used for documentation and potential future decorator support.
+ */
+export interface Injectable {
+    readonly __injectable?: true;
+}
+/**
+ * Type for a class constructor that takes dependencies
+ */
+export type InjectableConstructor<T, D> = new (deps: D) => T;
+/**
+ * Type for a factory function that creates a service
+ */
+export type ServiceFactory<T, D = PartialDependencies> = (deps: D) => T;
+//# sourceMappingURL=di.d.ts.map

package/dist/common/di.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"di.d.ts","sourceRoot":"","sources":["../../src/common/di.ts"],"names":[],"mappings":"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"}