@serfab/cadre-host 1.13.0 → 1.15.0

package/src/nat/__tests__/nat-store.test.ts

@@ -16,13 +16,17 @@ afterEach(() => {
   try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
 });
 
+function rawFile(): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(tmpRoot, 'nat.json'), 'utf8')) as Record<string, unknown>;
+}
+
 describe('NatStore', () => {
   it('returns defaults when file is missing', () => {
     const store = new NatStore(tmpRoot);
     const s = store.load();
-    expect(s.externalPort).toBe(4001);
-    expect(s.internalPort).toBe(4001);
+    expect(s.network).toBe('auto');
     expect(s.upnpEnabled).toBe(true);
+    expect(s.forwards).toEqual({});
     expect(s.ddns.providerId).toBeNull();
     expect(s.ddns.externallyManaged).toBe(false);
     expect(s.ddns.intervalMs).toBe(5 * 60 * 1000);
@@ -30,15 +34,37 @@ describe('NatStore', () => {
 
   it('persists and reloads settings atomically', () => {
     const store = new NatStore(tmpRoot);
-    store.update({ externalPort: 4002, upnpEnabled: false });
+    store.update({ upnpEnabled: false });
 
     expect(existsSync(join(tmpRoot, 'nat.json'))).toBe(true);
     expect(existsSync(join(tmpRoot, 'nat.json.tmp'))).toBe(false);
 
     const reread = new NatStore(tmpRoot);
-    const s = reread.load();
-    expect(s.externalPort).toBe(4002);
+    expect(reread.load().upnpEnabled).toBe(false);
+    expect(rawFile().version).toBe(1);
+  });
+
+  it('loads a file written by an older build and drops its single-port fields on save', () => {
+    writeFileSync(join(tmpRoot, 'nat.json'), JSON.stringify({
+      version: 1,
+      externalPort: 4001,
+      internalPort: 4001,
+      upnpEnabled: false,
+      ddns: { providerId: null, hostname: null, externallyManaged: false, intervalMs: 300_000 },
+    }), 'utf8');
+    const store = new NatStore(tmpRoot);
+    const s = store.load();
     expect(s.upnpEnabled).toBe(false);
+    expect(s.forwards).toEqual({});
+    expect('externalPort' in s).toBe(false);
+    // Written before network modes existed: reads as `auto`.
+    expect(s.network).toBe('auto');
+
+    store.update({ upnpEnabled: true });
+    const raw = rawFile();
+    expect(raw.externalPort).toBeUndefined();
+    expect(raw.internalPort).toBeUndefined();
+    expect(raw.forwards).toEqual({});
   });
 
   it('merges ddns subtree on update', () => {
@@ -61,11 +87,21 @@ describe('NatStore', () => {
     expect(s.ddns.intervalMs).toBe(60_000);
   });
 
-  it('persists version field', () => {
+  it('setForward sets, clears and removes per-port entries', () => {
+    const store = new NatStore(tmpRoot);
+    expect(store.setForward('a', { tcp: 40000, ws: 40001 }).forwards).toEqual({ a: { tcp: 40000, ws: 40001 } });
+    expect(store.setForward('a', { tcp: null }).forwards).toEqual({ a: { ws: 40001 } });
+    expect(store.setForward('a', { ws: 40002 }).forwards).toEqual({ a: { ws: 40002 } });
+    expect(store.setForward('a', { ws: null }).forwards).toEqual({});
+    expect(new NatStore(tmpRoot).load().forwards).toEqual({});
+  });
+
+  it('deleteForward drops one node and leaves the rest', () => {
     const store = new NatStore(tmpRoot);
-    store.update({ externalPort: 4001 });
-    const raw = JSON.parse(readFileSync(join(tmpRoot, 'nat.json'), 'utf8'));
-    expect(raw.version).toBe(1);
+    store.setForward('a', { tcp: 40000 });
+    store.setForward('b', { ws: 40001 });
+    expect(store.deleteForward('a').forwards).toEqual({ b: { ws: 40001 } });
+    expect(store.deleteForward('missing').forwards).toEqual({ b: { ws: 40001 } });
   });
 
   it('throws on malformed JSON rather than silently wiping', () => {
@@ -74,10 +110,11 @@ describe('NatStore', () => {
     expect(() => store.load()).toThrow(NatError);
   });
 
-  it('rejects invalid port', () => {
+  it('rejects an out-of-range or non-integer forwarded port', () => {
     const store = new NatStore(tmpRoot);
-    expect(() => store.update({ externalPort: 0 })).toThrow(NatError);
-    expect(() => store.update({ externalPort: 70000 })).toThrow(NatError);
+    expect(() => store.setForward('a', { tcp: 0 })).toThrow(NatError);
+    expect(() => store.setForward('a', { ws: 70000 })).toThrow(NatError);
+    expect(() => store.setForward('a', { tcp: 1.5 })).toThrow(NatError);
   });
 
   it('rejects too-small interval', () => {

package/src/nat/__tests__/network-mode.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import type { NetworkInterfaceInfo } from 'node:os';
+
+import { effectiveNetworkMode, publicInterfaceAddress } from '../network-mode.js';
+
+/** One IPv4 interface entry, as `os.networkInterfaces()` reports it. */
+function v4(address: string, internal = false): NetworkInterfaceInfo {
+  return { address, netmask: '255.255.255.0', family: 'IPv4', mac: '00:00:00:00:00:00', internal, cidr: `${address}/24` };
+}
+
+describe('publicInterfaceAddress', () => {
+  it('finds a VPS\'s public address among private, Docker and loopback interfaces', () => {
+    expect(publicInterfaceAddress({
+      lo: [v4('127.0.0.1', true)],
+      docker0: [v4('172.17.0.1')],
+      eth1: [v4('10.10.0.5')],
+      eth0: [v4('107.170.255.209')],
+    })).toBe('107.170.255.209');
+  });
+
+  it('is null behind a router: private, carrier-grade and link-local addresses only', () => {
+    expect(publicInterfaceAddress({
+      eno1: [v4('192.168.2.27')],
+      tailscale0: [v4('100.101.102.103')],
+      bk0: [v4('10.9.9.1')],
+      wlan0: [v4('169.254.10.10')],
+    })).toBeNull();
+  });
+});
+
+describe('effectiveNetworkMode', () => {
+  it('auto follows the interfaces; an explicit setting wins', () => {
+    expect(effectiveNetworkMode('auto', '203.0.113.7')).toBe('public');
+    expect(effectiveNetworkMode('auto', null)).toBe('lan');
+    expect(effectiveNetworkMode('lan', '203.0.113.7')).toBe('lan');
+    expect(effectiveNetworkMode('public', null)).toBe('public');
+  });
+});

package/src/nat/__tests__/port-mapper.test.ts

@@ -1,191 +1,30 @@
-import { describe, expect, it } from 'vitest';
-
-import { NatError } from '../types.js';
-import {
-  PortMapperService,
-  type PortMapper,
-  type PortMappingResult,
-} from '../port-mapper.js';
-
-interface FakeOpts {
-  mapShouldThrow?: Error;
-  verifyResult?: boolean;
-  verifyShouldThrow?: Error;
-  externalIp?: string | null;
-}
-
-function makeFakeMapper(initial: FakeOpts = {}): PortMapper & {
-  calls: { map: number; verify: number; unmap: number; stop: number };
-  options: FakeOpts;
-} {
-  const opts = { ...initial };
-  const calls = { map: 0, verify: 0, unmap: 0, stop: 0 };
-  return {
-    options: opts,
-    calls,
-    async map(o): Promise<PortMappingResult> {
-      calls.map++;
-      if (opts.mapShouldThrow) throw opts.mapShouldThrow;
-      return {
-        mode: 'auto-upnp',
-        externalIp: opts.externalIp ?? '203.0.113.1',
-        externalPort: o.externalPort,
-        internalPort: o.internalPort,
-        protocol: o.protocol ?? 'tcp',
-        leaseExpiresAt: new Date(Date.now() + (o.ttlMs ?? 60_000)),
-      };
-    },
-    async verify() {
-      calls.verify++;
-      if (opts.verifyShouldThrow) throw opts.verifyShouldThrow;
-      return opts.verifyResult ?? true;
-    },
-    async externalIp() {
-      return opts.externalIp ?? '203.0.113.1';
-    },
-    async unmap() {
-      calls.unmap++;
-    },
-    async stop() {
-      calls.stop++;
-    },
-  };
-}
-
-function fakeTimers(): {
-  setTimer: (fn: () => void, ms: number) => NodeJS.Timeout;
-  clearTimer: (h: NodeJS.Timeout) => void;
-  fire(): void;
-  pending: number;
-} {
-  let callback: (() => void) | null = null;
-  return {
-    setTimer: (fn) => {
-      callback = fn;
-      return {} as NodeJS.Timeout;
-    },
-    clearTimer: () => {
-      callback = null;
-    },
-    fire: () => {
-      const cb = callback;
-      callback = null;
-      cb?.();
-    },
-    get pending() { return callback ? 1 : 0; },
-  };
-}
-
-describe('PortMapperService', () => {
-  it('installs the mapping on start and records mode + externalIp', async () => {
-    const mapper = makeFakeMapper({ externalIp: '203.0.113.42' });
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper,
-      externalPort: 4001,
-      internalPort: 4001,
-      setTimer: timers.setTimer,
-      clearTimer: timers.clearTimer,
-    });
-
-    await svc.start();
-    const state = svc.getState();
-    expect(state.mode).toBe('auto-upnp');
-    expect(state.routerExternalIp).toBe('203.0.113.42');
-    expect(state.externalPort).toBe(4001);
-    expect(state.lastError).toBeNull();
-    expect(mapper.calls.map).toBe(1);
-  });
-
-  it('flips to mode=failed when the mapper throws', async () => {
-    const mapper = makeFakeMapper({ mapShouldThrow: new NatError('mapping_failed', 'router said no') });
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper,
-      externalPort: 4001,
-      internalPort: 4001,
-      setTimer: timers.setTimer,
-      clearTimer: timers.clearTimer,
-    });
-
-    await svc.start();
-    expect(svc.getState().mode).toBe('failed');
-    expect(svc.getState().lastError).toContain('router said no');
-  });
-
-  it('unmaps and stops the mapper on stop()', async () => {
-    const mapper = makeFakeMapper();
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper,
-      externalPort: 4001,
-      internalPort: 4001,
-      setTimer: timers.setTimer,
-      clearTimer: timers.clearTimer,
-    });
-    await svc.start();
-    await svc.stop();
-    expect(mapper.calls.unmap).toBeGreaterThanOrEqual(1);
-    expect(mapper.calls.stop).toBeGreaterThanOrEqual(1);
-    expect(svc.getState().mode).toBe('disabled');
-  });
-
-  it('stop() is idempotent', async () => {
-    const mapper = makeFakeMapper();
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper, externalPort: 4001, internalPort: 4001,
-      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
-    });
-    await svc.start();
-    await svc.stop();
-    await svc.stop();
-    expect(mapper.calls.unmap).toBe(1);
-  });
-
-  it('refresh() re-maps when verify fails', async () => {
-    const mapper = makeFakeMapper({ verifyResult: false });
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper, externalPort: 4001, internalPort: 4001,
-      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
-    });
-    await svc.start();
-    expect(mapper.calls.map).toBe(1);
-
-    await svc.refresh();
-    // verify=false → re-map
-    expect(mapper.calls.map).toBe(2);
-  });
-
-  it('refresh() re-issues the mapping when verify succeeds (extends lease)', async () => {
-    const mapper = makeFakeMapper({ verifyResult: true });
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper, externalPort: 4001, internalPort: 4001,
-      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
-    });
-    await svc.start();
-    expect(mapper.calls.map).toBe(1);
-    await svc.refresh();
-    expect(mapper.calls.map).toBe(2);
-    expect(mapper.calls.verify).toBe(1);
-  });
-
-  it('schedules a refresh timer', async () => {
-    const mapper = makeFakeMapper();
-    const timers = fakeTimers();
-    const svc = new PortMapperService({
-      mapper, externalPort: 4001, internalPort: 4001,
-      setTimer: timers.setTimer, clearTimer: timers.clearTimer,
-    });
-    await svc.start();
-    expect(timers.pending).toBe(1);
-
-    // Fire the timer — should re-arm after the inner refresh resolves.
-    timers.fire();
-    // Wait for the async refresh chain to complete.
-    await new Promise((r) => setTimeout(r, 0));
-    expect(timers.pending).toBe(1);
-  });
-});
+import { describe, expect, it } from 'vitest';
+import type { NetworkInterfaceInfo } from 'node:os';
+
+import { pickLanAddress } from '../port-mapper.js';
+
+function v4(address: string, cidr: string, internal = false): NetworkInterfaceInfo {
+  return { address, netmask: '', family: 'IPv4', mac: '00:00:00:00:00:00', internal, cidr };
+}
+
+/**
+ * The address a mapping points at (and a user is told to forward to) must be
+ * the one on the router's own subnet — not a VPN or container interface that
+ * happens to come first.
+ */
+describe('pickLanAddress', () => {
+  it('picks the interface whose subnet contains the router, skipping loopback and other subnets', () => {
+    const interfaces = {
+      lo: [{ address: '127.0.0.1', netmask: '', family: 'IPv4', mac: '', internal: true, cidr: '127.0.0.1/8' } as NetworkInterfaceInfo],
+      docker0: [v4('172.17.0.1', '172.17.0.1/16')],
+      tun0: [v4('10.8.0.2', '10.8.0.2/24')],
+      eth0: [v4('192.168.1.20', '192.168.1.20/24')],
+    };
+    expect(pickLanAddress('192.168.1.1', interfaces)).toBe('192.168.1.20');
+    expect(pickLanAddress('10.8.0.1', interfaces)).toBe('10.8.0.2');
+  });
+
+  it('returns null when no interface shares the router subnet', () => {
+    expect(pickLanAddress('192.168.1.1', { eth0: [v4('10.0.0.5', '10.0.0.5/24')] })).toBeNull();
+  });
+});

package/src/nat/__tests__/reachability.test.ts

@@ -1,24 +1,107 @@
 import { describe, expect, it } from 'vitest';
 
-import { evaluateReachability } from '../reachability.js';
+import { evaluateHostReachability, evaluateNodeReachability, type NodeVerdictInput } from '../reachability.js';
+import type { PortRoute } from '../types.js';
 
-describe('evaluateReachability', () => {
-  it('returns cgnat when cgnatDetected is true (overrides portMode)', () => {
-    expect(evaluateReachability({ portMode: 'auto-upnp', cgnatDetected: true })).toBe('cgnat');
-    expect(evaluateReachability({ portMode: 'failed', cgnatDetected: true })).toBe('cgnat');
+function upnp(internalPort: number): PortRoute {
+  return { internalPort, externalPort: internalPort, source: 'upnp', leaseExpiresAt: null, error: null };
+}
+function manual(internalPort: number): PortRoute {
+  return { internalPort, externalPort: 40000, source: 'manual', leaseExpiresAt: null, error: null };
+}
+function none(internalPort: number, error: string | null = null): PortRoute {
+  return { internalPort, externalPort: null, source: null, leaseExpiresAt: null, error };
+}
+
+const BASE: NodeVerdictInput = {
+  tcp: upnp(10003),
+  ws: upnp(10004),
+  hostKnown: true,
+  cgnatDetected: false,
+  upnpEnabled: true,
+  gatewayFound: true,
+  lanAddress: '192.168.1.20',
+};
+
+describe('evaluateNodeReachability', () => {
+  it('mapped when both ports have UPnP routes', () => {
+    expect(evaluateNodeReachability(BASE)).toEqual({ verdict: 'mapped', reason: null });
+  });
+
+  it('manual when either port is forwarded by hand', () => {
+    expect(evaluateNodeReachability({ ...BASE, ws: manual(10004) }).verdict).toBe('manual');
+  });
+
+  it('a node without a WebSocket port is judged on TCP alone', () => {
+    expect(evaluateNodeReachability({ ...BASE, ws: null }).verdict).toBe('mapped');
+  });
+
+  it('unreachable when the host part is unknown, whatever the routes', () => {
+    const r = evaluateNodeReachability({ ...BASE, hostKnown: false });
+    expect(r.verdict).toBe('unreachable');
+    expect(r.reason).toContain('public address is unknown');
+  });
+
+  it('a refused port names the port, the LAN address and the remedy', () => {
+    const r = evaluateNodeReachability({ ...BASE, ws: none(10004, 'mapping table is full') });
+    expect(r.verdict).toBe('unreachable');
+    expect(r.reason).toBe(
+      'Router refused the WebSocket port 10004 mapping (mapping table is full). ' +
+      'Forward port 10004 to 192.168.1.20 on your router, then tell cadre-host the external port.',
+    );
+  });
+
+  it('two ports failing for one cause are named in one sentence', () => {
+    const r = evaluateNodeReachability({ ...BASE, tcp: none(10003), ws: none(10004), upnpEnabled: false });
+    expect(r.reason).toContain('TCP port 10003 and WebSocket port 10004 are not mapped');
+    expect(r.reason).toContain('forward ports 10003 and 10004 to 192.168.1.20');
+  });
+
+  it('with no gateway the remedy says so and falls back to a generic LAN address', () => {
+    const r = evaluateNodeReachability({ ...BASE, tcp: none(10003), ws: none(10004), gatewayFound: false, lanAddress: null });
+    expect(r.reason).toContain('No UPnP router answered');
+    expect(r.reason).toContain("this machine's LAN address");
+  });
+
+  it('a port not yet attempted reads as pending', () => {
+    expect(evaluateNodeReachability({ ...BASE, tcp: none(10003) }).reason).toContain('not mapped yet');
+  });
+
+  it('under CGNAT a UPnP route is unreachable and a forward will not help; manual routes are fine', () => {
+    const r = evaluateNodeReachability({ ...BASE, cgnatDetected: true });
+    expect(r.verdict).toBe('unreachable');
+    expect(r.reason).toContain('carrier-grade NAT');
+    expect(r.reason).toContain('a relay is needed');
+    const refused = evaluateNodeReachability({ ...BASE, cgnatDetected: true, ws: none(10004, 'mapping table is full') });
+    expect(refused.reason).not.toContain('Forward port');
+    expect(evaluateNodeReachability({ ...BASE, cgnatDetected: true, tcp: manual(10003), ws: manual(10004) }).verdict).toBe('manual');
+  });
+});
+
+describe('evaluateHostReachability', () => {
+  it('unknown with no running nodes', () => {
+    expect(evaluateHostReachability([], false)).toBe('unknown');
+    expect(evaluateHostReachability([{ running: false, verdict: 'unreachable' }], false)).toBe('unknown');
   });
 
-  it('returns reachable for auto-upnp / auto-natpmp', () => {
-    expect(evaluateReachability({ portMode: 'auto-upnp', cgnatDetected: false })).toBe('reachable');
-    expect(evaluateReachability({ portMode: 'auto-natpmp', cgnatDetected: false })).toBe('reachable');
+  it('reachable when every running node is mapped or manual', () => {
+    expect(evaluateHostReachability([
+      { running: true, verdict: 'mapped' },
+      { running: true, verdict: 'manual' },
+      { running: false, verdict: 'unreachable' },
+    ], false)).toBe('reachable');
   });
 
-  it('returns unreachable when port mapping failed', () => {
-    expect(evaluateReachability({ portMode: 'failed', cgnatDetected: false })).toBe('unreachable');
+  it('unreachable when any running node is', () => {
+    expect(evaluateHostReachability([
+      { running: true, verdict: 'mapped' },
+      { running: true, verdict: 'unreachable' },
+    ], false)).toBe('unreachable');
   });
 
-  it('returns unknown for manual / disabled', () => {
-    expect(evaluateReachability({ portMode: 'manual', cgnatDetected: false })).toBe('unknown');
-    expect(evaluateReachability({ portMode: 'disabled', cgnatDetected: false })).toBe('unknown');
+  it('cgnat when detected and no node is reachable through a manual route', () => {
+    expect(evaluateHostReachability([{ running: true, verdict: 'unreachable' }], true)).toBe('cgnat');
+    expect(evaluateHostReachability([], true)).toBe('cgnat');
+    expect(evaluateHostReachability([{ running: true, verdict: 'manual' }], true)).toBe('reachable');
   });
 });

package/src/nat/address-resolver.ts

@@ -1,52 +1,94 @@
-/**
- * Build the multiaddrs that should be embedded in invites.
- *
- * Inputs are the host's currently-best understanding of its dialable surface:
- *   - DDNS hostname (`/dns4/<hostname>/...`) when configured AND reachable.
- *   - Raw external IP (`/ip4/<ip>/...`) when no DDNS but reachable.
- *   - Whatever libp2p reports otherwise — which would include a `/p2p-circuit/`
- *     address once cadre-host passes a relay to its owner node; it passes none
- *     yet (docs/cadre-host.md → "NAT and DDNS", item 2).
- *
- * This is intentionally a pure function so it's trivial to unit-test, and so
- * the NatService can be the only place that knows about settings → multiaddrs.
- */
-export interface BuildInviteAddressesInput {
-  peerId: string;
-  externalPort: number;
-  ddnsHostname: string | null;
-  externalIp: string | null;
-  reachable: boolean;
-  /** Multiaddrs reported by the underlying libp2p node. */
-  libp2pAddrs: string[];
-}
-
-export function buildInviteAddresses(input: BuildInviteAddressesInput): string[] {
-  const suffix = `/p2p/${input.peerId}`;
-  // DNS path-of-truth: stable across IP changes.
-  if (input.reachable && input.ddnsHostname) {
-    return [`/dns4/${input.ddnsHostname}/tcp/${input.externalPort}${suffix}`];
-  }
-  // Raw IPv4: works when we know our external IP.
-  if (input.reachable && input.externalIp && isIpv4(input.externalIp)) {
-    return [`/ip4/${input.externalIp}/tcp/${input.externalPort}${suffix}`];
-  }
-  // Fallback: whatever libp2p sees. Strip any addresses that lack the
-  // peer suffix and append it for clarity, but otherwise pass through.
-  return input.libp2pAddrs.map((a) => withPeerSuffix(a, input.peerId));
-}
-
-function withPeerSuffix(addr: string, peerId: string): string {
-  if (addr.includes(`/p2p/${peerId}`)) return addr;
-  if (addr.includes('/p2p/')) return addr;  // already has *some* peer
-  return `${addr}/p2p/${peerId}`;
-}
-
-function isIpv4(s: string): boolean {
-  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(s);
-  if (!m) return false;
-  return m.slice(1).every((octet) => {
-    const n = Number(octet);
-    return n >= 0 && n <= 255;
-  });
-}
+/**
+ * Build the public multiaddrs of one hosted node from the host's current
+ * understanding of its dialable surface.
+ *
+ * Pure so it's trivial to unit-test, and so `NatService` is the only place
+ * that turns settings and routes into addresses. The addresses carry no
+ * `/p2p/` suffix: the node appends its own (cadre-core `normalizeSelfAddrs`,
+ * libp2p for announce addresses). The node's own LAN addresses are not here
+ * either — libp2p reports those itself.
+ */
+
+import type { PortRoute } from './types.js';
+
+export interface PublicAddressInput {
+  ddnsHostname: string | null;
+  /** Last known public IPv4; null when unknown. */
+  externalIp: string | null;
+  cgnatDetected: boolean;
+  tcp: PortRoute;
+  ws: PortRoute | null;
+}
+
+export function buildPublicAddresses(input: PublicAddressInput): string[] {
+  const host = publicHost(input);
+  if (!host) return [];
+  const out: string[] = [];
+  const tcpPort = routedPort(input.tcp, input.cgnatDetected);
+  if (tcpPort !== null) out.push(`${host}/tcp/${tcpPort}`);
+  const wsPort = input.ws ? routedPort(input.ws, input.cgnatDetected) : null;
+  if (wsPort !== null) out.push(`${host}/tcp/${wsPort}/ws`);
+  return out;
+}
+
+/**
+ * `/dns4/<hostname>` when a DDNS hostname is configured (externally managed
+ * included), else `/ip4/<externalIp>` when that is a public IPv4, else none.
+ *
+ * A hostname that is not a DNS name is skipped rather than used: these addresses
+ * reach each node as `CADRE_APPEND_ANNOUNCE_ADDRS`, a comma-separated list that
+ * cadre-core validates at start, so one bad entry (a pasted URL, a comma) would
+ * stop every hosted node from starting.
+ */
+function publicHost(input: PublicAddressInput): string | null {
+  if (input.ddnsHostname && isDnsHostname(input.ddnsHostname)) return `/dns4/${input.ddnsHostname}`;
+  if (input.externalIp && isPublicIpv4(input.externalIp)) return `/ip4/${input.externalIp}`;
+  return null;
+}
+
+/** One RFC 1123 label: letters, digits and inner hyphens, 1–63 characters. */
+const DNS_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i;
+
+/** True for a hostname of dot-separated RFC 1123 labels, at most 253 characters. */
+export function isDnsHostname(s: string): boolean {
+  return s.length <= 253 && s.split('.').every((label) => DNS_LABEL.test(label));
+}
+
+/**
+ * Under CGNAT a UPnP route produces nothing: the router's mapping is on a
+ * carrier-private address. A manual route still does, since the user asserted
+ * the forward (the CGNAT check can misfire).
+ */
+function routedPort(route: PortRoute, cgnatDetected: boolean): number | null {
+  if (route.externalPort === null || route.source === null) return null;
+  if (cgnatDetected && route.source === 'upnp') return null;
+  return route.externalPort;
+}
+
+/** Private, carrier-grade, loopback, link-local, multicast and reserved IPv4 ranges. */
+const NON_PUBLIC_IPV4: ReadonlyArray<[number, number]> = [
+  [0x00000000, 8],  // 0.0.0.0/8
+  [0x0a000000, 8],  // 10.0.0.0/8
+  [0x64400000, 10], // 100.64.0.0/10 (carrier-grade NAT)
+  [0x7f000000, 8],  // 127.0.0.0/8
+  [0xa9fe0000, 16], // 169.254.0.0/16
+  [0xac100000, 12], // 172.16.0.0/12
+  [0xc0a80000, 16], // 192.168.0.0/16
+  [0xe0000000, 4],  // 224.0.0.0/4 (multicast)
+  [0xf0000000, 4],  // 240.0.0.0/4 (reserved, broadcast)
+];
+
+/** True for a dotted-quad IPv4 outside every non-public range above. */
+export function isPublicIpv4(s: string): boolean {
+  const octets = parseIpv4(s);
+  if (!octets) return false;
+  const value = ((octets[0]! << 24) | (octets[1]! << 16) | (octets[2]! << 8) | octets[3]!) >>> 0;
+  return !NON_PUBLIC_IPV4.some(([base, prefix]) => (value >>> (32 - prefix)) === (base >>> (32 - prefix)));
+}
+
+function parseIpv4(s: string): number[] | null {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(s);
+  if (!m) return null;
+  const octets = m.slice(1).map(Number);
+  return octets.every((n) => n >= 0 && n <= 255) ? octets : null;
+}