@serfab/cadre-host 0.7.1

package/src/index.ts

@@ -0,0 +1,167 @@
+/**
+ * @serfab/cadre-host — self-hosted cadre node manager.
+ *
+ * This package is the sibling of @serfab/cadre-provider for self-hosted
+ * basement-PC deployments. It depends on @serfab/cadre-provider for the
+ * orchestration interface and container lifecycle types but ships its own
+ * orchestrator (host processes, not Docker), auth (trust circle, not API
+ * keys), installer, NAT layer, and local management UI.
+ *
+ * Implementations of HostProcessOrchestrator, TrustCircleAuth, the NAT
+ * layer, installer scripts, and the local UI live in sibling subdirectories
+ * under src/ and are added by their respective tickets:
+ *
+ *   - cadre-host-process-orchestrator     [DONE]
+ *   - cadre-host-trust-circle             [DONE]
+ *   - cadre-host-nat
+ *   - cadre-host-installer
+ *   - cadre-host-local-ui
+ */
+
+export type {
+  Orchestrator,
+  OrchestratorCreateRequest,
+  OrchestratorCreateResult,
+  OrchestratorStats,
+  ContainerStatus,
+  ContainerResources,
+} from '@serfab/cadre-provider';
+
+export { HostProcessOrchestrator } from './orchestrator/index.js';
+export type {
+  HostProcessConfig,
+  PersistedHandle,
+  ManagedNodeInfo,
+  NodeStateListener,
+} from './orchestrator/index.js';
+
+export {
+  TrustCircleService,
+  TrustCircleStore,
+  TrustCircleError,
+  createTrustCircleHandlers,
+  parseDuration,
+  DEFAULT_INVITE_TTL_MS,
+} from './auth/index.js';
+export type {
+  TrustCircleServiceOptions,
+  CadreNodeLike,
+  TrustCircleMember,
+  PendingInvite,
+  TrustCircleFile,
+  TrustCircleSnapshot,
+  TrustCircleHandlers,
+  TrustCircleErrorCode,
+} from './auth/index.js';
+
+export { Installer } from './installer/index.js';
+export type {
+  InstallOptions,
+  InstallResult,
+  UninstallOptions,
+  InstallerOptions,
+  HostConfigFile,
+  WizardAnswers,
+  WizardDefaults,
+  ServiceHost,
+  ServiceHostContext,
+  ServiceHostStatus,
+} from './installer/index.js';
+
+export {
+  UpdateService,
+  createUpdateHandlers,
+  UpdateStateStore,
+  UpdateErrorException,
+  applyUpdate,
+  defaultNpmExecutor,
+  fetchManifest,
+  verifyManifest,
+  canonicalJson,
+  signManifestForTesting,
+  compareVersions,
+  parseVersion,
+  getReleasePublicKey,
+  getReleasePublicKeyBase64,
+  ed25519FromRaw,
+} from './update/index.js';
+export type {
+  UpdateServiceOptions,
+  UpdateHandlers,
+  UpdateState,
+  UpdateApplyResult,
+  UpdateSettings,
+  UpdateManifest,
+  UpdateErrorCode,
+  NpmExecutor,
+  ServiceRestarter,
+} from './update/index.js';
+
+export {
+  NatService,
+  NatStore,
+  NatError,
+  createNatHandlers,
+  ExternalIpDetector,
+  PortMapperService,
+  createDefaultPortMapper,
+  evaluateReachability,
+  buildInviteAddresses,
+  BUILTIN_PROVIDERS,
+  getProvider,
+  listProviders,
+  duckDnsProvider,
+  DdnsUpdater,
+  KeytarSecretsStore,
+  FileSecretsStore,
+  createSecretsStore,
+  ddnsAccount,
+  KEYTAR_SERVICE,
+  DEFAULT_LEASE_TTL_MS,
+  DEFAULT_REFRESH_MS,
+  isPlausibleIp,
+} from './nat/index.js';
+export type {
+  NatServiceOptions,
+  CadreNodeLike as NatCadreNodeLike,
+  NatStatusSnapshot,
+  NatDdnsStatus,
+  NatSettingsFile,
+  NatDdnsSettings,
+  NatHandlers,
+  NatErrorCode,
+  PortForwardMode,
+  DirectReachability,
+  DdnsProviderInfo,
+  DdnsConfigField,
+  ExternalIpResult,
+  RouterIpProbe,
+  ExternalIpDetectorOptions,
+  PortMapper,
+  PortMappingResult,
+  PortMapOptions,
+  PortMapperState,
+  PortMapperServiceOptions,
+  BuildInviteAddressesInput,
+  DdnsProvider,
+  DdnsProviderDeps,
+  DdnsUpdaterOptions,
+  DdnsUpdateOutcome,
+  SecretsStore,
+  KeytarLike,
+} from './nat/index.js';
+
+/* ──────────────── local UI server (6.5.1) ──────────────── */
+
+export {
+  createLocalUiServer,
+  EventBus,
+  HostSettingsStore,
+} from './server/index.js';
+export type {
+  LocalUiServer,
+  LocalUiServerOptions,
+  LocalUiEvent,
+  LocalUiEventType,
+  LocalUiEventListener,
+} from './server/index.js';

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

