@serfab/cadre-host 1.14.0 → 1.16.0

package/src/nat/types.ts

@@ -1,209 +1,232 @@
-/**
- * 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>;
-}
+/**
+ * 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';
+
+/**
+ * How this machine meets the internet. `lan`: behind a router (home or office), so node ports need
+ * UPnP or a forward on the router. `public`: an interface holds a public IPv4 (a VPS, a server with a
+ * routed address), so node ports are reachable at their own numbers unless a firewall blocks them.
+ */
+export type NetworkMode = 'lan' | 'public';
+
+/** The `network` setting: `auto` picks the mode from this machine's interfaces. */
+export type NetworkSetting = 'auto' | NetworkMode;
+
+/** The network section of the status snapshot. */
+export interface NatNetworkStatus {
+  setting: NetworkSetting;
+  /** The mode in effect: the setting, or what `auto` found. */
+  mode: NetworkMode;
+  /** The public IPv4 an interface holds, when one does; what `auto` decides on. */
+  publicInterfaceIp: string | null;
+}
+
+/** Where a port's external route came from. `direct`: public mode, the port as-is. */
+export type PortRouteSource = 'upnp' | 'manual' | 'direct';
+
+/** 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. `direct`: reachable at this machine's public address, firewall permitting. */
+export type NodeVerdict = 'mapped' | 'manual' | 'direct' | '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." For `direct`, the
+   * firewall reminder: which ports to allow.
+   */
+  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 {
+  network: NatNetworkStatus;
+  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;
+  /** LAN or public-IP mode; `auto` (default) decides from the interfaces. Absent in older files. */
+  network: NetworkSetting;
+  /** Whether to ask the router for port mappings at all. Ignored in public mode. */
+  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>;
+}