@digitaldefiance/node-express-suite 3.12.12 → 3.12.15

package/src/services/upnp.d.ts

@@ -0,0 +1,241 @@
+/**
+ * UPnP Port Mapping Service.
+ *
+ * Provides automatic port forwarding via UPnP/NAT-PMP protocols,
+ * enabling servers behind NAT routers to be reachable from the internet.
+ * Uses nat-upnp as the primary client with retry logic and exponential
+ * backoff for resilience against slow or unreliable routers.
+ *
+ * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 2.10
+ */
+import { IUpnpService } from '../interfaces/network/upnpService';
+import { IUpnpConfig, IUpnpMapping, PortMappingProtocol } from '../interfaces/network/upnpTypes';
+/**
+ * Error thrown when a port number is outside the valid range (1-65535).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   UpnpService.validatePort(70000);
+ * } catch (err) {
+ *   if (err instanceof PortRangeError) {
+ *     console.error(err.message); // "Port 70000 is outside the valid range (1-65535)"
+ *   }
+ * }
+ * ```
+ */
+export declare class PortRangeError extends Error {
+    constructor(port: number);
+}
+/**
+ * Error thrown when UPnP operations fail after all retry attempts.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await service.getExternalIp();
+ * } catch (err) {
+ *   if (err instanceof UpnpOperationError) {
+ *     console.error(`Operation failed: ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class UpnpOperationError extends Error {
+    constructor(operation: string, cause?: string);
+}
+/**
+ * Error thrown when the UPnP service has been closed and an operation is attempted.
+ *
+ * @example
+ * ```typescript
+ * const service = new UpnpService();
+ * await service.close();
+ *
+ * try {
+ *   await service.getExternalIp(); // throws UpnpServiceClosedError
+ * } catch (err) {
+ *   if (err instanceof UpnpServiceClosedError) {
+ *     console.error('Service already closed');
+ *   }
+ * }
+ * ```
+ */
+export declare class UpnpServiceClosedError extends Error {
+    constructor();
+}
+/**
+ * UPnP port mapping service implementation.
+ *
+ * Manages port mappings on a NAT router via the UPnP protocol, with
+ * support for external IP discovery, mapping lifecycle management,
+ * and retry logic with exponential backoff.
+ *
+ * **Validates: Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 2.10**
+ *
+ * @example
+ * ```typescript
+ * const service = new UpnpService();
+ *
+ * const externalIp = await service.getExternalIp();
+ * await service.createPortMapping({
+ *   public: 3000,
+ *   private: 3000,
+ *   protocol: 'tcp',
+ *   description: 'Express App HTTP',
+ *   ttl: 3600,
+ * });
+ *
+ * // On shutdown
+ * await service.close();
+ * ```
+ */
+export declare class UpnpService implements IUpnpService {
+    /** The nat-upnp client instance */
+    private client;
+    /** Service configuration */
+    private readonly config;
+    /** Active port mappings tracked in memory (keyed by "port:protocol") */
+    private readonly activeMappings;
+    /** Cached external IP address */
+    private cachedExternalIp;
+    /** Timestamp when the external IP was last fetched */
+    private ipCacheTimestamp;
+    /** TTL for the external IP cache in milliseconds */
+    private readonly ipCacheTtlMs;
+    /** Whether the service has been closed */
+    private closed;
+    /**
+     * Create a new UpnpService.
+     *
+     * **Validates: Requirement 2.1** — Accepts partial config and merges with defaults
+     *
+     * @param config - UPnP configuration (uses defaults for omitted fields)
+     * @param ipCacheTtlMs - External IP cache TTL in milliseconds (default 5 minutes)
+     */
+    constructor(config?: Partial<IUpnpConfig>, ipCacheTtlMs?: number);
+    /**
+     * Query the router for the external (public) IP address.
+     * Results are cached for the configured TTL to reduce router queries.
+     *
+     * **Validates: Requirement 2.8** — Return cached IP or query router and cache result
+     *
+     * @returns The external IP address as a string
+     * @throws {UpnpServiceClosedError} If the service has been closed
+     * @throws {UpnpOperationError} If the IP cannot be retrieved after retries
+     */
+    getExternalIp(): Promise<string>;
+    /**
+     * Create a port mapping on the router.
+     *
+     * **Validates: Requirements 2.2, 2.3** — Validate ports and create mapping with tracking
+     *
+     * @param mapping - The port mapping configuration to create
+     * @throws {PortRangeError} If any port is outside 1-65535
+     * @throws {UpnpServiceClosedError} If the service has been closed
+     * @throws {UpnpOperationError} If the mapping cannot be created after retries
+     */
+    createPortMapping(mapping: IUpnpMapping): Promise<void>;
+    /**
+     * Remove a specific port mapping from the router.
+     *
+     * **Validates: Requirement 2.4** — Remove mapping from router and in-memory tracking
+     *
+     * @param publicPort - The external port number to unmap
+     * @param protocol - The transport protocol of the mapping to remove
+     * @throws {PortRangeError} If the port is outside 1-65535
+     * @throws {UpnpServiceClosedError} If the service has been closed
+     * @throws {UpnpOperationError} If the mapping cannot be removed after retries
+     */
+    removePortMapping(publicPort: number, protocol: PortMappingProtocol): Promise<void>;
+    /**
+     * Remove all port mappings created by this service.
+     *
+     * **Validates: Requirement 2.9** — Remove all active mappings on close
+     *
+     * Attempts to remove each mapping individually. Failures on individual
+     * mappings are logged but do not prevent removal of remaining mappings.
+     */
+    removeAllMappings(): Promise<void>;
+    /**
+     * Get all active port mappings managed by this service.
+     *
+     * **Validates: Requirement 2.5** — Return all mappings tracked in memory
+     *
+     * @returns Array of active port mappings
+     */
+    getMappings(): Promise<IUpnpMapping[]>;
+    /**
+     * Close the UPnP client and release resources.
+     * Removes all active mappings before closing.
+     *
+     * **Validates: Requirement 2.9** — Remove all mappings, close client, reject subsequent ops
+     *
+     * @throws {UpnpServiceClosedError} If the service has already been closed
+     */
+    close(): Promise<void>;
+    /**
+     * Validate that a port number is within the valid range (1-65535).
+     *
+     * @param port - The port number to validate
+     * @throws {PortRangeError} If the port is outside the valid range
+     */
+    static validatePort(port: number): void;
+    /**
+     * Generate a unique key for a mapping based on port and protocol.
+     *
+     * @param port - The public port number
+     * @param protocol - The transport protocol
+     * @returns A string key in the format "port:protocol"
+     */
+    static mappingKey(port: number, protocol: PortMappingProtocol): string;
+    /**
+     * Ensure the service has not been closed.
+     *
+     * @throws {UpnpServiceClosedError} If the service has been closed
+     */
+    private ensureNotClosed;
+    /**
+     * Check whether the cached external IP has expired.
+     *
+     * @returns true if the cache has expired or was never set
+     */
+    private isIpCacheExpired;
+    /**
+     * Execute an operation with retry logic and exponential backoff.
+     *
+     * **Validates: Requirements 2.6, 2.7** — Retry with exponential backoff, throw UpnpOperationError on exhaustion
+     *
+     * @param operationName - Name of the operation (for error messages)
+     * @param operation - The async operation to execute
+     * @returns The result of the operation
+     * @throws {UpnpOperationError} If all retry attempts are exhausted
+     */
+    private withRetry;
+    /**
+     * Promisified wrapper around the nat-upnp externalIp callback API.
+     *
+     * @returns The external IP address
+     */
+    private promisifiedExternalIp;
+    /**
+     * Promisified wrapper around the nat-upnp portMapping callback API.
+     *
+     * @param options - Port mapping options
+     */
+    private promisifiedPortMapping;
+    /**
+     * Promisified wrapper around the nat-upnp portUnmapping callback API.
+     *
+     * @param options - Port unmapping options
+     */
+    private promisifiedPortUnmapping;
+    /**
+     * Sleep for the specified duration.
+     *
+     * @param ms - Duration in milliseconds
+     * @returns A promise that resolves after the specified duration
+     */
+    static sleep(ms: number): Promise<void>;
+}
+//# sourceMappingURL=upnp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"upnp.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/services/upnp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EACL,WAAW,EACX,YAAY,EACZ,mBAAmB,EAEpB,MAAM,iCAAiC,CAAC;AAezC;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,IAAI,EAAE,MAAM;CAIzB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAO9C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;;CAKhD;AAID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,WAAY,YAAW,YAAY;IAC9C,mCAAmC;IACnC,OAAO,CAAC,MAAM,CAAiB;IAE/B,4BAA4B;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAE/C,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwC;IAEvE,iCAAiC;IACjC,OAAO,CAAC,gBAAgB,CAAuB;IAE/C,sDAAsD;IACtD,OAAO,CAAC,gBAAgB,CAAK;IAE7B,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,0CAA0C;IAC1C,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;;;;OAOG;gBAED,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM,EACjC,YAAY,GAAE,MAAgC;IAShD;;;;;;;;;OASG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAkBtC;;;;;;;;;OASG;IACG,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB7D;;;;;;;;;;OAUG;IACG,iBAAiB,CACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC;IAgBhB;;;;;;;OAOG;IACG,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BxC;;;;;;OAMG;IACG,WAAW,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAK5C;;;;;;;OAOG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB5B;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAMvC;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,GAAG,MAAM;IAMtE;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAMvB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAIxB;;;;;;;;;OASG;YACW,SAAS;IA0BvB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAc9B;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAchC;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxC"}