@@ -0,0 +1,86 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { readHostConfig, writeHostConfig, type HostConfigFile } from '../config.js';
+
+describe('host.config.json round-trip', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'cadre-host-cfg-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  function makeCfg(overrides: Partial<HostConfigFile> = {}): HostConfigFile {
+    return {
+      version: 2,
+      installId: 'abc123',
+      uiPort: 8765,
+      libp2pPort: 4001,
+      dataDir: tmp,
+      identityPath: join(tmp, 'identity.key'),
+      upnpEnabled: true,
+      installedAt: '2026-01-01T00:00:00.000Z',
+      installerVersion: '0.6.0',
+      updates: { autoApply: false },
+      ...overrides,
+    };
+  }
+
+  it('writes and reads the same shape', () => {
+    const cfg = makeCfg();
+    const path = join(tmp, 'host.config.json');
+    writeHostConfig(path, cfg);
+    expect(readHostConfig(path)).toEqual(cfg);
+  });
+
+  it('upgrades v1 files in place on read', () => {
+    const path = join(tmp, 'host.config.json');
+    const v1 = {
+      version: 1,
+      installId: 'abc123',
+      uiPort: 8765,
+      libp2pPort: 4001,
+      dataDir: tmp,
+      identityPath: join(tmp, 'identity.key'),
+      upnpEnabled: true,
+      installedAt: '2026-01-01T00:00:00.000Z',
+      installerVersion: '0.6.0',
+    };
+    writeFileSync(path, JSON.stringify(v1));
+    const upgraded = readHostConfig(path);
+    expect(upgraded.version).toBe(2);
+    expect(upgraded.updates).toEqual({ autoApply: false });
+    // Reading again should be idempotent and stay v2.
+    const reRead = readHostConfig(path);
+    expect(reRead.version).toBe(2);
+  });
+
+  it('rejects unknown versions', () => {
+    const path = join(tmp, 'host.config.json');
+    writeFileSync(path, JSON.stringify({ ...makeCfg(), version: 99 }));
+    expect(() => readHostConfig(path)).toThrow(/unsupported version=99/);
+  });
+
+  it('rejects malformed JSON', () => {
+    const path = join(tmp, 'host.config.json');
+    writeFileSync(path, 'not json');
+    expect(() => readHostConfig(path)).toThrow(/Failed to parse/);
+  });
+
+  it('rejects missing required fields', () => {
+    const path = join(tmp, 'host.config.json');
+    writeFileSync(path, JSON.stringify({ version: 2, uiPort: 1234 }));
+    expect(() => readHostConfig(path)).toThrow(/missing required fields/);
+  });
+
+  it('refuses to write the wrong version', () => {
+    const path = join(tmp, 'host.config.json');
+    expect(() => writeHostConfig(path, { ...makeCfg(), version: 3 as never })).toThrow(/version=3/);
+  });
+});

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

@@ -0,0 +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);
+  });
+});

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

