@serfab/cadre-host 1.14.0 → 1.16.0

package/src/installer/__tests__/installer.smoke.test.ts

@@ -1,182 +1,184 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { existsSync, mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { Installer } from '../index.js';
-import type { ServiceHost, ServiceHostContext, ServiceHostStatus } from '../service-host/types.js';
-
-class FakeServiceHost implements ServiceHost {
-  readonly name = 'cadre-host';
-  installCalls: ServiceHostContext[] = [];
-  uninstallCalls: ServiceHostContext[] = [];
-  installed = false;
-  running = false;
-
-  async install(ctx: ServiceHostContext): Promise<void> {
-    this.installCalls.push(ctx);
-    this.installed = true;
-    this.running = true;
-  }
-  async uninstall(ctx: ServiceHostContext): Promise<void> {
-    this.uninstallCalls.push(ctx);
-    this.installed = false;
-    this.running = false;
-  }
-  async restart(_ctx: ServiceHostContext): Promise<void> {
-    this.running = true;
-  }
-  async status(_ctx: ServiceHostContext): Promise<ServiceHostStatus> {
-    return { installed: this.installed, running: this.running };
-  }
-  renderUnit(_ctx: ServiceHostContext): string | null {
-    return 'rendered-unit';
-  }
-}
-
-describe('Installer smoke', () => {
-  let tmp: string;
-
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), 'cadre-host-installer-smoke-'));
-  });
-
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  it('install creates config + invokes service-host', async () => {
-    const fake = new FakeServiceHost();
-    const installer = new Installer({ platform: 'linux', installerVersion: 'test-1.0.0' });
-    const result = await installer.install({
-      nonInteractive: true,
-      dataDir: tmp,
-      uiPort: 19999,
-      openBrowser: false,
-      serviceHost: fake,
-    });
-
-    expect(result.dataDir).toBe(tmp);
-    expect(result.uiUrl).toBe('http://127.0.0.1:19999/');
-    expect(result.serviceName).toBe('cadre-host');
-    expect(result.configPath).toBe(join(tmp, 'host.config.json'));
-
-    expect(existsSync(join(tmp, 'host.config.json'))).toBe(true);
-    // The host holds no identity of its own; each node writes its own key in its workdir.
-    expect(existsSync(join(tmp, 'identity.key'))).toBe(false);
-    expect(existsSync(join(tmp, 'nat.json'))).toBe(true);
-    expect(existsSync(join(tmp, 'logs'))).toBe(true);
-
-    expect(fake.installCalls).toHaveLength(1);
-    expect(fake.installCalls[0]!.dataDir).toBe(tmp);
-  });
-
-  it('noService writes the data dir without registering a service', async () => {
-    const fake = new FakeServiceHost();
-    const installer = new Installer({ platform: 'linux', installerVersion: 'test-1.0.0' });
-    const result = await installer.install({
-      nonInteractive: true,
-      dataDir: tmp,
-      uiPort: 19995,
-      noService: true,
-      serviceHost: fake,
-    });
-
-    expect(fake.installCalls).toHaveLength(0);
-    expect(result.serviceName).toBeUndefined();
-    expect(result.uiUrl).toBe('http://127.0.0.1:19995/');
-    expect(existsSync(join(tmp, 'host.config.json'))).toBe(true);
-    expect(existsSync(join(tmp, 'nat.json'))).toBe(true);
-  });
-
-  it('uninstall removes data only when --remove-data is set', async () => {
-    const fake = new FakeServiceHost();
-    const installer = new Installer({ platform: 'linux' });
-    await installer.install({
-      nonInteractive: true,
-      dataDir: tmp,
-      uiPort: 19998,
-      openBrowser: false,
-      serviceHost: fake,
-    });
-    expect(existsSync(join(tmp, 'host.config.json'))).toBe(true);
-
-    await installer.uninstall({ yes: true, removeData: false, dataDir: tmp, serviceHost: fake });
-    expect(fake.uninstallCalls).toHaveLength(1);
-    expect(existsSync(join(tmp, 'host.config.json'))).toBe(true);
-
-    await installer.uninstall({ yes: true, removeData: true, dataDir: tmp, serviceHost: fake });
-    expect(existsSync(tmp)).toBe(false);
-  });
-
-  it('rejects --system in v1', async () => {
-    const fake = new FakeServiceHost();
-    const installer = new Installer({ platform: 'linux' });
-    await expect(installer.install({
-      nonInteractive: true,
-      dataDir: tmp,
-      system: true,
-      serviceHost: fake,
-      openBrowser: false,
-    })).rejects.toThrow(/system.*not yet supported/);
-    expect(fake.installCalls).toHaveLength(0);
-  });
-
-  it('passes CLI overrides to the wizard as suggested defaults', async () => {
-    // Regression: the interactive wizard previously showed the platform
-    // default (`~/.local/share/cadre-host`) in the prompt even when the
-    // caller passed `--data-dir <path>`. Whatever the user typed was then
-    // silently discarded because the CLI flag won post-hoc. The fix: CLI
-    // overrides become the wizard's suggested defaults, and the wizard's
-    // returned answers stand on their own.
-    const fake = new FakeServiceHost();
-    const installer = new Installer({ platform: 'linux' });
-    let seenDefaults: { dataDir: string; uiPort: number; upnpEnabled: boolean } | undefined;
-    await installer.install({
-      nonInteractive: false,
-      dataDir: tmp,
-      uiPort: 19997,
-      noUpnp: true,
-      openBrowser: false,
-      serviceHost: fake,
-      wizard: async (defaults) => {
-        seenDefaults = { ...defaults };
-        // Simulate the user pressing Enter at every prompt.
-        return {
-          dataDir: defaults.dataDir,
-          uiPort: defaults.uiPort,
-          upnpEnabled: defaults.upnpEnabled,
-          configureDdns: false,
-        };
-      },
-    });
-
-    expect(seenDefaults).toEqual({
-      dataDir: tmp,
-      uiPort: 19997,
-      upnpEnabled: false,
-    });
-    expect(fake.installCalls).toHaveLength(1);
-    expect(fake.installCalls[0]!.dataDir).toBe(tmp);
-  });
-
-  it('honors wizard-typed input when no CLI override is passed', async () => {
-    // Mirror of the previous test: with no `--data-dir`, the wizard's
-    // returned value is what the installer uses.
-    const fake = new FakeServiceHost();
-    const installer = new Installer({ platform: 'linux' });
-    await installer.install({
-      nonInteractive: false,
-      openBrowser: false,
-      serviceHost: fake,
-      wizard: async () => ({
-        dataDir: tmp,
-        uiPort: 19996,
-        upnpEnabled: true,
-        configureDdns: false,
-      }),
-    });
-    expect(fake.installCalls).toHaveLength(1);
-    expect(fake.installCalls[0]!.dataDir).toBe(tmp);
-  });
-});
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { Installer } from '../index.js';
+import type { ServiceHost, ServiceHostContext, ServiceHostStatus } from '../service-host/types.js';
+
+class FakeServiceHost implements ServiceHost {
+  readonly name = 'cadre-host';
+  installCalls: ServiceHostContext[] = [];
+  uninstallCalls: ServiceHostContext[] = [];
+  installed = false;
+  running = false;
+
+  async install(ctx: ServiceHostContext): Promise<void> {
+    this.installCalls.push(ctx);
+    this.installed = true;
+    this.running = true;
+  }
+  async uninstall(ctx: ServiceHostContext): Promise<void> {
+    this.uninstallCalls.push(ctx);
+    this.installed = false;
+    this.running = false;
+  }
+  async restart(_ctx: ServiceHostContext): Promise<void> {
+    this.running = true;
+  }
+  async status(_ctx: ServiceHostContext): Promise<ServiceHostStatus> {
+    return { installed: this.installed, running: this.running };
+  }
+  renderUnit(_ctx: ServiceHostContext): string | null {
+    return 'rendered-unit';
+  }
+}
+
+describe('Installer smoke', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'cadre-host-installer-smoke-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('install creates config + invokes service-host', async () => {
+    const fake = new FakeServiceHost();
+    const installer = new Installer({ platform: 'linux', installerVersion: 'test-1.0.0' });
+    const result = await installer.install({
+      nonInteractive: true,
+      dataDir: tmp,
+      uiPort: 19999,
+      openBrowser: false,
+      serviceHost: fake,
+    });
+
+    expect(result.dataDir).toBe(tmp);
+    expect(result.uiUrl).toBe('http://127.0.0.1:19999/');
+    expect(result.serviceName).toBe('cadre-host');
+    expect(result.configPath).toBe(join(tmp, 'host.config.json'));
+
+    expect(existsSync(join(tmp, 'host.config.json'))).toBe(true);
+    // The host holds no identity of its own; each node writes its own key in its workdir.
+    expect(existsSync(join(tmp, 'identity.key'))).toBe(false);
+    expect(existsSync(join(tmp, 'nat.json'))).toBe(true);
+    expect(existsSync(join(tmp, 'logs'))).toBe(true);
+
+    expect(fake.installCalls).toHaveLength(1);
+    expect(fake.installCalls[0]!.dataDir).toBe(tmp);
+  });
+
+  it('noService writes the data dir without registering a service', async () => {
+    const fake = new FakeServiceHost();
+    const installer = new Installer({ platform: 'linux', installerVersion: 'test-1.0.0' });
+    const result = await installer.install({
+      nonInteractive: true,
+      dataDir: tmp,
+      uiPort: 19995,
+      noService: true,
+      serviceHost: fake,
+    });
+
+    expect(fake.installCalls).toHaveLength(0);
+    expect(result.serviceName).toBeUndefined();
+    expect(result.uiUrl).toBe('http://127.0.0.1:19995/');
+    expect(existsSync(join(tmp, 'host.config.json'))).toBe(true);
+    expect(existsSync(join(tmp, 'nat.json'))).toBe(true);
+  });
+
+  it('uninstall removes data only when --remove-data is set', async () => {
+    const fake = new FakeServiceHost();
+    const installer = new Installer({ platform: 'linux' });
+    await installer.install({
+      nonInteractive: true,
+      dataDir: tmp,
+      uiPort: 19998,
+      openBrowser: false,
+      serviceHost: fake,
+    });
+    expect(existsSync(join(tmp, 'host.config.json'))).toBe(true);
+
+    await installer.uninstall({ yes: true, removeData: false, dataDir: tmp, serviceHost: fake });
+    expect(fake.uninstallCalls).toHaveLength(1);
+    expect(existsSync(join(tmp, 'host.config.json'))).toBe(true);
+
+    await installer.uninstall({ yes: true, removeData: true, dataDir: tmp, serviceHost: fake });
+    expect(existsSync(tmp)).toBe(false);
+  });
+
+  it('rejects --system in v1', async () => {
+    const fake = new FakeServiceHost();
+    const installer = new Installer({ platform: 'linux' });
+    await expect(installer.install({
+      nonInteractive: true,
+      dataDir: tmp,
+      system: true,
+      serviceHost: fake,
+      openBrowser: false,
+    })).rejects.toThrow(/system.*not yet supported/);
+    expect(fake.installCalls).toHaveLength(0);
+  });
+
+  it('passes CLI overrides to the wizard as suggested defaults', async () => {
+    // Regression: the interactive wizard previously showed the platform
+    // default (`~/.local/share/cadre-host`) in the prompt even when the
+    // caller passed `--data-dir <path>`. Whatever the user typed was then
+    // silently discarded because the CLI flag won post-hoc. The fix: CLI
+    // overrides become the wizard's suggested defaults, and the wizard's
+    // returned answers stand on their own.
+    const fake = new FakeServiceHost();
+    const installer = new Installer({ platform: 'linux' });
+    let seenDefaults: Record<string, unknown> | undefined;
+    await installer.install({
+      nonInteractive: false,
+      dataDir: tmp,
+      uiPort: 19997,
+      noUpnp: true,
+      openBrowser: false,
+      serviceHost: fake,
+      publicInterfaceAddress: () => null,
+      wizard: async (defaults) => {
+        seenDefaults = { ...defaults };
+        // Simulate the user pressing Enter at every prompt.
+        return {
+          dataDir: defaults.dataDir,
+          uiPort: defaults.uiPort,
+          upnpEnabled: defaults.upnpEnabled,
+        };
+      },
+    });
+
+    // Every value came from a flag, so the wizard is told not to ask for any of them.
+    expect(seenDefaults).toEqual({
+      dataDir: tmp,
+      uiPort: 19997,
+      upnpEnabled: false,
+      given: { dataDir: true, uiPort: true, upnpEnabled: true },
+      publicInterfaceIp: null,
+    });
+    expect(fake.installCalls).toHaveLength(1);
+    expect(fake.installCalls[0]!.dataDir).toBe(tmp);
+  });
+
+  it('honors wizard-typed input when no CLI override is passed', async () => {
+    // Mirror of the previous test: with no `--data-dir`, the wizard's
+    // returned value is what the installer uses.
+    const fake = new FakeServiceHost();
+    const installer = new Installer({ platform: 'linux' });
+    await installer.install({
+      nonInteractive: false,
+      openBrowser: false,
+      serviceHost: fake,
+      wizard: async () => ({
+        dataDir: tmp,
+        uiPort: 19996,
+        upnpEnabled: true,
+      }),
+    });
+    expect(fake.installCalls).toHaveLength(1);
+    expect(fake.installCalls[0]!.dataDir).toBe(tmp);
+  });
+});

