@morojs/moro 1.8.12 → 1.8.13

package/dist/core/config/index.js

@@ -23,6 +23,23 @@ import { loadConfigFromAllSources, loadConfigFromAllSourcesAsync } from './confi
 import { initializeAndLockConfig, getGlobalConfig as getConfig, isConfigLocked, resetConfigForTesting, } from './config-manager.js';
 import { createFrameworkLogger } from '../logger/index.js';
 const logger = createFrameworkLogger('ConfigSystem');
+/**
+ * Configuration is one-per-process: the first createApp() locks it and every
+ * later createApp() in the same process (or worker thread) receives that
+ * same config. A second app that passes its OWN options (another port, TLS,
+ * ...) would otherwise silently boot with the first app's settings, so name
+ * the ignored keys at ERROR rather than a debug line nobody sees.
+ */
+function warnIgnoredOptions(options) {
+    const ignored = options ? Object.keys(options).filter(k => k !== 'logger') : [];
+    if (ignored.length === 0) {
+        logger.debug('Configuration already locked, returning existing config');
+        return;
+    }
+    logger.error(`createApp() called again after the configuration was locked; ignoring options [${ignored.join(', ')}]. ` +
+        'MoroJS keeps one configuration per process: the first createApp() wins and later apps share it. ' +
+        'Run a second differently-configured app in its own process.', 'ConfigLock');
+}
 /**
  * Initialize configuration system with createApp options
  * This is the main entry point called by createApp()
@@ -32,7 +49,7 @@ const logger = createFrameworkLogger('ConfigSystem');
  */
 export function initializeConfig(options) {
     if (isConfigLocked()) {
-        logger.debug('Configuration already locked, returning existing config');
+        warnIgnoredOptions(options);
         return getConfig();
     }
     logger.debug('Initializing configuration system');
@@ -53,7 +70,7 @@ export function initializeConfig(options) {
  */
 export async function initializeConfigAsync(options) {
     if (isConfigLocked()) {
-        logger.debug('Configuration already locked, returning existing config');
+        warnIgnoredOptions(options);
         return getConfig();
     }
     logger.debug('Initializing configuration system (async)');

package/dist/core/config/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/config/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,mCAAmC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AAGjC,mEAAmE;AACnE,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,8CAA8C;AAC9C,cAAc,YAAY,CAAC;AAI3B,OAAO,EAAE,wBAAwB,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAC9F,OAAO,EACL,uBAAuB,EACvB,eAAe,IAAI,SAAS,EAC5B,cAAc,EACd,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,MAAM,GAAG,qBAAqB,CAAC,cAAc,CAAC,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAqB;IACpD,IAAI,cAAc,EAAE,EAAE,CAAC;QACrB,MAAM,CAAC,KAAK,CAAC,yDAAyD,CAAC,CAAC;QACxE,OAAO,SAAS,EAAE,CAAC;IACrB,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;IAElD,6DAA6D;IAC7D,MAAM,MAAM,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAEjD,oDAAoD;IACpD,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAEhC,MAAM,CAAC,IAAI,CACT,gDAAgD,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,aAAa,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,6CAA6C,CACzJ,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,OAAqB;IAC/D,IAAI,cAAc,EAAE,EAAE,CAAC;QACrB,MAAM,CAAC,KAAK,CAAC,yDAAyD,CAAC,CAAC;QACxE,OAAO,SAAS,EAAE,CAAC;IACrB,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAE1D,MAAM,MAAM,GAAG,MAAM,6BAA6B,CAAC,OAAO,CAAC,CAAC;IAE5D,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAEhC,MAAM,CAAC,IAAI,CACT,gDAAgD,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,aAAa,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,6CAA6C,CACzJ,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,wBAAwB,EAAE,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAoB;IACxD,OAAO,wBAAwB,CAAC,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,SAAS,EAAE,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,cAAc,EAAE,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,qBAAqB,EAAE,CAAC;AAC1B,CAAC","sourcesContent":["/**\n * Configuration System - Immutable Config with createApp Override Support\n *\n * This is the main entry point for the MoroJS configuration system.\n * It provides a clean, immutable configuration that is locked at createApp() time.\n *\n * Key Features:\n * - Immutable configuration after initialization\n * - Clear precedence: Env Vars > createApp Options > Config File > Defaults\n * - Type-safe validation\n * - Single source of truth\n */\n\n// Export types and core components\nexport * from './schema.js';\nexport * from './config-sources.js';\nexport * from './config-validator.js';\nexport * from './file-loader.js';\nexport type { OriginFunction } from '../../types/config.js';\n\n// Export specific functions from config-manager to avoid conflicts\nexport {\n  initializeAndLockConfig,\n  isConfigLocked,\n  resetConfigForTesting,\n} from './config-manager.js';\n\n// Export utilities for backward compatibility\nexport * from './utils.js';\n\nimport { MoroOptions } from '../../types/core.js';\nimport { AppConfig } from '../../types/config.js';\nimport { loadConfigFromAllSources, loadConfigFromAllSourcesAsync } from './config-sources.js';\nimport {\n  initializeAndLockConfig,\n  getGlobalConfig as getConfig,\n  isConfigLocked,\n  resetConfigForTesting,\n} from './config-manager.js';\nimport { createFrameworkLogger } from '../logger/index.js';\n\nconst logger = createFrameworkLogger('ConfigSystem');\n\n/**\n * Initialize configuration system with createApp options\n * This is the main entry point called by createApp()\n *\n * @param options - createApp options that can override config file and defaults\n * @returns Immutable, validated configuration object\n */\nexport function initializeConfig(options?: MoroOptions): Readonly<AppConfig> {\n  if (isConfigLocked()) {\n    logger.debug('Configuration already locked, returning existing config');\n    return getConfig();\n  }\n\n  logger.debug('Initializing configuration system');\n\n  // Load configuration from all sources with proper precedence\n  const config = loadConfigFromAllSources(options);\n\n  // Lock the configuration to prevent further changes\n  initializeAndLockConfig(config);\n\n  logger.info(\n    `Configuration system initialized and locked: ${process.env.NODE_ENV || 'development'}:${config.server.port} (sources: env + file + options + defaults)`\n  );\n\n  return config;\n}\n\n/**\n * Initialize configuration system asynchronously.\n * Uses dynamic import() for the config file — supports ESM config files in\n * projects with \"type\":\"module\". Called internally by the async createApp().\n *\n * @param options - createApp options that can override config file and defaults\n * @returns Immutable, validated configuration object\n */\nexport async function initializeConfigAsync(options?: MoroOptions): Promise<Readonly<AppConfig>> {\n  if (isConfigLocked()) {\n    logger.debug('Configuration already locked, returning existing config');\n    return getConfig();\n  }\n\n  logger.debug('Initializing configuration system (async)');\n\n  const config = await loadConfigFromAllSourcesAsync(options);\n\n  initializeAndLockConfig(config);\n\n  logger.info(\n    `Configuration system initialized and locked: ${process.env.NODE_ENV || 'development'}:${config.server.port} (sources: env + file + options + defaults)`\n  );\n\n  return config;\n}\n\n/**\n * Load configuration without locking (for testing and utilities)\n * This maintains backward compatibility with existing code\n */\nexport function loadConfig(): AppConfig {\n  return loadConfigFromAllSources();\n}\n\n/**\n * Load configuration with createApp options (for testing and utilities)\n * This maintains backward compatibility with existing code\n */\nexport function loadConfigWithOptions(options: MoroOptions): AppConfig {\n  return loadConfigFromAllSources(options);\n}\n\n/**\n * Get the current global configuration\n * Alias for getGlobalConfig() for backward compatibility\n */\nexport function getGlobalConfig(): Readonly<AppConfig> {\n  return getConfig();\n}\n\n/**\n * Check if configuration has been initialized and locked\n * Alias for isConfigLocked() for backward compatibility\n */\nexport function isConfigInitialized(): boolean {\n  return isConfigLocked();\n}\n\n/**\n * Reset configuration state (for testing only)\n * @internal\n */\nexport function resetConfig(): void {\n  resetConfigForTesting();\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/config/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Configuration System - Immutable Config with createApp Override Support\n *\n * This is the main entry point for the MoroJS configuration system.\n * It provides a clean, immutable configuration that is locked at createApp() time.\n *\n * Key Features:\n * - Immutable configuration after initialization\n * - Clear precedence: Env Vars > createApp Options > Config File > Defaults\n * - Type-safe validation\n * - Single source of truth\n */\n\n// Export types and core components\nexport * from './schema.js';\nexport * from './config-sources.js';\nexport * from './config-validator.js';\nexport * from './file-loader.js';\nexport type { OriginFunction } from '../../types/config.js';\n\n// Export specific functions from config-manager to avoid conflicts\nexport {\n  initializeAndLockConfig,\n  isConfigLocked,\n  resetConfigForTesting,\n} from './config-manager.js';\n\n// Export utilities for backward compatibility\nexport * from './utils.js';\n\nimport { MoroOptions } from '../../types/core.js';\nimport { AppConfig } from '../../types/config.js';\nimport { loadConfigFromAllSources, loadConfigFromAllSourcesAsync } from './config-sources.js';\nimport {\n  initializeAndLockConfig,\n  getGlobalConfig as getConfig,\n  isConfigLocked,\n  resetConfigForTesting,\n} from './config-manager.js';\nimport { createFrameworkLogger } from '../logger/index.js';\n\nconst logger = createFrameworkLogger('ConfigSystem');\n\n/**\n * Configuration is one-per-process: the first createApp() locks it and every\n * later createApp() in the same process (or worker thread) receives that\n * same config. A second app that passes its OWN options (another port, TLS,\n * ...) would otherwise silently boot with the first app's settings, so name\n * the ignored keys at ERROR rather than a debug line nobody sees.\n */\nfunction warnIgnoredOptions(options?: MoroOptions): void {\n  const ignored = options ? Object.keys(options).filter(k => k !== 'logger') : [];\n  if (ignored.length === 0) {\n    logger.debug('Configuration already locked, returning existing config');\n    return;\n  }\n  logger.error(\n    `createApp() called again after the configuration was locked; ignoring options [${ignored.join(', ')}]. ` +\n      'MoroJS keeps one configuration per process: the first createApp() wins and later apps share it. ' +\n      'Run a second differently-configured app in its own process.',\n    'ConfigLock'\n  );\n}\n\n/**\n * Initialize configuration system with createApp options\n * This is the main entry point called by createApp()\n *\n * @param options - createApp options that can override config file and defaults\n * @returns Immutable, validated configuration object\n */\nexport function initializeConfig(options?: MoroOptions): Readonly<AppConfig> {\n  if (isConfigLocked()) {\n    warnIgnoredOptions(options);\n    return getConfig();\n  }\n\n  logger.debug('Initializing configuration system');\n\n  // Load configuration from all sources with proper precedence\n  const config = loadConfigFromAllSources(options);\n\n  // Lock the configuration to prevent further changes\n  initializeAndLockConfig(config);\n\n  logger.info(\n    `Configuration system initialized and locked: ${process.env.NODE_ENV || 'development'}:${config.server.port} (sources: env + file + options + defaults)`\n  );\n\n  return config;\n}\n\n/**\n * Initialize configuration system asynchronously.\n * Uses dynamic import() for the config file — supports ESM config files in\n * projects with \"type\":\"module\". Called internally by the async createApp().\n *\n * @param options - createApp options that can override config file and defaults\n * @returns Immutable, validated configuration object\n */\nexport async function initializeConfigAsync(options?: MoroOptions): Promise<Readonly<AppConfig>> {\n  if (isConfigLocked()) {\n    warnIgnoredOptions(options);\n    return getConfig();\n  }\n\n  logger.debug('Initializing configuration system (async)');\n\n  const config = await loadConfigFromAllSourcesAsync(options);\n\n  initializeAndLockConfig(config);\n\n  logger.info(\n    `Configuration system initialized and locked: ${process.env.NODE_ENV || 'development'}:${config.server.port} (sources: env + file + options + defaults)`\n  );\n\n  return config;\n}\n\n/**\n * Load configuration without locking (for testing and utilities)\n * This maintains backward compatibility with existing code\n */\nexport function loadConfig(): AppConfig {\n  return loadConfigFromAllSources();\n}\n\n/**\n * Load configuration with createApp options (for testing and utilities)\n * This maintains backward compatibility with existing code\n */\nexport function loadConfigWithOptions(options: MoroOptions): AppConfig {\n  return loadConfigFromAllSources(options);\n}\n\n/**\n * Get the current global configuration\n * Alias for getGlobalConfig() for backward compatibility\n */\nexport function getGlobalConfig(): Readonly<AppConfig> {\n  return getConfig();\n}\n\n/**\n * Check if configuration has been initialized and locked\n * Alias for isConfigLocked() for backward compatibility\n */\nexport function isConfigInitialized(): boolean {\n  return isConfigLocked();\n}\n\n/**\n * Reset configuration state (for testing only)\n * @internal\n */\nexport function resetConfig(): void {\n  resetConfigForTesting();\n}\n"]}

package/dist/core/framework.d.ts

@@ -5,6 +5,7 @@ import { MoroEngineServer } from './http/moro-engine-server.js';
 import { MoroHttp2Server, Http2ServerOptions } from './http/http2-server.js';
 import { Container } from './utilities/index.js';
 import { WebSocketManager } from './networking/websocket-manager.js';
+import { type SSLConfigInput } from './http/utils/ssl-config.js';
 import { ModuleConfig } from '../types/module.js';
 import { MoroOptions as CoreMoroOptions } from '../types/core.js';
 import { WebSocketAdapter, WebSocketAdapterOptions } from './networking/websocket-adapter.js';
@@ -56,6 +57,12 @@ export declare class Moro extends EventEmitter {
     private usingEngine;
     private usingHttp2;
     private engineInfo;
+    /** The normalized server.ssl in effect (updated by reloadTLS) */
+    private sslConfig;
+    private tlsWatchers;
+    private tlsWatchTimer;
+    /** Hash of the last key/cert/CA bytes loaded from disk (skips no-op reloads) */
+    private tlsMaterialHash;
     private websocketSetupPromise;
     constructor(options?: MoroOptions);
     use(middleware: any): this;
@@ -116,6 +123,25 @@ export declare class Moro extends EventEmitter {
     setupFinalModuleHandler(): void;
     private setupWebSocketHandlers;
     private checkRateLimit;
+    /**
+     * Rotate the TLS certificate/key on the running listener. The new material
+     * is validated (files readable, PEM parses, key matches cert) BEFORE the
+     * listener is touched, so a half-written file or a wrong pair rejects and
+     * the current certificate keeps serving; connections that already
+     * handshaked are never affected. Policy fields (minVersion, mTLS flags,
+     * passphrase) and the CA carry over unless the update sets them.
+     */
+    reloadTLS(ssl?: SSLConfigInput): Promise<void>;
+    /**
+     * `server.ssl.watch`: reload the certificate when its files change on disk.
+     * The DIRECTORIES holding the files are watched (an ACME client or a
+     * Kubernetes secret mount replaces files by rename/symlink swap, which a
+     * per-file watcher misses), changes are debounced, unchanged bytes are
+     * ignored, and a failed reload is logged while the current certificate
+     * keeps serving. Watchers are non-persistent and closed by stopTlsWatch().
+     */
+    startTlsWatch(): void;
+    stopTlsWatch(): void;
     /**
      * Which HTTP server backs this app, which package provides it, and the
      * fallback reason when the native engine was requested but unavailable.

package/dist/core/framework.js

@@ -1,5 +1,8 @@
 import crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
 import { EventEmitter } from 'events';
+import { requireBuiltin } from './utilities/builtin.js';
 import { MoroHttpServer } from './http/index.js';
 import { UWebSocketsHttpServer } from './http/uws-http-server.js';
 import { MoroEngineServer } from './http/moro-engine-server.js';
@@ -11,7 +14,7 @@ import { WebSocketManager } from './networking/websocket-manager.js';
 import { CircuitBreaker } from './utilities/circuit-breaker.js';
 import { isPackageAvailable, loadNativeEngine, getNativeEngineLoadErrors, } from './utilities/package-utils.js';
 import { parseSizeToBytes } from './http/utils/size.js';
-import { normalizeSSLConfig, sslForNode, sslForUws, sslIsComplete, } from './http/utils/ssl-config.js';
+import { normalizeSSLConfig, sslForEngine, sslForNode, sslForUws, sslIsComplete, } from './http/utils/ssl-config.js';
 import { MoroEventBus } from './events/index.js';
 import { createFrameworkLogger, logger as globalLogger } from './logger/index.js';
 import { mergeWebSocketConfig, } from './networking/websocket-adapter.js';
@@ -38,6 +41,12 @@ export class Moro extends EventEmitter {
     usingHttp2 = false;
     // Which server actually booted (engine = native uWS-style engine)
     engineInfo = { server: 'node' };
+    /** The normalized server.ssl in effect (updated by reloadTLS) */
+    sslConfig = null;
+    tlsWatchers = [];
+    tlsWatchTimer;
+    /** Hash of the last key/cert/CA bytes loaded from disk (skips no-op reloads) */
+    tlsMaterialHash;
     // WebSocket initialization promise to handle async adapter detection
     websocketSetupPromise = null;
     constructor(options = {}) {
@@ -73,6 +82,7 @@ export class Moro extends EventEmitter {
         // projected per-runtime, so a single server.ssl / server.limits flows
         // everywhere regardless of which server boots.
         const ssl = normalizeSSLConfig(this.config.server?.ssl, options.https, this.logger);
+        this.sslConfig = ssl;
         const rt = this.buildRuntimeLimits();
         if (engineChoice.kind === 'engine') {
             try {
@@ -84,7 +94,10 @@ export class Moro extends EventEmitter {
                 if (typeof engineSurface?.serve === 'function' &&
                     typeof engineSurface?.respond === 'function') {
                     this.httpServer = new MoroEngineServer({
-                        ssl,
+                        // Project to the engine's own option names (key_file_name / key,
+                        // ...). The normalized shape's keyFile/certFile mean nothing to
+                        // serve(), which would throw and silently fall back to Node https.
+                        ...(ssl ? { ssl: sslForEngine(ssl) } : {}),
                         limits: rt,
                         maxBodySize: rt.maxBodySize,
                         maxUploadSize: rt.maxUploadSize,
@@ -124,7 +137,10 @@ export class Moro extends EventEmitter {
                 // Construction failed after a successful module load - unexpected, but
                 // never boot nothing: fall back to the Node.js http server.
                 const reason = error instanceof Error ? error.message : String(error);
-                this.logger.warn(`Native engine (${engineChoice.requested}) failed to initialize, falling back to Node.js http.Server. Error: ${reason}`, 'ServerInit');
+                // With TLS configured this is almost always a certificate/key problem,
+                // and a deployment tuned for the engine would otherwise run on a
+                // different server behind a warning buried among INFO lines.
+                this.logger[ssl ? 'error' : 'warn'](`Native engine (${engineChoice.requested}) failed to initialize, falling back to Node.js http.Server. Error: ${reason}`, 'ServerInit');
                 this.usingUWebSockets = false;
                 this.usingEngine = false;
                 this.engineInfo = { server: 'node', fallbackReason: reason };
@@ -987,6 +1003,162 @@ export class Moro extends EventEmitter {
         limit.count++;
         return true;
     }
+    /**
+     * Rotate the TLS certificate/key on the running listener. The new material
+     * is validated (files readable, PEM parses, key matches cert) BEFORE the
+     * listener is touched, so a half-written file or a wrong pair rejects and
+     * the current certificate keeps serving; connections that already
+     * handshaked are never affected. Policy fields (minVersion, mTLS flags,
+     * passphrase) and the CA carry over unless the update sets them.
+     */
+    async reloadTLS(ssl) {
+        const current = this.sslConfig;
+        if (!current) {
+            throw new Error('reloadTLS: this app was not started with TLS (server.ssl)');
+        }
+        if (this.usingUWebSockets) {
+            throw new Error('reloadTLS is not supported on the uWebSockets.js engine');
+        }
+        let next;
+        if (ssl) {
+            const update = normalizeSSLConfig(ssl, undefined, this.logger);
+            if (!update || !sslIsComplete(update)) {
+                throw new Error('reloadTLS: ssl must carry both a key and a certificate');
+            }
+            const hasCa = Boolean(update.ca || update.caFile);
+            next = {
+                // operator policy carries over...
+                passphrase: current.passphrase,
+                minVersion: current.minVersion,
+                requestCert: current.requestCert,
+                rejectUnauthorized: current.rejectUnauthorized,
+                // ...as does the CA when the update names none
+                ...(hasCa ? {} : { ca: current.ca, caFile: current.caFile }),
+                // and the update's own fields win (undefined entries dropped so they
+                // do not shadow the carried-over values)
+                ...Object.fromEntries(Object.entries(update).filter(([, v]) => v !== undefined)),
+            };
+        }
+        else {
+            if (!current.keyFile || !current.certFile) {
+                throw new Error('reloadTLS() with no argument re-reads the server.ssl key/cert files, but this app was configured with inline PEM - pass the new material');
+            }
+            next = { ...current };
+        }
+        // One consistent snapshot of the material, validated on every backend the
+        // same way (node's own parser: bad PEM / key-cert mismatch throw here).
+        const nodeSsl = sslForNode(next);
+        const tls = requireBuiltin('tls');
+        tls.createSecureContext(nodeSsl);
+        if (this.usingEngine) {
+            // Hand the engine the validated bytes rather than the paths, so it
+            // cannot read a different (newer, half-written) file than we checked.
+            const engineSsl = sslForEngine({
+                ...next,
+                key: nodeSsl.key,
+                cert: nodeSsl.cert,
+                ca: nodeSsl.ca,
+                keyFile: undefined,
+                certFile: undefined,
+                caFile: undefined,
+            });
+            this.httpServer.updateSsl(engineSsl);
+        }
+        else if (this.usingHttp2) {
+            this.httpServer.updateSsl(nodeSsl);
+        }
+        else {
+            this.httpServer.updateSsl(nodeSsl);
+        }
+        this.sslConfig = next;
+        this.tlsMaterialHash = MoroCoreTls.hashMaterial(nodeSsl);
+        this.logger.info('TLS certificate reloaded', 'TLS');
+    }
+    /**
+     * `server.ssl.watch`: reload the certificate when its files change on disk.
+     * The DIRECTORIES holding the files are watched (an ACME client or a
+     * Kubernetes secret mount replaces files by rename/symlink swap, which a
+     * per-file watcher misses), changes are debounced, unchanged bytes are
+     * ignored, and a failed reload is logged while the current certificate
+     * keeps serving. Watchers are non-persistent and closed by stopTlsWatch().
+     */
+    startTlsWatch() {
+        const ssl = this.sslConfig;
+        const watch = this.config.server?.ssl?.watch;
+        if (!ssl || !watch || this.tlsWatchers.length > 0)
+            return;
+        if (!ssl.keyFile || !ssl.certFile) {
+            this.logger.warn('server.ssl.watch needs keyFile/certFile paths - inline PEM cannot be watched', 'TLS');
+            return;
+        }
+        if (this.usingUWebSockets) {
+            this.logger.warn('server.ssl.watch is not supported on the uWebSockets.js engine', 'TLS');
+            return;
+        }
+        const debounceMs = typeof watch === 'object' && typeof watch.debounceMs === 'number' && watch.debounceMs > 0
+            ? watch.debounceMs
+            : 1000;
+        try {
+            this.tlsMaterialHash = MoroCoreTls.hashMaterial(sslForNode(ssl));
+        }
+        catch {
+            // unreadable now; the first change event will report properly
+        }
+        const files = [ssl.keyFile, ssl.certFile, ...(ssl.caFile ?? [])].map(f => path.resolve(f));
+        const schedule = () => {
+            if (this.tlsWatchTimer)
+                clearTimeout(this.tlsWatchTimer);
+            this.tlsWatchTimer = setTimeout(() => {
+                this.tlsWatchTimer = undefined;
+                let hash;
+                try {
+                    hash = MoroCoreTls.hashMaterial(sslForNode(this.sslConfig ?? ssl));
+                }
+                catch (err) {
+                    // Mid-rotation (one file replaced, the other not yet): wait for the
+                    // next event rather than logging a scary error per half-write.
+                    this.logger.debug(`TLS files not readable yet: ${err instanceof Error ? err.message : String(err)}`, 'TLS');
+                    return;
+                }
+                if (hash === this.tlsMaterialHash)
+                    return; // touched, not changed
+                this.reloadTLS().catch(err => {
+                    this.logger.error(`TLS reload failed; the current certificate keeps serving: ${err instanceof Error ? err.message : String(err)}`, 'TLS');
+                });
+            }, debounceMs);
+            this.tlsWatchTimer.unref?.();
+        };
+        for (const dir of new Set(files.map(f => path.dirname(f)))) {
+            try {
+                const watcher = fs.watch(dir, { persistent: false }, () => schedule());
+                watcher.on('error', err => {
+                    this.logger.warn(`TLS file watcher error on ${dir}: ${err.message}`, 'TLS');
+                });
+                this.tlsWatchers.push(watcher);
+            }
+            catch (err) {
+                this.logger.warn(`Cannot watch ${dir} for certificate changes: ${err instanceof Error ? err.message : String(err)}`, 'TLS');
+            }
+        }
+        if (this.tlsWatchers.length > 0) {
+            this.logger.info(`Watching TLS certificate files for changes (${files.length} files)`, 'TLS');
+        }
+    }
+    stopTlsWatch() {
+        if (this.tlsWatchTimer) {
+            clearTimeout(this.tlsWatchTimer);
+            this.tlsWatchTimer = undefined;
+        }
+        for (const watcher of this.tlsWatchers) {
+            try {
+                watcher.close();
+            }
+            catch {
+                // already closed
+            }
+        }
+        this.tlsWatchers = [];
+    }
     /**
      * Which HTTP server backs this app, which package provides it, and the
      * fallback reason when the native engine was requested but unavailable.
@@ -1214,14 +1386,20 @@ export class Moro extends EventEmitter {
         return this.circuitBreakers.get(key);
     }
     listen(port, host, callback) {
+        // Certificate watching (server.ssl.watch) starts once the listener is up
+        const userCb = typeof host === 'function' ? host : callback;
+        const onListening = () => {
+            this.startTlsWatch();
+            userCb?.();
+        };
         if (typeof host === 'function') {
-            this.httpServer.listen(port, host);
+            this.httpServer.listen(port, onListening);
         }
         else if (host) {
-            this.httpServer.listen(port, host, callback);
+            this.httpServer.listen(port, host, onListening);
         }
         else {
-            this.httpServer.listen(port, callback);
+            this.httpServer.listen(port, onListening);
         }
     }
     // Compatibility method for existing controllers
@@ -1238,4 +1416,15 @@ export class Moro extends EventEmitter {
         return undefined;
     }
 }
+/** TLS helpers kept out of the class body (no per-instance state). */
+const MoroCoreTls = {
+    hashMaterial(ssl) {
+        const h = crypto.createHash('sha256');
+        h.update(ssl.key);
+        h.update(ssl.cert);
+        for (const ca of ssl.ca ?? [])
+            h.update(ca);
+        return h.digest('hex');
+    },
+};
 //# sourceMappingURL=framework.js.map