@libp2p/upnp-nat 0.0.0-97ab31c0c

package/LICENSE

@@ -0,0 +1,4 @@
+This project is dual licensed under MIT and Apache-2.0.
+
+MIT: https://www.opensource.org/licenses/mit
+Apache-2.0: https://www.apache.org/licenses/license-2.0

package/README.md

@@ -0,0 +1,62 @@
+[![libp2p.io](https://img.shields.io/badge/project-libp2p-yellow.svg?style=flat-square)](http://libp2p.io/)
+[![Discuss](https://img.shields.io/discourse/https/discuss.libp2p.io/posts.svg?style=flat-square)](https://discuss.libp2p.io)
+[![codecov](https://img.shields.io/codecov/c/github/libp2p/js-libp2p.svg?style=flat-square)](https://codecov.io/gh/libp2p/js-libp2p)
+[![CI](https://img.shields.io/github/actions/workflow/status/libp2p/js-libp2p/main.yml?branch=master\&style=flat-square)](https://github.com/libp2p/js-libp2p/actions/workflows/main.yml?query=branch%3Amaster)
+
+> UPnP NAT hole punching
+
+# About
+
+The service exported by this module attempts to configure NAT hole punching
+via UPnP.
+
+This will make your node publicly accessible from the internet.
+
+For this to work there are some prerequisites:
+
+1. Your router must have UPnP support enabled
+2. Your libp2p node must be listening on a non-loopback IPv4 address
+3. You must not be [double-NATed](https://kb.netgear.com/30186/What-is-double-NAT-and-why-is-it-bad) by your ISP
+
+## Example
+
+```typescript
+import { createLibp2p } from 'libp2p'
+import { tcp } from '@libp2p/tcp'
+import { uPnPNAT } from '@libp2p/upnp-nat'
+
+const node = await createLibp2p({
+  addresses: [
+    listen: [
+      '/ip4/0.0.0.0/tcp/0'
+    ]
+  ],
+  transports: [
+    tcp()
+  ],
+  services: {
+    upnpNAT: uPnPNAT()
+  }
+})
+```
+
+# Install
+
+```console
+$ npm i @libp2p/upnp-nat
+```
+
+# API Docs
+
+- <https://libp2p.github.io/js-libp2p/modules/_libp2p_upnp_nat.html>
+
+# License
+
+Licensed under either of
+
+- Apache 2.0, ([LICENSE-APACHE](LICENSE-APACHE) / <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT ([LICENSE-MIT](LICENSE-MIT) / <http://opensource.org/licenses/MIT>)
+
+# Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

package/dist/src/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @packageDocumentation
+ *
+ * The service exported by this module attempts to configure NAT hole punching
+ * via UPnP.
+ *
+ * This will make your node publicly accessible from the internet.
+ *
+ * For this to work there are some prerequisites:
+ *
+ * 1. Your router must have UPnP support enabled
+ * 2. Your libp2p node must be listening on a non-loopback IPv4 address
+ * 3. You must not be [double-NATed](https://kb.netgear.com/30186/What-is-double-NAT-and-why-is-it-bad) by your ISP
+ *
+ * @example
+ *
+ * ```typescript
+ * import { createLibp2p } from 'libp2p'
+ * import { tcp } from '@libp2p/tcp'
+ * import { uPnPNAT } from '@libp2p/upnp-nat'
+ *
+ * const node = await createLibp2p({
+ *   addresses: [
+ *     listen: [
+ *       '/ip4/0.0.0.0/tcp/0'
+ *     ]
+ *   ],
+ *   transports: [
+ *     tcp()
+ *   ],
+ *   services: {
+ *     upnpNAT: uPnPNAT()
+ *   }
+ * })
+ * ```
+ */
+import type { ComponentLogger, NodeInfo } from '@libp2p/interface';
+import type { PeerId } from '@libp2p/interface/peer-id';
+import type { AddressManager } from '@libp2p/interface-internal/address-manager';
+import type { TransportManager } from '@libp2p/interface-internal/transport-manager';
+export interface PMPOptions {
+    /**
+     * Whether to enable PMP as well as UPnP
+     */
+    enabled?: boolean;
+}
+export interface UPnPNATInit {
+    /**
+     * Pass a value to use instead of auto-detection
+     */
+    externalAddress?: string;
+    /**
+     * Pass a value to use instead of auto-detection
+     */
+    localAddress?: string;
+    /**
+     * A string value to use for the port mapping description on the gateway
+     */
+    description?: string;
+    /**
+     * How long UPnP port mappings should last for in seconds (minimum 1200)
+     */
+    ttl?: number;
+    /**
+     * Whether to automatically refresh UPnP port mappings when their TTL is reached
+     */
+    keepAlive?: boolean;
+    /**
+     * Pass a value to use instead of auto-detection
+     */
+    gateway?: string;
+}
+export interface UPnPNATComponents {
+    peerId: PeerId;
+    nodeInfo: NodeInfo;
+    logger: ComponentLogger;
+    transportManager: TransportManager;
+    addressManager: AddressManager;
+}
+export declare function uPnPNAT(init?: UPnPNATInit): (components: UPnPNATComponents) => unknown;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAClE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4CAA4C,CAAA;AAChF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAA;AAEpF,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,QAAQ,CAAA;IAClB,MAAM,EAAE,eAAe,CAAA;IACvB,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,cAAc,EAAE,cAAc,CAAA;CAC/B;AAED,wBAAgB,OAAO,CAAE,IAAI,GAAE,WAAgB,GAAG,CAAC,UAAU,EAAE,iBAAiB,KAAK,OAAO,CAI3F"}

package/dist/src/index.js

@@ -0,0 +1,43 @@
+/**
+ * @packageDocumentation
+ *
+ * The service exported by this module attempts to configure NAT hole punching
+ * via UPnP.
+ *
+ * This will make your node publicly accessible from the internet.
+ *
+ * For this to work there are some prerequisites:
+ *
+ * 1. Your router must have UPnP support enabled
+ * 2. Your libp2p node must be listening on a non-loopback IPv4 address
+ * 3. You must not be [double-NATed](https://kb.netgear.com/30186/What-is-double-NAT-and-why-is-it-bad) by your ISP
+ *
+ * @example
+ *
+ * ```typescript
+ * import { createLibp2p } from 'libp2p'
+ * import { tcp } from '@libp2p/tcp'
+ * import { uPnPNAT } from '@libp2p/upnp-nat'
+ *
+ * const node = await createLibp2p({
+ *   addresses: [
+ *     listen: [
+ *       '/ip4/0.0.0.0/tcp/0'
+ *     ]
+ *   ],
+ *   transports: [
+ *     tcp()
+ *   ],
+ *   services: {
+ *     upnpNAT: uPnPNAT()
+ *   }
+ * })
+ * ```
+ */
+import { UPnPNAT } from './upnp-nat.js';
+export function uPnPNAT(init = {}) {
+    return (components) => {
+        return new UPnPNAT(components, init);
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAqDvC,MAAM,UAAU,OAAO,CAAE,OAAoB,EAAE;IAC7C,OAAO,CAAC,UAA6B,EAAE,EAAE;QACvC,OAAO,IAAI,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;IACtC,CAAC,CAAA;AACH,CAAC"}

package/dist/src/upnp-nat.d.ts

@@ -0,0 +1,31 @@
+import { type NatAPI } from '@achingbrain/nat-port-mapper';
+import type { UPnPNATComponents, UPnPNATInit } from './index.js';
+import type { Startable } from '@libp2p/interface/startable';
+export declare class UPnPNAT implements Startable {
+    private readonly components;
+    private readonly externalAddress?;
+    private readonly localAddress?;
+    private readonly description;
+    private readonly ttl;
+    private readonly keepAlive;
+    private readonly gateway?;
+    private started;
+    private client?;
+    private readonly log;
+    constructor(components: UPnPNATComponents, init: UPnPNATInit);
+    isStarted(): boolean;
+    start(): void;
+    /**
+     * Attempt to use uPnP to configure port mapping using the current gateway.
+     *
+     * Run after start to ensure the transport manager has all addresses configured.
+     */
+    afterStart(): void;
+    mapIpAddresses(): Promise<void>;
+    _getClient(): NatAPI;
+    /**
+     * Stops the NAT manager
+     */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=upnp-nat.d.ts.map

package/dist/src/upnp-nat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upnp-nat.d.ts","sourceRoot":"","sources":["../../src/upnp-nat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,8BAA8B,CAAA;AAMnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAEhE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAA;AAQ5D,qBAAa,OAAQ,YAAW,SAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAQ;IACjC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAC,CAAQ;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;gBAEf,UAAU,EAAE,iBAAiB,EAAE,IAAI,EAAE,WAAW;IAiB7D,SAAS,IAAK,OAAO;IAIrB,KAAK,IAAK,IAAI;IAId;;;;OAIG;IACH,UAAU,IAAK,IAAI;IAcb,cAAc,IAAK,OAAO,CAAC,IAAI,CAAC;IAuDtC,UAAU,IAAK,MAAM;IAerB;;OAEG;IACG,IAAI,IAAK,OAAO,CAAC,IAAI,CAAC;CAY7B"}

package/dist/src/upnp-nat.js

@@ -0,0 +1,129 @@
+import { upnpNat } from '@achingbrain/nat-port-mapper';
+import { CodeError, ERR_INVALID_PARAMETERS } from '@libp2p/interface/errors';
+import { isLoopback } from '@libp2p/utils/multiaddr/is-loopback';
+import { fromNodeAddress } from '@multiformats/multiaddr';
+import isPrivateIp from 'private-ip';
+import { isBrowser } from 'wherearewe';
+const DEFAULT_TTL = 7200;
+function highPort(min = 1024, max = 65535) {
+    return Math.floor(Math.random() * (max - min + 1) + min);
+}
+export class UPnPNAT {
+    components;
+    externalAddress;
+    localAddress;
+    description;
+    ttl;
+    keepAlive;
+    gateway;
+    started;
+    client;
+    log;
+    constructor(components, init) {
+        this.components = components;
+        this.log = components.logger.forComponent('libp2p:upnp-nat');
+        this.started = false;
+        this.externalAddress = init.externalAddress;
+        this.localAddress = init.localAddress;
+        this.description = init.description ?? `${components.nodeInfo.name}@${components.nodeInfo.version} ${this.components.peerId.toString()}`;
+        this.ttl = init.ttl ?? DEFAULT_TTL;
+        this.keepAlive = init.keepAlive ?? true;
+        this.gateway = init.gateway;
+        if (this.ttl < DEFAULT_TTL) {
+            throw new CodeError(`NatManager ttl should be at least ${DEFAULT_TTL} seconds`, ERR_INVALID_PARAMETERS);
+        }
+    }
+    isStarted() {
+        return this.started;
+    }
+    start() {
+        // #TODO: is there a way to remove this? Seems like a hack
+    }
+    /**
+     * Attempt to use uPnP to configure port mapping using the current gateway.
+     *
+     * Run after start to ensure the transport manager has all addresses configured.
+     */
+    afterStart() {
+        if (isBrowser || this.started) {
+            return;
+        }
+        this.started = true;
+        // done async to not slow down startup
+        void this.mapIpAddresses().catch((err) => {
+            // hole punching errors are non-fatal
+            this.log.error(err);
+        });
+    }
+    async mapIpAddresses() {
+        const addrs = this.components.transportManager.getAddrs();
+        for (const addr of addrs) {
+            // try to open uPnP ports for each thin waist address
+            const { family, host, port, transport } = addr.toOptions();
+            if (!addr.isThinWaistAddress() || transport !== 'tcp') {
+                // only bare tcp addresses
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+            if (isLoopback(addr)) {
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+            if (family !== 4) {
+                // ignore ipv6
+                // eslint-disable-next-line no-continue
+                continue;
+            }
+            const client = this._getClient();
+            const publicIp = this.externalAddress ?? await client.externalIp();
+            const isPrivate = isPrivateIp(publicIp);
+            if (isPrivate === true) {
+                throw new CodeError(`${publicIp} is private - please set config.nat.externalIp to an externally routable IP or ensure you are not behind a double NAT`, 'ERR_DOUBLE_NAT');
+            }
+            if (isPrivate == null) {
+                throw new CodeError(`${publicIp} is not an IP address`, ERR_INVALID_PARAMETERS);
+            }
+            const publicPort = highPort();
+            this.log(`opening uPnP connection from ${publicIp}:${publicPort} to ${host}:${port}`);
+            await client.map({
+                publicPort,
+                localPort: port,
+                localAddress: this.localAddress,
+                protocol: transport.toUpperCase() === 'TCP' ? 'TCP' : 'UDP'
+            });
+            this.components.addressManager.addObservedAddr(fromNodeAddress({
+                family: 4,
+                address: publicIp,
+                port: publicPort
+            }, transport));
+        }
+    }
+    _getClient() {
+        if (this.client != null) {
+            return this.client;
+        }
+        this.client = upnpNat({
+            description: this.description,
+            ttl: this.ttl,
+            keepAlive: this.keepAlive,
+            gateway: this.gateway
+        });
+        return this.client;
+    }
+    /**
+     * Stops the NAT manager
+     */
+    async stop() {
+        if (isBrowser || this.client == null) {
+            return;
+        }
+        try {
+            await this.client.close();
+            this.client = undefined;
+        }
+        catch (err) {
+            this.log.error(err);
+        }
+    }
+}
+//# sourceMappingURL=upnp-nat.js.map

package/dist/src/upnp-nat.js.map

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

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@libp2p/upnp-nat",
+  "version": "0.0.0-97ab31c0c",
+  "description": "UPnP NAT hole punching",
+  "license": "Apache-2.0 OR MIT",
+  "homepage": "https://github.com/libp2p/js-libp2p/tree/master/packages/upnp-nat#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/libp2p/js-libp2p.git"
+  },
+  "bugs": {
+    "url": "https://github.com/libp2p/js-libp2p/issues"
+  },
+  "keywords": [
+    "IPFS"
+  ],
+  "type": "module",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "src",
+    "dist",
+    "!dist/test",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "eslintConfig": {
+    "extends": "ipfs",
+    "parserOptions": {
+      "project": true,
+      "sourceType": "module"
+    }
+  },
+  "scripts": {
+    "clean": "aegir clean",
+    "lint": "aegir lint",
+    "dep-check": "aegir dep-check",
+    "build": "aegir build --no-bundle",
+    "test": "aegir test -t node -t electron-main",
+    "test:node": "aegir test -t node --cov",
+    "test:electron-main": "aegir test -t electron-main"
+  },
+  "dependencies": {
+    "@achingbrain/nat-port-mapper": "^1.0.12",
+    "@libp2p/interface": "0.1.6-97ab31c0c",
+    "@libp2p/interface-internal": "0.1.9-97ab31c0c",
+    "@libp2p/utils": "4.0.7-97ab31c0c",
+    "@multiformats/multiaddr": "^12.1.10",
+    "private-ip": "^3.0.1",
+    "wherearewe": "^2.0.1"
+  },
+  "devDependencies": {
+    "@libp2p/logger": "3.1.0-97ab31c0c",
+    "@libp2p/peer-id-factory": "3.0.8-97ab31c0c",
+    "aegir": "^41.0.2",
+    "sinon-ts": "^2.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+/**
+ * @packageDocumentation
+ *
+ * The service exported by this module attempts to configure NAT hole punching
+ * via UPnP.
+ *
+ * This will make your node publicly accessible from the internet.
+ *
+ * For this to work there are some prerequisites:
+ *
+ * 1. Your router must have UPnP support enabled
+ * 2. Your libp2p node must be listening on a non-loopback IPv4 address
+ * 3. You must not be [double-NATed](https://kb.netgear.com/30186/What-is-double-NAT-and-why-is-it-bad) by your ISP
+ *
+ * @example
+ *
+ * ```typescript
+ * import { createLibp2p } from 'libp2p'
+ * import { tcp } from '@libp2p/tcp'
+ * import { uPnPNAT } from '@libp2p/upnp-nat'
+ *
+ * const node = await createLibp2p({
+ *   addresses: [
+ *     listen: [
+ *       '/ip4/0.0.0.0/tcp/0'
+ *     ]
+ *   ],
+ *   transports: [
+ *     tcp()
+ *   ],
+ *   services: {
+ *     upnpNAT: uPnPNAT()
+ *   }
+ * })
+ * ```
+ */
+
+import { UPnPNAT } from './upnp-nat.js'
+import type { ComponentLogger, NodeInfo } from '@libp2p/interface'
+import type { PeerId } from '@libp2p/interface/peer-id'
+import type { AddressManager } from '@libp2p/interface-internal/address-manager'
+import type { TransportManager } from '@libp2p/interface-internal/transport-manager'
+
+export interface PMPOptions {
+  /**
+   * Whether to enable PMP as well as UPnP
+   */
+  enabled?: boolean
+}
+
+export interface UPnPNATInit {
+  /**
+   * Pass a value to use instead of auto-detection
+   */
+  externalAddress?: string
+
+  /**
+   * Pass a value to use instead of auto-detection
+   */
+  localAddress?: string
+
+  /**
+   * A string value to use for the port mapping description on the gateway
+   */
+  description?: string
+
+  /**
+   * How long UPnP port mappings should last for in seconds (minimum 1200)
+   */
+  ttl?: number
+
+  /**
+   * Whether to automatically refresh UPnP port mappings when their TTL is reached
+   */
+  keepAlive?: boolean
+
+  /**
+   * Pass a value to use instead of auto-detection
+   */
+  gateway?: string
+}
+
+export interface UPnPNATComponents {
+  peerId: PeerId
+  nodeInfo: NodeInfo
+  logger: ComponentLogger
+  transportManager: TransportManager
+  addressManager: AddressManager
+}
+
+export function uPnPNAT (init: UPnPNATInit = {}): (components: UPnPNATComponents) => unknown {
+  return (components: UPnPNATComponents) => {
+    return new UPnPNAT(components, init)
+  }
+}

package/src/upnp-nat.ts

@@ -0,0 +1,158 @@
+import { upnpNat, type NatAPI } from '@achingbrain/nat-port-mapper'
+import { CodeError, ERR_INVALID_PARAMETERS } from '@libp2p/interface/errors'
+import { isLoopback } from '@libp2p/utils/multiaddr/is-loopback'
+import { fromNodeAddress } from '@multiformats/multiaddr'
+import isPrivateIp from 'private-ip'
+import { isBrowser } from 'wherearewe'
+import type { UPnPNATComponents, UPnPNATInit } from './index.js'
+import type { Logger } from '@libp2p/interface'
+import type { Startable } from '@libp2p/interface/startable'
+
+const DEFAULT_TTL = 7200
+
+function highPort (min = 1024, max = 65535): number {
+  return Math.floor(Math.random() * (max - min + 1) + min)
+}
+
+export class UPnPNAT implements Startable {
+  private readonly components: UPnPNATComponents
+  private readonly externalAddress?: string
+  private readonly localAddress?: string
+  private readonly description: string
+  private readonly ttl: number
+  private readonly keepAlive: boolean
+  private readonly gateway?: string
+  private started: boolean
+  private client?: NatAPI
+  private readonly log: Logger
+
+  constructor (components: UPnPNATComponents, init: UPnPNATInit) {
+    this.components = components
+
+    this.log = components.logger.forComponent('libp2p:upnp-nat')
+    this.started = false
+    this.externalAddress = init.externalAddress
+    this.localAddress = init.localAddress
+    this.description = init.description ?? `${components.nodeInfo.name}@${components.nodeInfo.version} ${this.components.peerId.toString()}`
+    this.ttl = init.ttl ?? DEFAULT_TTL
+    this.keepAlive = init.keepAlive ?? true
+    this.gateway = init.gateway
+
+    if (this.ttl < DEFAULT_TTL) {
+      throw new CodeError(`NatManager ttl should be at least ${DEFAULT_TTL} seconds`, ERR_INVALID_PARAMETERS)
+    }
+  }
+
+  isStarted (): boolean {
+    return this.started
+  }
+
+  start (): void {
+    // #TODO: is there a way to remove this? Seems like a hack
+  }
+
+  /**
+   * Attempt to use uPnP to configure port mapping using the current gateway.
+   *
+   * Run after start to ensure the transport manager has all addresses configured.
+   */
+  afterStart (): void {
+    if (isBrowser || this.started) {
+      return
+    }
+
+    this.started = true
+
+    // done async to not slow down startup
+    void this.mapIpAddresses().catch((err) => {
+      // hole punching errors are non-fatal
+      this.log.error(err)
+    })
+  }
+
+  async mapIpAddresses (): Promise<void> {
+    const addrs = this.components.transportManager.getAddrs()
+
+    for (const addr of addrs) {
+      // try to open uPnP ports for each thin waist address
+      const { family, host, port, transport } = addr.toOptions()
+
+      if (!addr.isThinWaistAddress() || transport !== 'tcp') {
+        // only bare tcp addresses
+        // eslint-disable-next-line no-continue
+        continue
+      }
+
+      if (isLoopback(addr)) {
+        // eslint-disable-next-line no-continue
+        continue
+      }
+
+      if (family !== 4) {
+        // ignore ipv6
+        // eslint-disable-next-line no-continue
+        continue
+      }
+
+      const client = this._getClient()
+      const publicIp = this.externalAddress ?? await client.externalIp()
+      const isPrivate = isPrivateIp(publicIp)
+
+      if (isPrivate === true) {
+        throw new CodeError(`${publicIp} is private - please set config.nat.externalIp to an externally routable IP or ensure you are not behind a double NAT`, 'ERR_DOUBLE_NAT')
+      }
+
+      if (isPrivate == null) {
+        throw new CodeError(`${publicIp} is not an IP address`, ERR_INVALID_PARAMETERS)
+      }
+
+      const publicPort = highPort()
+
+      this.log(`opening uPnP connection from ${publicIp}:${publicPort} to ${host}:${port}`)
+
+      await client.map({
+        publicPort,
+        localPort: port,
+        localAddress: this.localAddress,
+        protocol: transport.toUpperCase() === 'TCP' ? 'TCP' : 'UDP'
+      })
+
+      this.components.addressManager.addObservedAddr(fromNodeAddress({
+        family: 4,
+        address: publicIp,
+        port: publicPort
+      }, transport))
+    }
+  }
+
+  _getClient (): NatAPI {
+    if (this.client != null) {
+      return this.client
+    }
+
+    this.client = upnpNat({
+      description: this.description,
+      ttl: this.ttl,
+      keepAlive: this.keepAlive,
+      gateway: this.gateway
+    })
+
+    return this.client
+  }
+
+  /**
+   * Stops the NAT manager
+   */
+  async stop (): Promise<void> {
+    if (isBrowser || this.client == null) {
+      return
+    }
+
+    try {
+      await this.client.close()
+      this.client = undefined
+    } catch (err: any) {
+      this.log.error(err)
+    }
+  }
+}