package/src/installer/__tests__/wizard.test.ts

@@ -1,56 +1,76 @@
-import { describe, expect, it } from 'vitest';
-
-import { runWizardWith, type WizardDefaults } from '../wizard.js';
-
-const defaults: WizardDefaults = {
-  dataDir: '/data/cadre-host',
-  uiPort: 8765,
-  upnpEnabled: true,
-};
-
-function scripted(answers: ReadonlyArray<string>): (label: string, fallback: string) => Promise<string> {
-  let i = 0;
-  return async (_label, _fallback) => {
-    if (i >= answers.length) throw new Error(`wizard asked more questions than scripted (i=${i})`);
-    return answers[i++]!;
-  };
-}
-
-describe('runWizardWith', () => {
-  it('returns the defaults when every answer is blank', async () => {
-    const out = await runWizardWith(defaults, scripted(['', '', '', '']));
-    expect(out).toEqual({
-      dataDir: '/data/cadre-host',
-      uiPort: 8765,
-      upnpEnabled: true,
-      configureDdns: false,
-    });
-  });
-
-  it('respects overrides', async () => {
-    const out = await runWizardWith(defaults, scripted([
-      '/srv/host',
-      '9000',
-      'n',
-      'y',
-    ]));
-    expect(out).toEqual({
-      dataDir: '/srv/host',
-      uiPort: 9000,
-      upnpEnabled: false,
-      configureDdns: true,
-    });
-  });
-
-  it('rejects invalid port input', async () => {
-    await expect(
-      runWizardWith(defaults, scripted(['', 'banana', '', ''])),
-    ).rejects.toThrow(/Invalid port/);
-  });
-
-  it('rejects unrecognized yes/no answers', async () => {
-    await expect(
-      runWizardWith(defaults, scripted(['', '', 'maybe', ''])),
-    ).rejects.toThrow(/Invalid yes\/no/);
-  });
-});
+import { describe, expect, it } from 'vitest';
+
+import { runWizardWith, type WizardDefaults } from '../wizard.js';
+
+const defaults: WizardDefaults = {
+  dataDir: '/data/cadre-host',
+  uiPort: 8765,
+  upnpEnabled: true,
+};
+
+function scripted(answers: ReadonlyArray<string>): (label: string, fallback: string) => Promise<string> {
+  let i = 0;
+  return async (_label, _fallback) => {
+    if (i >= answers.length) throw new Error(`wizard asked more questions than scripted (i=${i})`);
+    return answers[i++]!;
+  };
+}
+
+describe('runWizardWith', () => {
+  it('returns the defaults when every answer is blank', async () => {
+    const out = await runWizardWith(defaults, scripted(['', '', '', '']));
+    expect(out).toEqual({
+      dataDir: '/data/cadre-host',
+      uiPort: 8765,
+      upnpEnabled: true,
+    });
+  });
+
+  it('respects overrides', async () => {
+    const out = await runWizardWith(defaults, scripted([
+      '/srv/host',
+      '9000',
+      'n',
+      'y',
+    ]));
+    expect(out).toEqual({
+      dataDir: '/srv/host',
+      uiPort: 9000,
+      upnpEnabled: false,
+    });
+  });
+
+  it('rejects invalid port input', async () => {
+    await expect(
+      runWizardWith(defaults, scripted(['', 'banana', '', ''])),
+    ).rejects.toThrow(/Invalid port/);
+  });
+
+  it('asks nothing a flag already answered', async () => {
+    const asked: string[] = [];
+    const out = await runWizardWith(
+      { ...defaults, dataDir: '/srv/host', uiPort: 9000, upnpEnabled: false, given: { dataDir: true, uiPort: true, upnpEnabled: true } },
+      async (label) => { asked.push(label); return ''; },
+    );
+    expect(asked).toEqual([]);
+    expect(out).toEqual({ dataDir: '/srv/host', uiPort: 9000, upnpEnabled: false });
+  });
+
+  it('does not ask about UPnP on a machine with a public IP, and says why', async () => {
+    const asked: string[] = [];
+    const said: string[] = [];
+    await runWizardWith(
+      { ...defaults, given: { dataDir: true }, publicInterfaceIp: '203.0.113.7' },
+      async (label) => { asked.push(label); return ''; },
+      (line) => said.push(line),
+    );
+    expect(asked).toEqual(['UI port (localhost only)']);
+    expect(said.join(' ')).toMatch(/public IP address \(203\.0\.113\.7\).*no UPnP/);
+  });
+
+  it('rejects unrecognized yes/no answers', async () => {
+    await expect(
+      runWizardWith(defaults, scripted(['', '', 'maybe', ''])),
+    ).rejects.toThrow(/Invalid yes\/no/);
+  });
+});

