@serfab/cadre-host 1.13.0 → 1.14.0

package/src/nat/reachability.ts

@@ -1,34 +1,143 @@
-import type { DirectReachability, PortForwardMode } from './types.js';
+/**
+ * Reachability verdicts: one per hosted node, and the host-level roll-up the
+ * dashboard badge shows. Heuristics over the mapping table, not a dial-back —
+ * libp2p AutoNAT is a later ticket.
+ */
+
+import type {
+  DirectReachability,
+  NodeReachability,
+  NodeVerdict,
+  PortKind,
+  PortRoute,
+} from './types.js';
 
-export interface ReachabilityInput {
-  portMode: PortForwardMode;
+export interface NodeVerdictInput {
+  tcp: PortRoute;
+  /** Null for a handle persisted by an older build without a WebSocket port. */
+  ws: PortRoute | null;
+  /** Whether a public host part exists: a DDNS hostname, or a public IPv4. */
+  hostKnown: boolean;
   cgnatDetected: boolean;
+  upnpEnabled: boolean;
+  gatewayFound: boolean;
+  /** The address a user forwards to; null when no gateway was found. */
+  lanAddress: string | null;
+}
+
+export interface NodeVerdictResult {
+  verdict: NodeVerdict;
+  reason: string | null;
 }
 
 /**
- * v1 reachability heuristic.
- *
- * Returns:
- *   - 'cgnat' when CGNAT was detected (highest signal — UPnP succeeded but our
- *     external IP isn't actually reachable from the open internet).
- *   - 'unreachable' when port mapping failed.
- *   - 'reachable' when an auto mapping succeeded.
- *   - 'unknown' otherwise (manual config, disabled UPnP, etc).
- *
- * A future ticket will replace this with libp2p AutoNAT or a sereus-owned
- * dial-back probe (see the follow-up section of `6.3-cadre-host-nat`).
+ * `unreachable` when either port has no usable route or the host part is
+ * unknown; otherwise `manual` when either port is forwarded by hand, else
+ * `mapped`. A UPnP route under CGNAT is not usable: the router's mapping is on
+ * a carrier-private address.
  */
-export function evaluateReachability(input: ReachabilityInput): DirectReachability {
+export function evaluateNodeReachability(input: NodeVerdictInput): NodeVerdictResult {
+  const ports = portRoutes(input);
+  const failing = ports.filter(({ route }) => !usable(route, input.cgnatDetected));
+  if (!input.hostKnown) {
+    return { verdict: 'unreachable', reason: HOST_UNKNOWN_REASON };
+  }
+  if (failing.length > 0) {
+    return { verdict: 'unreachable', reason: describeFailures(failing, input) };
+  }
+  const manual = ports.some(({ route }) => route.source === 'manual');
+  return { verdict: manual ? 'manual' : 'mapped', reason: null };
+}
+
+/**
+ * Host roll-up: `cgnat` when CGNAT is detected and no node is reachable
+ * through a manual route; `unknown` with no running nodes; `reachable` when
+ * every running node is `mapped`/`manual`; else `unreachable`.
+ */
+export function evaluateHostReachability(
+  nodes: ReadonlyArray<Pick<NodeReachability, 'running' | 'verdict'>>,
+  cgnatDetected: boolean,
+): DirectReachability {
+  const running = nodes.filter((n) => n.running);
+  if (cgnatDetected && !running.some((n) => n.verdict === 'manual')) return 'cgnat';
+  if (running.length === 0) return 'unknown';
+  return running.every((n) => n.verdict !== 'unreachable') ? 'reachable' : 'unreachable';
+}
+
+const HOST_UNKNOWN_REASON =
+  "This host's public address is unknown: no dynamic DNS hostname is set and no public IPv4 address was detected. " +
+  'Set a DDNS hostname, or check that this machine can reach the internet.';
+
+interface PortEntry {
+  kind: PortKind;
+  route: PortRoute;
+}
+
+function portRoutes(input: NodeVerdictInput): PortEntry[] {
+  const out: PortEntry[] = [{ kind: 'tcp', route: input.tcp }];
+  if (input.ws) out.push({ kind: 'ws', route: input.ws });
+  return out;
+}
+
+function usable(route: PortRoute, cgnatDetected: boolean): boolean {
+  if (route.externalPort === null || route.source === null) return false;
+  return !(cgnatDetected && route.source === 'upnp');
+}
+
+type FailureCause = 'cgnat' | 'refused' | 'upnp_off' | 'no_gateway' | 'pending';
+
+/** Behind CGNAT no router-side remedy helps, so CGNAT outranks whatever else failed the port. */
+function causeOf(route: PortRoute, input: NodeVerdictInput): FailureCause {
   if (input.cgnatDetected) return 'cgnat';
-  switch (input.portMode) {
-    case 'auto-upnp':
-    case 'auto-natpmp':
-      return 'reachable';
-    case 'failed':
-      return 'unreachable';
-    case 'manual':
-    case 'disabled':
-    default:
-      return 'unknown';
+  if (route.error) return 'refused';
+  if (!input.upnpEnabled) return 'upnp_off';
+  if (!input.gatewayFound) return 'no_gateway';
+  return 'pending';
+}
+
+/** One sentence per distinct cause, each naming every port that failed for it. */
+function describeFailures(failing: PortEntry[], input: NodeVerdictInput): string {
+  const byCause = new Map<FailureCause, PortEntry[]>();
+  for (const entry of failing) {
+    const cause = causeOf(entry.route, input);
+    byCause.set(cause, [...(byCause.get(cause) ?? []), entry]);
+  }
+  return [...byCause.entries()].map(([cause, entries]) => describeCause(cause, entries, input)).join(' ');
+}
+
+function describeCause(cause: FailureCause, entries: PortEntry[], input: NodeVerdictInput): string {
+  const names = entries.map(({ kind, route }) => `${kindLabel(kind)} port ${route.internalPort}`);
+  const lan = input.lanAddress ?? "this machine's LAN address";
+  const forwardHint = `Forward ${entries.length === 1 ? 'port' : 'ports'} ${listPorts(entries)} to ${lan} on your router, then tell cadre-host the external ${entries.length === 1 ? 'port' : 'ports'}.`;
+  switch (cause) {
+    case 'cgnat':
+      return `This host is behind carrier-grade NAT, so the ${joinNames(names)} cannot be reached from outside through your router, and neither UPnP nor a port forward on your router will help; a relay is needed.`;
+    case 'refused': {
+      const errors = entries.map(({ route }) => route.error).filter((e): e is string => !!e);
+      return `Router refused the ${joinNames(names)} mapping (${errors.join('; ')}). ${forwardHint}`;
+    }
+    case 'upnp_off':
+      return `UPnP is off, so the ${joinNames(names)} ${entries.length === 1 ? 'is' : 'are'} not mapped. Turn UPnP on, or: ${lowerFirst(forwardHint)}`;
+    case 'no_gateway':
+      return `No UPnP router answered, so the ${joinNames(names)} ${entries.length === 1 ? 'is' : 'are'} not mapped. Enable UPnP on your router, or: ${lowerFirst(forwardHint)}`;
+    case 'pending':
+      return `The ${joinNames(names)} ${entries.length === 1 ? 'is' : 'are'} not mapped yet; the router is being asked.`;
   }
 }
+
+function kindLabel(kind: PortKind): string {
+  return kind === 'tcp' ? 'TCP' : 'WebSocket';
+}
+
+function listPorts(entries: PortEntry[]): string {
+  return joinNames(entries.map(({ route }) => String(route.internalPort)));
+}
+
+function joinNames(names: string[]): string {
+  if (names.length <= 1) return names[0] ?? '';
+  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+}
+
+function lowerFirst(s: string): string {
+  return s.charAt(0).toLowerCase() + s.slice(1);
+}

package/src/nat/types.ts

@@ -1,159 +1,209 @@
-/**
- * NAT/DDNS types for cadre-host.
- *
- * cadre-host runs on home/SMB machines that are typically behind NAT. To be
- * dialable from the open internet the host must:
- *   1. Punch a port forward on the upstream router (UPnP/NAT-PMP).
- *   2. Detect its external IP (and whether it's behind CGNAT).
- *   3. Optionally publish a stable hostname via dynamic DNS.
- *
- * State for these three concerns lives in `<rootDir>/nat.json` (user settings)
- * and is exposed as a single `NatStatusSnapshot` to the management UI.
- *
- * Credentials for DDNS providers are NOT stored in `nat.json`. They go through
- * the SecretsStore (keytar, with a 0600 file fallback).
- */
-
-/** Port-forwarding mode currently in effect. */
-export type PortForwardMode =
-  | 'auto-upnp'
-  | 'auto-natpmp'
-  | 'manual'
-  | 'failed'
-  | 'disabled';
-
-/** Reachability verdict — best-effort heuristic until AutoNAT lands. */
-export type DirectReachability = 'reachable' | 'unreachable' | 'unknown' | 'cgnat';
-
-/** Snapshot returned to the management UI / CLI. */
-export interface NatStatusSnapshot {
-  // Port forwarding
-  portMode: PortForwardMode;
-  externalPort: number;
-  internalPort: number;
-  /** IP the router reports as its WAN address. Null when not auto-mapped. */
-  routerExternalIp: string | null;
-  /** ISO timestamp when the current mapping lease expires. */
-  mappingLeaseExpiresAt: string | null;
-
-  // External IP (from public probe; may differ from routerExternalIp under CGNAT)
-  externalIp: string | null;
-  externalIpDetectedAt: string | null;
-  cgnatDetected: boolean;
-
-  // Reachability verdict
-  directReachability: DirectReachability;
-  lastTestedAt: string | null;
-
-  // DDNS
-  ddns: NatDdnsStatus;
-}
-
-/** DDNS sub-section of the status snapshot. */
-export interface NatDdnsStatus {
-  /** Provider ID (e.g. "duckdns"), null when no DDNS is configured. */
-  providerId: string | null;
-  /** Configured hostname (e.g. "foo.duckdns.org"), null when unconfigured. */
-  hostname: string | null;
-  /** True when the user opted out of cadre-host updating the record. */
-  externallyManaged: boolean;
-  /** Last attempt timestamp (ISO), null until first attempt. */
-  lastUpdateAt: string | null;
-  /** Whether the most recent attempt succeeded. */
-  lastUpdateOk: boolean | null;
-  /** Most recent error message, null when last attempt succeeded. */
-  lastError: string | null;
-}
-
-/**
- * On-disk shape of `nat.json`. NEVER contains DDNS credentials — those live
- * in the SecretsStore.
- */
-export interface NatSettingsFile {
-  version: 1;
-  /** External port to map (and announce). Default 4001. */
-  externalPort: number;
-  /** Internal libp2p port. Default 4001. */
-  internalPort: number;
-  /** Whether to attempt UPnP/NAT-PMP at all. */
-  upnpEnabled: boolean;
-  ddns: NatDdnsSettings;
-}
-
-/** DDNS sub-section of `nat.json`. */
-export interface NatDdnsSettings {
-  /** Provider ID (e.g. "duckdns"). Null = unconfigured. */
-  providerId: string | null;
-  /** Hostname to publish. Null = unconfigured. */
-  hostname: string | null;
-  /**
-   * True means the user maintains the DNS record themselves (e.g. via the
-   * provider's own auto-update agent on the router). cadre-host shows the
-   * hostname but never tries to update it.
-   */
-  externallyManaged: boolean;
-  /** DDNS update interval in milliseconds. Default 5 min. */
-  intervalMs: number;
-}
-
-/** Typed error codes for NatError. */
-export type NatErrorCode =
-  | 'mapping_failed'
-  | 'router_unreachable'
-  | 'ip_detection_failed'
-  | 'ddns_provider_unknown'
-  | 'ddns_credentials_missing'
-  | 'ddns_update_failed'
-  | 'secrets_unavailable'
-  | 'storage_error'
-  | 'invalid_config'
-  /** The owner node's admin channel is unreachable / not ready. */
-  | 'node_unavailable';
-
-/** Typed error carrying a stable `code` for HTTP mapping in the local-ui. */
-export class NatError extends Error {
-  readonly code: NatErrorCode;
-
-  constructor(code: NatErrorCode, message: string) {
-    super(message);
-    this.name = 'NatError';
-    this.code = code;
-  }
-}
-
-/** Description of a configurable field on a DDNS provider. */
-export interface DdnsConfigField {
-  /** Field key (e.g. "token"). */
-  key: string;
-  /** Human-readable label (e.g. "DuckDNS token"). */
-  label: string;
-  /** True if the value is a credential that must be stored in the SecretsStore. */
-  secret: boolean;
-}
-
-/** Summary of a DDNS provider for UI / CLI listing. */
-export interface DdnsProviderInfo {
-  id: string;
-  displayName: string;
-  configFields: ReadonlyArray<DdnsConfigField>;
-}
-
-/**
- * Typed HTTP handlers exposed to `cadre-host-local-ui` for Fastify wiring.
- *
- * Like TrustCircleHandlers, these take typed objects and either return typed
- * results or throw a `NatError` whose `.code` the UI ticket maps to an HTTP
- * status code.
- */
-export interface NatHandlers {
-  getStatus(): Promise<NatStatusSnapshot>;
-  testReachability(): Promise<NatStatusSnapshot>;
-  listDdnsProviders(): Promise<DdnsProviderInfo[]>;
-  putDdns(body: {
-    providerId: string;
-    hostname: string;
-    config: Record<string, string>;
-    externallyManaged?: boolean;
-  }): Promise<NatStatusSnapshot>;
-  putSettings(body: Partial<Omit<NatSettingsFile, 'version'>>): Promise<NatStatusSnapshot>;
-}
+/**
+ * NAT/DDNS types for cadre-host.
+ *
+ * cadre-host runs on home/SMB machines that are typically behind NAT. For the
+ * nodes it runs to be dialable from the open internet the host must:
+ *   1. Map every hosted node's two libp2p ports (TCP, and the WebSocket port a
+ *      phone dials) through the upstream router, or let the user forward them
+ *      by hand.
+ *   2. Detect its external IP (and whether it's behind CGNAT).
+ *   3. Optionally publish a stable hostname via dynamic DNS.
+ *
+ * State for these concerns lives in `<rootDir>/nat.json` (user settings) and is
+ * exposed as a single `NatStatusSnapshot` to the management UI, with one
+ * `NodeReachability` entry per hosted node.
+ *
+ * Credentials for DDNS providers are NOT stored in `nat.json`. They go through
+ * the SecretsStore (keytar, with a 0600 file fallback).
+ */
+
+/** Reachability roll-up across the host's running nodes — see `reachability.ts`. */
+export type DirectReachability = 'reachable' | 'unreachable' | 'unknown' | 'cgnat';
+
+/** The two ports of a hosted node that are mapped: libp2p TCP and libp2p WebSocket. */
+export type PortKind = 'tcp' | 'ws';
+
+/** Where a port's external route came from. */
+export type PortRouteSource = 'upnp' | 'manual';
+
+/** How one of a node's ports is reached from outside the home network. */
+export interface PortRoute {
+  internalPort: number;
+  /** Port reachable from outside; null when there is no route. */
+  externalPort: number | null;
+  source: PortRouteSource | null;
+  /** ISO timestamp when the router lease expires; UPnP routes only. */
+  leaseExpiresAt: string | null;
+  /** Last mapping failure, in plain language; null when the last attempt succeeded. */
+  error: string | null;
+}
+
+/** Per-node verdict. */
+export type NodeVerdict = 'mapped' | 'manual' | 'unreachable';
+
+/** Reachability of one hosted node, as reported in the status snapshot. */
+export interface NodeReachability {
+  nodeId: string;
+  /** Whether the node's process is running; a stopped node keeps its last routes until the unmap grace elapses. */
+  running: boolean;
+  verdict: NodeVerdict;
+  /**
+   * Plain-language reason and remedy when unreachable, e.g. "Router refused
+   * the WebSocket port mapping. Forward port 10004 to 192.168.1.20 on your
+   * router, then tell cadre-host the external port."
+   */
+  reason: string | null;
+  tcp: PortRoute;
+  /** Null for a handle persisted by an older build without a WebSocket port. */
+  ws: PortRoute | null;
+  /** Multiaddrs (no `/p2p/` suffix) through which the node is reachable from outside. */
+  publicAddrs: string[];
+}
+
+/** The UPnP gateway as the host last saw it. */
+export interface NatGatewayStatus {
+  found: boolean;
+  /** This machine's address on the router's subnet — the address a user forwards to. */
+  lanAddress: string | null;
+  /** The WAN address the router reports for itself. */
+  routerExternalIp: string | null;
+  /** Why discovery or the last gateway operation failed; null when it did not. */
+  lastError: string | null;
+}
+
+/** Snapshot returned to the management UI / CLI. */
+export interface NatStatusSnapshot {
+  upnpEnabled: boolean;
+  gateway: NatGatewayStatus;
+
+  // External IP (from the public probe, falling back to the router's report).
+  externalIp: string | null;
+  externalIpDetectedAt: string | null;
+  cgnatDetected: boolean;
+
+  /** Roll-up across running nodes; see `reachability.ts`. */
+  directReachability: DirectReachability;
+  lastTestedAt: string | null;
+
+  ddns: NatDdnsStatus;
+  nodes: NodeReachability[];
+}
+
+/** DDNS sub-section of the status snapshot. */
+export interface NatDdnsStatus {
+  /** Provider ID (e.g. "duckdns"), null when no DDNS is configured. */
+  providerId: string | null;
+  /** Configured hostname (e.g. "foo.duckdns.org"), null when unconfigured. */
+  hostname: string | null;
+  /** True when the user opted out of cadre-host updating the record. */
+  externallyManaged: boolean;
+  /** Last attempt timestamp (ISO), null until first attempt. */
+  lastUpdateAt: string | null;
+  /** Whether the most recent attempt succeeded. */
+  lastUpdateOk: boolean | null;
+  /** Most recent error message, null when last attempt succeeded. */
+  lastError: string | null;
+}
+
+/** The external ports a user forwarded on their router for one node, per port kind. */
+export interface ManualForward {
+  tcp?: number;
+  ws?: number;
+}
+
+/** Patch applied by `PUT /nat/nodes/:nodeId/forward`: `null` clears that port. */
+export interface ManualForwardPatch {
+  tcp?: number | null;
+  ws?: number | null;
+}
+
+/**
+ * On-disk shape of `nat.json`. NEVER contains DDNS credentials — those live
+ * in the SecretsStore.
+ */
+export interface NatSettingsFile {
+  version: 1;
+  /** Whether to ask the router for port mappings at all. */
+  upnpEnabled: boolean;
+  /** Per node id: the external port the user forwarded on their router, per port kind. */
+  forwards: Record<string, ManualForward>;
+  ddns: NatDdnsSettings;
+}
+
+/** DDNS sub-section of `nat.json`. */
+export interface NatDdnsSettings {
+  /** Provider ID (e.g. "duckdns"). Null = unconfigured. */
+  providerId: string | null;
+  /** Hostname to publish. Null = unconfigured. */
+  hostname: string | null;
+  /**
+   * True means the user maintains the DNS record themselves (e.g. via the
+   * provider's own auto-update agent on the router). cadre-host shows the
+   * hostname but never tries to update it.
+   */
+  externallyManaged: boolean;
+  /** DDNS update interval in milliseconds. Default 5 min. */
+  intervalMs: number;
+}
+
+/** Typed error codes for NatError. */
+export type NatErrorCode =
+  | 'mapping_failed'
+  | 'router_unreachable'
+  | 'ip_detection_failed'
+  | 'ddns_provider_unknown'
+  | 'ddns_credentials_missing'
+  | 'ddns_update_failed'
+  | 'secrets_unavailable'
+  | 'storage_error'
+  | 'invalid_config'
+  /** A manual forward named a node id the host does not run. */
+  | 'unknown_node';
+
+/** Typed error carrying a stable `code` for HTTP mapping in the local-ui. */
+export class NatError extends Error {
+  readonly code: NatErrorCode;
+
+  constructor(code: NatErrorCode, message: string) {
+    super(message);
+    this.name = 'NatError';
+    this.code = code;
+  }
+}
+
+/** Description of a configurable field on a DDNS provider. */
+export interface DdnsConfigField {
+  /** Field key (e.g. "token"). */
+  key: string;
+  /** Human-readable label (e.g. "DuckDNS token"). */
+  label: string;
+  /** True if the value is a credential that must be stored in the SecretsStore. */
+  secret: boolean;
+}
+
+/** Summary of a DDNS provider for UI / CLI listing. */
+export interface DdnsProviderInfo {
+  id: string;
+  displayName: string;
+  configFields: ReadonlyArray<DdnsConfigField>;
+}
+
+/**
+ * Typed HTTP handlers exposed to the local UI server for Fastify wiring.
+ *
+ * These take typed objects and either return typed results or throw a
+ * `NatError` whose `.code` the error handler maps to an HTTP status code.
+ */
+export interface NatHandlers {
+  getStatus(): Promise<NatStatusSnapshot>;
+  testReachability(): Promise<NatStatusSnapshot>;
+  listDdnsProviders(): Promise<DdnsProviderInfo[]>;
+  putDdns(body: {
+    providerId: string;
+    hostname: string;
+    config: Record<string, string>;
+    externallyManaged?: boolean;
+  }): Promise<NatStatusSnapshot>;
+  putSettings(body: Partial<Omit<NatSettingsFile, 'version' | 'forwards'>>): Promise<NatStatusSnapshot>;
+  putForward(nodeId: string, patch: ManualForwardPatch): Promise<NatStatusSnapshot>;
+}

package/src/{installer/__tests__/identity.test.ts → orchestrator/__tests__/identity-file.test.ts}

@@ -1,34 +1,34 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { mkdtempSync, rmSync, statSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { generateIdentity, loadIdentity } from '../identity.js';
-
-describe('installer identity', () => {
-  let tmp: string;
-
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), 'cadre-host-id-'));
-  });
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  it('round-trips an Ed25519 keypair through the file', async () => {
-    const path = join(tmp, 'identity.key');
-    const generated = await generateIdentity(path);
-    expect(generated.peerId).toMatch(/^12D3Koo/);
-
-    const loaded = loadIdentity(path);
-    expect(loaded.peerId).toBe(generated.peerId);
-  });
-
-  it.runIf(process.platform !== 'win32')('persists with mode 0600 on POSIX', async () => {
-    const path = join(tmp, 'identity.key');
-    await generateIdentity(path);
-    const mode = statSync(path).mode & 0o777;
-    expect(mode).toBe(0o600);
-  });
-});
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { generateIdentity, loadIdentity } from '../identity-file.js';
+
+describe('identity file', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'cadre-host-id-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('round-trips an Ed25519 keypair through the file', async () => {
+    const path = join(tmp, 'identity.key');
+    const generated = await generateIdentity(path);
+    expect(generated.peerId).toMatch(/^12D3Koo/);
+
+    const loaded = loadIdentity(path);
+    expect(loaded.peerId).toBe(generated.peerId);
+  });
+
+  it.runIf(process.platform !== 'win32')('persists with mode 0600 on POSIX', async () => {
+    const path = join(tmp, 'identity.key');
+    await generateIdentity(path);
+    const mode = statSync(path).mode & 0o777;
+    expect(mode).toBe(0o600);
+  });
+});