@serfab/cadre-host 1.12.0 → 1.14.0

package/src/installer/paths.ts

@@ -1,109 +1,104 @@
-/**
- * Per-platform default paths for the installer.
- *
- * Linux:   XDG_DATA_HOME / ~/.local/share/cadre-host
- * macOS:   ~/Library/Application Support/CadreHost
- * Windows: %LocalAppData%\CadreHost
- *
- * The package root (where the installed `dist/bin/host.js` and `service/`
- * directory live) is resolved at runtime relative to this module. The
- * installer needs both: the data dir is per-user state, while the package
- * root is what the service-host unit's `ExecStart` line points at.
- */
-
-import { homedir } from 'node:os';
-import { posix, win32, join, resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import type { SupportedPlatform } from './platform.js';
-
-/** Use the path joiner the *target* platform would use, not the runtime's. */
-function joinFor(platform: SupportedPlatform, ...parts: string[]): string {
-  return platform === 'win32' ? win32.join(...parts) : posix.join(...parts);
-}
-
-export interface InstallerEnv {
-  HOME?: string;
-  XDG_DATA_HOME?: string;
-  XDG_CONFIG_HOME?: string;
-  LocalAppData?: string;
-}
-
-/** Default data dir for the given platform. Honors XDG_DATA_HOME / LocalAppData. */
-export function defaultDataDir(
-  platform: SupportedPlatform,
-  env: InstallerEnv = process.env as InstallerEnv,
-  home: string = homedir(),
-): string {
-  switch (platform) {
-    case 'linux': {
-      const base = env.XDG_DATA_HOME?.trim() || joinFor(platform, env.HOME?.trim() || home, '.local', 'share');
-      return joinFor(platform, base, 'cadre-host');
-    }
-    case 'darwin': {
-      return joinFor(platform, env.HOME?.trim() || home, 'Library', 'Application Support', 'CadreHost');
-    }
-    case 'win32': {
-      // %LocalAppData% is the canonical per-user, non-roaming app data dir.
-      const base = env.LocalAppData?.trim();
-      if (!base) {
-        // Fallback: derive from HOME (works under cygwin/MSYS test envs too).
-        return joinFor(platform, home, 'AppData', 'Local', 'CadreHost');
-      }
-      return joinFor(platform, base, 'CadreHost');
-    }
-  }
-}
-
-/** Path on disk for the installed cadre-host CLI entrypoint. */
-export function defaultHostJs(): string {
-  // dist/installer/paths.js -> ../../dist/bin/host.js
-  // src/installer/paths.ts  -> ../bin/host.ts (only used by tests; build emits dist)
-  const here = dirname(fileURLToPath(import.meta.url));
-  return resolve(here, '..', 'bin', 'host.js');
-}
-
-/** Directory containing service templates (cadre-host.service.tmpl etc.). */
-export function defaultServiceDir(): string {
-  // dist/installer/paths.js -> ../../service/
-  const here = dirname(fileURLToPath(import.meta.url));
-  return resolve(here, '..', '..', 'service');
-}
-
-/** Where the wizard writes the JSON config. */
-export function configPath(dataDir: string): string {
-  return join(dataDir, 'host.config.json');
-}
-
-/** Where the wizard writes the Ed25519 identity. */
-export function identityPath(dataDir: string): string {
-  return join(dataDir, 'identity.key');
-}
-
-/** Logs directory (used by launchd / NSSM unit templates). */
-export function logsDir(dataDir: string): string {
-  return join(dataDir, 'logs');
-}
-
-/** Per-platform install dir for the rendered service unit file. */
-export function serviceInstallPath(
-  platform: SupportedPlatform,
-  env: InstallerEnv = process.env as InstallerEnv,
-  home: string = homedir(),
-): string {
-  const hd = env.HOME?.trim() || home;
-  switch (platform) {
-    case 'linux': {
-      const base = env.XDG_CONFIG_HOME?.trim() || joinFor(platform, hd, '.config');
-      return joinFor(platform, base, 'systemd', 'user', 'cadre-host.service');
-    }
-    case 'darwin': {
-      return joinFor(platform, hd, 'Library', 'LaunchAgents', 'com.serfab.cadre-host.plist');
-    }
-    case 'win32': {
-      // NSSM stores service config in the registry; this path is unused
-      // on Windows but returned for symmetry / logging.
-      return 'HKLM\\SYSTEM\\CurrentControlSet\\Services\\CadreHost';
-    }
-  }
-}
+/**
+ * Per-platform default paths for the installer.
+ *
+ * Linux:   XDG_DATA_HOME / ~/.local/share/cadre-host
+ * macOS:   ~/Library/Application Support/CadreHost
+ * Windows: %LocalAppData%\CadreHost
+ *
+ * The package root (where the installed `dist/bin/host.js` and `service/`
+ * directory live) is resolved at runtime relative to this module. The
+ * installer needs both: the data dir is per-user state, while the package
+ * root is what the service-host unit's `ExecStart` line points at.
+ */
+
+import { homedir } from 'node:os';
+import { posix, win32, join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { SupportedPlatform } from './platform.js';
+
+/** Use the path joiner the *target* platform would use, not the runtime's. */
+function joinFor(platform: SupportedPlatform, ...parts: string[]): string {
+  return platform === 'win32' ? win32.join(...parts) : posix.join(...parts);
+}
+
+export interface InstallerEnv {
+  HOME?: string;
+  XDG_DATA_HOME?: string;
+  XDG_CONFIG_HOME?: string;
+  LocalAppData?: string;
+}
+
+/** Default data dir for the given platform. Honors XDG_DATA_HOME / LocalAppData. */
+export function defaultDataDir(
+  platform: SupportedPlatform,
+  env: InstallerEnv = process.env as InstallerEnv,
+  home: string = homedir(),
+): string {
+  switch (platform) {
+    case 'linux': {
+      const base = env.XDG_DATA_HOME?.trim() || joinFor(platform, env.HOME?.trim() || home, '.local', 'share');
+      return joinFor(platform, base, 'cadre-host');
+    }
+    case 'darwin': {
+      return joinFor(platform, env.HOME?.trim() || home, 'Library', 'Application Support', 'CadreHost');
+    }
+    case 'win32': {
+      // %LocalAppData% is the canonical per-user, non-roaming app data dir.
+      const base = env.LocalAppData?.trim();
+      if (!base) {
+        // Fallback: derive from HOME (works under cygwin/MSYS test envs too).
+        return joinFor(platform, home, 'AppData', 'Local', 'CadreHost');
+      }
+      return joinFor(platform, base, 'CadreHost');
+    }
+  }
+}
+
+/** Path on disk for the installed cadre-host CLI entrypoint. */
+export function defaultHostJs(): string {
+  // dist/installer/paths.js -> ../../dist/bin/host.js
+  // src/installer/paths.ts  -> ../bin/host.ts (only used by tests; build emits dist)
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, '..', 'bin', 'host.js');
+}
+
+/** Directory containing service templates (cadre-host.service.tmpl etc.). */
+export function defaultServiceDir(): string {
+  // dist/installer/paths.js -> ../../service/
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, '..', '..', 'service');
+}
+
+/** Where the wizard writes the JSON config. */
+export function configPath(dataDir: string): string {
+  return join(dataDir, 'host.config.json');
+}
+
+/** Logs directory (used by launchd / NSSM unit templates). */
+export function logsDir(dataDir: string): string {
+  return join(dataDir, 'logs');
+}
+
+/** Per-platform install dir for the rendered service unit file. */
+export function serviceInstallPath(
+  platform: SupportedPlatform,
+  env: InstallerEnv = process.env as InstallerEnv,
+  home: string = homedir(),
+): string {
+  const hd = env.HOME?.trim() || home;
+  switch (platform) {
+    case 'linux': {
+      const base = env.XDG_CONFIG_HOME?.trim() || joinFor(platform, hd, '.config');
+      return joinFor(platform, base, 'systemd', 'user', 'cadre-host.service');
+    }
+    case 'darwin': {
+      return joinFor(platform, hd, 'Library', 'LaunchAgents', 'com.serfab.cadre-host.plist');
+    }
+    case 'win32': {
+      // NSSM stores service config in the registry; this path is unused
+      // on Windows but returned for symmetry / logging.
+      return 'HKLM\\SYSTEM\\CurrentControlSet\\Services\\CadreHost';
+    }
+  }
+}

