@digitaldefiance/node-express-suite 3.12.12 → 3.12.13

package/src/plugins/upnp.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * UPnP Plugin for the express-suite plugin system.
+ *
+ * Integrates the UPnP port mapping lifecycle (UpnpManager) with the
+ * application plugin system. Register this plugin to automatically
+ * manage UPnP port mappings during application startup and shutdown.
+ *
+ * Requirements: 5.1, 5.2, 5.3, 5.4, 5.5
+ *
+ * @module plugins/upnp
+ *
+ * @example
+ * ```typescript
+ * import { UpnpPlugin } from '@digitaldefiance/node-express-suite';
+ *
+ * // Register with defaults (reads config from environment)
+ * app.plugins.register(new UpnpPlugin());
+ *
+ * // Register with config overrides
+ * app.plugins.register(new UpnpPlugin({
+ *   config: { enabled: true, httpPort: 8080 },
+ *   descriptionPrefix: 'My App',
+ * }));
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpnpPlugin = void 0;
+const upnp_config_1 = require("../services/upnp-config");
+const upnp_manager_1 = require("../services/upnp-manager");
+/**
+ * UPnP plugin implementing {@link IApplicationPlugin}.
+ *
+ * Manages UPnP port mapping lifecycle through the express-suite plugin system.
+ * On `init`, reads configuration (from environment or overrides) and starts
+ * the UpnpManager. On `stop`, shuts down the manager and removes mappings.
+ *
+ * @template TID - Platform ID type (defaults to Buffer)
+ *
+ * @example
+ * ```typescript
+ * const plugin = new UpnpPlugin({ descriptionPrefix: 'My App' });
+ * pluginManager.register(plugin);
+ *
+ * // After init, access the manager for endpoint queries
+ * const endpoints = await plugin.getManager()?.getExternalEndpoints();
+ * ```
+ */
+class UpnpPlugin {
+    name = 'upnp';
+    version = '1.0.0';
+    manager = null;
+    options;
+    /**
+     * Create a new UpnpPlugin.
+     *
+     * @param options - Optional plugin configuration
+     */
+    constructor(options) {
+        this.options = options ?? {};
+    }
+    /**
+     * Initialize the UPnP plugin.
+     *
+     * Builds configuration from environment variables (with optional overrides),
+     * creates a UpnpManager, and initializes port mappings.
+     *
+     * If UPnP is disabled in the configuration, skips initialization and logs
+     * a message.
+     *
+     * **Validates: Requirements 5.2, 5.4, 5.5**
+     *
+     * @param _app - The application instance (unused, config comes from env)
+     */
+    async init(_app) {
+        // Build config: use override if provided, else load from environment
+        const config = this.options.config
+            ? upnp_config_1.UpnpConfig.fromEnvironment({
+                ...process.env,
+                ...this.envOverridesFromConfig(this.options.config),
+            })
+            : upnp_config_1.UpnpConfig.fromEnvironment();
+        if (!config.enabled) {
+            console.log('[UPnP Plugin] UPnP is disabled, skipping initialization');
+            return;
+        }
+        this.manager = new upnp_manager_1.UpnpManager({
+            config,
+            descriptionPrefix: this.options.descriptionPrefix,
+        });
+        await this.manager.initialize();
+    }
+    /**
+     * Stop the UPnP plugin.
+     *
+     * Shuts down the UpnpManager, removing all port mappings and cleaning up.
+     *
+     * **Validates: Requirement 5.3**
+     */
+    async stop() {
+        if (this.manager) {
+            await this.manager.shutdown();
+            this.manager = null;
+        }
+    }
+    /**
+     * Get the underlying UpnpManager instance.
+     *
+     * Returns `null` if the plugin has not been initialized or UPnP is disabled.
+     * Use this to query external endpoints or inspect manager state.
+     *
+     * @returns The UpnpManager instance, or `null` if not initialized
+     *
+     * @example
+     * ```typescript
+     * const manager = plugin.getManager();
+     * if (manager) {
+     *   const endpoints = await manager.getExternalEndpoints();
+     *   console.log(endpoints);
+     * }
+     * ```
+     */
+    getManager() {
+        return this.manager;
+    }
+    /**
+     * Convert a partial IUpnpConfig into environment variable overrides.
+     *
+     * Maps each defined config field to its corresponding `UPNP_*` environment
+     * variable name, converting values to strings. These overrides are merged
+     * with `process.env` before passing to `UpnpConfig.fromEnvironment`.
+     *
+     * @param config - Partial configuration with fields to override
+     * @returns Record of environment variable name → string value
+     */
+    envOverridesFromConfig(config) {
+        const env = {};
+        if (config.enabled !== undefined)
+            env['UPNP_ENABLED'] = String(config.enabled);
+        if (config.httpPort !== undefined)
+            env['UPNP_HTTP_PORT'] = String(config.httpPort);
+        if (config.websocketPort !== undefined)
+            env['UPNP_WEBSOCKET_PORT'] = String(config.websocketPort);
+        if (config.ttl !== undefined)
+            env['UPNP_TTL'] = String(config.ttl);
+        if (config.refreshInterval !== undefined)
+            env['UPNP_REFRESH_INTERVAL'] = String(config.refreshInterval);
+        if (config.protocol !== undefined)
+            env['UPNP_PROTOCOL'] = config.protocol;
+        if (config.retryAttempts !== undefined)
+            env['UPNP_RETRY_ATTEMPTS'] = String(config.retryAttempts);
+        if (config.retryDelay !== undefined)
+            env['UPNP_RETRY_DELAY'] = String(config.retryDelay);
+        return env;
+    }
+}
+exports.UpnpPlugin = UpnpPlugin;
+//# sourceMappingURL=upnp.js.map

package/src/plugins/upnp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upnp.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/plugins/upnp.ts"],"names":[],"mappings":"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"}

package/src/services/index.d.ts

@@ -16,4 +16,7 @@ export * from './symmetric';
 export * from './system-user';
 export * from './user';
 export * from './xor';
+export * from './upnp';
+export * from './upnp-config';
+export * from './upnp-manager';
 //# sourceMappingURL=index.d.ts.map

package/src/services/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,OAAO,CAAC;AACtB,cAAc,qBAAqB,CAAC;AACpC,cAAc,OAAO,CAAC;AACtB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,OAAO,CAAC;AACtB,cAAc,qBAAqB,CAAC;AACpC,cAAc,OAAO,CAAC;AACtB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}

package/src/services/index.js

@@ -19,4 +19,7 @@ tslib_1.__exportStar(require("./symmetric"), exports);
 tslib_1.__exportStar(require("./system-user"), exports);
 tslib_1.__exportStar(require("./user"), exports);
 tslib_1.__exportStar(require("./xor"), exports);
+tslib_1.__exportStar(require("./upnp"), exports);
+tslib_1.__exportStar(require("./upnp-config"), exports);
+tslib_1.__exportStar(require("./upnp-manager"), exports);
 //# sourceMappingURL=index.js.map

package/src/services/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/index.ts"],"names":[],"mappings":";;;AAAA,wDAA8B;AAC9B,iDAAuB;AACvB,qDAA2B;AAC3B,oEAA0C;AAC1C,0DAAgC;AAChC,+DAAqC;AACrC,gEAAsC;AACtC,gDAAsB;AACtB,8DAAoC;AACpC,gDAAsB;AACtB,yDAA+B;AAC/B,qDAA2B;AAC3B,yDAA+B;AAC/B,iDAAuB;AACvB,sDAA4B;AAC5B,wDAA8B;AAC9B,iDAAuB;AACvB,gDAAsB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/index.ts"],"names":[],"mappings":";;;AAAA,wDAA8B;AAC9B,iDAAuB;AACvB,qDAA2B;AAC3B,oEAA0C;AAC1C,0DAAgC;AAChC,+DAAqC;AACrC,gEAAsC;AACtC,gDAAsB;AACtB,8DAAoC;AACpC,gDAAsB;AACtB,yDAA+B;AAC/B,qDAA2B;AAC3B,yDAA+B;AAC/B,iDAAuB;AACvB,sDAA4B;AAC5B,wDAA8B;AAC9B,iDAAuB;AACvB,gDAAsB;AACtB,iDAAuB;AACvB,wDAA8B;AAC9B,yDAA+B"}

package/src/services/upnp-config.d.ts

@@ -0,0 +1,131 @@
+/**
+ * UPnP Configuration Loader and Validator.
+ *
+ * Reads UPnP settings from environment variables, applies defaults
+ * for missing values, and validates all configuration parameters.
+ * Use the static {@link UpnpConfig.fromEnvironment} factory method
+ * to create validated instances.
+ *
+ * Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9
+ */
+import { IUpnpConfig, UpnpProtocol } from '../interfaces/network/upnpTypes';
+/**
+ * Error thrown when UPnP configuration validation fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const config = UpnpConfig.fromEnvironment({ UPNP_HTTP_PORT: '99999' });
+ * } catch (err) {
+ *   if (err instanceof UpnpConfigValidationError) {
+ *     console.error(`Invalid config: ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class UpnpConfigValidationError extends Error {
+    /**
+     * @param message - Description of the validation failure
+     */
+    constructor(message: string);
+}
+/**
+ * UPnP configuration loaded from environment variables.
+ *
+ * Reads `UPNP_*` env vars, falls back to {@link UPNP_CONFIG_DEFAULTS},
+ * and validates all values on construction. Use the static
+ * {@link UpnpConfig.fromEnvironment} factory method to create instances.
+ *
+ * @example
+ * ```typescript
+ * // Load from process.env (production usage)
+ * const config = UpnpConfig.fromEnvironment();
+ *
+ * // Load from custom env (testing)
+ * const testConfig = UpnpConfig.fromEnvironment({
+ *   UPNP_ENABLED: 'true',
+ *   UPNP_HTTP_PORT: '8080',
+ * });
+ *
+ * console.log(config.enabled);   // false (default)
+ * console.log(config.httpPort);  // 3000 (default)
+ * ```
+ */
+export declare class UpnpConfig implements IUpnpConfig {
+    /** Whether UPnP is enabled */
+    readonly enabled: boolean;
+    /** HTTP/Express port to map externally */
+    readonly httpPort: number;
+    /** WebSocket port to map externally */
+    readonly websocketPort: number;
+    /** Mapping time-to-live in seconds */
+    readonly ttl: number;
+    /** Refresh interval in milliseconds */
+    readonly refreshInterval: number;
+    /** UPnP protocol to use (upnp, natpmp, or auto) */
+    readonly protocol: UpnpProtocol;
+    /** Number of retry attempts for failed operations */
+    readonly retryAttempts: number;
+    /** Delay between retries in milliseconds */
+    readonly retryDelay: number;
+    /**
+     * Private constructor — use {@link UpnpConfig.fromEnvironment} to create instances.
+     *
+     * @param config - Validated configuration values
+     */
+    private constructor();
+    /**
+     * Create an UpnpConfig from the current process environment.
+     * Missing variables fall back to {@link UPNP_CONFIG_DEFAULTS}.
+     *
+     * @param env - Environment variable map (defaults to `process.env`)
+     * @returns A validated UpnpConfig instance
+     * @throws {UpnpConfigValidationError} If any value is invalid
+     *
+     * @example
+     * ```typescript
+     * // Use process.env
+     * const config = UpnpConfig.fromEnvironment();
+     *
+     * // Use custom env for testing
+     * const config = UpnpConfig.fromEnvironment({
+     *   UPNP_ENABLED: 'true',
+     *   UPNP_HTTP_PORT: '8080',
+     *   UPNP_TTL: '7200',
+     * });
+     * ```
+     */
+    static fromEnvironment(env?: Record<string, string | undefined>): UpnpConfig;
+    /**
+     * Validate all configuration values. Throws on the first invalid value.
+     *
+     * @param config - The configuration object to validate
+     * @throws {UpnpConfigValidationError} If any value is outside its valid range:
+     *   - `httpPort` / `websocketPort`: must be 1–65535
+     *   - `ttl`: must be 60–86400 seconds (24 hours max)
+     *   - `refreshInterval`: must be positive and less than `ttl * 1000`
+     *   - `retryAttempts`: must be 1–10
+     *   - `retryDelay`: must be 1000–60000 ms
+     *   - `protocol`: must be a valid {@link UpnpProtocol} value
+     */
+    static validate(config: IUpnpConfig): void;
+    /**
+     * Parse a string environment variable as an integer.
+     *
+     * @param value - The raw environment variable value
+     * @param fallback - Default value when the variable is undefined or empty
+     * @returns The parsed integer or the fallback value
+     * @throws {UpnpConfigValidationError} If the value is not a valid integer
+     */
+    private static parseIntEnv;
+    /**
+     * Parse a string environment variable as a {@link UpnpProtocol} value.
+     *
+     * @param value - The raw environment variable value
+     * @param fallback - Default protocol when the variable is undefined or empty
+     * @returns The parsed protocol or the fallback value
+     * @throws {UpnpConfigValidationError} If the value is not a valid protocol
+     */
+    private static parseProtocol;
+}
+//# sourceMappingURL=upnp-config.d.ts.map

