@serfab/cadre-host 0.7.1

package/src/nat/ddns/updater.ts

@@ -0,0 +1,243 @@
+import debug from 'debug';
+
+import type { SecretsStore } from '../secrets/index.js';
+import { ddnsAccount } from '../secrets/index.js';
+import { NatError, type NatDdnsStatus, type NatDdnsSettings } from '../types.js';
+import type { DdnsProvider } from './index.js';
+import { getProvider } from './index.js';
+
+const log = debug('cadre:host:nat-ddns:updater');
+
+/** Outcome of a single DDNS update attempt. */
+export interface DdnsUpdateOutcome {
+  attempted: boolean;
+  ok: boolean;
+  ip: string | null;
+  error: string | null;
+  at: Date;
+}
+
+export interface DdnsUpdaterOptions {
+  /** Current DDNS settings (provider, hostname, externally-managed flag). */
+  settings: NatDdnsSettings;
+  /** Backing credential store. */
+  secrets: SecretsStore;
+  /** Returns the most recently observed external IP (null when unknown). */
+  getExternalIp: () => string | null;
+  /** Fetch override for tests. */
+  fetch?: typeof fetch;
+  /** Provider resolver override (tests can inject fakes). */
+  resolveProvider?: (providerId: string) => DdnsProvider;
+  /** Clock override for tests. */
+  now?: () => Date;
+  /** Timer overrides for tests. */
+  setInterval?: (fn: () => void, ms: number) => NodeJS.Timeout;
+  clearInterval?: (h: NodeJS.Timeout) => void;
+}
+
+/**
+ * DDNS update loop.
+ *
+ * Lifecycle:
+ *   - `start()`: if a provider is configured AND not externally managed, runs
+ *     an immediate update, then schedules `setInterval(intervalMs)`.
+ *   - On each tick: re-evaluates the IP. If unchanged from the last successful
+ *     update, no provider call. If changed, calls `provider.update`. Errors
+ *     are recorded but the timer keeps ticking.
+ *   - `stop()`: clears the timer. Idempotent.
+ *   - `updateSettings(...)`: swap in new settings, re-starting if needed.
+ *   - `forceUpdate()`: bypass the unchanged-IP check (used by `testReachability`).
+ */
+export class DdnsUpdater {
+  private settings: NatDdnsSettings;
+  private readonly secrets: SecretsStore;
+  private readonly getExternalIp: () => string | null;
+  private readonly fetchImpl: typeof fetch;
+  private readonly resolveProvider: (providerId: string) => DdnsProvider;
+  private readonly nowFn: () => Date;
+  private readonly setIntervalFn: (fn: () => void, ms: number) => NodeJS.Timeout;
+  private readonly clearIntervalFn: (h: NodeJS.Timeout) => void;
+
+  private timer: NodeJS.Timeout | null = null;
+  private lastPushedIp: string | null = null;
+  private lastOutcome: DdnsUpdateOutcome | null = null;
+  private started = false;
+
+  constructor(opts: DdnsUpdaterOptions) {
+    this.settings = opts.settings;
+    this.secrets = opts.secrets;
+    this.getExternalIp = opts.getExternalIp;
+    this.fetchImpl = opts.fetch ?? fetch;
+    this.resolveProvider = opts.resolveProvider ?? getProvider;
+    this.nowFn = opts.now ?? (() => new Date());
+    this.setIntervalFn = opts.setInterval ?? ((fn, ms) => setInterval(fn, ms));
+    this.clearIntervalFn = opts.clearInterval ?? ((h) => clearInterval(h));
+  }
+
+  /** Current status (for the NatService snapshot). */
+  getStatus(): NatDdnsStatus {
+    return {
+      providerId: this.settings.providerId,
+      hostname: this.settings.hostname,
+      externallyManaged: this.settings.externallyManaged,
+      lastUpdateAt: this.lastOutcome?.at.toISOString() ?? null,
+      lastUpdateOk: this.lastOutcome?.ok ?? null,
+      lastError: this.lastOutcome?.error ?? null,
+    };
+  }
+
+  async start(): Promise<DdnsUpdateOutcome> {
+    if (this.started) {
+      return this.lastOutcome ?? notAttempted(this.nowFn());
+    }
+    this.started = true;
+
+    if (!this.shouldUpdate()) {
+      const outcome = notAttempted(this.nowFn());
+      // For an externally-managed entry we still report state, but never push.
+      return outcome;
+    }
+
+    const outcome = await this.runOnce();
+    this.scheduleNext();
+    return outcome;
+  }
+
+  stop(): void {
+    if (!this.started) return;
+    this.started = false;
+    if (this.timer) {
+      this.clearIntervalFn(this.timer);
+      this.timer = null;
+    }
+  }
+
+  /** Replace settings; restart the loop with the new configuration. */
+  async updateSettings(next: NatDdnsSettings): Promise<DdnsUpdateOutcome> {
+    const wasRunning = this.started;
+    this.stop();
+    this.settings = next;
+    this.lastPushedIp = null;
+    if (!wasRunning) return this.lastOutcome ?? notAttempted(this.nowFn());
+    return await this.start();
+  }
+
+  /** Force an immediate update, bypassing the unchanged-IP skip. */
+  async forceUpdate(): Promise<DdnsUpdateOutcome> {
+    if (!this.shouldUpdate()) return notAttempted(this.nowFn());
+    this.lastPushedIp = null;
+    return await this.runOnce();
+  }
+
+  private shouldUpdate(): boolean {
+    if (!this.settings.providerId) return false;
+    if (!this.settings.hostname) return false;
+    if (this.settings.externallyManaged) return false;
+    return true;
+  }
+
+  private scheduleNext(): void {
+    if (this.timer) this.clearIntervalFn(this.timer);
+    this.timer = this.setIntervalFn(() => {
+      void this.runOnce().catch((err) => log('updater tick error: %s', (err as Error).message));
+    }, this.settings.intervalMs);
+  }
+
+  private async runOnce(): Promise<DdnsUpdateOutcome> {
+    const ip = this.getExternalIp();
+    if (!ip) {
+      const outcome: DdnsUpdateOutcome = {
+        attempted: false,
+        ok: false,
+        ip: null,
+        error: 'external IP unknown',
+        at: this.nowFn(),
+      };
+      this.lastOutcome = outcome;
+      return outcome;
+    }
+
+    if (ip === this.lastPushedIp) {
+      // Unchanged: no provider call (per DuckDNS guidance: don't re-push).
+      log('DDNS skip: IP unchanged (%s)', ip);
+      return this.lastOutcome ?? notAttempted(this.nowFn());
+    }
+
+    let provider: DdnsProvider;
+    try {
+      provider = this.resolveProvider(this.settings.providerId!);
+    } catch (err) {
+      const outcome: DdnsUpdateOutcome = {
+        attempted: true,
+        ok: false,
+        ip,
+        error: (err as Error).message,
+        at: this.nowFn(),
+      };
+      this.lastOutcome = outcome;
+      return outcome;
+    }
+
+    let config: Record<string, string>;
+    try {
+      config = await this.loadConfig(provider);
+    } catch (err) {
+      const outcome: DdnsUpdateOutcome = {
+        attempted: true,
+        ok: false,
+        ip,
+        error: (err as Error).message,
+        at: this.nowFn(),
+      };
+      this.lastOutcome = outcome;
+      return outcome;
+    }
+
+    try {
+      await provider.update(config, this.settings.hostname!, ip, { fetch: this.fetchImpl });
+      this.lastPushedIp = ip;
+      const outcome: DdnsUpdateOutcome = {
+        attempted: true,
+        ok: true,
+        ip,
+        error: null,
+        at: this.nowFn(),
+      };
+      this.lastOutcome = outcome;
+      log('DDNS update OK: %s → %s', this.settings.hostname, ip);
+      return outcome;
+    } catch (err) {
+      const outcome: DdnsUpdateOutcome = {
+        attempted: true,
+        ok: false,
+        ip,
+        error: (err as Error).message,
+        at: this.nowFn(),
+      };
+      this.lastOutcome = outcome;
+      log('DDNS update FAIL: %s', outcome.error);
+      return outcome;
+    }
+  }
+
+  private async loadConfig(provider: DdnsProvider): Promise<Record<string, string>> {
+    const result: Record<string, string> = {};
+    for (const field of provider.configFields) {
+      if (!field.secret) continue;
+      const value = await this.secrets.get(ddnsAccount(provider.id, field.key));
+      if (value === null) {
+        throw new NatError(
+          'ddns_credentials_missing',
+          `Missing DDNS credential for provider "${provider.id}", field "${field.key}". ` +
+          `Configure with \`cadre-host nat ddns set ${provider.id}\`.`,
+        );
+      }
+      result[field.key] = value;
+    }
+    return result;
+  }
+}
+
+function notAttempted(at: Date): DdnsUpdateOutcome {
+  return { attempted: false, ok: false, ip: null, error: null, at };
+}