package/src/installer/wizard.ts

@@ -1,103 +1,87 @@
-/**
- * Interactive install wizard.
- *
- * Pure readline — no extra deps. Each prompt is decomposed into a small
- * `Prompt` so the test can drive the wizard with a scripted Iterable of
- * answers. Production code wires the prompts to stdin.
- */
-
-import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
-
-import { defaultDataDir } from './paths.js';
-import type { SupportedPlatform } from './platform.js';
-
-export interface WizardDefaults {
-  dataDir: string;
-  uiPort: number;
-  libp2pPort: number;
-  upnpEnabled: boolean;
-  /** Also run the host's own personal cadre here (founder persona). Default false. */
-  ownCadre: boolean;
-}
-
-export interface WizardAnswers {
-  dataDir: string;
-  uiPort: number;
-  libp2pPort: number;
-  upnpEnabled: boolean;
-  configureDdns: boolean;
-  /** Also run the host's own personal cadre here (founder persona). */
-  ownCadre: boolean;
-}
-
-export const DEFAULT_UI_PORT = 8765;
-export const DEFAULT_LIBP2P_PORT = 4001;
-
-export function defaultsForPlatform(platform: SupportedPlatform): WizardDefaults {
-  return {
-    dataDir: defaultDataDir(platform),
-    uiPort: DEFAULT_UI_PORT,
-    libp2pPort: DEFAULT_LIBP2P_PORT,
-    upnpEnabled: true,
-    ownCadre: false,
-  };
-}
-
-/**
- * Drive the wizard with a function that returns the next user answer for
- * a prompt. Used both by the readline-backed `runWizard` and by tests.
- */
-export async function runWizardWith(
-  defaults: WizardDefaults,
-  ask: (label: string, fallback: string) => Promise<string>,
-): Promise<WizardAnswers> {
-  const dataDir = (await ask('Data directory', defaults.dataDir)).trim() || defaults.dataDir;
-  const uiPort = parsePort(await ask('UI port (localhost only)', String(defaults.uiPort)), defaults.uiPort);
-  const libp2pPort = parsePort(await ask('Cadre libp2p port', String(defaults.libp2pPort)), defaults.libp2pPort);
-  const upnpEnabled = parseBool(
-    await ask('Attempt UPnP port mapping on this network? [Y/n]', defaults.upnpEnabled ? 'Y' : 'n'),
-    defaults.upnpEnabled,
-  );
-  const configureDdns = parseBool(await ask('Configure DDNS now? [y/N]', 'N'), false);
-  // Founder persona (opt-in). Most installs just donate nodes to friends and
-  // answer no — a no leaves cadre-host donor-only (no owner node, no /auth+/nat).
-  const ownCadre = parseBool(
-    await ask('Also run your own personal cadre on this machine? (most people just donating nodes to friends say no) [y/N]', defaults.ownCadre ? 'Y' : 'N'),
-    defaults.ownCadre,
-  );
-  return { dataDir, uiPort, libp2pPort, upnpEnabled, configureDdns, ownCadre };
-}
-
-/** Production entrypoint — drives the wizard over stdin/stdout. */
-export async function runWizard(defaults: WizardDefaults): Promise<WizardAnswers> {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    return await runWizardWith(defaults, async (label, fallback) => prompt(rl, label, fallback));
-  } finally {
-    rl.close();
-  }
-}
-
-function prompt(rl: ReadlineInterface, label: string, fallback: string): Promise<string> {
-  return new Promise<string>((resolve) => {
-    rl.question(`${label} [${fallback}]: `, (answer) => resolve(answer));
-  });
-}
-
-function parsePort(input: string, fallback: number): number {
-  const trimmed = input.trim();
-  if (!trimmed) return fallback;
-  const n = Number(trimmed);
-  if (!Number.isInteger(n) || n <= 0 || n > 65535) {
-    throw new Error(`Invalid port: ${input}`);
-  }
-  return n;
-}
-
-function parseBool(input: string, fallback: boolean): boolean {
-  const trimmed = input.trim().toLowerCase();
-  if (!trimmed) return fallback;
-  if (['y', 'yes', 'true', '1'].includes(trimmed)) return true;
-  if (['n', 'no', 'false', '0'].includes(trimmed)) return false;
-  throw new Error(`Invalid yes/no answer: ${input}`);
-}
+/**
+ * Interactive install wizard.
+ *
+ * Pure readline — no extra deps. Each prompt is decomposed into a small
+ * `Prompt` so the test can drive the wizard with a scripted Iterable of
+ * answers. Production code wires the prompts to stdin.
+ */
+
+import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
+
+import { defaultDataDir } from './paths.js';
+import type { SupportedPlatform } from './platform.js';
+
+export interface WizardDefaults {
+  dataDir: string;
+  uiPort: number;
+  upnpEnabled: boolean;
+}
+
+export interface WizardAnswers {
+  dataDir: string;
+  uiPort: number;
+  upnpEnabled: boolean;
+  configureDdns: boolean;
+}
+
+export const DEFAULT_UI_PORT = 8765;
+
+export function defaultsForPlatform(platform: SupportedPlatform): WizardDefaults {
+  return {
+    dataDir: defaultDataDir(platform),
+    uiPort: DEFAULT_UI_PORT,
+    upnpEnabled: true,
+  };
+}
+
+/**
+ * Drive the wizard with a function that returns the next user answer for
+ * a prompt. Used both by the readline-backed `runWizard` and by tests.
+ */
+export async function runWizardWith(
+  defaults: WizardDefaults,
+  ask: (label: string, fallback: string) => Promise<string>,
+): Promise<WizardAnswers> {
+  const dataDir = (await ask('Data directory', defaults.dataDir)).trim() || defaults.dataDir;
+  const uiPort = parsePort(await ask('UI port (localhost only)', String(defaults.uiPort)), defaults.uiPort);
+  const upnpEnabled = parseBool(
+    await ask('Attempt UPnP port mapping on this network? [Y/n]', defaults.upnpEnabled ? 'Y' : 'n'),
+    defaults.upnpEnabled,
+  );
+  const configureDdns = parseBool(await ask('Configure DDNS now? [y/N]', 'N'), false);
+  return { dataDir, uiPort, upnpEnabled, configureDdns };
+}
+
+/** Production entrypoint — drives the wizard over stdin/stdout. */
+export async function runWizard(defaults: WizardDefaults): Promise<WizardAnswers> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await runWizardWith(defaults, async (label, fallback) => prompt(rl, label, fallback));
+  } finally {
+    rl.close();
+  }
+}
+
+function prompt(rl: ReadlineInterface, label: string, fallback: string): Promise<string> {
+  return new Promise<string>((resolve) => {
+    rl.question(`${label} [${fallback}]: `, (answer) => resolve(answer));
+  });
+}
+
+function parsePort(input: string, fallback: number): number {
+  const trimmed = input.trim();
+  if (!trimmed) return fallback;
+  const n = Number(trimmed);
+  if (!Number.isInteger(n) || n <= 0 || n > 65535) {
+    throw new Error(`Invalid port: ${input}`);
+  }
+  return n;
+}
+
+function parseBool(input: string, fallback: boolean): boolean {
+  const trimmed = input.trim().toLowerCase();
+  if (!trimmed) return fallback;
+  if (['y', 'yes', 'true', '1'].includes(trimmed)) return true;
+  if (['n', 'no', 'false', '0'].includes(trimmed)) return false;
+  throw new Error(`Invalid yes/no answer: ${input}`);
+}