package/src/services/upnp-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upnp-config.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/upnp-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,WAAW,EAEX,YAAY,EACb,MAAM,iCAAiC,CAAC;AAEzC;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD;;OAEG;gBACS,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,UAAW,YAAW,WAAW;IAC5C,8BAA8B;IAC9B,SAAgB,OAAO,EAAE,OAAO,CAAC;IACjC,0CAA0C;IAC1C,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,uCAAuC;IACvC,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,sCAAsC;IACtC,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,uCAAuC;IACvC,SAAgB,eAAe,EAAE,MAAM,CAAC;IACxC,mDAAmD;IACnD,SAAgB,QAAQ,EAAE,YAAY,CAAC;IACvC,qDAAqD;IACrD,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,4CAA4C;IAC5C,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC;;;;OAIG;IACH,OAAO;IAWP;;;;;;;;;;;;;;;;;;;;OAoBG;WACW,eAAe,CAC3B,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,UAAU;IAqCb;;;;;;;;;;;OAWG;WACW,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IA8EjD;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAgB1B;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;CAgB7B"}

package/src/services/upnp-config.js

@@ -0,0 +1,225 @@
+"use strict";
+/**
+ * UPnP Configuration Loader and Validator.
+ *
+ * Reads UPnP settings from environment variables, applies defaults
+ * for missing values, and validates all configuration parameters.
+ * Use the static {@link UpnpConfig.fromEnvironment} factory method
+ * to create validated instances.
+ *
+ * Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpnpConfig = exports.UpnpConfigValidationError = void 0;
+const upnpTypes_1 = require("../interfaces/network/upnpTypes");
+/**
+ * Error thrown when UPnP configuration validation fails.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const config = UpnpConfig.fromEnvironment({ UPNP_HTTP_PORT: '99999' });
+ * } catch (err) {
+ *   if (err instanceof UpnpConfigValidationError) {
+ *     console.error(`Invalid config: ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+class UpnpConfigValidationError extends Error {
+    /**
+     * @param message - Description of the validation failure
+     */
+    constructor(message) {
+        super(message);
+        this.name = 'UpnpConfigValidationError';
+    }
+}
+exports.UpnpConfigValidationError = UpnpConfigValidationError;
+/**
+ * UPnP configuration loaded from environment variables.
+ *
+ * Reads `UPNP_*` env vars, falls back to {@link UPNP_CONFIG_DEFAULTS},
+ * and validates all values on construction. Use the static
+ * {@link UpnpConfig.fromEnvironment} factory method to create instances.
+ *
+ * @example
+ * ```typescript
+ * // Load from process.env (production usage)
+ * const config = UpnpConfig.fromEnvironment();
+ *
+ * // Load from custom env (testing)
+ * const testConfig = UpnpConfig.fromEnvironment({
+ *   UPNP_ENABLED: 'true',
+ *   UPNP_HTTP_PORT: '8080',
+ * });
+ *
+ * console.log(config.enabled);   // false (default)
+ * console.log(config.httpPort);  // 3000 (default)
+ * ```
+ */
+class UpnpConfig {
+    /** Whether UPnP is enabled */
+    enabled;
+    /** HTTP/Express port to map externally */
+    httpPort;
+    /** WebSocket port to map externally */
+    websocketPort;
+    /** Mapping time-to-live in seconds */
+    ttl;
+    /** Refresh interval in milliseconds */
+    refreshInterval;
+    /** UPnP protocol to use (upnp, natpmp, or auto) */
+    protocol;
+    /** Number of retry attempts for failed operations */
+    retryAttempts;
+    /** Delay between retries in milliseconds */
+    retryDelay;
+    /**
+     * Private constructor — use {@link UpnpConfig.fromEnvironment} to create instances.
+     *
+     * @param config - Validated configuration values
+     */
+    constructor(config) {
+        this.enabled = config.enabled;
+        this.httpPort = config.httpPort;
+        this.websocketPort = config.websocketPort;
+        this.ttl = config.ttl;
+        this.refreshInterval = config.refreshInterval;
+        this.protocol = config.protocol;
+        this.retryAttempts = config.retryAttempts;
+        this.retryDelay = config.retryDelay;
+    }
+    /**
+     * Create an UpnpConfig from the current process environment.
+     * Missing variables fall back to {@link UPNP_CONFIG_DEFAULTS}.
+     *
+     * @param env - Environment variable map (defaults to `process.env`)
+     * @returns A validated UpnpConfig instance
+     * @throws {UpnpConfigValidationError} If any value is invalid
+     *
+     * @example
+     * ```typescript
+     * // Use process.env
+     * const config = UpnpConfig.fromEnvironment();
+     *
+     * // Use custom env for testing
+     * const config = UpnpConfig.fromEnvironment({
+     *   UPNP_ENABLED: 'true',
+     *   UPNP_HTTP_PORT: '8080',
+     *   UPNP_TTL: '7200',
+     * });
+     * ```
+     */
+    static fromEnvironment(env = process.env) {
+        const config = {
+            enabled: env['UPNP_ENABLED'] !== undefined
+                ? env['UPNP_ENABLED'].toLowerCase() === 'true'
+                : upnpTypes_1.UPNP_CONFIG_DEFAULTS.enabled,
+            httpPort: UpnpConfig.parseIntEnv(env['UPNP_HTTP_PORT'], upnpTypes_1.UPNP_CONFIG_DEFAULTS.httpPort),
+            websocketPort: UpnpConfig.parseIntEnv(env['UPNP_WEBSOCKET_PORT'], upnpTypes_1.UPNP_CONFIG_DEFAULTS.websocketPort),
+            ttl: UpnpConfig.parseIntEnv(env['UPNP_TTL'], upnpTypes_1.UPNP_CONFIG_DEFAULTS.ttl),
+            refreshInterval: UpnpConfig.parseIntEnv(env['UPNP_REFRESH_INTERVAL'], upnpTypes_1.UPNP_CONFIG_DEFAULTS.refreshInterval),
+            protocol: UpnpConfig.parseProtocol(env['UPNP_PROTOCOL'], upnpTypes_1.UPNP_CONFIG_DEFAULTS.protocol),
+            retryAttempts: UpnpConfig.parseIntEnv(env['UPNP_RETRY_ATTEMPTS'], upnpTypes_1.UPNP_CONFIG_DEFAULTS.retryAttempts),
+            retryDelay: UpnpConfig.parseIntEnv(env['UPNP_RETRY_DELAY'], upnpTypes_1.UPNP_CONFIG_DEFAULTS.retryDelay),
+        };
+        UpnpConfig.validate(config);
+        return new UpnpConfig(config);
+    }
+    /**
+     * Validate all configuration values. Throws on the first invalid value.
+     *
+     * @param config - The configuration object to validate
+     * @throws {UpnpConfigValidationError} If any value is outside its valid range:
+     *   - `httpPort` / `websocketPort`: must be 1–65535
+     *   - `ttl`: must be 60–86400 seconds (24 hours max)
+     *   - `refreshInterval`: must be positive and less than `ttl * 1000`
+     *   - `retryAttempts`: must be 1–10
+     *   - `retryDelay`: must be 1000–60000 ms
+     *   - `protocol`: must be a valid {@link UpnpProtocol} value
+     */
+    static validate(config) {
+        // Port validation (1–65535)
+        if (!Number.isInteger(config.httpPort) ||
+            config.httpPort < 1 ||
+            config.httpPort > 65535) {
+            throw new UpnpConfigValidationError(`httpPort must be an integer between 1 and 65535, got ${config.httpPort}`);
+        }
+        if (!Number.isInteger(config.websocketPort) ||
+            config.websocketPort < 1 ||
+            config.websocketPort > 65535) {
+            throw new UpnpConfigValidationError(`websocketPort must be an integer between 1 and 65535, got ${config.websocketPort}`);
+        }
+        // TTL validation (minimum 60 seconds, maximum 86400 seconds / 24 hours)
+        if (!Number.isInteger(config.ttl) ||
+            config.ttl < 60 ||
+            config.ttl > 86400) {
+            throw new UpnpConfigValidationError(`ttl must be an integer between 60 and 86400 seconds (24 hours), got ${config.ttl}`);
+        }
+        // Refresh interval must be less than TTL * 1000 (TTL is seconds, refresh is ms)
+        if (!Number.isInteger(config.refreshInterval) ||
+            config.refreshInterval <= 0) {
+            throw new UpnpConfigValidationError(`refreshInterval must be a positive integer, got ${config.refreshInterval}`);
+        }
+        if (config.refreshInterval >= config.ttl * 1000) {
+            throw new UpnpConfigValidationError(`refreshInterval (${config.refreshInterval}ms) must be less than ttl * 1000 (${config.ttl * 1000}ms)`);
+        }
+        // Retry attempts (1–10)
+        if (!Number.isInteger(config.retryAttempts) ||
+            config.retryAttempts < 1 ||
+            config.retryAttempts > 10) {
+            throw new UpnpConfigValidationError(`retryAttempts must be an integer between 1 and 10, got ${config.retryAttempts}`);
+        }
+        // Retry delay (1000–60000ms)
+        if (!Number.isInteger(config.retryDelay) ||
+            config.retryDelay < 1000 ||
+            config.retryDelay > 60000) {
+            throw new UpnpConfigValidationError(`retryDelay must be an integer between 1000 and 60000ms, got ${config.retryDelay}`);
+        }
+        // Protocol validation
+        const validProtocols = Object.values(upnpTypes_1.UpnpProtocol);
+        if (!validProtocols.includes(config.protocol)) {
+            throw new UpnpConfigValidationError(`protocol must be one of ${validProtocols.join(', ')}, got ${config.protocol}`);
+        }
+    }
+    /**
+     * Parse a string environment variable as an integer.
+     *
+     * @param value - The raw environment variable value
+     * @param fallback - Default value when the variable is undefined or empty
+     * @returns The parsed integer or the fallback value
+     * @throws {UpnpConfigValidationError} If the value is not a valid integer
+     */
+    static parseIntEnv(value, fallback) {
+        if (value === undefined || value === '') {
+            return fallback;
+        }
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isNaN(parsed)) {
+            throw new UpnpConfigValidationError(`Expected integer value, got "${value}"`);
+        }
+        return parsed;
+    }
+    /**
+     * Parse a string environment variable as a {@link UpnpProtocol} value.
+     *
+     * @param value - The raw environment variable value
+     * @param fallback - Default protocol when the variable is undefined or empty
+     * @returns The parsed protocol or the fallback value
+     * @throws {UpnpConfigValidationError} If the value is not a valid protocol
+     */
+    static parseProtocol(value, fallback) {
+        if (value === undefined || value === '') {
+            return fallback;
+        }
+        const lower = value.toLowerCase();
+        const validProtocols = Object.values(upnpTypes_1.UpnpProtocol);
+        if (!validProtocols.includes(lower)) {
+            throw new UpnpConfigValidationError(`protocol must be one of ${validProtocols.join(', ')}, got "${value}"`);
+        }
+        return lower;
+    }
+}
+exports.UpnpConfig = UpnpConfig;
+//# sourceMappingURL=upnp-config.js.map

package/src/services/upnp-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upnp-config.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/upnp-config.ts"],"names":[],"mappings":"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"}