@@ -0,0 +1,124 @@
+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 + identity + 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,
+      libp2pPort: 14001,
+      openBrowser: false,
+      noInvite: true,
+      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);
+    expect(existsSync(join(tmp, 'identity.key'))).toBe(true);
+    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('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,
+      libp2pPort: 14002,
+      openBrowser: false,
+      noInvite: true,
+      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,
+      noInvite: true,
+    })).rejects.toThrow(/system.*not yet supported/);
+    expect(fake.installCalls).toHaveLength(0);
+  });
+
+  it('re-running install preserves the existing identity', async () => {
+    const fake = new FakeServiceHost();
+    const installer = new Installer({ platform: 'linux' });
+    await installer.install({
+      nonInteractive: true, dataDir: tmp, openBrowser: false, noInvite: true, serviceHost: fake,
+    });
+    const idBefore = (await import('node:fs')).readFileSync(join(tmp, 'identity.key'));
+    await installer.install({
+      nonInteractive: true, dataDir: tmp, openBrowser: false, noInvite: true, serviceHost: fake,
+    });
+    const idAfter = (await import('node:fs')).readFileSync(join(tmp, 'identity.key'));
+    expect(Buffer.from(idBefore).equals(Buffer.from(idAfter))).toBe(true);
+  });
+});

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

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+
+import { defaultDataDir, serviceInstallPath } from '../paths.js';
+
+describe('defaultDataDir', () => {
+  it('honors XDG_DATA_HOME on linux', () => {
+    expect(defaultDataDir('linux', { XDG_DATA_HOME: '/tmp/xdg', HOME: '/home/me' }, '/home/me'))
+      .toBe('/tmp/xdg/cadre-host');
+  });
+
+  it('falls back to ~/.local/share on linux', () => {
+    expect(defaultDataDir('linux', { HOME: '/home/me' }, '/home/me'))
+      .toBe('/home/me/.local/share/cadre-host');
+  });
+
+  it('uses Application Support on darwin', () => {
+    expect(defaultDataDir('darwin', { HOME: '/Users/me' }, '/Users/me'))
+      .toBe('/Users/me/Library/Application Support/CadreHost');
+  });
+
+  it('uses LocalAppData on win32', () => {
+    expect(defaultDataDir('win32', { LocalAppData: 'C:\\Users\\me\\AppData\\Local' }, 'C:\\Users\\me'))
+      .toBe('C:\\Users\\me\\AppData\\Local\\CadreHost');
+  });
+
+  it('falls back to ~/AppData/Local on win32 without LocalAppData', () => {
+    expect(defaultDataDir('win32', {}, 'C:\\Users\\me'))
+      .toBe('C:\\Users\\me\\AppData\\Local\\CadreHost');
+  });
+});
+
+describe('serviceInstallPath', () => {
+  it('honors XDG_CONFIG_HOME on linux', () => {
+    expect(serviceInstallPath('linux', { XDG_CONFIG_HOME: '/tmp/cfg', HOME: '/home/me' }, '/home/me'))
+      .toBe('/tmp/cfg/systemd/user/cadre-host.service');
+  });
+
+  it('uses LaunchAgents on darwin', () => {
+    expect(serviceInstallPath('darwin', { HOME: '/Users/me' }, '/Users/me'))
+      .toBe('/Users/me/Library/LaunchAgents/com.serfab.cadre-host.plist');
+  });
+
+  it('returns a registry-style path on win32 (for logging only)', () => {
+    expect(serviceInstallPath('win32', {}, 'C:\\Users\\me'))
+      .toMatch(/CadreHost/);
+  });
+});