package/src/nat/__tests__/address-resolver.test.ts

@@ -1,82 +1,107 @@
-import { describe, expect, it } from 'vitest';
-
-import { buildInviteAddresses } from '../address-resolver.js';
-
-const PEER = '12D3KooWHost';
-
-describe('buildInviteAddresses', () => {
-  it('returns dns4 when reachable and a DDNS hostname is configured', () => {
-    const addrs = buildInviteAddresses({
-      peerId: PEER,
-      externalPort: 4001,
-      ddnsHostname: 'foo.duckdns.org',
-      externalIp: '1.2.3.4',
-      reachable: true,
-      libp2pAddrs: ['/ip4/192.168.1.10/tcp/4001'],
-    });
-    expect(addrs).toEqual([`/dns4/foo.duckdns.org/tcp/4001/p2p/${PEER}`]);
-  });
-
-  it('falls back to ip4 when reachable but no DDNS hostname', () => {
-    const addrs = buildInviteAddresses({
-      peerId: PEER,
-      externalPort: 4001,
-      ddnsHostname: null,
-      externalIp: '203.0.113.5',
-      reachable: true,
-      libp2pAddrs: ['/ip4/192.168.1.10/tcp/4001'],
-    });
-    expect(addrs).toEqual([`/ip4/203.0.113.5/tcp/4001/p2p/${PEER}`]);
-  });
-
-  it('falls back to libp2p addrs when not reachable', () => {
-    const addrs = buildInviteAddresses({
-      peerId: PEER,
-      externalPort: 4001,
-      ddnsHostname: 'foo.duckdns.org',
-      externalIp: '1.2.3.4',
-      reachable: false,
-      libp2pAddrs: ['/ip4/192.168.1.10/tcp/4001', '/p2p-circuit'],
-    });
-    expect(addrs.length).toBeGreaterThan(0);
-    expect(addrs.some((a) => a.startsWith('/dns4/'))).toBe(false);
-    expect(addrs.some((a) => a.startsWith('/ip4/'))).toBe(true);
-  });
-
-  it('appends peer suffix to libp2p addrs that lack one', () => {
-    const addrs = buildInviteAddresses({
-      peerId: PEER,
-      externalPort: 4001,
-      ddnsHostname: null,
-      externalIp: null,
-      reachable: false,
-      libp2pAddrs: ['/ip4/192.168.1.10/tcp/4001'],
-    });
-    expect(addrs).toEqual([`/ip4/192.168.1.10/tcp/4001/p2p/${PEER}`]);
-  });
-
-  it('preserves libp2p addrs that already have a /p2p/ suffix', () => {
-    const existing = `/ip4/192.168.1.10/tcp/4001/p2p/${PEER}`;
-    const addrs = buildInviteAddresses({
-      peerId: PEER,
-      externalPort: 4001,
-      ddnsHostname: null,
-      externalIp: null,
-      reachable: false,
-      libp2pAddrs: [existing],
-    });
-    expect(addrs).toEqual([existing]);
-  });
-
-  it('does not emit /ip4/ for IPv6 external IP — falls back instead', () => {
-    const addrs = buildInviteAddresses({
-      peerId: PEER,
-      externalPort: 4001,
-      ddnsHostname: null,
-      externalIp: '2001:db8::1',
-      reachable: true,
-      libp2pAddrs: ['/ip4/192.168.1.10/tcp/4001'],
-    });
-    expect(addrs.some((a) => a.startsWith('/ip4/192.168.1.10'))).toBe(true);
-  });
-});
+import { describe, expect, it } from 'vitest';
+
+import { buildPublicAddresses, isPublicIpv4, type PublicAddressInput } from '../address-resolver.js';
+import type { PortRoute } from '../types.js';
+
+function upnp(internalPort: number, externalPort = internalPort): PortRoute {
+  return { internalPort, externalPort, source: 'upnp', leaseExpiresAt: null, error: null };
+}
+function manual(internalPort: number, externalPort: number): PortRoute {
+  return { internalPort, externalPort, source: 'manual', leaseExpiresAt: null, error: null };
+}
+function none(internalPort: number): PortRoute {
+  return { internalPort, externalPort: null, source: null, leaseExpiresAt: null, error: 'refused' };
+}
+
+const BASE: PublicAddressInput = {
+  ddnsHostname: null,
+  externalIp: '203.0.113.5',
+  cgnatDetected: false,
+  tcp: upnp(10003),
+  ws: upnp(10004),
+};
+
+describe('buildPublicAddresses', () => {
+  const cases: Array<{ name: string; input: Partial<PublicAddressInput>; expected: string[] }> = [
+    {
+      name: 'DDNS hostname wins over the external IP',
+      input: { ddnsHostname: 'foo.duckdns.org' },
+      expected: ['/dns4/foo.duckdns.org/tcp/10003', '/dns4/foo.duckdns.org/tcp/10004/ws'],
+    },
+    {
+      name: 'a hostname that is not a DNS name is skipped, so no entry can stop a node starting',
+      input: { ddnsHostname: 'https://foo.duckdns.org,bar' },
+      expected: ['/ip4/203.0.113.5/tcp/10003', '/ip4/203.0.113.5/tcp/10004/ws'],
+    },
+    {
+      name: 'public IPv4 without DDNS',
+      input: {},
+      expected: ['/ip4/203.0.113.5/tcp/10003', '/ip4/203.0.113.5/tcp/10004/ws'],
+    },
+    {
+      name: 'a private external IP is no host part',
+      input: { externalIp: '192.168.1.1' },
+      expected: [],
+    },
+    {
+      name: 'an IPv6 external IP is no host part',
+      input: { externalIp: '2001:db8::1' },
+      expected: [],
+    },
+    {
+      name: 'no hostname and no IP',
+      input: { externalIp: null },
+      expected: [],
+    },
+    {
+      name: 'the assigned external port is the one announced',
+      input: { tcp: upnp(10003, 10103), ws: upnp(10004, 10104) },
+      expected: ['/ip4/203.0.113.5/tcp/10103', '/ip4/203.0.113.5/tcp/10104/ws'],
+    },
+    {
+      name: 'a port with no route is left out',
+      input: { ws: none(10004) },
+      expected: ['/ip4/203.0.113.5/tcp/10003'],
+    },
+    {
+      name: 'no WebSocket port at all',
+      input: { ws: null },
+      expected: ['/ip4/203.0.113.5/tcp/10003'],
+    },
+    {
+      name: 'CGNAT: upnp routes produce nothing',
+      input: { cgnatDetected: true },
+      expected: [],
+    },
+    {
+      name: 'CGNAT: a manual route still produces an address',
+      input: { cgnatDetected: true, tcp: manual(10003, 40000) },
+      expected: ['/ip4/203.0.113.5/tcp/40000'],
+    },
+    {
+      name: 'CGNAT with DDNS: manual only',
+      input: { cgnatDetected: true, ddnsHostname: 'foo.duckdns.org', ws: manual(10004, 40004) },
+      expected: ['/dns4/foo.duckdns.org/tcp/40004/ws'],
+    },
+  ];
+
+  for (const c of cases) {
+    it(c.name, () => {
+      expect(buildPublicAddresses({ ...BASE, ...c.input })).toEqual(c.expected);
+    });
+  }
+});
+
+describe('isPublicIpv4', () => {
+  it('accepts a public address and rejects private, carrier, loopback and link-local ranges', () => {
+    expect(isPublicIpv4('203.0.113.5')).toBe(true);
+    expect(isPublicIpv4('8.8.8.8')).toBe(true);
+    for (const ip of ['10.1.2.3', '172.16.0.1', '172.31.255.255', '192.168.0.1', '100.64.0.5', '100.127.255.255', '127.0.0.1', '169.254.1.1', '0.0.0.0', '224.0.0.1', '255.255.255.255']) {
+      expect(isPublicIpv4(ip), ip).toBe(false);
+    }
+    expect(isPublicIpv4('172.32.0.1')).toBe(true);
+    expect(isPublicIpv4('100.128.0.1')).toBe(true);
+    expect(isPublicIpv4('2001:db8::1')).toBe(false);
+    expect(isPublicIpv4('not an ip')).toBe(false);
+  });
+});