package/src/services/upnp.js

@@ -0,0 +1,415 @@
+"use strict";
+/**
+ * UPnP Port Mapping Service.
+ *
+ * Provides automatic port forwarding via UPnP/NAT-PMP protocols,
+ * enabling servers behind NAT routers to be reachable from the internet.
+ * Uses nat-upnp as the primary client with retry logic and exponential
+ * backoff for resilience against slow or unreliable routers.
+ *
+ * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 2.10
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpnpService = exports.UpnpServiceClosedError = exports.UpnpOperationError = exports.PortRangeError = void 0;
+const tslib_1 = require("tslib");
+const natUpnp = tslib_1.__importStar(require("nat-upnp"));
+const upnpTypes_1 = require("../interfaces/network/upnpTypes");
+// ─── Constants ──────────────────────────────────────────────────────────────
+/** Minimum valid port number */
+const MIN_PORT = 1;
+/** Maximum valid port number */
+const MAX_PORT = 65535;
+/** Default external IP cache TTL in milliseconds (5 minutes) */
+const DEFAULT_IP_CACHE_TTL_MS = 5 * 60 * 1000;
+// ─── Error classes ──────────────────────────────────────────────────────────
+/**
+ * Error thrown when a port number is outside the valid range (1-65535).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   UpnpService.validatePort(70000);
+ * } catch (err) {
+ *   if (err instanceof PortRangeError) {
+ *     console.error(err.message); // "Port 70000 is outside the valid range (1-65535)"
+ *   }
+ * }
+ * ```
+ */
+class PortRangeError extends Error {
+    constructor(port) {
+        super(`Port ${port} is outside the valid range (${MIN_PORT}-${MAX_PORT})`);
+        this.name = 'PortRangeError';
+    }
+}
+exports.PortRangeError = PortRangeError;
+/**
+ * Error thrown when UPnP operations fail after all retry attempts.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await service.getExternalIp();
+ * } catch (err) {
+ *   if (err instanceof UpnpOperationError) {
+ *     console.error(`Operation failed: ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+class UpnpOperationError extends Error {
+    constructor(operation, cause) {
+        const message = cause
+            ? `UPnP ${operation} failed: ${cause}`
+            : `UPnP ${operation} failed`;
+        super(message);
+        this.name = 'UpnpOperationError';
+    }
+}
+exports.UpnpOperationError = UpnpOperationError;
+/**
+ * Error thrown when the UPnP service has been closed and an operation is attempted.
+ *
+ * @example
+ * ```typescript
+ * const service = new UpnpService();
+ * await service.close();
+ *
+ * try {
+ *   await service.getExternalIp(); // throws UpnpServiceClosedError
+ * } catch (err) {
+ *   if (err instanceof UpnpServiceClosedError) {
+ *     console.error('Service already closed');
+ *   }
+ * }
+ * ```
+ */
+class UpnpServiceClosedError extends Error {
+    constructor() {
+        super('UPnP service has been closed');
+        this.name = 'UpnpServiceClosedError';
+    }
+}
+exports.UpnpServiceClosedError = UpnpServiceClosedError;
+// ─── Service ────────────────────────────────────────────────────────────────
+/**
+ * UPnP port mapping service implementation.
+ *
+ * Manages port mappings on a NAT router via the UPnP protocol, with
+ * support for external IP discovery, mapping lifecycle management,
+ * and retry logic with exponential backoff.
+ *
+ * **Validates: Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9, 2.10**
+ *
+ * @example
+ * ```typescript
+ * const service = new UpnpService();
+ *
+ * const externalIp = await service.getExternalIp();
+ * await service.createPortMapping({
+ *   public: 3000,
+ *   private: 3000,
+ *   protocol: 'tcp',
+ *   description: 'Express App HTTP',
+ *   ttl: 3600,
+ * });
+ *
+ * // On shutdown
+ * await service.close();
+ * ```
+ */
+class UpnpService {
+    /** The nat-upnp client instance */
+    client;
+    /** Service configuration */
+    config;
+    /** Active port mappings tracked in memory (keyed by "port:protocol") */
+    activeMappings = new Map();
+    /** Cached external IP address */
+    cachedExternalIp = null;
+    /** Timestamp when the external IP was last fetched */
+    ipCacheTimestamp = 0;
+    /** TTL for the external IP cache in milliseconds */
+    ipCacheTtlMs;
+    /** Whether the service has been closed */
+    closed = false;
+    /**
+     * Create a new UpnpService.
+     *
+     * **Validates: Requirement 2.1** — Accepts partial config and merges with defaults
+     *
+     * @param config - UPnP configuration (uses defaults for omitted fields)
+     * @param ipCacheTtlMs - External IP cache TTL in milliseconds (default 5 minutes)
+     */
+    constructor(config = {}, ipCacheTtlMs = DEFAULT_IP_CACHE_TTL_MS) {
+        this.config = { ...upnpTypes_1.UPNP_CONFIG_DEFAULTS, ...config };
+        this.ipCacheTtlMs = ipCacheTtlMs;
+        this.client = natUpnp.createClient();
+    }
+    // ─── Public API ─────────────────────────────────────────────────────────
+    /**
+     * Query the router for the external (public) IP address.
+     * Results are cached for the configured TTL to reduce router queries.
+     *
+     * **Validates: Requirement 2.8** — Return cached IP or query router and cache result
+     *
+     * @returns The external IP address as a string
+     * @throws {UpnpServiceClosedError} If the service has been closed
+     * @throws {UpnpOperationError} If the IP cannot be retrieved after retries
+     */
+    async getExternalIp() {
+        this.ensureNotClosed();
+        // Return cached IP if still valid
+        if (this.cachedExternalIp && !this.isIpCacheExpired()) {
+            return this.cachedExternalIp;
+        }
+        const ip = await this.withRetry('getExternalIp', () => this.promisifiedExternalIp());
+        this.cachedExternalIp = ip;
+        this.ipCacheTimestamp = Date.now();
+        return ip;
+    }
+    /**
+     * Create a port mapping on the router.
+     *
+     * **Validates: Requirements 2.2, 2.3** — Validate ports and create mapping with tracking
+     *
+     * @param mapping - The port mapping configuration to create
+     * @throws {PortRangeError} If any port is outside 1-65535
+     * @throws {UpnpServiceClosedError} If the service has been closed
+     * @throws {UpnpOperationError} If the mapping cannot be created after retries
+     */
+    async createPortMapping(mapping) {
+        this.ensureNotClosed();
+        UpnpService.validatePort(mapping.public);
+        UpnpService.validatePort(mapping.private);
+        await this.withRetry('createPortMapping', () => this.promisifiedPortMapping({
+            public: mapping.public,
+            private: mapping.private,
+            protocol: mapping.protocol,
+            description: mapping.description,
+            ttl: mapping.ttl,
+        }));
+        // Track the mapping in memory
+        const key = UpnpService.mappingKey(mapping.public, mapping.protocol);
+        this.activeMappings.set(key, { ...mapping });
+    }
+    /**
+     * Remove a specific port mapping from the router.
+     *
+     * **Validates: Requirement 2.4** — Remove mapping from router and in-memory tracking
+     *
+     * @param publicPort - The external port number to unmap
+     * @param protocol - The transport protocol of the mapping to remove
+     * @throws {PortRangeError} If the port is outside 1-65535
+     * @throws {UpnpServiceClosedError} If the service has been closed
+     * @throws {UpnpOperationError} If the mapping cannot be removed after retries
+     */
+    async removePortMapping(publicPort, protocol) {
+        this.ensureNotClosed();
+        UpnpService.validatePort(publicPort);
+        await this.withRetry('removePortMapping', () => this.promisifiedPortUnmapping({
+            public: publicPort,
+            protocol,
+        }));
+        // Remove from tracked mappings
+        const key = UpnpService.mappingKey(publicPort, protocol);
+        this.activeMappings.delete(key);
+    }
+    /**
+     * Remove all port mappings created by this service.
+     *
+     * **Validates: Requirement 2.9** — Remove all active mappings on close
+     *
+     * Attempts to remove each mapping individually. Failures on individual
+     * mappings are logged but do not prevent removal of remaining mappings.
+     */
+    async removeAllMappings() {
+        this.ensureNotClosed();
+        const mappings = Array.from(this.activeMappings.values());
+        const errors = [];
+        for (const mapping of mappings) {
+            try {
+                await this.removePortMapping(mapping.public, mapping.protocol);
+            }
+            catch (error) {
+                errors.push({
+                    mapping,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            }
+        }
+        // Clear all tracked mappings even if some removals failed
+        this.activeMappings.clear();
+        if (errors.length > 0) {
+            const details = errors
+                .map((e) => `${e.mapping.public}/${e.mapping.protocol}: ${e.error.message}`)
+                .join('; ');
+            throw new UpnpOperationError('removeAllMappings', details);
+        }
+    }
+    /**
+     * Get all active port mappings managed by this service.
+     *
+     * **Validates: Requirement 2.5** — Return all mappings tracked in memory
+     *
+     * @returns Array of active port mappings
+     */
+    async getMappings() {
+        this.ensureNotClosed();
+        return Array.from(this.activeMappings.values());
+    }
+    /**
+     * Close the UPnP client and release resources.
+     * Removes all active mappings before closing.
+     *
+     * **Validates: Requirement 2.9** — Remove all mappings, close client, reject subsequent ops
+     *
+     * @throws {UpnpServiceClosedError} If the service has already been closed
+     */
+    async close() {
+        this.ensureNotClosed();
+        // Best-effort removal of all mappings before closing
+        try {
+            await this.removeAllMappings();
+        }
+        catch {
+            // Swallow errors during cleanup — we're shutting down
+        }
+        this.client.close();
+        this.closed = true;
+        this.cachedExternalIp = null;
+    }
+    // ─── Static helpers ─────────────────────────────────────────────────────
+    /**
+     * Validate that a port number is within the valid range (1-65535).
+     *
+     * @param port - The port number to validate
+     * @throws {PortRangeError} If the port is outside the valid range
+     */
+    static validatePort(port) {
+        if (!Number.isInteger(port) || port < MIN_PORT || port > MAX_PORT) {
+            throw new PortRangeError(port);
+        }
+    }
+    /**
+     * Generate a unique key for a mapping based on port and protocol.
+     *
+     * @param port - The public port number
+     * @param protocol - The transport protocol
+     * @returns A string key in the format "port:protocol"
+     */
+    static mappingKey(port, protocol) {
+        return `${port}:${protocol}`;
+    }
+    // ─── Private helpers ────────────────────────────────────────────────────
+    /**
+     * Ensure the service has not been closed.
+     *
+     * @throws {UpnpServiceClosedError} If the service has been closed
+     */
+    ensureNotClosed() {
+        if (this.closed) {
+            throw new UpnpServiceClosedError();
+        }
+    }
+    /**
+     * Check whether the cached external IP has expired.
+     *
+     * @returns true if the cache has expired or was never set
+     */
+    isIpCacheExpired() {
+        return Date.now() - this.ipCacheTimestamp > this.ipCacheTtlMs;
+    }
+    /**
+     * Execute an operation with retry logic and exponential backoff.
+     *
+     * **Validates: Requirements 2.6, 2.7** — Retry with exponential backoff, throw UpnpOperationError on exhaustion
+     *
+     * @param operationName - Name of the operation (for error messages)
+     * @param operation - The async operation to execute
+     * @returns The result of the operation
+     * @throws {UpnpOperationError} If all retry attempts are exhausted
+     */
+    async withRetry(operationName, operation) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.config.retryAttempts; attempt++) {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Don't delay after the last attempt
+                if (attempt < this.config.retryAttempts) {
+                    const delay = this.config.retryDelay * Math.pow(2, attempt);
+                    await UpnpService.sleep(delay);
+                }
+            }
+        }
+        throw new UpnpOperationError(operationName, lastError?.message ?? 'unknown error');
+    }
+    /**
+     * Promisified wrapper around the nat-upnp externalIp callback API.
+     *
+     * @returns The external IP address
+     */
+    promisifiedExternalIp() {
+        return new Promise((resolve, reject) => {
+            this.client.externalIp((err, ip) => {
+                if (err) {
+                    reject(err);
+                }
+                else if (ip) {
+                    resolve(ip);
+                }
+                else {
+                    reject(new Error('No external IP returned'));
+                }
+            });
+        });
+    }
+    /**
+     * Promisified wrapper around the nat-upnp portMapping callback API.
+     *
+     * @param options - Port mapping options
+     */
+    promisifiedPortMapping(options) {
+        return new Promise((resolve, reject) => {
+            this.client.portMapping(options, (err) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Promisified wrapper around the nat-upnp portUnmapping callback API.
+     *
+     * @param options - Port unmapping options
+     */
+    promisifiedPortUnmapping(options) {
+        return new Promise((resolve, reject) => {
+            this.client.portUnmapping(options, (err) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    }
+    /**
+     * Sleep for the specified duration.
+     *
+     * @param ms - Duration in milliseconds
+     * @returns A promise that resolves after the specified duration
+     */
+    static sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.UpnpService = UpnpService;
+//# sourceMappingURL=upnp.js.map

package/src/services/upnp.js.map

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

package/src/utils.d.ts

@@ -237,4 +237,17 @@ export declare function getLengthEncodingTypeFromValue(value: number): LengthEnc
  */
 export declare function getLengthForLengthType(type: LengthEncodingType): number;
 export declare function parseBackupCodes(user: 'admin' | 'member' | 'system', environment: Record<string, string | undefined>): BackupCode[];
+/**
+ * Validates whether a hostname is a valid FQDN or wildcard pattern.
+ * @param hostname The hostname string to validate
+ * @returns true if the hostname matches either the FQDN or wildcard pattern
+ */
+export declare function isValidHostname(hostname: string): boolean;
+/**
+ * Parses a comma-separated string of hostnames into an array.
+ * Trims whitespace from each entry and filters out empty strings.
+ * @param raw The raw comma-separated hostname string
+ * @returns An array of trimmed, non-empty hostname strings
+ */
+export declare function parseHostnames(raw: string): string[];
 //# sourceMappingURL=utils.d.ts.map