@digitaldefiance/node-express-suite 3.12.12 → 3.12.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitaldefiance/node-express-suite",
-  "version": "3.12.12",
+  "version": "3.12.13",
   "homepage": "https://github.com/Digital-Defiance/node-express-suite",
   "repository": {
     "type": "git",
@@ -58,15 +58,18 @@
     "mongodb": "^6.20.0",
     "mongodb-memory-server": "^10.1.4",
     "mongoose": "^8.18.2",
+    "nat-upnp": "^1.1.1",
     "reflect-metadata": "^0.2.2",
     "zod": "^3.24.0"
   },
   "devDependencies": {
     "@digitaldefiance/express-suite-test-utils": "1.1.1",
+    "@types/nat-upnp": "^1.1.5",
     "@typescript-eslint/eslint-plugin": "^8.53.1",
     "@typescript-eslint/parser": "^8.53.1",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-prettier": "^5.5.4"
+    "eslint-plugin-prettier": "^5.5.4",
+    "fast-check": "^4.3.0"
   },
   "files": [
     "src",

package/src/interfaces/index.d.ts

@@ -25,6 +25,7 @@ export * from './jwt-consts';
 export * from './jwt-sign-response';
 export * from './models';
 export * from './mongo-errors';
+export * from './network';
 export * from './openApi';
 export * from './request-user';
 export * from './required-string-keys';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/interfaces/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,yCAAyC,CAAC;AACxD,cAAc,wBAAwB,CAAC;AACvC,cAAc,uCAAuC,CAAC;AACtD,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/interfaces/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,yCAAyC,CAAC;AACxD,cAAc,wBAAwB,CAAC;AACvC,cAAc,uCAAuC,CAAC;AACtD,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kBAAkB,CAAC"}

package/src/interfaces/index.js

@@ -28,6 +28,7 @@ tslib_1.__exportStar(require("./jwt-consts"), exports);
 tslib_1.__exportStar(require("./jwt-sign-response"), exports);
 tslib_1.__exportStar(require("./models"), exports);
 tslib_1.__exportStar(require("./mongo-errors"), exports);
+tslib_1.__exportStar(require("./network"), exports);
 tslib_1.__exportStar(require("./openApi"), exports);
 tslib_1.__exportStar(require("./request-user"), exports);
 tslib_1.__exportStar(require("./required-string-keys"), exports);

package/src/interfaces/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/interfaces/index.ts"],"names":[],"mappings":";;;AAAA,+DAAqC;AACrC,kFAAwD;AACxD,iEAAuC;AACvC,gFAAsD;AACtD,0DAAgC;AAChC,wDAA8B;AAC9B,4DAAkC;AAClC,4DAAkC;AAClC,4DAAkC;AAClC,sDAA4B;AAC5B,8DAAoC;AACpC,+DAAqC;AACrC,uDAA6B;AAC7B,2DAAiC;AACjC,2DAAiC;AACjC,sEAA4C;AAC5C,0DAAgC;AAChC,wDAA8B;AAC9B,8DAAoC;AACpC,4DAAkC;AAClC,uDAA6B;AAC7B,yDAA+B;AAC/B,qEAA2C;AAC3C,uDAA6B;AAC7B,8DAAoC;AACpC,mDAAyB;AACzB,yDAA+B;AAC/B,oDAA0B;AAC1B,yDAA+B;AAC/B,iEAAuC;AACvC,mDAAyB;AACzB,+DAAqC;AACrC,iEAAuC;AACvC,yEAA+C;AAC/C,2DAAiC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/interfaces/index.ts"],"names":[],"mappings":";;;AAAA,+DAAqC;AACrC,kFAAwD;AACxD,iEAAuC;AACvC,gFAAsD;AACtD,0DAAgC;AAChC,wDAA8B;AAC9B,4DAAkC;AAClC,4DAAkC;AAClC,4DAAkC;AAClC,sDAA4B;AAC5B,8DAAoC;AACpC,+DAAqC;AACrC,uDAA6B;AAC7B,2DAAiC;AACjC,2DAAiC;AACjC,sEAA4C;AAC5C,0DAAgC;AAChC,wDAA8B;AAC9B,8DAAoC;AACpC,4DAAkC;AAClC,uDAA6B;AAC7B,yDAA+B;AAC/B,qEAA2C;AAC3C,uDAA6B;AAC7B,8DAAoC;AACpC,mDAAyB;AACzB,yDAA+B;AAC/B,oDAA0B;AAC1B,oDAA0B;AAC1B,yDAA+B;AAC/B,iEAAuC;AACvC,mDAAyB;AACzB,+DAAqC;AACrC,iEAAuC;AACvC,yEAA+C;AAC/C,2DAAiC"}

package/src/interfaces/network/index.d.ts

@@ -0,0 +1,3 @@
+export * from './upnpTypes';
+export * from './upnpService';
+//# sourceMappingURL=index.d.ts.map

package/src/interfaces/network/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../packages/digitaldefiance-node-express-suite/src/interfaces/network/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/src/interfaces/network/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./upnpTypes"), exports);
+tslib_1.__exportStar(require("./upnpService"), exports);
+//# sourceMappingURL=index.js.map

package/src/interfaces/network/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../packages/digitaldefiance-node-express-suite/src/interfaces/network/index.ts"],"names":[],"mappings":";;;AAAA,sDAA4B;AAC5B,wDAA8B"}

package/src/interfaces/network/upnpService.d.ts

@@ -0,0 +1,86 @@
+import { IUpnpMapping, PortMappingProtocol } from './upnpTypes';
+/**
+ * Interface for UPnP/NAT-PMP port mapping service.
+ *
+ * Supports protocol auto-detection with fallback between UPnP and NAT-PMP.
+ * Implementations should track active mappings in memory and provide
+ * cleanup guarantees on close.
+ *
+ * @example
+ * ```typescript
+ * import { IUpnpService } from '@digitaldefiance/node-express-suite';
+ *
+ * async function setupPortMapping(service: IUpnpService): Promise<void> {
+ *   const externalIp = await service.getExternalIp();
+ *   await service.createPortMapping({
+ *     public: 3000,
+ *     private: 3000,
+ *     protocol: 'tcp',
+ *     description: 'Express App HTTP',
+ *     ttl: 3600,
+ *   });
+ *   console.log(`Accessible at ${externalIp}:3000`);
+ * }
+ * ```
+ */
+export interface IUpnpService {
+    /**
+     * Query the router for the external (public) IP address.
+     * Results may be cached by the implementation to reduce router queries.
+     *
+     * @returns The external IP address as a string (e.g. `"203.0.113.42"`)
+     * @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.
+     *
+     * @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.
+     *
+     * @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.
+     *
+     * Attempts to remove each mapping individually. Failures on individual
+     * mappings do not prevent removal of remaining mappings.
+     *
+     * @throws {UpnpServiceClosedError} If the service has been closed
+     * @throws {UpnpOperationError} If one or more mappings cannot be removed
+     */
+    removeAllMappings(): Promise<void>;
+    /**
+     * Get all active port mappings managed by this service.
+     *
+     * Returns only mappings tracked in memory by this service instance,
+     * not all mappings on the router.
+     *
+     * @returns Array of active port mappings
+     * @throws {UpnpServiceClosedError} If the service has been closed
+     */
+    getMappings(): Promise<IUpnpMapping[]>;
+    /**
+     * Close the UPnP client and release resources.
+     *
+     * Removes all active mappings before closing the underlying client.
+     * Should be called during service shutdown. After calling close,
+     * all subsequent operations will throw {@link UpnpServiceClosedError}.
+     *
+     * @throws {UpnpServiceClosedError} If the service has already been closed
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=upnpService.d.ts.map

package/src/interfaces/network/upnpService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upnpService.d.ts","sourceRoot":"","sources":["../../../../../../packages/digitaldefiance-node-express-suite/src/interfaces/network/upnpService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEjC;;;;;;;OAOG;IACH,iBAAiB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;;;;;;OAQG;IACH,iBAAiB,CACf,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;OAQG;IACH,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;;;;;;OAQG;IACH,WAAW,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAEvC;;;;;;;;OAQG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/src/interfaces/network/upnpService.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=upnpService.js.map

package/src/interfaces/network/upnpService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upnpService.js","sourceRoot":"","sources":["../../../../../../packages/digitaldefiance-node-express-suite/src/interfaces/network/upnpService.ts"],"names":[],"mappings":""}

package/src/interfaces/network/upnpTypes.d.ts

@@ -0,0 +1,120 @@
+/**
+ * UPnP protocol type for port mapping.
+ *
+ * Determines which NAT traversal protocol the service should use
+ * when communicating with the router.
+ *
+ * @example
+ * ```typescript
+ * import { UpnpProtocol } from '@digitaldefiance/node-express-suite';
+ *
+ * // Auto-detect the best available protocol
+ * const protocol = UpnpProtocol.AUTO;
+ *
+ * // Force UPnP (most common)
+ * const upnp = UpnpProtocol.UPNP;
+ *
+ * // Force NAT-PMP (Apple routers)
+ * const natpmp = UpnpProtocol.NATPMP;
+ * ```
+ */
+export declare enum UpnpProtocol {
+    /** Standard UPnP IGD protocol (most routers) */
+    UPNP = "upnp",
+    /** NAT-PMP protocol (common on Apple routers) */
+    NATPMP = "natpmp",
+    /** Auto-detect: try UPnP first, fall back to NAT-PMP */
+    AUTO = "auto"
+}
+/**
+ * Transport protocol for port mappings.
+ *
+ * @example
+ * ```typescript
+ * const protocol: PortMappingProtocol = 'tcp';
+ * ```
+ */
+export type PortMappingProtocol = 'tcp' | 'udp';
+/**
+ * Represents a single UPnP port mapping on the router.
+ *
+ * @example
+ * ```typescript
+ * const mapping: IUpnpMapping = {
+ *   public: 3000,
+ *   private: 3000,
+ *   protocol: 'tcp',
+ *   description: 'Express App HTTP',
+ *   ttl: 3600,
+ * };
+ * ```
+ */
+export interface IUpnpMapping {
+    /** External (public) port number */
+    public: number;
+    /** Internal (private) port number */
+    private: number;
+    /** Transport protocol */
+    protocol: PortMappingProtocol;
+    /** Human-readable description of the mapping */
+    description: string;
+    /** Time-to-live in seconds */
+    ttl: number;
+}
+/**
+ * UPnP service configuration.
+ *
+ * All fields have sensible defaults provided by {@link UPNP_CONFIG_DEFAULTS}.
+ * In production, values are typically loaded from environment variables
+ * via {@link UpnpConfig.fromEnvironment}.
+ *
+ * @see UPNP_CONFIG_DEFAULTS for default values
+ *
+ * @example
+ * ```typescript
+ * const config: IUpnpConfig = {
+ *   enabled: true,
+ *   httpPort: 8080,
+ *   websocketPort: 8080,
+ *   ttl: 3600,
+ *   refreshInterval: 1800000,
+ *   protocol: UpnpProtocol.AUTO,
+ *   retryAttempts: 3,
+ *   retryDelay: 5000,
+ * };
+ * ```
+ */
+export interface IUpnpConfig {
+    /** Whether UPnP is enabled */
+    enabled: boolean;
+    /** HTTP/Express port to map */
+    httpPort: number;
+    /** WebSocket port to map */
+    websocketPort: number;
+    /** Mapping time-to-live in seconds */
+    ttl: number;
+    /** Refresh interval in milliseconds */
+    refreshInterval: number;
+    /** UPnP protocol to use */
+    protocol: UpnpProtocol;
+    /** Number of retry attempts */
+    retryAttempts: number;
+    /** Delay between retries in milliseconds */
+    retryDelay: number;
+}
+/**
+ * Default UPnP configuration values.
+ *
+ * Used as fallback when environment variables are not set.
+ * UPnP is disabled by default (opt-in).
+ *
+ * @example
+ * ```typescript
+ * import { UPNP_CONFIG_DEFAULTS } from '@digitaldefiance/node-express-suite';
+ *
+ * // Use defaults with overrides
+ * const config = { ...UPNP_CONFIG_DEFAULTS, enabled: true, httpPort: 8080 };
+ * ```
+ */
+export declare const UPNP_CONFIG_DEFAULTS: Readonly<IUpnpConfig>;
+//# sourceMappingURL=upnpTypes.d.ts.map

package/src/interfaces/network/upnpTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upnpTypes.d.ts","sourceRoot":"","sources":["../../../../../../packages/digitaldefiance-node-express-suite/src/interfaces/network/upnpTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,oBAAY,YAAY;IACtB,gDAAgD;IAChD,IAAI,SAAS;IACb,iDAAiD;IACjD,MAAM,WAAW;IACjB,wDAAwD;IACxD,IAAI,SAAS;CACd;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,KAAK,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,eAAe,EAAE,MAAM,CAAC;IACxB,2BAA2B;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,WAAW,CAS7C,CAAC"}

package/src/interfaces/network/upnpTypes.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UPNP_CONFIG_DEFAULTS = exports.UpnpProtocol = void 0;
+/**
+ * UPnP protocol type for port mapping.
+ *
+ * Determines which NAT traversal protocol the service should use
+ * when communicating with the router.
+ *
+ * @example
+ * ```typescript
+ * import { UpnpProtocol } from '@digitaldefiance/node-express-suite';
+ *
+ * // Auto-detect the best available protocol
+ * const protocol = UpnpProtocol.AUTO;
+ *
+ * // Force UPnP (most common)
+ * const upnp = UpnpProtocol.UPNP;
+ *
+ * // Force NAT-PMP (Apple routers)
+ * const natpmp = UpnpProtocol.NATPMP;
+ * ```
+ */
+var UpnpProtocol;
+(function (UpnpProtocol) {
+    /** Standard UPnP IGD protocol (most routers) */
+    UpnpProtocol["UPNP"] = "upnp";
+    /** NAT-PMP protocol (common on Apple routers) */
+    UpnpProtocol["NATPMP"] = "natpmp";
+    /** Auto-detect: try UPnP first, fall back to NAT-PMP */
+    UpnpProtocol["AUTO"] = "auto";
+})(UpnpProtocol || (exports.UpnpProtocol = UpnpProtocol = {}));
+/**
+ * Default UPnP configuration values.
+ *
+ * Used as fallback when environment variables are not set.
+ * UPnP is disabled by default (opt-in).
+ *
+ * @example
+ * ```typescript
+ * import { UPNP_CONFIG_DEFAULTS } from '@digitaldefiance/node-express-suite';
+ *
+ * // Use defaults with overrides
+ * const config = { ...UPNP_CONFIG_DEFAULTS, enabled: true, httpPort: 8080 };
+ * ```
+ */
+exports.UPNP_CONFIG_DEFAULTS = {
+    enabled: false,
+    httpPort: 3000,
+    websocketPort: 3000,
+    ttl: 3600,
+    refreshInterval: 1800000,
+    protocol: UpnpProtocol.AUTO,
+    retryAttempts: 3,
+    retryDelay: 5000,
+};
+//# sourceMappingURL=upnpTypes.js.map

package/src/interfaces/network/upnpTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upnpTypes.js","sourceRoot":"","sources":["../../../../../../packages/digitaldefiance-node-express-suite/src/interfaces/network/upnpTypes.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,IAAY,YAOX;AAPD,WAAY,YAAY;IACtB,gDAAgD;IAChD,6BAAa,CAAA;IACb,iDAAiD;IACjD,iCAAiB,CAAA;IACjB,wDAAwD;IACxD,6BAAa,CAAA;AACf,CAAC,EAPW,YAAY,4BAAZ,YAAY,QAOvB;AAiFD;;;;;;;;;;;;;GAaG;AACU,QAAA,oBAAoB,GAA0B;IACzD,OAAO,EAAE,KAAK;IACd,QAAQ,EAAE,IAAI;IACd,aAAa,EAAE,IAAI;IACnB,GAAG,EAAE,IAAI;IACT,eAAe,EAAE,OAAO;IACxB,QAAQ,EAAE,YAAY,CAAC,IAAI;IAC3B,aAAa,EAAE,CAAC;IAChB,UAAU,EAAE,IAAI;CACR,CAAC"}

package/src/plugins/index.d.ts

@@ -1,3 +1,4 @@
 export * from './plugin-interface';
 export * from './plugin-manager';
+export * from './upnp';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/plugins/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/plugins/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,QAAQ,CAAC"}

package/src/plugins/index.js

@@ -3,4 +3,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./plugin-interface"), exports);
 tslib_1.__exportStar(require("./plugin-manager"), exports);
+tslib_1.__exportStar(require("./upnp"), exports);
 //# sourceMappingURL=index.js.map

package/src/plugins/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/plugins/index.ts"],"names":[],"mappings":";;;AAAA,6DAAmC;AACnC,2DAAiC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/plugins/index.ts"],"names":[],"mappings":";;;AAAA,6DAAmC;AACnC,2DAAiC;AACjC,iDAAuB"}

package/src/plugins/upnp.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 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',
+ * }));
+ * ```
+ */
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { IApplication } from '../interfaces/application';
+import { IApplicationPlugin } from './plugin-interface';
+import { UpnpManager } from '../services/upnp-manager';
+import { IUpnpConfig } from '../interfaces/network/upnpTypes';
+/**
+ * Options for configuring the UPnP plugin.
+ *
+ * @example
+ * ```typescript
+ * const options: UpnpPluginOptions = {
+ *   config: { enabled: true, httpPort: 8080 },
+ *   descriptionPrefix: 'My App',
+ * };
+ * ```
+ */
+export interface UpnpPluginOptions {
+    /** Override config instead of reading from environment */
+    config?: Partial<IUpnpConfig>;
+    /** Description prefix for port mapping labels */
+    descriptionPrefix?: string;
+}
+/**
+ * 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();
+ * ```
+ */
+export declare class UpnpPlugin<TID extends PlatformID = Buffer> implements IApplicationPlugin<TID> {
+    readonly name = "upnp";
+    readonly version = "1.0.0";
+    private manager;
+    private readonly options;
+    /**
+     * Create a new UpnpPlugin.
+     *
+     * @param options - Optional plugin configuration
+     */
+    constructor(options?: UpnpPluginOptions);
+    /**
+     * 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)
+     */
+    init(_app: IApplication<TID>): Promise<void>;
+    /**
+     * Stop the UPnP plugin.
+     *
+     * Shuts down the UpnpManager, removing all port mappings and cleaning up.
+     *
+     * **Validates: Requirement 5.3**
+     */
+    stop(): Promise<void>;
+    /**
+     * 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(): UpnpManager | null;
+    /**
+     * 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
+     */
+    private envOverridesFromConfig;
+}
+//# sourceMappingURL=upnp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"upnp.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite/src/plugins/upnp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9B,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,UAAU,CACrB,GAAG,SAAS,UAAU,GAAG,MAAM,CAC/B,YAAW,kBAAkB,CAAC,GAAG,CAAC;IAClC,QAAQ,CAAC,IAAI,UAAU;IACvB,QAAQ,CAAC,OAAO,WAAW;IAE3B,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAE5C;;;;OAIG;gBACS,OAAO,CAAC,EAAE,iBAAiB;IAIvC;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBlD;;;;;;OAMG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,IAAI,WAAW,GAAG,IAAI;IAIhC;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;CAoB/B"}