@serfab/cadre-host 1.13.0 → 1.14.0

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;
+}

package/src/nat/address-watch.ts

@@ -0,0 +1,92 @@
+import debug from 'debug';
+
+import type { ManagedNodeInfo } from '../orchestrator/types.js';
+
+const log = debug('cadre:host:nat-address-watch');
+
+/**
+ * The shortest gap between two address restarts of one node. Bounds a flapping
+ * router (a mapping that keeps failing and coming back) to one restart per node
+ * per window; a difference found inside the window waits for the first check
+ * after it ends.
+ */
+export const NAT_ADDRESS_RESTART_MIN_INTERVAL_MS = 10 * 60_000;
+
+/** Asked to restart one node so it starts announcing its current public addresses. */
+export type NodeAddressesStaleListener = (nodeId: string) => void | Promise<void>;
+
+/**
+ * Notices a running node whose announced public addresses differ from the ones
+ * it should announce now, and asks its listeners to restart that node. A node
+ * learns its public addresses only at start (`CADRE_APPEND_ANNOUNCE_ADDRS`), so
+ * a restart is how a changed mapping, forward, DDNS hostname or external IP
+ * reaches it.
+ */
+export class AddressWatch {
+  private readonly listeners = new Set<NodeAddressesStaleListener>();
+  /** When each node was last asked to restart (ms since epoch). */
+  private readonly lastRestartAt = new Map<string, number>();
+
+  constructor(private readonly now: () => number) {}
+
+  /** Register a restart listener. Returns an unsubscribe fn. */
+  subscribe(listener: NodeAddressesStaleListener): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  /**
+   * Compare every running node's announced addresses with `expected(node)`, as
+   * sets, and ask for a restart of each that differs and was not restarted
+   * within {@link NAT_ADDRESS_RESTART_MIN_INTERVAL_MS}.
+   */
+  check(nodes: ManagedNodeInfo[], expected: (node: ManagedNodeInfo) => string[]): void {
+    this.forgetMissing(nodes);
+    if (this.listeners.size === 0) return;
+    for (const node of nodes) {
+      if (node.status !== 'running') continue;
+      if (sameAddressSet(node.announcedAddrs, expected(node))) continue;
+      if (this.restartedRecently(node.id)) {
+        log('node %s announces stale addresses; restart deferred by the rate limit', node.id);
+        continue;
+      }
+      this.lastRestartAt.set(node.id, this.now());
+      log('node %s announces stale addresses; asking for a restart', node.id);
+      this.notify(node.id);
+    }
+  }
+
+  /** A terminated node's id may come back as a fresh node, which owes nothing to the old window. */
+  private forgetMissing(nodes: ManagedNodeInfo[]): void {
+    const listed = new Set(nodes.map((n) => n.id));
+    for (const id of this.lastRestartAt.keys()) {
+      if (!listed.has(id)) this.lastRestartAt.delete(id);
+    }
+  }
+
+  private restartedRecently(nodeId: string): boolean {
+    const last = this.lastRestartAt.get(nodeId);
+    return last !== undefined && this.now() - last < NAT_ADDRESS_RESTART_MIN_INTERVAL_MS;
+  }
+
+  /** Fire-and-forget: a restart takes seconds and must not hold up the NAT pass that found it. */
+  private notify(nodeId: string): void {
+    for (const listener of this.listeners) {
+      try {
+        void Promise.resolve(listener(nodeId)).catch((err: unknown) => { logRestartFailure(nodeId, err); });
+      } catch (err) {
+        logRestartFailure(nodeId, err);
+      }
+    }
+  }
+}
+
+function sameAddressSet(a: readonly string[], b: readonly string[]): boolean {
+  const left = new Set(a);
+  const right = new Set(b);
+  return left.size === right.size && [...left].every((addr) => right.has(addr));
+}
+
+function logRestartFailure(nodeId: string, err: unknown): void {
+  log('address restart of node %s failed: %s', nodeId, err instanceof Error ? err.message : String(err));
+}

package/src/nat/ddns/duckdns.ts

@@ -13,7 +13,8 @@ const log = debug('cadre:host:nat-ddns:duckdns');
  * Response is plain text — `OK` on success, `KO` on failure.
  *
  * `hostname` may be supplied as the bare subdomain (`foo`) or the FQDN