package/src/installer/__tests__/service-host.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { LaunchdServiceHost } from '../service-host/launchd.js';
+import { SystemdServiceHost } from '../service-host/systemd.js';
+import { NssmServiceHost } from '../service-host/nssm.js';
+import { renderTemplate } from '../service-host/template.js';
+import type { ServiceHostContext } from '../service-host/types.js';
+
+const here = fileURLToPath(new URL('.', import.meta.url));
+const serviceDir = resolve(here, '..', '..', '..', 'service');
+
+function ctx(): ServiceHostContext {
+  return {
+    nodePath: '/usr/local/bin/node',
+    hostJs: '/opt/cadre-host/dist/bin/host.js',
+    dataDir: '/var/data/cadre-host',
+    serviceDir,
+  };
+}
+
+describe('renderTemplate', () => {
+  it('substitutes @TOKEN@ values', () => {
+    expect(renderTemplate('@A@ x @B@', { A: 'foo', B: 'bar' })).toBe('foo x bar');
+  });
+
+  it('throws on unknown tokens', () => {
+    expect(() => renderTemplate('@A@ @MISSING@', { A: 'foo' })).toThrow(/missing value for token @MISSING@/);
+  });
+});
+
+describe('SystemdServiceHost.renderUnit', () => {
+  it('produces an enable-able [Install] section and substitutes ExecStart', () => {
+    const unit = new SystemdServiceHost().renderUnit(ctx());
+    expect(unit).toContain('[Install]');
+    expect(unit).toContain('WantedBy=default.target');
+    expect(unit).toContain('ExecStart=/usr/local/bin/node /opt/cadre-host/dist/bin/host.js start --no-tui --data-dir /var/data/cadre-host');
+    expect(unit).toContain('RestartPreventExitStatus=0');
+  });
+});
+
+describe('LaunchdServiceHost.renderUnit', () => {
+  it('produces a plist with the substituted ProgramArguments', () => {
+    const unit = new LaunchdServiceHost().renderUnit(ctx());
+    expect(unit).toContain('<key>Label</key>');
+    expect(unit).toContain('<string>com.serfab.cadre-host</string>');
+    expect(unit).toContain('<string>/usr/local/bin/node</string>');
+    expect(unit).toContain('<string>/opt/cadre-host/dist/bin/host.js</string>');
+    expect(unit).toContain('<string>--data-dir</string>');
+    expect(unit).toContain('<string>/var/data/cadre-host</string>');
+    expect(unit).toContain('<key>KeepAlive</key>');
+    expect(unit).toContain('<key>SuccessfulExit</key>');
+    expect(unit).toContain('<key>Crashed</key>');
+  });
+});
+
+describe('NssmServiceHost', () => {
+  it('returns null from renderUnit (NSSM stores config in the registry)', () => {
+    expect(new NssmServiceHost().renderUnit(ctx())).toBeNull();
+  });
+});

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

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+
+import { runWizardWith, type WizardDefaults } from '../wizard.js';
+
+const defaults: WizardDefaults = {
+  dataDir: '/data/cadre-host',
+  uiPort: 8765,
+  libp2pPort: 4001,
+  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,
+      libp2pPort: 4001,
+      upnpEnabled: true,
+      configureDdns: false,
+    });
+  });
+
+  it('respects overrides', async () => {
+    const out = await runWizardWith(defaults, scripted([
+      '/srv/host',
+      '9000',
+      '5000',
+      'n',
+      'y',
+    ]));
+    expect(out).toEqual({
+      dataDir: '/srv/host',
+      uiPort: 9000,
+      libp2pPort: 5000,
+      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/);
+  });
+});

package/src/installer/browser.ts

@@ -0,0 +1,42 @@
+/**
+ * Best-effort URL opener. Never throws — if the platform launcher isn't
+ * available (headless box, missing xdg-utils, etc.) we just log the URL.
+ *
+ * Implemented inline rather than pulling in the `open` npm dep so the
+ * installer keeps its dependency tree small.
+ */
+
+import { spawn } from 'node:child_process';
+
+export interface OpenBrowserResult {
+  attempted: boolean;
+  spawned: boolean;
+  /** Set when the spawn attempt errored synchronously. */
+  error?: string;
+}
+
+export function openBrowser(url: string, platform: NodeJS.Platform = process.platform): OpenBrowserResult {
+  try {
+    if (platform === 'darwin') {
+      const child = spawn('open', [url], { detached: true, stdio: 'ignore' });
+      child.unref();
+      return { attempted: true, spawned: true };
+    }
+    if (platform === 'win32') {
+      // rundll32 is the most portable way to invoke the registered handler
+      // without going through cmd.exe (which would require escaping URLs).
+      const child = spawn('rundll32', ['url.dll,FileProtocolHandler', url], {
+        detached: true,
+        stdio: 'ignore',
+      });
+      child.unref();
+      return { attempted: true, spawned: true };
+    }
+    // linux + everything else POSIX-ish
+    const child = spawn('xdg-open', [url], { detached: true, stdio: 'ignore' });
+    child.unref();
+    return { attempted: true, spawned: true };
+  } catch (err) {
+    return { attempted: true, spawned: false, error: (err as Error).message };
+  }
+}