package/src/installer/config.ts

@@ -12,8 +12,11 @@
  */
 
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { isIP } from 'node:net';
 import { dirname } from 'node:path';
 
+import { destinationPeerIdOf } from '@serfab/cadre-core';
+
 export interface UpdatesConfig {
   /** When true, the daily-check timer auto-applies updates. Default false. */
   autoApply: boolean;
@@ -41,6 +44,65 @@ export interface PushSettings {
   debounceMs?: number;
 }
 
+/**
+ * Which addresses a hosted node's QR code carries (cadre-core's `selectNodeClaimAddresses`).
+ * Absent ⇒ `{ lan: 'auto' }`. Read on every claim-code request, so an edit applies to the
+ * next code shown.
+ */
+export interface ClaimAddressSettings {
+  /**
+   * The LAN address a phone at home dials: `'auto'` (the address on the router's subnet, else
+   * the machine's primary one; none in public-IP mode), `'none'` (public addresses only), or an
+   * IP address. Other private addresses (Docker bridges, VPNs) are left out either way.
+   */
+  lan?: string;
+  /**
+   * Exact addresses to put in every code instead, for an operator who knows better than the
+   * rule, such as one name behind a proxy. Each names no destination peer (a relay address ends
+   * at its `/p2p-circuit` hop); every node's code appends its own peer id.
+   */
+  addrs?: string[];
+}
+
+/** Why a `claimAddresses` value is unacceptable, naming the field; undefined when it is fine. */
+export function claimAddressSettingsProblem(value: unknown): string | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return '"claimAddresses" must be an object';
+  const o = value as Record<string, unknown>;
+  for (const key of Object.keys(o)) {
+    if (key !== 'lan' && key !== 'addrs') return `Unknown setting "claimAddresses.${key}"`;
+  }
+  if (o.lan !== undefined) {
+    if (typeof o.lan !== 'string' || (o.lan !== 'auto' && o.lan !== 'none' && isIP(o.lan) === 0)) {
+      return '"claimAddresses.lan" must be "auto", "none" or an IP address';
+    }
+  }
+  if (o.addrs !== undefined) {
+    if (!Array.isArray(o.addrs) || !o.addrs.every((a) => typeof a === 'string')) {
+      return '"claimAddresses.addrs" must be a list of multiaddr strings';
+    }
+    for (const addr of o.addrs as string[]) {
+      const problem = exactClaimAddressProblem(addr);
+      if (problem) return `"claimAddresses.addrs" entry "${addr}" ${problem}`;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Why one `claimAddresses.addrs` entry is unacceptable. It must not name its destination peer:
+ * the list is host-wide and each hosted node's code appends its own peer id, so a named one
+ * would be some other node's address in every code but that node's.
+ */
+function exactClaimAddressProblem(addr: string): string | undefined {
+  let destination: string | null;
+  try {
+    destination = destinationPeerIdOf(addr.trim());
+  } catch {
+    return 'is not a valid multiaddr';
+  }
+  return destination === null ? undefined : 'must not end in /p2p/<peer id>: each node\'s own id is appended';
+}
+
 export interface HostConfigFile {
   version: 3;
   /** A stable per-install id, for log correlation. */
@@ -63,6 +125,8 @@ export interface HostConfigFile {
    * they are read from the secret store at node-spawn time (`src/push/`).
    */
   push?: PushSettings;
+  /** Which addresses claim codes carry; absent ⇒ automatic. */
+  claimAddresses?: ClaimAddressSettings;
 }
 
 const CURRENT_VERSION = 3;
@@ -111,6 +175,8 @@ export function readHostConfig(filePath: string): HostConfigFile {
   if (!isHostConfigShape(obj)) {
     throw new Error(`host.config.json at ${filePath} is missing required fields`);
   }
+  const claimAddressesProblem = obj.claimAddresses === undefined ? undefined : claimAddressSettingsProblem(obj.claimAddresses);
+  if (claimAddressesProblem) throw new Error(`host.config.json at ${filePath}: ${claimAddressesProblem}`);
   return obj;
 }