- * (`foo.duckdns.org`); we strip the suffix.
+ * (`foo.duckdns.org`); the update strips the suffix, and `qualifyHostname`
+ * adds it.
  */
 export const duckDnsProvider: DdnsProvider = {
   id: 'duckdns',
@@ -21,6 +22,9 @@ export const duckDnsProvider: DdnsProvider = {
   configFields: [
     { key: 'token', label: 'DuckDNS token', secret: true },
   ],
+  qualifyHostname(hostname: string): string {
+    return `${stripSuffix(hostname)}${SUFFIX}`;
+  },
   async update(
     config: Record<string, string>,
     hostname: string,

package/src/nat/ddns/index.ts

@@ -19,6 +19,12 @@ export interface DdnsProvider {
   readonly id: string;
   readonly displayName: string;
   readonly configFields: ReadonlyArray<DdnsConfigField>;
+  /**
+   * The fully qualified name the provider publishes for a hostname as the user
+   * typed it. Stored in place of the typed form because hosted nodes announce the
+   * stored hostname as `/dns4/<hostname>`, so it has to resolve on its own.
+   */
+  qualifyHostname(hostname: string): string;
   /** Push `ip` for `hostname`. Throws NatError(ddns_update_failed) on failure. */
   update(
     config: Record<string, string>,

package/src/nat/index.ts

@@ -1,71 +1,87 @@
-/**
- * NAT / DDNS substrate for cadre-host.
- *
- * See ./nat-service.ts for the top-level orchestrator and `docs/cadre-host.md`
- * for integration notes (the long-running process owner is `cadre-host-local-ui`).
- */
-
-export { NatService, createNatHandlers } from './nat-service.js';
-export type { NatServiceOptions, CadreNodeLike, AddressesChangedListener } from './nat-service.js';
-export { NatStore } from './nat-store.js';
-export {
-  NatError,
-} from './types.js';
-export type {
-  NatStatusSnapshot,
-  NatDdnsStatus,
-  NatSettingsFile,
-  NatDdnsSettings,
-  NatHandlers,
-  NatErrorCode,
-  PortForwardMode,
-  DirectReachability,
-  DdnsProviderInfo,
-  DdnsConfigField,
-} from './types.js';
-export {
-  ExternalIpDetector,
-  isPlausibleIp,
-} from './external-ip.js';
-export type {
-  ExternalIpResult,
-  RouterIpProbe,
-  ExternalIpDetectorOptions,
-} from './external-ip.js';
-export {
-  PortMapperService,
-  createDefaultPortMapper,
-  DEFAULT_LEASE_TTL_MS,
-  DEFAULT_REFRESH_MS,
-} from './port-mapper.js';
-export type {
-  PortMapper,
-  PortMappingResult,
-  PortMapOptions,
-  PortMapperState,
-  PortMapperServiceOptions,
-} from './port-mapper.js';
-export { evaluateReachability } from './reachability.js';
-export { buildInviteAddresses } from './address-resolver.js';
-export type { BuildInviteAddressesInput } from './address-resolver.js';
-export {
-  BUILTIN_PROVIDERS,
-  getProvider,
-  listProviders,
-  duckDnsProvider,
-  DdnsUpdater,
-} from './ddns/index.js';
-export type {
-  DdnsProvider,
-  DdnsProviderDeps,
-  DdnsUpdaterOptions,
-  DdnsUpdateOutcome,
-} from './ddns/index.js';
-export {
-  KeytarSecretsStore,
-  FileSecretsStore,
-  createSecretsStore,
-  ddnsAccount,
-  KEYTAR_SERVICE,
-} from './secrets/index.js';
-export type { SecretsStore, KeytarLike } from './secrets/index.js';
+/**
+ * NAT / DDNS substrate for cadre-host.
+ *
+ * See ./nat-service.ts for the top-level orchestrator and `docs/cadre-host.md`
+ * for integration notes (the long-running process owner is `cadre-host start`).
+ */
+
+export {
+  NatService,
+  createNatHandlers,
+  NAT_UNMAP_GRACE_MS,
+  NAT_RECONCILE_INTERVAL_MS,
+  NAT_IP_REDETECT_INTERVAL_MS,
+} from './nat-service.js';
+export type { NatServiceOptions, NatNodeSource, NatChangeListener } from './nat-service.js';
+export { NAT_ADDRESS_RESTART_MIN_INTERVAL_MS } from './address-watch.js';
+export type { NodeAddressesStaleListener } from './address-watch.js';
+export { NatStore } from './nat-store.js';
+export {
+  NatError,
+} from './types.js';
+export type {
+  NatStatusSnapshot,
+  NatGatewayStatus,
+  NatDdnsStatus,
+  NatSettingsFile,
+  NatDdnsSettings,
+  NatHandlers,
+  NatErrorCode,
+  DirectReachability,
+  NodeReachability,
+  NodeVerdict,
+  PortKind,
+  PortRoute,
+  PortRouteSource,
+  ManualForward,
+  ManualForwardPatch,
+  DdnsProviderInfo,
+  DdnsConfigField,
+} from './types.js';
+export {
+  ExternalIpDetector,
+  isPlausibleIp,
+} from './external-ip.js';
+export type {
+  ExternalIpResult,
+  RouterIpProbe,
+  ExternalIpDetectorOptions,
+} from './external-ip.js';
+export {
+  UpnpPortMapper,
+  pickLanAddress,
+  DEFAULT_LEASE_TTL_MS,
+  DEFAULT_REFRESH_MS,
+  GATEWAY_DISCOVERY_TIMEOUT_MS,
+} from './port-mapper.js';
+export type {
+  PortMapper,
+  GatewayInfo,
+  PortMapRequest,
+  PortMapResult,
+} from './port-mapper.js';
+export { evaluateNodeReachability, evaluateHostReachability } from './reachability.js';
+export type { NodeVerdictInput, NodeVerdictResult } from './reachability.js';
+export { buildPublicAddresses, isPublicIpv4 } from './address-resolver.js';
+export type { PublicAddressInput } from './address-resolver.js';
+export {
+  BUILTIN_PROVIDERS,
+  getProvider,
+  listProviders,
+  duckDnsProvider,
+  DdnsUpdater,
+} from './ddns/index.js';
+export type {
+  DdnsProvider,
+  DdnsProviderDeps,
+  DdnsUpdaterOptions,
+  DdnsUpdateOutcome,
+} from './ddns/index.js';
+export {
+  KeytarSecretsStore,
+  FileSecretsStore,
+  createSecretsStore,
+  ddnsAccount,
+  KEYTAR_SERVICE,
+} from './secrets/index.js';
+export type { SecretsStore, KeytarLike } from './secrets/index.js';