package/src/nat/external-ip.ts

@@ -0,0 +1,154 @@
+import debug from 'debug';
+
+const log = debug('cadre:host:nat-external-ip');
+
+/** Result of an external-IP detection cycle. */
+export interface ExternalIpResult {
+  /** IP reported by the upstream router (UPnP/NAT-PMP gateway), if reachable. */
+  routerIp: string | null;
+  /** IP reported by a public IP echo service. */
+  publicIp: string | null;
+  /**
+   * True when both probes succeeded AND returned different addresses, which
+   * is the textbook CGNAT signature: the router thinks its WAN address is
+   * private to the carrier.
+   */
+  cgnat: boolean;
+  /** When this snapshot was taken. */
+  detectedAt: Date;
+}
+
+/** Abstract router-side probe (gateway WAN address). */
+export type RouterIpProbe = () => Promise<string | null>;
+
+/** Public IP echo endpoints. Tried in order; first success wins. */
+const DEFAULT_PUBLIC_IP_URLS: ReadonlyArray<string> = [
+  'https://api.ipify.org',
+  'https://ifconfig.me/ip',
+  'https://icanhazip.com',
+];
+
+export interface ExternalIpDetectorOptions {
+  /** Probe the local router's external IP (typically via the port mapper). */
+  routerProbe?: RouterIpProbe;
+  /** Public IP service endpoints. */
+  publicIpUrls?: ReadonlyArray<string>;
+  /** Fetch override (tests stub this). Defaults to global fetch. */
+  fetch?: typeof fetch;
+  /** Clock override for tests. */
+  now?: () => Date;
+  /** Per-request timeout in ms (default 5000). */
+  requestTimeoutMs?: number;
+}
+
+/**
+ * External-IP detector.
+ *
+ * Two independent sources:
+ *   - The router (queried via the port mapper's gateway interface). May be
+ *     unavailable if UPnP is off or the upstream device doesn't expose
+ *     WANIPConnection.
+ *   - A public HTTPS echo service (api.ipify.org and friends). May be
+ *     unreachable on a firewalled / offline machine.
+ *
+ * When both succeed AND disagree, we flag CGNAT. The check is heuristic — a
+ * fast-changing IP, a sliced VPN, or an IPv6-only public probe could all
+ * trigger a false positive. The verdict is informational, not enforced.
+ */
+export class ExternalIpDetector {
+  private readonly routerProbe: RouterIpProbe | undefined;
+  private readonly publicIpUrls: ReadonlyArray<string>;
+  private readonly fetchImpl: typeof fetch;
+  private readonly nowFn: () => Date;
+  private readonly requestTimeoutMs: number;
+
+  constructor(opts: ExternalIpDetectorOptions = {}) {
+    this.routerProbe = opts.routerProbe;
+    this.publicIpUrls = opts.publicIpUrls ?? DEFAULT_PUBLIC_IP_URLS;
+    this.fetchImpl = opts.fetch ?? fetch;
+    this.nowFn = opts.now ?? (() => new Date());
+    this.requestTimeoutMs = opts.requestTimeoutMs ?? 5_000;
+  }
+
+  /** Run both probes in parallel and return the snapshot. */
+  async detect(): Promise<ExternalIpResult> {
+    const [routerIp, publicIp] = await Promise.all([
+      this.runRouterProbe(),
+      this.runPublicProbe(),
+    ]);
+
+    const cgnat = routerIp !== null && publicIp !== null && routerIp !== publicIp;
+    if (cgnat) {
+      log('CGNAT detected: routerIp=%s, publicIp=%s', routerIp, publicIp);
+    }
+
+    return {
+      routerIp,
+      publicIp,
+      cgnat,
+      detectedAt: this.nowFn(),
+    };
+  }
+
+  private async runRouterProbe(): Promise<string | null> {
+    if (!this.routerProbe) return null;
+    try {
+      const ip = await this.routerProbe();
+      return ip && isPlausibleIp(ip) ? ip : null;
+    } catch (err) {
+      log('routerProbe failed: %s', (err as Error).message);
+      return null;
+    }
+  }
+
+  private async runPublicProbe(): Promise<string | null> {
+    for (const url of this.publicIpUrls) {
+      const ip = await this.tryPublicUrl(url);
+      if (ip) return ip;
+    }
+    return null;
+  }
+
+  private async tryPublicUrl(url: string): Promise<string | null> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+    try {
+      const res = await this.fetchImpl(url, { signal: controller.signal });
+      if (!res.ok) {
+        log('public IP probe %s returned %d', url, res.status);
+        return null;
+      }
+      const text = (await res.text()).trim();
+      if (!isPlausibleIp(text)) {
+        log('public IP probe %s returned non-IP: %s', url, text.slice(0, 64));
+        return null;
+      }
+      return text;
+    } catch (err) {
+      log('public IP probe %s failed: %s', url, (err as Error).message);
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/**
+ * Liberal IP validation — accepts both IPv4 and IPv6 in dotted/colon form.
+ * Tighter validation lives at the consumer (`nat-service` checks for IPv4
+ * before building an `/ip4/` multiaddr).
+ */
+export function isPlausibleIp(s: string): boolean {
+  if (!s || s.length > 45) return false;
+  // IPv4: 4 dotted octets, 0-255 each.
+  const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(s);
+  if (v4) {
+    return v4.slice(1).every((octet) => {
+      const n = Number(octet);
+      return n >= 0 && n <= 255;
+    });
+  }
+  // IPv6: very liberal — at least two colons, only hex/colon characters.
+  if (/^[0-9a-fA-F:]+$/.test(s) && s.split(':').length >= 3) return true;
+  return false;
+}

package/src/nat/index.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 } 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';