@serfab/cadre-host 0.7.1

package/src/installer/service-host/launchd.ts

@@ -0,0 +1,90 @@
+/**
+ * launchd LaunchAgent registration.
+ *
+ * Renders the .plist into `~/Library/LaunchAgents/com.serfab.cadre-host.plist`,
+ * `launchctl bootstrap`s it into the gui session, then `kickstart -k` to
+ * start (or restart) it. Uninstall uses `bootout` (the modern unload).
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import debug from 'debug';
+
+import { renderTemplate } from './template.js';
+import { logsDir, serviceInstallPath } from '../paths.js';
+import type { ServiceHost, ServiceHostContext, ServiceHostStatus } from './types.js';
+
+const log = debug('cadre:host:installer:launchd');
+
+const SERVICE_NAME = 'cadre-host';
+const LABEL = 'com.serfab.cadre-host';
+
+export class LaunchdServiceHost implements ServiceHost {
+  readonly name = SERVICE_NAME;
+
+  renderUnit(ctx: ServiceHostContext): string {
+    const tmpl = readFileSync(`${ctx.serviceDir}/com.serfab.cadre-host.plist.tmpl`, 'utf8');
+    return renderTemplate(tmpl, {
+      NODE_PATH: ctx.nodePath,
+      HOST_JS: ctx.hostJs,
+      DATA_DIR: ctx.dataDir,
+    });
+  }
+
+  async install(ctx: ServiceHostContext): Promise<void> {
+    const unitPath = serviceInstallPath('darwin');
+    const unit = this.renderUnit(ctx);
+
+    mkdirSync(logsDir(ctx.dataDir), { recursive: true });
+    mkdirSync(dirname(unitPath), { recursive: true });
+    writeFileSync(unitPath, unit, { mode: 0o644 });
+    log('wrote %s', unitPath);
+
+    const target = guiTarget();
+    // bootout first to make install idempotent. May fail if it wasn't
+    // loaded — that's fine.
+    spawnSync('launchctl', ['bootout', target, unitPath], { stdio: 'ignore' });
+    run('launchctl', ['bootstrap', target, unitPath]);
+    run('launchctl', ['kickstart', '-k', `${target}/${LABEL}`]);
+  }
+
+  async uninstall(ctx: ServiceHostContext): Promise<void> {
+    const unitPath = serviceInstallPath('darwin');
+    if (existsSync(unitPath)) {
+      const target = guiTarget();
+      spawnSync('launchctl', ['bootout', target, unitPath], { stdio: 'inherit' });
+      rmSync(unitPath, { force: true });
+      log('removed %s', unitPath);
+    }
+    void ctx;
+  }
+
+  async restart(ctx: ServiceHostContext): Promise<void> {
+    void ctx;
+    const target = guiTarget();
+    run('launchctl', ['kickstart', '-k', `${target}/${LABEL}`]);
+  }
+
+  async status(ctx: ServiceHostContext): Promise<ServiceHostStatus> {
+    void ctx;
+    const unitPath = serviceInstallPath('darwin');
+    const installed = existsSync(unitPath);
+    const target = guiTarget();
+    const result = spawnSync('launchctl', ['print', `${target}/${LABEL}`], { encoding: 'utf8' });
+    const running = result.status === 0 && /state\s*=\s*running/i.test(result.stdout);
+    return { installed, running };
+  }
+}
+
+function guiTarget(): string {
+  return `gui/${process.getuid?.() ?? ''}`;
+}
+
+function run(cmd: string, args: string[]): void {
+  try {
+    execFileSync(cmd, args, { stdio: 'inherit' });
+  } catch (err) {
+    throw new Error(`${cmd} ${args.join(' ')} failed: ${(err as Error).message}`);
+  }
+}

package/src/installer/service-host/nssm.ts

@@ -0,0 +1,100 @@
+/**
+ * NSSM-backed Windows service.
+ *
+ * Delegates to the bundled PowerShell scripts (`install-service.ps1` /
+ * `uninstall-service.ps1`) which encapsulate the NSSM CLI dance and the
+ * stdout/stderr log redirection.
+ *
+ * Bundling NSSM itself with the npm package is out of scope for v1 — the
+ * standalone-binary distribution will ship it (see backlog).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import debug from 'debug';
+
+import type { ServiceHost, ServiceHostContext, ServiceHostStatus } from './types.js';
+
+const log = debug('cadre:host:installer:nssm');
+
+const SERVICE_NAME = 'CadreHost';
+
+export class NssmServiceHost implements ServiceHost {
+  readonly name = SERVICE_NAME;
+
+  /** No template to render — NSSM stores its config in the registry. */
+  renderUnit(ctx: ServiceHostContext): string | null {
+    void ctx;
+    return null;
+  }
+
+  async install(ctx: ServiceHostContext): Promise<void> {
+    requireNssmAvailable();
+    const script = join(ctx.serviceDir, 'install-service.ps1');
+    if (!existsSync(script)) {
+      throw new Error(`install-service.ps1 not found at ${script}`);
+    }
+    runPwsh([
+      '-ExecutionPolicy', 'Bypass',
+      '-NoProfile',
+      '-File', script,
+      '-NodePath', ctx.nodePath,
+      '-HostJs', ctx.hostJs,
+      '-DataDir', ctx.dataDir,
+    ]);
+    // Start the service after install — install-service.ps1 sets
+    // SERVICE_AUTO_START but doesn't run it immediately.
+    runPwsh(['-ExecutionPolicy', 'Bypass', '-NoProfile', '-Command', `nssm.exe start ${SERVICE_NAME}`]);
+  }
+
+  async uninstall(ctx: ServiceHostContext): Promise<void> {
+    requireNssmAvailable();
+    const script = join(ctx.serviceDir, 'uninstall-service.ps1');
+    if (!existsSync(script)) {
+      // Fall back to a direct nssm remove if the script isn't there.
+      runPwsh(['-ExecutionPolicy', 'Bypass', '-NoProfile', '-Command', `nssm.exe stop ${SERVICE_NAME} confirm; nssm.exe remove ${SERVICE_NAME} confirm`]);
+      return;
+    }
+    runPwsh(['-ExecutionPolicy', 'Bypass', '-NoProfile', '-File', script]);
+  }
+
+  async restart(ctx: ServiceHostContext): Promise<void> {
+    void ctx;
+    requireNssmAvailable();
+    runPwsh(['-ExecutionPolicy', 'Bypass', '-NoProfile', '-Command', `nssm.exe restart ${SERVICE_NAME}`]);
+  }
+
+  async status(ctx: ServiceHostContext): Promise<ServiceHostStatus> {
+    void ctx;
+    const statusResult = spawnSync('nssm.exe', ['status', SERVICE_NAME], { encoding: 'utf8' });
+    if (statusResult.error || statusResult.status !== 0) {
+      return { installed: false, running: false };
+    }
+    const stateLine = statusResult.stdout.trim();
+    return { installed: true, running: /SERVICE_RUNNING/i.test(stateLine) };
+  }
+}
+
+function requireNssmAvailable(): void {
+  const probe = spawnSync('nssm.exe', ['--version'], { encoding: 'utf8' });
+  if (probe.error) {
+    throw new Error(
+      'nssm.exe not found on PATH. Install NSSM from https://nssm.cc/download ' +
+        'and add it to PATH, then re-run `cadre-host install`.',
+    );
+  }
+}
+
+function runPwsh(args: string[]): void {
+  // powershell.exe is the in-box Windows PowerShell 5.1 — present on every
+  // supported Windows version. pwsh.exe (PowerShell 7) is an optional install.
+  const result = spawnSync('powershell.exe', args, { stdio: 'inherit' });
+  if (result.error) {
+    throw new Error(`powershell.exe failed: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    log('powershell.exe exit %s for args %j', result.status, args);
+    throw new Error(`powershell.exe exited with status ${result.status}`);
+  }
+}

package/src/installer/service-host/systemd.ts

@@ -0,0 +1,88 @@
+/**
+ * systemd `--user` unit registration.
+ *
+ * Renders the template into `~/.config/systemd/user/cadre-host.service`,
+ * runs `systemctl --user daemon-reload`, `enable --now cadre-host`, and
+ * `loginctl enable-linger <user>` so the unit survives logout / reboot.
+ */
+
+import { mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { userInfo } from 'node:os';
+import debug from 'debug';
+
+import { renderTemplate } from './template.js';
+import { serviceInstallPath } from '../paths.js';
+import type { ServiceHost, ServiceHostContext, ServiceHostStatus } from './types.js';
+
+const log = debug('cadre:host:installer:systemd');
+
+const SERVICE_NAME = 'cadre-host';
+
+export class SystemdServiceHost implements ServiceHost {
+  readonly name = SERVICE_NAME;
+
+  renderUnit(ctx: ServiceHostContext): string {
+    const tmpl = readFileSync(`${ctx.serviceDir}/cadre-host.service.tmpl`, 'utf8');
+    return renderTemplate(tmpl, {
+      NODE_PATH: ctx.nodePath,
+      HOST_JS: ctx.hostJs,
+      DATA_DIR: ctx.dataDir,
+    });
+  }
+
+  async install(ctx: ServiceHostContext): Promise<void> {
+    const unitPath = serviceInstallPath('linux');
+    const unit = this.renderUnit(ctx);
+
+    mkdirSync(dirname(unitPath), { recursive: true });
+    writeFileSync(unitPath, unit, { mode: 0o644 });
+    log('wrote %s', unitPath);
+
+    run('systemctl', ['--user', 'daemon-reload']);
+    run('systemctl', ['--user', 'enable', '--now', SERVICE_NAME]);
+    // enable-linger is opportunistic — it requires `loginctl` and may
+    // fail in containers / minimal images. Don't kill the install for it.
+    const user = userInfo().username;
+    const linger = spawnSync('loginctl', ['enable-linger', user], { stdio: 'inherit' });
+    if (linger.status !== 0) {
+      log('loginctl enable-linger %s failed (status=%s) — service may not run after logout', user, linger.status);
+    }
+  }
+
+  async uninstall(ctx: ServiceHostContext): Promise<void> {
+    const unitPath = serviceInstallPath('linux');
+    // Stop + disable even if the unit file is missing — covers manual cleanup.
+    spawnSync('systemctl', ['--user', 'stop', SERVICE_NAME], { stdio: 'inherit' });
+    spawnSync('systemctl', ['--user', 'disable', SERVICE_NAME], { stdio: 'inherit' });
+    if (existsSync(unitPath)) {
+      rmSync(unitPath, { force: true });
+      log('removed %s', unitPath);
+    }
+    spawnSync('systemctl', ['--user', 'daemon-reload'], { stdio: 'inherit' });
+    void ctx;
+  }
+
+  async restart(ctx: ServiceHostContext): Promise<void> {
+    void ctx;
+    run('systemctl', ['--user', 'restart', SERVICE_NAME]);
+  }
+
+  async status(ctx: ServiceHostContext): Promise<ServiceHostStatus> {
+    void ctx;
+    const unitPath = serviceInstallPath('linux');
+    const installed = existsSync(unitPath);
+    const result = spawnSync('systemctl', ['--user', 'is-active', SERVICE_NAME], { encoding: 'utf8' });
+    const running = result.status === 0 && result.stdout.trim() === 'active';
+    return { installed, running };
+  }
+}
+
+function run(cmd: string, args: string[]): void {
+  try {
+    execFileSync(cmd, args, { stdio: 'inherit' });
+  } catch (err) {
+    throw new Error(`${cmd} ${args.join(' ')} failed: ${(err as Error).message}`);
+  }
+}

package/src/installer/service-host/template.ts

@@ -0,0 +1,21 @@
+/**
+ * Tiny `@TOKEN@` substitution. Used to render systemd / launchd unit
+ * files. Throws if any tokens are left after substitution to catch
+ * typos at install time rather than at service-startup time.
+ */
+
+const TOKEN_RE = /@([A-Z][A-Z0-9_]*)@/g;
+
+export function renderTemplate(template: string, tokens: Readonly<Record<string, string>>): string {
+  const rendered = template.replace(TOKEN_RE, (full, key: string) => {
+    if (!Object.prototype.hasOwnProperty.call(tokens, key)) {
+      throw new Error(`renderTemplate: missing value for token ${full}`);
+    }
+    return tokens[key];
+  });
+  const leftover = rendered.match(TOKEN_RE);
+  if (leftover) {
+    throw new Error(`renderTemplate: unresolved tokens: ${leftover.join(', ')}`);
+  }
+  return rendered;
+}

package/src/installer/service-host/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Service-host abstraction. The wizard picks a concrete impl by platform
+ * (systemd / launchd / NSSM) and drives it through this common interface.
+ */
+
+export interface ServiceHostContext {
+  /** Absolute path to node.exe / node. */
+  nodePath: string;
+  /** Absolute path to the cadre-host CLI entrypoint (dist/bin/host.js). */
+  hostJs: string;
+  /** Absolute path to the cadre-host data dir. */
+  dataDir: string;
+  /** Directory containing template files / PowerShell scripts. */
+  serviceDir: string;
+}
+
+export interface ServiceHostStatus {
+  installed: boolean;
+  running: boolean;
+}
+
+export interface ServiceHost {
+  /** Stable service name (used for status / logging). */
+  readonly name: string;
+
+  /** Render unit file(s) and register with the OS service manager. */
+  install(ctx: ServiceHostContext): Promise<void>;
+
+  /** Stop + deregister. Idempotent: no-op when not installed. */
+  uninstall(ctx: ServiceHostContext): Promise<void>;
+
+  /**
+   * Restart the running service. Used by the update flow after `npm install -g`
+   * to pick up the new binary. Throws if the OS service manager reports a
+   * non-zero exit — callers are responsible for surfacing that as a warning
+   * (the binary swap already succeeded).
+   */
+  restart(ctx: ServiceHostContext): Promise<void>;
+
+  /** Cheap status read. */
+  status(ctx: ServiceHostContext): Promise<ServiceHostStatus>;
+
+  /**
+   * Render the unit-file text without touching the OS. Surfaced for unit
+   * tests; the install() path uses this internally too.
+   */
+  renderUnit(ctx: ServiceHostContext): string | null;
+}

package/src/installer/wizard.ts

@@ -0,0 +1,92 @@
+/**
+ * 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;
+}
+
+export interface WizardAnswers {
+  dataDir: string;
+  uiPort: number;
+  libp2pPort: number;
+  upnpEnabled: boolean;
+  configureDdns: 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,
+  };
+}
+
+/**
+ * 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);
+  return { dataDir, uiPort, libp2pPort, 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

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

package/src/nat/__tests__/ddns-duckdns.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+
+import { duckDnsProvider } from '../ddns/duckdns.js';
+import { NatError } from '../types.js';
+
+function makeFetch(responses: Array<{ ok: boolean; status?: number; body: string }>): {
+  fetch: typeof fetch;
+  calls: string[];
+} {
+  const calls: string[] = [];
+  let i = 0;
+  const fetchImpl = (async (input: RequestInfo | URL) => {
+    calls.push(String(input));
+    const r = responses[i++] ?? { ok: false, body: '' };
+    return {
+      ok: r.ok,
+      status: r.status ?? (r.ok ? 200 : 500),
+      statusText: r.ok ? 'OK' : 'Server Error',
+      async text() { return r.body; },
+    } as unknown as Response;
+  }) as typeof fetch;
+  return { fetch: fetchImpl, calls };
+}
+
+describe('duckDnsProvider', () => {
+  it('exposes metadata', () => {
+    expect(duckDnsProvider.id).toBe('duckdns');
+    expect(duckDnsProvider.displayName).toBe('DuckDNS');
+    expect(duckDnsProvider.configFields).toHaveLength(1);
+    expect(duckDnsProvider.configFields[0]).toMatchObject({ key: 'token', secret: true });
+  });
+
+  it('OK response → resolves', async () => {
+    const f = makeFetch([{ ok: true, body: 'OK' }]);
+    await expect(
+      duckDnsProvider.update({ token: 'T' }, 'foo.duckdns.org', '1.2.3.4', { fetch: f.fetch }),
+    ).resolves.toBeUndefined();
+    expect(f.calls[0]).toContain('domains=foo');
+    expect(f.calls[0]).toContain('token=T');
+    expect(f.calls[0]).toContain('ip=1.2.3.4');
+  });
+
+  it('KO response → throws ddns_update_failed', async () => {
+    const f = makeFetch([{ ok: true, body: 'KO' }]);
+    await expect(
+      duckDnsProvider.update({ token: 'T' }, 'foo', '1.2.3.4', { fetch: f.fetch }),
+    ).rejects.toMatchObject({ code: 'ddns_update_failed' });
+  });
+
+  it('HTTP error → throws ddns_update_failed', async () => {
+    const f = makeFetch([{ ok: false, status: 503, body: '' }]);
+    await expect(
+      duckDnsProvider.update({ token: 'T' }, 'foo', '1.2.3.4', { fetch: f.fetch }),
+    ).rejects.toMatchObject({ code: 'ddns_update_failed' });
+  });
+
+  it('strips trailing .duckdns.org from hostname', async () => {
+    const f = makeFetch([{ ok: true, body: 'OK' }]);
+    await duckDnsProvider.update({ token: 'T' }, 'MyHost.DuckDNS.ORG', '1.2.3.4', { fetch: f.fetch });
+    expect(f.calls[0]).toContain('domains=myhost');
+  });
+
+  it('missing token → ddns_credentials_missing', async () => {
+    const f = makeFetch([]);
+    await expect(
+      duckDnsProvider.update({}, 'foo', '1.2.3.4', { fetch: f.fetch }),
+    ).rejects.toMatchObject({ code: 'ddns_credentials_missing' });
+  });
+
+  it('empty hostname → invalid_config', async () => {
+    const f = makeFetch([]);
+    await expect(
+      duckDnsProvider.update({ token: 'T' }, '   ', '1.2.3.4', { fetch: f.fetch }),
+    ).rejects.toBeInstanceOf(NatError);
+  });
+
+  it('network error → ddns_update_failed', async () => {
+    const f = (async () => { throw new Error('ENETUNREACH'); }) as typeof fetch;
+    await expect(
+      duckDnsProvider.update({ token: 'T' }, 'foo', '1.2.3.4', { fetch: f }),
+    ).rejects.toMatchObject({ code: 'ddns_update_failed' });
+  });
+});